| name | agent-orchestrator |
| description | Design and implement multi-agent systems with proven coordination patterns. Use when building agent teams, delegation architectures, inter-agent communication, lead-agent orchestration, or agent swarm coordination. Covers 5 orchestration topologies (hub-and-spoke, pipeline, broadcast, hierarchical, mesh), delegation protocols, state sharing across agent boundaries, conflict resolution, and the plan-and-execute pattern. Based on patterns from Kimi Agent Swarm, Devin, BabyAGI, MetaGPT, Google A2A, and DyLAN architectures. |
Agent Orchestrator
Design multi-agent systems with proven coordination and delegation patterns.
Workflow
Design Workflow
- Identify the task domain and decompose into agent roles
- Select an orchestration topology from the topology guide
- Define inter-agent communication protocol
- Implement delegation rules and conflict resolution
- Add observability and fallback handling
Evaluation Workflow
- Map existing multi-agent system to topology patterns
- Check for single points of failure
- Verify delegation boundaries and escalation paths
- Score against the orchestration checklist
Orchestration Topologies
Five topologies for multi-agent coordination. Read the relevant reference for templates.
| # | Topology | When to Use | Reference |
|---|
| 1 | Hub-and-Spoke | Single coordinator delegates to specialists | references/01-hub-and-spoke.md |
| 2 | Pipeline | Sequential processing with handoff gates | references/02-pipeline.md |
| 3 | Broadcast | Parallel execution with result aggregation | references/03-broadcast.md |
| 4 | Hierarchical | Multi-level delegation with sub-coordinators | references/04-hierarchical.md |
| 5 | Mesh | Peer-to-peer collaboration with shared state | references/05-mesh.md |
Topology Selection Guide
Customer service system (triage → route → resolve):
→ Topology 1 (Hub-and-Spoke) with triage coordinator
Data processing pipeline (extract → transform → validate → load):
→ Topology 2 (Pipeline) with validation gates between stages
Code review system (multiple reviewers in parallel):
→ Topology 3 (Broadcast) with consensus aggregation
Enterprise workflow (departments with sub-teams):
→ Topology 4 (Hierarchical) with department-level coordinators
Collaborative research (agents share findings dynamically):
→ Topology 5 (Mesh) with shared knowledge graph
Agent Role Definition Template
When defining agent roles, specify:
<agent name="[NAME]" role="[ROLE]">
<capabilities>
- [Specific capability 1]
- [Specific capability 2]
</capabilities>
<boundaries>
- Cannot [limitation 1]
- Cannot [limitation 2]
</boundaries>
<inputs>[What this agent receives]</inputs>
<outputs>[What this agent produces]</outputs>
<escalation>[When and how to escalate to coordinator]</escalation>
</agent>
Inter-Agent Communication Protocol
Message Format
<agent_message>
<from>[sender_agent]</from>
<to>[receiver_agent]</to>
<type>[request|response|broadcast|escalation]</type>
<payload>[structured data]</payload>
<context>[relevant state for receiver]</context>
<priority>[low|normal|high|critical]</priority>
</agent_message>
Delegation Rules
- Coordinator MUST include task context in every delegation
- Worker agents MUST report completion status back to coordinator
- Failed tasks MUST include error details and partial results
- Escalation MUST happen when confidence drops below threshold
Conflict Resolution
When multiple agents produce conflicting outputs:
- Voting — majority wins (use for low-stakes decisions)
- Authority — designated expert agent decides (use for domain-specific conflicts)
- Escalation — human-in-the-loop resolves (use for high-stakes ambiguity)
- Synthesis — coordinator merges compatible parts (use when outputs are complementary)
Anti-Patterns
- God Agent — one agent does everything, others are stubs
- Chat Loop — agents endlessly request clarification from each other
- State Amnesia — agents lose context between interactions
- Over-delegation — breaking tasks too fine, coordination cost exceeds benefit
- Missing Fallback — no recovery path when a worker agent fails
Validation Scripts
Validate orchestration topology configs with automated scoring (0-10):
python3 scripts/validate_topology.py <config_file> [--strict]
Checks topology detection, agent count, required sections (roles, routing, communication, error handling), and flags anti-patterns (SPOF, deadlocks, shared mutable state).
