PHASE 11 · MULTI-AGENT
Goal: Decompose hard problems across specialized agents.
One agent with too many tools gets confused — it picks the wrong tool, drifts off-task on long jobs, blows the context window. Multi-agent means decomposing the problem across specialized agents that hand work to each other.
Anthropic's Building Effective AI Agents codifies 6 patterns: prompt chaining (sequential), routing (pick the right specialist), parallelization (fan-out), orchestrator-workers (a manager that delegates), evaluator-optimizer (one agent reviews another's work), and autonomous agents (long-running, goal-directed loops). Internalize these — they're the vocabulary for any multi-agent design.
Frameworks: LangGraph (graph-based, explicit state, the most flexible), Strands (lighter, AWS-aligned, easier to start), OpenAI Swarm (peer-to-peer handoff, minimal). Pick one. They all express the same patterns differently.
The honest caveat: multi-agent is overkill for most apps. A single well-prompted agent with good tools beats a 6-agent swarm 80% of the time. Reach for multi-agent when a single agent demonstrably fails — not because the architecture sounds cool.
swarm.py — A planner + researcher + SQL agent, coordinated by an orchestrator — with notes on what helped and what didn't.
Concepts unlocked: orchestration · handoffs · the 6 patterns · when multi-agent hurts
Your agent has come a long way: it answers from your docs (Phase 2), queries your database (Phase 5), and since Phase 10 you can even test its behavior. But keep piling tools onto that one agent and it starts to crack: with fifteen tools it picks the wrong one, on long jobs it drifts off-task, and it blows the context window trying to hold everything at once. A single brain can only juggle so much.
Restaurants solved this exact problem long ago. A tiny café has one cook who does everything — takes the order, grills, plates, washes up. It works until the dinner rush, when that one cook starts burning things. A busy kitchen runs differently: a head chef reads each incoming order and calls out the pieces; each station — grill, sauté, pastry — owns exactly one job with its own equipment; finished plates come back to the head chef, who assembles the dish. Crucially, nobody shouts across the kitchen at each other — everything flows through the head chef.
Multi-agent is that kitchen. You split the job across specialist agents — each with one narrow job and a small set of tools — coordinated by one agent that hands out work and combines the results.
What multi-agent is. Multi-agent breaks a hard problem into specialized agents that pass work between them — a kitchen brigade instead of one overwhelmed cook. Each agent has a narrow job and a small set of tools, so it stays focused.
So a team beats an overloaded generalist. But what does “hand work to each other” actually mean, mechanically? Is one agent messaging another? Sharing a chat room? Reading each other's minds?
Here's the satisfying part: you already know the mechanism. It's the Phase 4 tool call, and nothing more. In Phase 4, your harness — the code around the model — told the LLM “a calculator tool exists,” and when the model asked for it, your code ran it and fed the text result back. To call a whole agent, the orchestrator's harness does exactly the same thing: it lists the worker as a tool. When the orchestrator asks for it, the harness runs the worker's entire agent loop — its own prompt, its own tools, as many rounds as it needs — and feeds the worker's final answer back as an ordinary tool result.
You'll never write this yourself — your coding assistant will — but seeing it kills the mystery. To the orchestrator, a whole agent sits in the tool list right next to a calculator, and the model can't tell the difference:
# to the orchestrator, a whole agent is just one more tool
def ask_researcher(question):
return researcher_agent(question) # runs a FULL agent loop, returns its final text
TOOLS = [ask_researcher_def, calculator_def] # side by side — request in, text out, either wayAn agent is just a tool that thinks. To the caller, a worker agent looks like any other tool: a request goes in, text comes back. The only difference is what happens inside — a full agent loop instead of one function. Every multi-agent pattern you'll meet is built from this one move.
Once agents can call agents, the question becomes: how do you wire the kitchen? Anthropic's Building Effective AI Agents — the short guide most teams start from — names five ways to arrange a team. (Its sixth pattern is one you already know: the single autonomous agent, the one you built in Phase 4.) These five are the vocabulary for any multi-agent design:
Here's the pattern you'll build — orchestrator-workers — drawn as a kitchen: the head chef in the middle, stations around it.
Reading the arrows: solid arrows are work being handed out — the head chef passing tickets to stations. Dashed arrows are results reporting back. Every hand-out and every report-back is the same Phase 4 move from the last section: a tool call in, text back out.
Before you rush off to build a brigade, here's the part most tutorials skip: multi-agent is overkill for most apps. A single well-prompted agent with good tools beats a six-agent swarm about 80% of the time — and the swarm adds latency, cost, and a pile of new ways to fail. A food truck with a three-item menu does not need a head chef and five stations.
The signals that you genuinely need a team are specific:
When NOT to use a team. One agent with good tools beats a team you can't debug. Every handoff is a seam where information gets dropped or garbled — and a wrong answer can now be hiding inside any of five agents or in the seams between them. Remember Phase 6: you needed traces to see inside one agent. A team multiplies that — you need a trace for every agent plus every handoff, or debugging becomes guesswork. Don't go multi-agent because the diagram looks impressive; do it when a single agent demonstrably can't cope.
Time to run the kitchen yourself. You'll rebuild your Phase 4 agent — agent.py, the one that routes questions to your RAG, a web search, or a calculator — as an orchestrator-workers team: a planner, a RAG agent, and a SQL agent, coordinated by an orchestrator. Then, just as important, you'll write down honestly where the team helped and where it just added overhead.
Read what it builds — the head chef in code. The orchestrator plans, hands each step to the right station, and plates the result:
# swarm.py — an orchestrator delegating to specialist agents
def orchestrator(task):
plan = planner_agent(task) # read the ticket: break the task into steps
results = []
for step in plan:
if step.kind == "docs":
results.append(rag_agent(step)) # Phase 2 RAG, working one station
elif step.kind == "data":
results.append(sql_agent(step)) # Phase 5 SQL, working another
return writer_agent(task, results) # plate it: combine into a final answerDeliverable — swarm.py. A planner + researcher + SQL agent coordinated by an orchestrator — plus an honest note on what the team helped with and what it didn't. Knowing when not to use multi-agent is half the skill. Next, in the finale, you'll step back and put a name on all the machinery you've built around the model.