Orchestration and multi-agent
Building agents · topic building-agents/orchestration
When one agent is not enough, something has to coordinate several. This topic contrasts orchestration written as code with orchestration decided by a model, surveys sequential, hierarchical and collaborative arrangements, and names the coordination cost that every extra agent adds.
Concepts
- Code- vs model-driven orchestration
- Two ways to coordinate agents. In code-driven orchestration a program decides which agent runs when, passing outputs along fixed paths; it is predictable, testable and cheap. In model-driven orchestration a model decides, delegating to other agents as tools; it adapts to unforeseen cases and is harder to bound. Use code for known workflows and a model for the genuinely open parts. glossary
- Sequential / hierarchical / collaborative
- Three arrangements. Sequential: agents form a pipeline, each transforming the previous output. Hierarchical: a manager agent delegates subtasks to workers and integrates their results. Collaborative: peer agents share a workspace or conversation and negotiate. Complexity and unpredictability rise in that order; sequential is enough far more often than it seems. glossary
- Orchestration tax
- The cost every additional agent adds: more tokens for handoffs and repeated context, latency from extra calls, information lost at each boundary, new failure modes when agents disagree or wait on each other, and harder debugging. A multi-agent design has to beat a single well-equipped agent by more than this tax, and often it does not. glossary
Links
- Builds on: Design patterns
- Leads to: nothing yet
- Competencies drawing on it: Designs and orchestrates multi-agent systems
Lessons
- Orchestration in code or by a model (tutorial)
- What every extra agent costs (explanation)
Your reference
Each lesson above adds its takeaways and its example here once you finish it. Your reference lists every lesson you have finished.
Orchestration in code or by a model
Unlocks when you finish Orchestration in code or by a model.
Takeaways
- In orchestration by code, a program decides which agent runs when. It runs the same way every time and costs no model call to decide.
- In orchestration by a model, a manager decides and calls the other agents as tools. It can handle steps nobody planned, and the same input can take another path.
- A fact can be lost at each handoff. Add a second agent when it can do something the first can't.
- Sequential, hierarchical and collaborative arrangements get harder to coordinate in that order. Check the result at each boundary in code, and stop with a report when it is wrong.
Example
Predict the handoffs · open in the lesson
What are the two handoff messages? Predict the output, then run it.
python3 agent.py handoffsPrints the lines below (verified in CI from site/examples/building-agents/orchestrating-agents/handoffs.py)
lookup -> writer: 'order 1042, kettle, delivered 12 days ago, wants a replacement' writer -> checker: 'Dear customer, we are sorry that your kettle broke. A replacement for order 1042 is on its way.'
What every extra agent costs
Unlocks when you finish What every extra agent costs.
Takeaways
- The orchestration tax is what each extra agent adds: tokens for handoffs and repeated context, calls to wait for, information lost at each boundary, new ways to fail and harder debugging.
- A loop repeats its own context on every call, and each extra agent repeats the shared context again. A manager also re-reads its whole conversation on each of its calls.
- A short handoff saves tokens and can drop what a later step needs.
- Before you add an agent, name what one agent can't do, and try the fixes inside one context first: loading just in time, compaction, tool search and skills.
- Add an agent only when one agent is shown to fail at the task. Compare the design with the single agent on the same golden set, and read the items that differ before you decide.
Example
The tokens of one email · open in the lesson
Run this, and compare what you see with the output below.
python3 tax.py tokensPrints the lines below (verified in CI from site/examples/building-agents/orchestration-tax/tokens.py)
email g06, tokens per arrangement
calls new handoff repeat written total
single agent 2 218 0 162 70 450 1.0x
pipeline 4 237 44 300 65 646 1.4x
manager + workers 6 250 100 718 157 1225 2.7xSources
AEC-07Multi-agent systems: architectures, roles, the orchestration tax, Agent Engineer Course (course)AEC-18Orchestrators: code- versus model-driven, patterns, anti-patterns, Agent Engineer Course (course)Academy claude-platform-101Claude Platform 101, Claude Academy (course)Academy introduction-to-subagentsIntroduction to subagents, Claude Academy (course)