Skip to main content

run Command

The run command is your primary way to execute an agentic workflow. It handles dependency resolution, parallel execution, and tool discovery automatically.

bash
BASH
agac run -a <workflow-name> [options]

:::tip Run from Anywhere You can run this command from any subdirectory within your project. The CLI will automatically find your project root. :::

Basic Usage​

Let's start with the essentials:

bash
BASH
# Run an agentic workflow
agac run -a my_workflow

# Run with custom tools
agac run -a my_workflow -u ./user_code --use-tools

# Force parallel execution
agac run -a my_workflow --execution-mode parallel

Options​

OptionDescription
-a, --agent NAMEAgentic workflow name (required)
-u, --user-code DIRECTORYPath to user's code folder containing tools
--use-toolsEnable tool usage for actions
-e, --execution-modeExecution mode: auto (default), parallel, or sequential
--concurrency-limitMax concurrent actions (default: 5, range: 1-50)
--freshClear stored results, dispositions, status, and event logs (events.json, errors.json) before execution. Gives a clean slate for debugging.
--verify-keysVerify API keys before execution

Parallel Execution​

Agent Actions automatically detects independent actions and runs them concurrently.

bash
BASH
# Auto-detect parallel execution (default)
agac run -a my_workflow

# Force parallel execution
agac run -a my_workflow --execution-mode parallel
# Or using short form:
agac run -a my_workflow -e parallel

# Force sequential execution
agac run -a my_workflow --execution-mode sequential

# Limit concurrent actions to 10
agac run -a my_workflow -e parallel --concurrency-limit 10

The diagram below shows how Agent Actions organizes actions into levels. Actions at the same level run in parallel because they don't depend on each other's outputs:

Notice that analyze and transform both depend on extract, but not on each other - so they run concurrently. The merge action waits for both to complete.

:::info Concurrency Limits The default concurrency limit is 5 actions. If your agentic workflow has many parallel actions and you're hitting rate limits, consider reducing this. If you have capacity, increase it up to 50. :::

See Also​