This skill covers patterns for coordinating multiple AI agents, decomposing complex tasks, managing handoffs, and building robust agent workflows.
Orchestration Fundamentals
Agent Hierarchy Model
┌─────────────────────────────────────────────────────┐
│ ORCHESTRATOR AGENT │
│ (Strategic coordination, task routing, synthesis) │
├─────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │
│ │ Specialist │ │ Specialist │ │ Specialist │ │
│ │ Agent A │ │ Agent B │ │ Agent C │ │
│ │ (Domain 1) │ │ (Domain 2) │ │ (Domain 3) │ │
│ └──────────────┘ └──────────────┘ └────────────┘ │
│ │
└─────────────────────────────────────────────────────┘
Core Principles
- Single Responsibility: Each agent has one clear domain
- Explicit Handoffs: Clear protocols for transferring work
- Context Preservation: State travels with the task
- Graceful Degradation: System works if agents fail
- Observable Execution: Can see what each agent is doing
Task Decomposition Patterns
Pattern 1: Hierarchical Decomposition
Complex Task: "Build a feature for user authentication"
Decomposed:
├── Research Phase (Research Agent)
│ ├── Analyze existing auth patterns in codebase
│ ├── Identify dependencies and constraints
│ └── Document findings
│
├── Design Phase (Architect Agent)
│ ├── Design auth flow
│ ├── Define API contracts
│ └── Create component structure
│
├── Implementation Phase (Developer Agent)
│ ├── Implement backend auth logic
│ ├── Build frontend components
│ └── Add error handling
│
├── Testing Phase (QA Agent)
│ ├── Write unit tests
│ ├── Integration tests
│ └── Security review
│
└── Documentation Phase (Docs Agent)
├── API documentation
├── User guide
└── Developer notes
Pattern 2: Parallel Decomposition
Task: "Analyze codebase and suggest improvements"
Parallel Execution:
┌─────────────────────────────────────────────────────┐
│ ORCHESTRATOR │
│ Spawns parallel agents │
└───────────┬─────────────┬─────────────┬────────────┘
│ │ │
▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌───────────┐
│ Security │ │Performance│ │ Code │
│ Analyst │ │ Analyst │ │ Quality │
└─────┬─────┘ └─────┬─────┘ └─────┬─────┘
│ │ │
▼ ▼ ▼
[Security [Performance [Quality
Report] Report] Report]
│ │ │
└──────────────┼──────────────┘
│
▼
┌─────────────────┐
│ ORCHESTRATOR │
│ Synthesizes │
└─────────────────┘
Pattern 3: Iterative Refinement
Task: "Write a technical blog post"
Iteration Loop:
1. Researcher → Gathers information
2. Writer → Creates draft
3. Editor → Reviews and critiques
4. Writer → Revises based on feedback
5. Editor → Approves or requests more changes
6. Repeat 4-5 until quality threshold met
7. Publisher → Formats and publishes
Handoff Patterns
Pattern 1: Explicit Handoff Protocol
interface TaskHandoff {
from_agent: string;
to_agent: string;
task_id: string;
context: {
original_request: string;
work_completed: string[];
current_state: any;
next_steps: string[];
};
artifacts: {
files_created: string[];
files_modified: string[];
decisions_made: Decision[];
};
}
// Example handoff
const handoff: TaskHandoff = {
from_agent: "ArchitectAgent",
to_agent: "DeveloperAgent",
task_id: "auth-feature-123",
context: {
original_request: "Implement user authentication",
work_completed: [
"Analyzed existing patterns",
"Designed auth flow",
"Created API contracts"
],
current_state: {
design_doc: "/docs/auth-design.md",
api_spec: "/specs/auth-api.yaml"
},
next_steps: [
"Implement AuthService class",
"Create login/logout endpoints",
"Build session management"
]
},
artifacts: {
files_created: ["/docs/auth-design.md", "/specs/auth-api.yaml"],
files_modified: [],
decisions_made: [
{ decision: "Use JWT for tokens", rationale: "Stateless, scalable" },
{ decision: "Redis for session store", rationale: "Fast, supports TTL" }
]
}
};
Pattern 2: Capability-Based Routing
const agentCapabilities = {
ResearchAgent: ["search", "analyze", "summarize", "compare"],
ArchitectAgent: ["design", "plan", "structure", "evaluate"],
DeveloperAgent: ["implement", "refactor", "debug", "optimize"],
ReviewerAgent: ["review", "critique", "validate", "approve"],
DocsAgent: ["document", "explain", "format", "publish"]
};
function routeTask(task: string): string {
const taskVerb = extractVerb(task);
for (const [agent, capabilities] of Object.entries(agentCapabilities)) {
if (capabilities.includes(taskVerb)) {
return agent;
}
}
return "GeneralAgent"; // Fallback
}
Pattern 3: Context Window Management
// Problem: Context grows as agents work
// Solution: Summarize and compress at handoffs
interface CompressedContext {
essential: {
task_goal: string;
key_decisions: string[];
current_blockers: string[];
};
reference: {
file_paths: string[]; // Can be re-read if needed
doc_links: string[]; // External references
};
discarded: {
exploration_notes: string; // Summarized, not full content
rejected_approaches: string[];
};
}
function compressForHandoff(fullContext: any): CompressedContext {
return {
essential: extractEssentials(fullContext),
reference: extractReferences(fullContext),
discarded: summarizeDiscarded(fullContext)
};
}
Reference
The full detail lives in references/ and loads only when needed:
references/advanced-patterns.md— coordination, error handling, observability & system application patterns.
Anti-Patterns to Avoid
❌ God Agent
One agent that does everything - no specialization, no delegation.
❌ Agent Explosion
Too many tiny agents with overlapping responsibilities.
❌ Lost Context
Handoffs that don't preserve essential information.
❌ Infinite Loops
Agents that keep handing work back and forth.
❌ Silent Failures
Agents that fail without proper error reporting.
❌ Unobservable Execution
Can't see what agents are doing or why.
Good orchestration is invisible - the system should feel like one coherent intelligence, not a committee of bickering agents.