agent-orchestrator

Multi-agent orchestration for OpenClaw. Implements 5 proven patterns for coordinating multiple AI agents: Work Crew, Supervisor, Pipeline, Expert Council, and Auto-Routing.

USE WHEN:

• A task can be parallelized for speed or redundancy (Work Crew)
• Complex tasks need dynamic planning and delegation (Supervisor)
• Work follows a predictable sequence of stages (Pipeline)
• Cross-domain input is needed from multiple specialists (Expert Council)
• Mixed task types need automatic routing to appropriate specialists (Auto-Routing)
• Research tasks require breadth-first exploration of multiple angles
• High-stakes decisions need confidence through multiple perspectives

DON'T USE WHEN:

• Simple tasks that fit in one agent's context window (use main session instead)
• Sequential tasks with no parallelization opportunity (use regular tool calls)
• One-shot deterministic tasks (use single agent)
• Tasks requiring real-time inter-agent conversation (this uses async spawning)
• Tasks where 15x token cost cannot be justified
• Quick/simple tasks where coordination overhead exceeds benefit

Outputs:

• Aggregated results from multiple parallel agents
• Synthesized consensus recommendations
• Routing decisions to appropriate specialists
• Structured output from staged processing

Decision Matrix

| Pattern | Use When | Avoid When |

|---------|----------|------------|

| crew | Same task from multiple angles, verification, research breadth | Results cannot be easily compared/merged |

| supervise | Dynamic decomposition needed, complex planning | Fixed workflow, simple delegation |

| pipeline | Well-defined sequential stages, content creation | Path needs runtime adaptation |

| council | Cross-domain expertise, risk assessment, policy review | Single-domain task, need fast consensus |

| route | Mixed workload types, automatic classification | Task type is already known |

Auto-Routing Pattern

The route command analyzes tasks and automatically classifies them by type, then routes to the appropriate specialist:

# Basic routing
claw agent-orchestrator route --task "Write Python parser"

# With custom specialist pool
claw agent-orchestrator route \
  --task "Analyze data and create report" \
  --specialists "analyst,data,writer"

# Force specific specialist
claw agent-orchestrator route \
  --task "Something complex" \
  --force coder

Confidence Thresholds

• High confidence (>0.85): Auto-route immediately
• Good confidence (0.7-0.85): Propose with confirmation option
• Moderate confidence (0.5-0.7): Show top alternatives
• Low confidence (<0.5): Request clarification

Available specialists: coder, researcher, writer, analyst, planner, reviewer, creative, data, devops, support

Common Workflows

# Parallel research with consensus
claw agent-orchestrator crew \
  --task "Research Bitcoin Lightning 2026 adoption" \
  --agents 4 \
  --perspectives technical,business,security,competitors \
  --converge consensus

# Best-of redundancy for critical analysis
claw agent-orchestrator crew \
  --task "Audit this smart contract for vulnerabilities" \
  --agents 3 \
  --converge best-of

# Supervisor-managed code review
claw agent-orchestrator supervise \
  --task "Refactor authentication module" \
  --workers coder,reviewer,tester \
  --strategy adaptive

# Staged content pipeline
claw agent-orchestrator pipeline \
  --stages research,draft,review,finalize \
  --input "topic: AI agent adoption trends"

# Expert council for decision
claw agent-orchestrator council \
  --question "Should we publish this blog post about unreleased features?" \
  --experts skeptic,ethicist,strategist \
  --converge consensus \
  --rounds 2

# Auto-route mixed tasks
claw agent-orchestrator route \
  --task "Write Python function to analyze CSV data" \
  --specialists coder,researcher,writer,analyst

# Force route to specific specialist
claw agent-orchestrator route \
  --task "Debug authentication error" \
  --force coder \
  --confidence-threshold 0.9

# Route and output as JSON for scripting
claw agent-orchestrator route \
  --task $TASK \
  --format json \
  --specialists "coder,data,analyst"

Negative Examples

DON'T: Use crew for simple single-answer questions

# WRONG: Wasteful for simple facts
claw agent-orchestrator crew --task "What is 2+2?" --agents 3

# RIGHT: Use main session directly
What is 2+2?

DON'T: Use supervise when pipeline suffices

# WRONG: Over-engineering fixed workflows
claw agent-orchestrator supervise --task "Draft, edit, publish"

# RIGHT: Use pipeline for fixed sequences
claw agent-orchestrator pipeline --stages draft,edit,publish

DON'T: Route when task type is obvious

# WRONG: Unnecessary classification overhead
claw agent-orchestrator route --task "Write Python code"

# RIGHT: Direct to appropriate specialist
claw agent-orchestrator crew --pattern code --task "Write Python code"

DON'T: Use multi-agent for very small context tasks

# WRONG: Coordination overhead exceeds value
claw agent-orchestrator crew --task "Fix typo" --agents 2

# RIGHT: Single agent or direct edit
edit file.py "typo" "correct"

Token Cost Warning

Multi-agent patterns use approximately 15x more tokens than single-agent interactions. Use only for high-value tasks where quality improvement justifies the cost. See Anthropic research: token usage explains 80% of performance variance in complex tasks.

Dependencies

• Python 3.8+
• OpenClaw sessions_spawn capability
• OpenClaw sessions_list capability
• OpenClaw sessions_history capability

Files

• main.py - CLI entry point
• crew.py - Work Crew pattern implementation
• supervise.py - Supervisor pattern (Phase 2)
• council.py - Expert Council pattern (Phase 2)
• pipeline.py - Pipeline pattern (Phase 2)
• route.py - Auto-Routing pattern (Phase 2)
• utils.py - Shared utilities for session management

Status

• MVP: Work Crew pattern implemented
• Phase 2: 100% Complete
• [x] Supervisor pattern implemented - dynamic task decomposition and worker delegation
• [x] Pipeline pattern implemented - sequential staged processing with validation gates
• [x] Council pattern implemented - multi-expert deliberation with convergence methods
• [x] Route pattern implemented - intelligent task classification and specialist routing

References

• Anthropic Multi-Agent Research System
• LangGraph Supervisor Pattern
• CrewAI Framework
• AutoGen Conversational Agents