Parallel Tool Execution

Sequential vs Parallel: The Difference

Consider an agent that needs to: search the web, read a file, and query a database — three independent operations. Sequentially this takes t1 + t2 + t3. In parallel it takes max(t1, t2, t3):

Sequential:  [web_search 2s]──[read_file 0.5s]──[db_query 1s] = 3.5s
Parallel:    [web_search 2s]
             [read_file  0.5s]                                  = 2.0s (same wall time)
             [db_query   1s  ]

The more independent tools your agent uses, the bigger the parallelism win.

Enable Parallel Execution

# config.yaml
parallelism:
  enabled: true
  max_workers: 4       # How many tool calls to run simultaneously
  timeout_per_tool: 15 # Seconds before a single tool call is killed
  strategy: auto       # "auto" | "dependency-graph" | "manual"

With strategy: auto, OpenClaw analyzes tool inputs at runtime to detect which calls are independent and can safely run in parallel.

Tool Dependency Graphs

For fine-grained control, define explicit dependencies in your agent YAML so OpenClaw knows which tools can run in parallel:

# agent.yaml
tools:
  - name: fetch_github_issues
    depends_on: []           # No dependencies — can run immediately
  - name: fetch_slack_messages
    depends_on: []           # Also independent
  - name: generate_report
    depends_on:              # Must wait for both above to finish
      - fetch_github_issues
      - fetch_slack_messages

OpenClaw builds a DAG (directed acyclic graph) from these dependencies and executes levels in parallel:

Level 1 (parallel): [fetch_github_issues] [fetch_slack_messages]
Level 2 (waits):    [generate_report]

Error Handling in Parallel Execution

When tool calls run in parallel, one failure shouldn't necessarily abort the entire task. Configure failure behavior:

parallelism:
  enabled: true
  on_tool_failure: continue  # "abort" | "continue" | "retry"
  max_retries: 2             # Retry failed tools up to 2 times
  retry_backoff: 1.5         # Exponential backoff multiplier

Rate Limiting Awareness

Parallel execution can trigger provider rate limits. OpenClaw handles this automatically:

llm:
  rate_limit:
    requests_per_minute: 500    # Match your tier's limit
    tokens_per_minute: 200000
    auto_throttle: true         # Back off automatically on 429 errors

When auto_throttle: true, OpenClaw detects rate limit responses and uses exponential backoff, then resumes parallel execution automatically.

Real-World Speedup Examples

When NOT to Parallelize

• Sequential reasoning chains — if step B depends on step A's output, parallelism doesn't help
• Rate-limited tools — some APIs only allow 1 req/s; parallelism just causes failures
• State-mutating operations — avoid parallel writes to the same resource
• Very short tasks — parallel overhead (~10ms) isn't worth it for sub-100ms tool calls

Designing for Parallel Execution

Not all agent tasks benefit equally from parallelism. Tasks with sequential dependencies — where step 3 needs the output of step 2 — cannot be parallelized no matter how many workers you add. Tasks that are independent of each other — processing 100 different customer records — parallelize perfectly and benefit linearly from additional workers up to your rate limit. Analyze your workload before adding parallelism: draw a dependency graph of your task steps and identify which subsets are independent. Parallelism delivers returns only on the independent parts.

Fan-out and fan-in is the most common parallel execution pattern in agent workflows. The orchestrating agent receives a batch input and fans it out to N worker agents in parallel. Each worker processes one item and returns a result. The orchestrator collects all results and fans back in to produce the final output. This pattern scales efficiently and is simple to implement — configure the orchestrator with a batch_size and parallelism setting, and OpenClaw handles the worker dispatching and result collection automatically.

Rate Limit Management

Parallel execution multiplies your API request rate by the number of parallel workers. With 10 parallel workers, you'll consume API quota 10x faster than sequential execution. Before increasing parallelism, check your API provider's rate limits and ensure your plan can support the increased throughput. Most providers offer higher rate limits at higher pricing tiers — the cost increase for a tier upgrade is often justified by the time savings from parallel processing. Monitor your rate limit headers in API responses and reduce parallelism automatically when approaching the limit.

Implement jitter (random delay variation) when starting parallel workers to avoid synchronized request bursts. If all 10 workers start simultaneously and each immediately makes an API call, you get a burst of 10 concurrent calls. With jitter (each worker starts with a random delay of 0-500ms), the calls spread out over time, reducing peak request rate by up to 3x for the same throughput. Jitter is a simple technique that prevents self-inflicted rate limit spikes without reducing overall throughput.

Error Handling in Parallel Contexts

When one worker in a parallel batch fails, decide whether to fail the entire batch or continue with the remaining workers. The right choice depends on your use case. For data enrichment (each item is independent), continuing is usually right — one failed item shouldn't prevent the other 99 from being processed. For a sequential pipeline where all outputs feed into a subsequent step, a single failure may invalidate the entire batch. Configure your failure policy explicitly — never rely on the default behavior to happen to match your requirements.