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.

agac run -a <workflow-name> [options]
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:

# 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)

Parallel Execution​

Agent Actions automatically detects independent actions and runs them concurrently.

# 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.

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​