All lessons · 44
Multi-Agent Systems
When one agent is not enough: context isolation, specialization, parallel work, the orchestrator-worker pattern, and the pitfalls nobody warns you about.
Why split one agent into several?
Picture one very capable person doing an entire project alone: research the market, write the copy, check the numbers, design the slides. Possible — but slow, and by hour six they are holding so much in their head that details start slipping. A team of four specialists is faster, and each one stays sharp on their own piece. The price is coordination: someone has to hand out the work and stitch the results together.
Agents have the same problem. A single agent has one context window — the text it can see at once, its working memory — and one personality. That becomes a constraint in three situations:
- Context isolation. One agent researching twenty sources will fill its context window with noise. By the time it writes the report, the useful facts are diluted by ten thousand tokens of irrelevant search results. Each worker, by contrast, reads its own sources and hands back only what matters.
- Specialization. A prompt that makes an agent a rigorous code reviewer also makes it a worse web researcher. Splitting roles lets each agent get focused instructions and only the tools it needs — the same reason a team has a designer and an accountant instead of one generalist.
- Parallel work. Summarizing ten documents takes ten times as long as one document if a single agent does them sequentially. Independent subtasks can run at the same time, in separate contexts, the way four people can each read one chapter.
The catch, stated honestly: multi-agent systems multiply everything — including costs, latency, and the number of places where things can go wrong. More agents mean more coordination, not just more hands. Start with one agent; split when you feel the specific pain above.
The orchestrator-worker pattern
The most common structure is not a committee of chatting agents. It is a boss and a team — continuing the analogy, a project lead who never writes a line of copy themselves, but decides who does what and assembles the result:
- Orchestrator receives the goal, breaks it into subtasks, and decides who does what.
- Workers each get one focused subtask, do it in their own clean context with their own tools, and return a result.
- Orchestrator collects the results, notices gaps, delegates follow-ups if needed, and assembles the final answer.
The user asks for a market report on electric scooters in Europe.
Note what made this work: each worker returned a compact summary, not a raw transcript. The orchestrator’s context stays small; that is the whole point of the pattern.
How agents talk to each other
Under the hood there is no mystery: an agent handoff is just a tool call
that runs another agent loop. The orchestrator has a tool like
assign_task(worker="pricing", task="..."); your code spins up the worker,
runs its loop, and returns its final message as the tool result.
The design choices that matter:
- What passes between them. Usually a task description in and a final report out — not the full conversation. Passing whole transcripts between agents recreates the noise problem you were trying to escape.
- Who sees what. A worker gets the task plus only the files or data it needs. Minimal inputs mean fewer distractions and lower token costs.
- Who is in charge. In hierarchical setups the orchestrator decides and workers execute. In “pipeline” setups, agents hand results along a fixed chain — writer, then reviewer, then editor. Fixed pipelines are less flexible and far easier to debug.
Costs and pitfalls
- Error propagation. If a worker returns a wrong fact, the orchestrator usually cannot tell — it synthesizes confidently. A mistake at step two silently poisons step five. Mitigations: verification agents that check claims, structured output schemas, and asking workers to cite sources.
- Debugging is harder. One agent’s transcript was a story you could read. Ten agents produce a web of interleaved loops. Tracing from agent SDKs stops being optional — it is the only way to see what happened.
- Costs multiply. Every worker boots with its own context and its own model calls; the orchestrator re-reads everything. A task that costs one dollar as a single agent can cost five as a team of five.
- Coordination overhead. Agents can duplicate each other’s work, wait on each other, or disagree. Every message between them is spent on coordination instead of the task.
The honest rule
Add an agent only when you can name the pain it removes: a context window that overflows, a role conflict in the prompt, or subtasks that could run in parallel. If you cannot name the pain, one well-prompted agent with good tools is almost always cheaper, faster, and easier to debug.
Check yourself
Which of these is a real reason to split one agent into several?
What should a worker agent return to the orchestrator?
What is the biggest hidden cost of a multi-agent system?
Where to go from here
You can now design systems where several agents share work under an orchestrator — and you know when not to. If any of this felt abstract, the two earlier lessons are worth a second look: what an AI agent actually is and agent SDKs and frameworks, which is where the plumbing for this pattern usually comes from.