The Orchestrator Pattern

Introduction

The orchestrator pattern is a multi-agent architecture where a main agent coordinates multiple specialist agents through an intermediate coordinator layer. This creates a tree structure: Main gives the coordinator a complex task, the coordinator breaks it into subtasks and spawns workers, and results flow back up for synthesis. This lesson covers the pattern, depth limits, and result synthesis strategies.

Key Concepts

• Orchestrator (Main Agent): The top-level agent that receives user requests and delegates to coordinators
• Coordinator: A middle-tier agent that decomposes tasks and manages workers
• Workers: Leaf-level agents that execute specific subtasks and return results
• maxSpawnDepth: 2: The maximum nesting level for spawned sessions (main > coordinator > worker)
• Parallel Task Distribution: Spawning multiple workers simultaneously to reduce total execution time
• Result Synthesis: Combining worker outputs into a coherent final response

Real World Context

A CTO asks their OpenClaw agent to prepare a technical due diligence report for an acquisition target. The main agent acts as the orchestrator, spawning a coordinator for each assessment area: codebase quality, infrastructure maturity, and security posture. Each coordinator then spawns 2-3 workers to analyze specific aspects. The results cascade back up, with each coordinator summarizing its area and the main agent producing the final report.

Deep Dive

The Three-Tier Architecture

The orchestrator pattern uses three levels of agents:

json
{
  "orchestration": {
    "main": {
      "role": "orchestrator",
      "spawns": ["code-quality-coordinator", "infra-coordinator", "security-coordinator"]
    },
    "coordinators": {
      "code-quality-coordinator": {
        "role": "coordinator",
        "spawns": ["frontend-reviewer", "backend-reviewer", "test-coverage-analyzer"]
      }
    },
    "workers": {
      "frontend-reviewer": {
        "role": "worker",
        "task": "Review frontend code quality and patterns"
      }
    }
  }
}

This configuration shows the hierarchy. The main orchestrator spawns coordinators, each coordinator spawns workers. Workers are the leaf nodes that do the actual analysis.

Spawn Depth Limits

OpenClaw enforces a maximum spawn depth of 2:

json
{
  "agents": {
    "defaults": {
      "maxSpawnDepth": 2
    }
  }
}

This means: Main (depth 0) can spawn Coordinators (depth 1), which can spawn Workers (depth 2). Workers cannot spawn further children. This limit prevents unbounded recursion and keeps resource consumption predictable.

Parallel Distribution

The coordinator spawns multiple workers in parallel:

json
[
  {
    "tool": "sessions_spawn",
    "params": {
      "task": "Review React components for performance anti-patterns",
      "label": "frontend-perf",
      "runTimeoutSeconds": 180
    }
  },
  {
    "tool": "sessions_spawn",
    "params": {
      "task": "Analyze API endpoints for N+1 query patterns",
      "label": "backend-queries",
      "runTimeoutSeconds": 180
    }
  },
  {
    "tool": "sessions_spawn",
    "params": {
      "task": "Check test coverage and identify untested critical paths",
      "label": "test-gaps",
      "runTimeoutSeconds": 120
    }
  }
]

All three workers start simultaneously. Instead of spending 9 minutes sequentially, the total time is bounded by the slowest worker (around 3 minutes).

Result Synthesis

The coordinator collects worker results and produces a summary. The main agent then synthesizes coordinator summaries into the final response. This two-stage synthesis ensures that information is progressively distilled from detailed findings to high-level conclusions.

Common Pitfalls

• Exceeding maxSpawnDepth: Attempting to spawn from a depth-2 worker will fail silently. Design your task decomposition to fit within 3 tiers.
• Not handling worker failures: If one worker times out, the coordinator must still produce a useful result from the remaining workers.
• Over-decomposing simple tasks: Not every task needs three tiers. Use the orchestrator pattern only when the task is genuinely complex enough to benefit from parallel decomposition.

Best Practices

• Design for graceful degradation so that partial worker results still produce useful coordinator summaries.
• Use the orchestrator pattern for tasks that are naturally parallelizable, like reviewing different parts of a codebase.
• Keep the coordinator's synthesis instructions explicit so it knows how to combine worker outputs effectively.

Summary

• The orchestrator pattern creates a Main > Coordinator > Worker hierarchy for complex tasks
• maxSpawnDepth of 2 limits nesting to three tiers to prevent unbounded recursion
• Parallel task distribution reduces total execution time by running workers concurrently
• Result synthesis occurs at two stages: workers to coordinator, coordinators to main
• Use this pattern for genuinely complex tasks that benefit from parallel decomposition