Initial commit
This commit is contained in:
Zhongwei Li
591
skills/create-subagents/references/orchestration-patterns.md
Normal file
591
skills/create-subagents/references/orchestration-patterns.md
Normal file
@@ -0,0 +1,591 @@
|
||||
# Orchestration Patterns for Multi-Agent Systems
|
||||
|
||||
<core_concept>
|
||||
Orchestration defines how multiple subagents coordinate to complete complex tasks.
|
||||
|
||||
**Single agent**: Sequential execution within one context.
|
||||
**Multi-agent**: Coordination between multiple specialized agents, each with focused expertise.
|
||||
</core_concept>
|
||||
|
||||
<pattern_catalog>
|
||||
|
||||
|
||||
<sequential>
|
||||
**Sequential pattern**: Agents chained in predefined, linear order.
|
||||
|
||||
<characteristics>
|
||||
- Each agent processes output from previous agent
|
||||
- Pipeline of specialized transformations
|
||||
- Deterministic flow (A → B → C)
|
||||
- Easy to reason about and debug
|
||||
</characteristics>
|
||||
|
||||
<when_to_use>
|
||||
**Ideal for**:
|
||||
- Document review workflows (security → performance → style)
|
||||
- Data processing pipelines (extract → transform → validate → load)
|
||||
- Multi-stage reasoning (research → analyze → synthesize → recommend)
|
||||
|
||||
**Example**:
|
||||
```markdown
|
||||
Task: Comprehensive code review
|
||||
|
||||
Flow:
|
||||
1. security-reviewer: Check for vulnerabilities
|
||||
↓ (security report)
|
||||
2. performance-analyzer: Identify performance issues
|
||||
↓ (performance report)
|
||||
3. test-coverage-checker: Assess test coverage
|
||||
↓ (coverage report)
|
||||
4. report-synthesizer: Combine all findings into actionable review
|
||||
```
|
||||
</when_to_use>
|
||||
|
||||
<implementation>
|
||||
```markdown
|
||||
<sequential_workflow>
|
||||
Main chat orchestrates:
|
||||
1. Launch security-reviewer with code changes
|
||||
2. Wait for security report
|
||||
3. Launch performance-analyzer with code changes + security report context
|
||||
4. Wait for performance report
|
||||
5. Launch test-coverage-checker with code changes
|
||||
6. Wait for coverage report
|
||||
7. Synthesize all reports for user
|
||||
</sequential_workflow>
|
||||
```
|
||||
|
||||
**Benefits**: Clear dependencies, each stage builds on previous.
|
||||
**Drawbacks**: Slower than parallel (sequential latency), one failure blocks pipeline.
|
||||
</implementation>
|
||||
</sequential>
|
||||
|
||||
<parallel>
|
||||
**Parallel/Concurrent pattern**: Multiple specialized subagents perform tasks simultaneously.
|
||||
|
||||
<characteristics>
|
||||
- Agents execute independently and concurrently
|
||||
- Outputs synthesized for final response
|
||||
- Significant speed improvements
|
||||
- Requires synchronization
|
||||
</characteristics>
|
||||
|
||||
<when_to_use>
|
||||
**Ideal for**:
|
||||
- Independent analyses of same input (security + performance + quality)
|
||||
- Processing multiple independent items (review multiple files)
|
||||
- Research tasks (gather information from multiple sources)
|
||||
|
||||
**Performance data**: Anthropic's research system with 3-5 subagents in parallel achieved 90% time reduction.
|
||||
|
||||
**Example**:
|
||||
```markdown
|
||||
Task: Comprehensive code review (parallel approach)
|
||||
|
||||
Launch simultaneously:
|
||||
- security-reviewer (analyzes auth.ts)
|
||||
- performance-analyzer (analyzes auth.ts)
|
||||
- test-coverage-checker (analyzes auth.ts test coverage)
|
||||
|
||||
Wait for all three to complete → synthesize findings.
|
||||
|
||||
Time: max(agent_1, agent_2, agent_3) vs sequential: agent_1 + agent_2 + agent_3
|
||||
```
|
||||
</when_to_use>
|
||||
|
||||
<implementation>
|
||||
```markdown
|
||||
<parallel_workflow>
|
||||
Main chat orchestrates:
|
||||
1. Launch all agents simultaneously with same context
|
||||
2. Collect outputs as they complete
|
||||
3. Synthesize results when all complete
|
||||
|
||||
Synchronization challenges:
|
||||
- Handling different completion times
|
||||
- Dealing with partial failures (some agents fail, others succeed)
|
||||
- Combining potentially conflicting outputs
|
||||
</parallel_workflow>
|
||||
```
|
||||
|
||||
**Benefits**: Massive speed improvement, efficient resource utilization.
|
||||
**Drawbacks**: Increased complexity, synchronization challenges, higher cost (multiple agents running).
|
||||
</implementation>
|
||||
</parallel>
|
||||
|
||||
<hierarchical>
|
||||
**Hierarchical pattern**: Agents organized in layers, higher-level agents oversee lower-level.
|
||||
|
||||
<characteristics>
|
||||
- Tree-like structure with delegation
|
||||
- Higher-level agents break down tasks
|
||||
- Lower-level agents execute specific subtasks
|
||||
- Master-worker relationships
|
||||
</characteristics>
|
||||
|
||||
<when_to_use>
|
||||
**Ideal for**:
|
||||
- Large, complex problems requiring decomposition
|
||||
- Tasks with natural hierarchy (system design → component design → implementation)
|
||||
- Situations requiring oversight and quality control
|
||||
|
||||
**Example**:
|
||||
```markdown
|
||||
Task: Implement complete authentication system
|
||||
|
||||
Hierarchy:
|
||||
- architect (top-level): Designs overall auth system, breaks into components
|
||||
↓ delegates to:
|
||||
- backend-dev: Implements API endpoints
|
||||
- frontend-dev: Implements login UI
|
||||
- security-reviewer: Reviews both for vulnerabilities
|
||||
- test-writer: Creates integration tests
|
||||
↑ reports back to:
|
||||
- architect: Integrates components, ensures coherence
|
||||
```
|
||||
</when_to_use>
|
||||
|
||||
<implementation>
|
||||
```markdown
|
||||
<hierarchical_workflow>
|
||||
Top-level agent (architect):
|
||||
1. Analyze requirements
|
||||
2. Break into subtasks
|
||||
3. Delegate to specialized agents
|
||||
4. Monitor progress
|
||||
5. Integrate results
|
||||
6. Validate coherence across components
|
||||
|
||||
Lower-level agents:
|
||||
- Receive focused subtask
|
||||
- Execute with deep expertise
|
||||
- Report results to coordinator
|
||||
- No awareness of other agents' work
|
||||
</hierarchical_workflow>
|
||||
```
|
||||
|
||||
**Benefits**: Handles complexity through decomposition, clear responsibility boundaries.
|
||||
**Drawbacks**: Overhead in coordination, risk of misalignment between levels.
|
||||
</implementation>
|
||||
</hierarchical>
|
||||
|
||||
<coordinator>
|
||||
**Coordinator pattern**: Central LLM agent routes tasks to specialized sub-agents.
|
||||
|
||||
<characteristics>
|
||||
- Central decision-maker
|
||||
- Dynamic routing (not hardcoded workflow)
|
||||
- AI model orchestrates based on task characteristics
|
||||
- Similar to hierarchical but focused on process flow
|
||||
</characteristics>
|
||||
|
||||
<when_to_use>
|
||||
**Ideal for**:
|
||||
- Diverse task types requiring different expertise
|
||||
- Dynamic workflows where next step depends on results
|
||||
- User-facing systems with varied requests
|
||||
|
||||
**Example**:
|
||||
```markdown
|
||||
Task: "Help me improve my codebase"
|
||||
|
||||
Coordinator analyzes request → determines relevant agents:
|
||||
- code-quality-analyzer: Assess overall code quality
|
||||
↓ findings suggest security issues
|
||||
- Coordinator: Route to security-reviewer
|
||||
↓ security issues found
|
||||
- Coordinator: Route to auto-fixer to generate patches
|
||||
↓ patches ready
|
||||
- Coordinator: Route to test-writer to create tests for fixes
|
||||
↓
|
||||
- Coordinator: Synthesize all work into improvement plan
|
||||
```
|
||||
|
||||
**Dynamic routing** based on intermediate results, not predefined flow.
|
||||
</when_to_use>
|
||||
|
||||
<implementation>
|
||||
```markdown
|
||||
<coordinator_workflow>
|
||||
Coordinator agent prompt:
|
||||
|
||||
<role>
|
||||
You are an orchestration coordinator. Route tasks to specialized agents based on:
|
||||
- Task characteristics
|
||||
- Available agents and their capabilities
|
||||
- Results from previous agents
|
||||
- User goals
|
||||
</role>
|
||||
|
||||
<available_agents>
|
||||
- security-reviewer: Security analysis
|
||||
- performance-analyzer: Performance optimization
|
||||
- test-writer: Test creation
|
||||
- debugger: Bug investigation
|
||||
- refactorer: Code improvement
|
||||
</available_agents>
|
||||
|
||||
<decision_process>
|
||||
1. Analyze incoming task
|
||||
2. Identify relevant agents (may be multiple)
|
||||
3. Determine execution strategy (sequential, parallel, conditional)
|
||||
4. Launch agents with appropriate context
|
||||
5. Analyze results
|
||||
6. Decide next step (more agents, synthesis, completion)
|
||||
7. Repeat until task complete
|
||||
</decision_process>
|
||||
```
|
||||
|
||||
**Benefits**: Flexible, adaptive to task requirements, efficient agent utilization.
|
||||
**Drawbacks**: Coordinator is single point of failure, complexity in routing logic.
|
||||
</implementation>
|
||||
</coordinator>
|
||||
|
||||
<orchestrator_worker>
|
||||
**Orchestrator-Worker pattern**: Central orchestrator assigns tasks, manages execution.
|
||||
|
||||
<characteristics>
|
||||
- Centralized coordination with distributed execution
|
||||
- Workers focus on specific, independent tasks
|
||||
- Similar to distributed computing master-worker pattern
|
||||
- Clear separation of planning (orchestrator) and execution (workers)
|
||||
</characteristics>
|
||||
|
||||
<when_to_use>
|
||||
**Ideal for**:
|
||||
- Batch processing (process 100 files)
|
||||
- Independent tasks that can be distributed (analyze multiple API endpoints)
|
||||
- Load balancing across workers
|
||||
|
||||
**Example**:
|
||||
```markdown
|
||||
Task: Security review of 50 microservices
|
||||
|
||||
Orchestrator:
|
||||
1. Identifies all 50 services
|
||||
2. Breaks into batches of 5
|
||||
3. Assigns batches to worker agents
|
||||
4. Monitors progress
|
||||
5. Aggregates results
|
||||
|
||||
Workers (5 concurrent instances of security-reviewer):
|
||||
- Each reviews assigned services
|
||||
- Reports findings to orchestrator
|
||||
- Independent execution (no inter-worker communication)
|
||||
```
|
||||
</when_to_use>
|
||||
|
||||
<sonnet_haiku_orchestration>
|
||||
**Sonnet 4.5 + Haiku 4.5 orchestration**: Optimal cost/performance pattern.
|
||||
|
||||
Research findings:
|
||||
- Sonnet 4.5: "Best model in the world for agents", exceptional at planning and validation
|
||||
- Haiku 4.5: "90% of Sonnet 4.5 performance", one of best coding models, fast and cost-efficient
|
||||
|
||||
**Pattern**:
|
||||
```markdown
|
||||
1. Sonnet 4.5 (Orchestrator):
|
||||
- Analyzes task
|
||||
- Creates plan
|
||||
- Breaks into subtasks
|
||||
- Identifies what can be parallelized
|
||||
|
||||
2. Multiple Haiku 4.5 instances (Workers):
|
||||
- Each completes assigned subtask
|
||||
- Executes in parallel for speed
|
||||
- Returns results to orchestrator
|
||||
|
||||
3. Sonnet 4.5 (Orchestrator):
|
||||
- Integrates results from all workers
|
||||
- Validates output quality
|
||||
- Ensures coherence
|
||||
- Delivers final output
|
||||
```
|
||||
|
||||
**Cost/performance optimization**: Expensive Sonnet only for planning/validation, cheap Haiku for execution.
|
||||
</sonnet_haiku_orchestration>
|
||||
</orchestrator_worker>
|
||||
</pattern_catalog>
|
||||
|
||||
<hybrid_approaches>
|
||||
|
||||
|
||||
Real-world systems often combine patterns for different workflow phases.
|
||||
|
||||
<example name="sequential_then_parallel">
|
||||
**Sequential for initial processing → Parallel for analysis**:
|
||||
|
||||
```markdown
|
||||
Task: Comprehensive feature implementation review
|
||||
|
||||
Sequential phase:
|
||||
1. requirements-validator: Check requirements completeness
|
||||
↓
|
||||
2. implementation-reviewer: Verify feature implemented correctly
|
||||
↓
|
||||
|
||||
Parallel phase (once implementation validated):
|
||||
3. Launch simultaneously:
|
||||
- security-reviewer
|
||||
- performance-analyzer
|
||||
- accessibility-checker
|
||||
- test-coverage-validator
|
||||
↓
|
||||
|
||||
Sequential synthesis:
|
||||
4. report-generator: Combine all findings
|
||||
```
|
||||
|
||||
**Rationale**: Early stages have dependencies (can't validate implementation before requirements), later stages are independent analyses.
|
||||
</example>
|
||||
|
||||
<example name="coordinator_with_hierarchy">
|
||||
**Coordinator orchestrating hierarchical teams**:
|
||||
|
||||
```markdown
|
||||
Top level: Coordinator receives "Build payment system"
|
||||
|
||||
Coordinator creates hierarchical teams:
|
||||
|
||||
Team 1 (Backend):
|
||||
- Lead: backend-architect
|
||||
- Workers: api-developer, database-designer, integration-specialist
|
||||
|
||||
Team 2 (Frontend):
|
||||
- Lead: frontend-architect
|
||||
- Workers: ui-developer, state-management-specialist
|
||||
|
||||
Team 3 (DevOps):
|
||||
- Lead: infra-architect
|
||||
- Workers: deployment-specialist, monitoring-specialist
|
||||
|
||||
Coordinator:
|
||||
- Manages team coordination
|
||||
- Resolves inter-team dependencies
|
||||
- Integrates deliverables
|
||||
```
|
||||
|
||||
**Benefit**: Combines dynamic routing (coordinator) with team structure (hierarchy).
|
||||
</example>
|
||||
</hybrid_approaches>
|
||||
|
||||
<implementation_guidance>
|
||||
|
||||
|
||||
<coordinator_subagent>
|
||||
**Example coordinator implementation**:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: workflow-coordinator
|
||||
description: Orchestrates multi-agent workflows. Use when task requires multiple specialized agents in coordination.
|
||||
tools: all
|
||||
model: sonnet
|
||||
---
|
||||
|
||||
<role>
|
||||
You are a workflow coordinator. Analyze tasks, identify required agents, orchestrate their execution.
|
||||
</role>
|
||||
|
||||
<available_agents>
|
||||
{list of specialized agents with capabilities}
|
||||
</available_agents>
|
||||
|
||||
<orchestration_strategies>
|
||||
**Sequential**: When agents depend on each other's outputs
|
||||
**Parallel**: When agents can work independently
|
||||
**Hierarchical**: When task needs decomposition with oversight
|
||||
**Adaptive**: Choose pattern based on task characteristics
|
||||
</orchestration_strategies>
|
||||
|
||||
<workflow>
|
||||
1. Analyze incoming task
|
||||
2. Identify required capabilities
|
||||
3. Select agents and pattern
|
||||
4. Launch agents (sequentially or parallel as appropriate)
|
||||
5. Monitor execution
|
||||
6. Handle errors (retry, fallback, escalate)
|
||||
7. Integrate results
|
||||
8. Validate coherence
|
||||
9. Deliver final output
|
||||
</workflow>
|
||||
|
||||
<error_handling>
|
||||
If agent fails:
|
||||
- Retry with refined context (1-2 attempts)
|
||||
- Try alternative agent if available
|
||||
- Proceed with partial results if acceptable
|
||||
- Escalate to human if critical
|
||||
</error_handling>
|
||||
```
|
||||
</coordinator_subagent>
|
||||
|
||||
<handoff_protocol>
|
||||
**Clean handoffs between agents**:
|
||||
|
||||
```markdown
|
||||
<agent_handoff_format>
|
||||
From: {source_agent}
|
||||
To: {target_agent}
|
||||
Task: {specific task}
|
||||
Context:
|
||||
- What was done: {summary of prior work}
|
||||
- Key findings: {important discoveries}
|
||||
- Constraints: {limitations or requirements}
|
||||
- Expected output: {what target agent should produce}
|
||||
|
||||
Attachments:
|
||||
- {relevant files, data, or previous outputs}
|
||||
</agent_handoff_format>
|
||||
```
|
||||
|
||||
**Why explicit format matters**: Prevents information loss, ensures target agent has full context, enables validation.
|
||||
</handoff_protocol>
|
||||
|
||||
<synchronization>
|
||||
**Handling parallel execution**:
|
||||
|
||||
```markdown
|
||||
<parallel_synchronization>
|
||||
Launch pattern:
|
||||
1. Initiate all parallel agents with shared context
|
||||
2. Track which agents have completed
|
||||
3. Collect outputs as they arrive
|
||||
4. Wait for all to complete OR timeout
|
||||
5. Proceed with available results (flag missing if timeout)
|
||||
|
||||
Partial failure handling:
|
||||
- If 1 of 3 agents fails: Proceed with 2 results, note gap
|
||||
- If 2 of 3 agents fail: Consider retry or workflow failure
|
||||
- Always communicate what was completed vs attempted
|
||||
</parallel_synchronization>
|
||||
```
|
||||
</synchronization>
|
||||
</implementation_guidance>
|
||||
|
||||
<anti_patterns>
|
||||
|
||||
|
||||
<anti_pattern name="over_orchestration">
|
||||
❌ Using multiple agents when single agent would suffice
|
||||
|
||||
**Example**: Three agents to review 10 lines of code (overkill).
|
||||
|
||||
**Fix**: Reserve multi-agent for genuinely complex tasks. Single capable agent often better than coordinating multiple simple agents.
|
||||
</anti_pattern>
|
||||
|
||||
<anti_pattern name="no_coordination">
|
||||
❌ Launching multiple agents with no coordination or synthesis
|
||||
|
||||
**Problem**: User gets conflicting reports, no coherent output, unclear which to trust.
|
||||
|
||||
**Fix**: Always synthesize multi-agent outputs into coherent final result.
|
||||
</anti_pattern>
|
||||
|
||||
<anti_pattern name="sequential_when_parallel">
|
||||
❌ Running independent analyses sequentially
|
||||
|
||||
**Example**: Security review → performance review → quality review (each independent, done sequentially).
|
||||
|
||||
**Fix**: Parallel execution for independent tasks. 3x speed improvement in this case.
|
||||
</anti_pattern>
|
||||
|
||||
<anti_pattern name="unclear_handoffs">
|
||||
❌ Agent outputs that don't provide sufficient context for next agent
|
||||
|
||||
**Example**:
|
||||
```markdown
|
||||
Agent 1: "Found issues"
|
||||
Agent 2: Receives "Found issues" with no details on what, where, or severity
|
||||
Agent 2: Can't effectively act on vague input
|
||||
```
|
||||
|
||||
**Fix**: Structured handoff format with complete context.
|
||||
</anti_pattern>
|
||||
|
||||
<anti_pattern name="no_error_recovery">
|
||||
❌ Orchestration with no fallback when agent fails
|
||||
|
||||
**Problem**: One agent failure causes entire workflow failure.
|
||||
|
||||
**Fix**: Graceful degradation, retry logic, alternative agents, partial results (see [error-handling-and-recovery.md](error-handling-and-recovery.md)).
|
||||
</anti_pattern>
|
||||
</anti_patterns>
|
||||
|
||||
<best_practices>
|
||||
|
||||
|
||||
<principle name="right_granularity">
|
||||
**Agent granularity**: Not too broad, not too narrow.
|
||||
|
||||
Too broad: "general-purpose-helper" (defeats purpose of specialization)
|
||||
Too narrow: "checks-for-sql-injection-in-nodejs-express-apps-only" (too specific)
|
||||
Right: "security-reviewer specializing in web application vulnerabilities"
|
||||
</principle>
|
||||
|
||||
<principle name="clear_responsibilities">
|
||||
**Each agent should have clear, non-overlapping responsibility**.
|
||||
|
||||
Bad: Two agents both "review code for quality" (overlap, confusion)
|
||||
Good: "security-reviewer" + "performance-analyzer" (distinct concerns)
|
||||
</principle>
|
||||
|
||||
<principle name="minimize_handoffs">
|
||||
**Minimize information loss at boundaries**.
|
||||
|
||||
Each handoff is opportunity for context loss. Structured handoff formats prevent this.
|
||||
</principle>
|
||||
|
||||
<principle name="parallel_where_possible">
|
||||
**Parallelize independent work**.
|
||||
|
||||
If agents don't depend on each other's outputs, run them concurrently.
|
||||
</principle>
|
||||
|
||||
<principle name="coordinator_lightweight">
|
||||
**Keep coordinator logic lightweight**.
|
||||
|
||||
Heavy coordinator = bottleneck. Coordinator should route and synthesize, not do deep work itself.
|
||||
</principle>
|
||||
|
||||
<principle name="cost_optimization">
|
||||
**Use model tiers strategically**.
|
||||
|
||||
- Planning/validation: Sonnet 4.5 (needs intelligence)
|
||||
- Execution of clear tasks: Haiku 4.5 (fast, cheap, still capable)
|
||||
- Highest stakes decisions: Sonnet 4.5
|
||||
- Bulk processing: Haiku 4.5
|
||||
</principle>
|
||||
</best_practices>
|
||||
|
||||
<pattern_selection>
|
||||
|
||||
|
||||
<decision_tree>
|
||||
```markdown
|
||||
Is task decomposable into independent subtasks?
|
||||
├─ Yes: Parallel pattern (fastest)
|
||||
└─ No: ↓
|
||||
|
||||
Do subtasks depend on each other's outputs?
|
||||
├─ Yes: Sequential pattern (clear dependencies)
|
||||
└─ No: ↓
|
||||
|
||||
Is task large/complex requiring decomposition AND oversight?
|
||||
├─ Yes: Hierarchical pattern (structured delegation)
|
||||
└─ No: ↓
|
||||
|
||||
Do task requirements vary dynamically?
|
||||
├─ Yes: Coordinator pattern (adaptive routing)
|
||||
└─ No: Single agent sufficient
|
||||
```
|
||||
</decision_tree>
|
||||
|
||||
<performance_vs_complexity>
|
||||
**Performance**: Parallel > Hierarchical > Sequential > Coordinator (overhead)
|
||||
**Complexity**: Coordinator > Hierarchical > Parallel > Sequential
|
||||
**Flexibility**: Coordinator > Hierarchical > Parallel > Sequential
|
||||
|
||||
**Trade-off**: Choose simplest pattern that meets requirements.
|
||||
</performance_vs_complexity>
|
||||
</pattern_selection>
|
||||
Reference in New Issue
Block a user