Module 8: Multi-Agent Orchestration
1. Introduction: from one agent to many
Overview
Module 7 solved a connectivity problem: your agent stopped having hardcoded tools and started discovering them dynamically from external MCP servers. With MCP, adding a new tool means deploying a server — without touching a single line of the agent's code. The Research Agent v4 connects to 3 MCP servers (filesystem, web search, papers), discovers 8+ tools over the protocol, and uses them inside its planning-research-reflection graph. It's an agent with a state machine, intelligent planning, persistent memory, and unlimited dynamic tools. But it's still one agent. A single graph that plans, searches, analyzes, reflects, synthesizes, and evaluates — all by itself. It's like having one brilliant employee who masters research, data analysis, technical writing, and quality control. Impressive. But in practice, that person does everything sequentially, mixes contexts, and when the task grows, they saturate.
This module is the most significant leap in the entire guide: going from an individual agent to a system of coordinated agents. Multi-agent systems solve the saturation problem with specialization. Instead of one agent that searches, analyzes, and writes — you have a Researcher that only searches, an Analyst that only analyzes, a Writer that only synthesizes, and a Supervisor that coordinates the three. Each agent has its own StateGraph optimized for its task, its own set of tools (possibly via MCP), and its own reduced context. The Researcher doesn't need to know how a report gets written. The Writer doesn't need to know how sources get evaluated. Each one does what it does best, and the Supervisor makes sure the combined result is coherent. This isn't an abstract idea — it's a design pattern with concrete implementations in LangGraph that you'll build capsule by capsule.
But multi-agent isn't free. More agents means more LLM calls, more latency, more cost, and more complexity in debugging. A single agent with a bug has one point of failure. Four coordinated agents have points of failure in each agent and in the coordination between them. That's why this module doesn't start with "how to implement multi-agent" but with "when do you need it?" The decision framework is the first tool you'll learn, before writing a single line of code. Then come the 4 fundamental patterns — Supervisor, Handoffs, Subagents, Router — each with clear trade-offs of control, autonomy, latency, and complexity. By the end, you'll have a design vocabulary for multi-agent systems and the hands-on experience of having built a real one: the Research Agent v5 with 4 specialized agents.
Where are we in the guide?
Context
This guide has 10 modules organized into 3 phases:
Phase 1: Agent Foundations (Modules 1-3) ✓ COMPLETED
├── Module 01: Anatomy of an AI Agent ✓ COMPLETED
├── Module 02: Tool Use Fundamentals ✓ COMPLETED
└── Module 03: Function Calling Patterns ✓ COMPLETED
Phase 2: Agent Architecture (Modules 4-6) ✓ COMPLETED
├── Module 04: State Machines for Agents ✓ COMPLETED
├── Module 05: Multi-Step Reasoning and Planning ✓ COMPLETED
└── Module 06: Memory Systems for Agents ✓ COMPLETED
Phase 3: Advanced Integration & Production (Modules 7-10) ← YOU ARE HERE
├── Module 07: MCP and Advanced Tool Integration ✓ COMPLETED
├── Module 08: Multi-Agent Orchestration ← THIS MODULE
├── Module 09: Testing and Evaluating Agents
└── Module 10: Agents in Production and Alternatives
Second module of Phase 3 — the leap from one complete individual agent to a team of specialized agents. Phases 1 and 2 built an agent with every internal capability: tool use (M2-M3), flow control (M4), deliberative intelligence (M5), and persistent memory (M6). Phase 3 takes that agent into the real world: external tools at scale (M7), multi-agent coordination (M8), formal testing (M9), and production deployment (M10).
The progression of Phase 3 is deliberate — each module opens a door the previous one made possible:
- Module 7 — How it connects to the world → MCP servers, clients, dynamic tools, ecosystem ✓
- Module 8 — How it works as a team → Supervisor, handoffs, subagents, shared state ← HERE
- Module 9 — How you know it works → Golden datasets, trajectory evaluation, regression testing
- Module 10 — How you ship it to production → Deployment, observability, cost, alternatives
Where are you coming from?
Module 7 left you with a Research Agent v4 that discovers tools dynamically:
- MCP servers as the source of tools: 3 servers (filesystem, web search, papers DB) expose 8+ tools the agent discovers over the protocol — no direct import, no hardcoding
- Dynamic tool loading:
langchain-mcp-adaptersturns MCP tools into LangChain tools inside the StateGraph. Adding a tool = adding an entry on the server, not modifying the agent - Server ecosystem: You plug in community servers (GitHub, Slack, PostgreSQL) in minutes, taking advantage of existing work
- Production-ready: Auth, rate limiting, monitoring, deployment with Docker — MCP that works beyond your laptop
That's an individually complete agent. It plans (M5), reflects (M5), remembers (M6), discovers tools (M7). But when you look at how it works, you see this:
START → planning_v2 → research → analysis → reflection → [quality ok?]
│
┌────────────┼──────────┐
"re-plan" "refine" "deliver"
│ │ │
↓ ↓ ▼
planning_v2 refinement synthesis → ENDOne graph. One agent. The research node searches for information, the analysis node processes it, the synthesis node writes it up. Each node is a function inside the same StateGraph, sharing the same state, the same context window, the same conversation. When the task is "research the latest advances in quantum computing and write a 3,000-word report with comparative analysis" — that agent loads into its context window the raw sources, the intermediate analysis, the partial drafts, the reflection notes, and the final report. All together. All mixed up.
Where are you headed?
The transition from M7 to M8 is the leap from "one agent with unlimited capabilities" to "a team of specialized agents that coordinate." M7 solved the tool bottleneck — the agent can connect to any service. M8 solves the capacity bottleneck — instead of one agent that does everything, you have specialized agents that each do their thing better.
After M8, Module 9 takes the multi-agent system and puts it through formal testing. The transition is direct: with 4 coordinated agents, a bug can be in any individual agent or in the coordination between them. Manual debugging is impossible — you need systematic evaluation: is each agent doing its job? Is the supervisor assigning correctly? Do the handoffs preserve the necessary context? And M10 deploys it all to production with per-agent observability.
When do you need multi-agent?
The question before the code
Not every system needs multiple agents. A well-designed individual agent with planning, reflection, memory, and MCP tools solves most use cases. Multi-agent adds value only when the problem has specific characteristics a single agent can't handle efficiently. Before you think about patterns and coordination, you need a decision framework.
Signs that you DO need multi-agent
1. Clearly separable sub-tasks with different expertise.
If the task has components that require distinct skills — finding information vs analyzing it vs writing it up — each sub-task benefits from an agent with its own optimized system prompt, its own set of tools, and its own reduced context. A Researcher agent with a search prompt and web search tools is more precise than a generalist agent that also has writing and analysis tools polluting its tool selection.
2. Context window insufficient for the whole process.
When the task generates so much intermediate information that a single agent saturates its context window — raw sources + analysis + drafts + reflections — splitting the work lets each agent operate with a clean context. The Researcher only sees its sources. The Analyst only sees the relevant data. The Writer only sees the processed analysis.
3. Real parallelization.
If there are independent sub-tasks that can run simultaneously — search the web AND search the papers DB at the same time — multiple agents enable real parallel execution. A single agent runs everything sequentially, even if the tasks don't depend on each other.
4. Different stakeholders or teams.
If different teams maintain different parts of the system — the NLP team maintains the analysis agent, the infrastructure team maintains the filesystem agent — multi-agent enables organizational separation of concerns, not just technical.
Signs that you DON'T need multi-agent
1. The task is linear.
If the flow is always A → B → C with no branching or parallelism, a pipeline inside a single agent is simpler, cheaper, and easier to debug. Don't disguise a pipeline as multi-agent.
2. The data volume is manageable.
If a modern model's context window (128K+ tokens) is enough for the whole task, the complexity of coordinating agents isn't justified. An agent with good conversation management (M6) handles far more than you'd think.
3. There's no differentiated expertise.
If all the agents would use the same system prompt, the same tools, and the same approach — you don't have real specialization. You have copies of the same agent. Multi-agent without specialization is pure overhead.
4. Cost matters more than quality.
Multi-agent multiplies LLM calls. If the quality difference between one agent and four doesn't justify the extra cost for your use case, stick with one.
The decision framework
Does your task have sub-tasks with clearly different expertise?
├── NO → A single agent. Optimize with planning and reflection (M5).
└── YES → Can the sub-tasks run in parallel?
├── NO → Does the context window saturate with all the info?
│ ├── NO → A single agent is probably enough.
│ └── YES → Multi-agent with Handoffs or Subagents.
└── YES → Multi-agent with Supervisor or Router.
Do you need centralized coordination?
├── YES → Supervisor pattern.
└── NO → Router pattern or peer-to-peer Handoffs.
This framework isn't dogma — it's a starting point. As you move through the module you'll refine your intuition about when each pattern applies. But the golden rule is: start with one agent. Scale to multi-agent only when you have evidence that one agent isn't enough.
The 4 patterns
The design vocabulary
Multi-agent isn't "create several agents and let them talk." There are established coordination patterns, each with specific trade-offs. This module covers four fundamental patterns that, alone or combined, solve most use cases:
1. Supervisor
A central coordinating agent that assigns tasks to specialized workers, monitors progress, and aggregates results.
┌───────────────┐
│ SUPERVISOR │
│ (coordinates) │
└───────┬───────┘
│
┌────────────┼────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│Researcher│ │ Analyst │ │ Writer │
└──────────┘ └──────────┘ └──────────┘
When to use it: When you need centralized control over which agent works, when, and in what order. The supervisor makes every routing decision and can re-assign tasks if a worker fails.
Trade-off: High control, but the supervisor is a single point of failure. If the supervisor makes bad routing decisions, the whole system suffers.
2. Handoffs
Direct peer-to-peer transfer of control between agents. An agent decides when it has finished its part and hands off to the next one, passing along the relevant context.
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Researcher │────▶│ Analyst │────▶│ Writer │
│ (searches) │ │ (analyzes) │ │ (writes) │
└──────────────┘ └──────────────┘ └──────────────┘
When to use it: When the flow is relatively predictable and each agent knows when its work is complete. The agents coordinate among themselves with no middleman.
Trade-off: Less overhead than a supervisor, but each agent needs logic for "am I done?" and "who do I hand control to?" Coordination is distributed, which makes debugging harder.
3. Subagents
A main agent delegates tasks to sub-agents with an isolated context. The sub-agent runs, returns a result, and the main agent continues. The sub-agent has no access to the main agent's full state.
┌───────────────────────────────────┐
│ MAIN AGENT │
│ │
│ "I need to analyze this data" │
│ │ │
│ ▼ │
│ ┌─────────────┐ │
│ │ Sub-agent │ (isolated │
│ │ Analyst │ context) │
│ └──────┬──────┘ │
│ │ result │
│ ▼ │
│ "Ok, I continue the analysis" │
└───────────────────────────────────┘
When to use it: When you want to delegate a specific subtask without polluting the main agent's context window. The sub-agent receives only what it needs and returns only the result.
Trade-off: Excellent for avoiding context bloat, but the sub-agent can't ask for clarification or reach into the main agent's extra context if it needs it. Communication is one-way: task → result.
4. Router
A classifier agent that analyzes the input and directs it to the right specialized agent. It doesn't execute the task — it only decides who executes it.
┌──────────────┐
input ────▶│ ROUTER │
│ (classifies) │
└──────┬───────┘
│
┌────────────┼────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Agent A │ │ Agent B │ │ Agent C │
│ (code) │ │ (data) │ │ (text) │
└──────────┘ └──────────┘ └──────────┘
When to use it: When you receive inputs of different types that require fundamentally different processing. The router can be deterministic (rules) or LLM-based (semantic classification).
Trade-off: Simple and efficient for classification, but there's no coordination between the destination agents. Each agent works independently — if the task requires collaboration, you need to combine Router with another pattern.
Patterns in combination
In practice, multi-agent systems combine patterns. A Router that classifies and directs to a Supervisor that coordinates Subagents. A Supervisor that uses Handoffs between workers. Capsules 02-05 teach you each pattern in isolation. Capsule 07 teaches you to compose them. The final project integrates them into a real system.
The cost of coordination
More agents ≠ better
Multi-agent has a real cost you need to quantify before adopting it. It's not a vague cost of "more complexity" — these are concrete numbers that hit your budget and the user's experience.
LLM calls multiply
An individual agent processing a research query makes roughly:
1 call: planning
1 call: research (tool selection + execution)
1 call: analysis
1 call: reflection
1 call: synthesis
─────────────────
~5 LLM calls total
The same flow with 4 specialized agents:
Supervisor:
1 call: decompose task
1 call: assign to researcher
1 call: assign to analyst
1 call: assign to writer
1 call: validate final result
Researcher:
1 call: search planning
1 call: execute search
1 call: evaluate results
Analyst:
1 call: receive data
1 call: analyze
1 call: format findings
Writer:
1 call: receive analysis
1 call: write
1 call: review
─────────────────
~14 LLM calls total
From 5 to 14 calls. Almost 3x. And that's a simple flow with no re-routing, no retries, no per-agent reflection loops. In a complex flow with supervisor re-assignments, you easily reach 25-30 calls.
Latency piles up
Each LLM call takes between 1-5 seconds depending on the model and the context size. With parallel execution you can mitigate part of the latency, but the supervisor's coordination is inherently sequential: it can't assign the task to the analyst until the researcher finishes.
Single agent: ████████████████████ (~10s total)
Multi-agent: Supervisor ████
Researcher ████████
Analyst ██████
Writer ████████
Supervisor (validate) ████
(~25s total)
When the cost is worth it
The cost of multi-agent is justified when the gain in quality offsets the extra cost:
| Scenario | Single agent | Multi-agent | Worth it? |
|---|---|---|---|
| Simple query: "What is quantum computing?" | 5 calls, good quality | 14 calls, same quality | No. Overhead with no benefit |
| Complex research report with 10+ sources | 8 calls, medium quality (saturated context) | 20 calls, high quality (clean contexts) | Yes. Specialization improves quality |
| Multi-domain analysis (technical + financial + legal) | 6 calls, diluted expertise | 18 calls, expertise per domain | Yes. Different system prompts per domain |
| Linear pipeline with no branching | 5 calls, enough | 12 calls, pure overhead | No. A pipeline doesn't need coordination |
The practical rule: if a single agent produces an acceptable result, don't add more agents. Add agents when the quality of the result improves enough to justify 2-3x the cost.
Debugging gets harder
With one agent, a bug lives in one place. With four coordinated agents, the bug can be in:
- The individual agent (its logic, its tools, its prompt)
- The coordination (the supervisor assigned the task badly)
- The communication (the handoff lost critical context)
- The shared state (one agent overwrote another's data)
- The aggregation (the partial results didn't combine well)
That's why M9 (Testing) comes immediately after M8. It's not a coincidence — it's a necessity.
Prerequisites
From Module 7 (MCP and Advanced Tool Integration)
This module assumes you have the Research Agent v4 from M7. You need to be solid on:
- MCP servers and clients: You know how to create servers with the official SDK, expose tools with schemas, and build clients that discover them dynamically
- langchain-mcp-adapters: You integrate MCP tools into your StateGraph as LangChain tools. The agent uses
mcp_client.get_tools()instead of hardcoded tools - Multi-server setup: Your agent connects to multiple MCP servers simultaneously with tool namespacing to avoid collisions
- Basic MCP production: Auth, monitoring, and deployment with Docker — the MCP servers you use in multi-agent need to be operational
From Module 6 (Memory Systems for Agents)
Memory is especially relevant in multi-agent because each agent can have independent memory, and the supervisor needs state tracking:
- Durable checkpointing: Each agent can have its own checkpointer. You know how to use
thread_idand you understand how state persistence works - Cross-session long-term memory: InMemoryStore/BaseStore with namespaces — in multi-agent, each agent can have its own memory namespace
- Conversation management: Trimming and summarization for context windows — critical when each agent has its own history
From Module 5 (Multi-Step Reasoning and Planning)
The supervisor uses planning to decompose tasks. The workers use reflection to validate their partial results:
- Intelligent planning: Decomposing tasks into sub-tasks with dependencies — the supervisor does this to assign work to workers
- Reflection with quality gates: Output evaluation with critique — each worker can have its own quality gate
- Reasoning traces: The thought process captured as data — essential for debugging the supervisor's decisions
From Module 4 (State Machines for Agents)
The foundation of the whole module — each agent is a StateGraph:
- StateGraph for agents: Functional nodes, explicit edges, controlled cycles — each worker is an independent graph
- Extensible typed state:
AgentStatewith fields that extend without breaking the existing ones - Conditional routing: Deterministic decision points — the supervisor uses conditional routing to assign tasks
- Modular subgraphs: Encapsulated capabilities — in M8, each worker is a subgraph of the system
From Phase 1 (Modules 1-3)
- Cognitive architecture (M1): Perceive-reason-act — each agent in the system follows this cycle independently
- Tool use (M2):
@toolwith Pydantic schemas — the workers have their own specialized tools - Function calling patterns (M3): Parallel calls, routing — patterns that apply both inside each agent and between agents
Tools for this module
- Python 3.11+
langchainv1.2+ andlangchain-openailanggraphv1.0+- OpenAI API key (GPT-4.1 or GPT-4.1-mini)
tavily-pythonfor web searchpython-dotenvfor environment variablesmcp, the official MCP SDKlangchain-mcp-adaptersfor LangGraph-MCP integration
pip install langchain langchain-openai langgraph tavily-python python-dotenv mcp langchain-mcp-adaptersNo new dependencies. Multi-agent orchestration is implemented with the same tools from M7. LangGraph natively handles multiple graphs, subgraphs, and communication between agents. You don't need an extra framework — everything is built with StateGraph, nodes, and edges.
Module 8 objectives
By the end of this module you'll be able to:
- ✅ Decide when multi-agent is necessary: Apply the decision framework to evaluate whether your use case benefits from multiple agents or whether one well-designed agent is enough. Be able to articulate the trade-off of quality vs cost vs complexity for each situation
- ✅ Implement the Supervisor pattern: Build a coordinating agent that decomposes tasks, assigns them to specialized workers, monitors progress, re-assigns on failure, and aggregates partial results into a coherent output
- ✅ Implement the Handoffs pattern: Create direct peer-to-peer transfers of control between agents, with explicit state transfer, handoff conditions, and preservation of the necessary context without polluting the receiver's context window
- ✅ Implement the Subagents pattern: Delegate sub-tasks to agents with isolated context that run and return results, preventing context bloat in the main agent. Know how much context to pass and how much to isolate
- ✅ Implement the Router pattern: Classify inputs and direct them to the right specialized agent, both with deterministic routing (rules) and LLM-based routing (semantic classification). Know when to use each approach
- ✅ Design communication between agents: Choose between shared state (everyone sees everything) and isolated state (each one sees its own), implement message passing, and manage the trade-offs of each approach. Design hybrid approaches for real cases
- ✅ Compose patterns and handle failure modes: Combine Supervisor + Subagents, Router + Handoffs, and hybrid patterns. Handle agents that fail, infinite supervisor loops, contradictory results between agents, and timeouts
- ✅ Build the Research Agent v5 with 4 agents: Expand the Research Agent into a system with Supervisor, Researcher, Analyst, and Writer — each with its own StateGraph, tools, and optimized context. The complete system works end-to-end
Module map
| # | Capsule | What you'll learn |
|---|---|---|
| 02 | Supervisor Pattern | Implement a central coordinating agent. The supervisor receives the task, decomposes it into sub-tasks, assigns each one to a specialized worker, monitors progress, and aggregates the results. Handling re-assignment when a worker fails or produces an insufficient result |
| 03 | Handoffs Pattern | Direct transfer of control between agents. State transfer: what context passes and what gets dropped. Handoff conditions: when an agent decides it's done. Bidirectional handoffs for iterative flows. Preserving context without polluting the context window |
| 04 | Subagents Pattern | Delegation to sub-agents with isolated context. The main agent sends a specific task, the sub-agent runs with its own clean context window, and returns only the result. Preventing context bloat. How much context to pass vs how much to isolate |
| 05 | Router Pattern | Classify the input and direct it to the right agent. Deterministic router with explicit rules vs LLM-based router with semantic classification. Fallback handling: what happens when no agent applies. Multi-level routing for complex inputs |
| 06 | Shared vs Isolated State | The most important design decision: do the agents share state or does each one have its own? Shared state: simple but causes context bloat. Isolated state: clean but makes coordination harder. Hybrid approaches for the real world |
| 07 | Advanced Orchestration | Composing patterns: Router → Supervisor → Subagents. Parallel execution of independent workers. Consensus between agents with contradictory results. Failure handling: timeouts, retries, fallback agents. Hierarchical agents (supervisor of supervisors) |
| 08 | Project: Multi-Agent System | Research Agent v5: 4 specialized agents — Supervisor (coordinates), Researcher (searches with MCP), Analyst (analyzes data), Writer (synthesizes reports). The supervisor decomposes the query, assigns agents, validates results, and delivers the final report |
Learning flow
The module follows a progression of individual patterns → communication design → advanced composition → complete system.
You start with the Supervisor Pattern (capsule 02) because it's the most intuitive pattern and the most used. One agent that coordinates others — clear concept, concrete implementation. By the end you have a working supervisor with 2 workers that coordinate to solve a task.
Then the Handoffs Pattern (capsule 03) shows you the decentralized alternative. Instead of a central coordinator, the agents pass control among themselves. The contrast with Supervisor is immediate: less overhead, less control. You see the same use case solved with both patterns and you compare trade-offs.
The Subagents Pattern (capsule 04) introduces context isolation. A main agent delegates without exposing its whole state. It's especially relevant when the context window saturates — the sub-agent works clean and returns only what's needed.
With the Router Pattern (capsule 05) you learn classification before execution. The router doesn't work — it directs. You implement deterministic and LLM-based routing, and you see when each approach makes sense.
Capsule 06 (Shared vs Isolated State) tackles the most important design decision in any multi-agent system. It's not one more pattern — it's the substrate all the patterns operate on. Shared state, isolated state, and hybrid approaches with their trade-offs.
Advanced Orchestration (capsule 07) composes everything. Combined patterns, parallel execution, consensus, conflict resolution, failure handling. This is where the real complexity of multi-agent shows up — and where you learn to handle it.
Finally, the project (capsule 08) integrates everything into the Research Agent v5: a system of 4 specialized agents that work together to solve complex research queries. It's the culmination of 7 modules of incremental building.
Connection with the evolving project
Research Agent v4 (M7) → Research Agent v5 (M8)
The Research Agent from M7 has its whole individual architecture solved:
┌─────────────────────────────┐
│ CHECKPOINTER │
│ (MemorySaver / PostgreSQL) │
└──────────┬──────────────────┘
│
START → planning_v2 → research → analysis → reflection → [quality ok?]
│ ▲ │
│ │ ┌─────────────┼──────────┐
│ │ "re-plan" "refine" "deliver"
│ │ │ │ │
│ └────────────────────────────────────┘ │ ▼
│ ▼ synthesis → END
│ refinement
│ │
└──── LONG-TERM MEMORY + MCP TOOLS ──────────────────────────┘
ONE SINGLE AGENT with:
- Intelligent planning (M5)
- Reflection + quality gates (M5)
- Checkpointing + long-term memory (M6)
- 3 MCP servers with 8+ dynamic tools (M7)
M8 transforms this individual agent into a system of 4 specialized agents:
┌─────────────────────┐
│ SUPERVISOR │
│ - Decomposes task │
│ - Assigns workers │
│ - Validates result │
└──────────┬──────────┘
│
┌────────────────────┼─────────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ RESEARCHER │ │ ANALYST │ │ WRITER │
│ │ │ │ │ │
│ Tools (MCP): │ │ Tools: │ │ Tools (MCP): │
│ - web_search │ │ - calculate │ │ - file_write │
│ - paper_search │ │ - data_process │ │ - format_report │
│ - news_search │ │ - compare │ │ - cite_sources │
│ │ │ │ │ │
│ Expertise: │ │ Expertise: │ │ Expertise: │
│ Find │ │ Evaluate data, │ │ Write │
│ relevant │ │ identify │ │ coherent │
│ sources │ │ patterns │ │ reports │
└─────────────────┘ └─────────────────┘ └─────────────────┘
What changes concretely
1. From one graph to four coordinated graphs
Before (M7) — a single StateGraph:
builder = StateGraph(AgentState)
builder.add_node("planning", planning_node)
builder.add_node("research", research_node)
builder.add_node("analysis", analysis_node)
builder.add_node("reflection", reflection_node)
builder.add_node("synthesis", synthesis_node)
# One graph, one agent, everything together
graph = builder.compile(checkpointer=checkpointer, store=store)After (M8) — a supervisor that coordinates workers:
researcher_graph = create_researcher_agent()
analyst_graph = create_analyst_agent()
writer_graph = create_writer_agent()
supervisor_builder = StateGraph(SupervisorState)
supervisor_builder.add_node("plan", decompose_task)
supervisor_builder.add_node("researcher", researcher_graph)
supervisor_builder.add_node("analyst", analyst_graph)
supervisor_builder.add_node("writer", writer_graph)
supervisor_builder.add_node("validate", validate_results)
supervisor_builder.add_conditional_edges("plan", assign_worker)
system = supervisor_builder.compile(checkpointer=checkpointer)Each worker is an independent graph — with its own state, its own set of tools, and its own context. The supervisor coordinates them as subgraphs inside the main graph.
2. Each agent has its own expertise
RESEARCHER_PROMPT = """You are a specialized research agent.
Your ONLY task is to find relevant, reliable sources.
Do not analyze the data. Do not write reports. Just search and report sources."""
ANALYST_PROMPT = """You are a specialized analysis agent.
Your ONLY task is to evaluate data, identify patterns, and extract findings.
Do not search for information. Do not write. Just analyze what you receive."""
WRITER_PROMPT = """You are a specialized writing agent.
Your ONLY task is to synthesize findings into a coherent, well-structured report.
Do not search for information. Do not analyze. Just write with what you receive."""Each system prompt is focused. An agent with a 50-word prompt produces a better result in its domain than a generalist agent with a 500-word prompt that mixes search, analysis, and writing instructions.
3. The MCP tools get distributed across agents
In M7, one agent had access to 8+ tools from 3 MCP servers. In M8, each agent receives only the tools it needs:
| Agent | MCP Server(s) | Tools |
|---|---|---|
| Supervisor | None | Runs no tools — it coordinates |
| Researcher | Web Search, Papers DB | web_search, news_search, paper_search, related_papers |
| Analyst | None (local tools) | calculate, data_process, compare |
| Writer | Filesystem | file_write, file_read, format_report |
This solves the tool selection problem M7 mentioned: with 8 tools in one agent, selection accuracy drops. With 3-4 tools per specialized agent, accuracy stays high (~95%).
4. State is designed for coordination
class SupervisorState(TypedDict):
task: str
sub_tasks: list[dict]
assignments: dict # {sub_task_id: agent_name}
agent_results: dict # {agent_name: result}
iteration: int
final_report: Optional[str]
status: str # "planning" | "executing" | "validating" | "complete"
class ResearcherState(TypedDict):
query: str
sources_found: list[dict]
search_iterations: int
confidence: float
class AnalystState(TypedDict):
data: list[dict]
findings: list[dict]
patterns: list[str]
class WriterState(TypedDict):
findings: list[dict]
draft: Optional[str]
revision_notes: list[str]Each agent has its own typed state, optimized for its task. The SupervisorState tracks coordination. The worker states are lightweight and focused. There's no shared mega-state — each agent sees only what it needs.
5. The complete evolution of the Research Agent
v1 (M4): Basic state machine
→ planning → research → synthesis → END
Tools: [web_search]
v2 (M5): + Intelligent planning + Reflection
→ planning_v2 → research → analysis → reflection → [quality gate]
Tools: [web_search, calculate]
v3 (M6): + Memory (checkpointing + long-term)
→ Same graph + checkpointer + memory store
Tools: [web_search, calculate] (hardcoded)
v4 (M7): + MCP dynamic tools
→ Same graph + MCP clients
Tools: [8+ tools from 3 MCP servers] (dynamic)
v5 (M8): → A SYSTEM of 4 agents
Supervisor → Researcher + Analyst + Writer
Each agent with its own graph, tools, and context
Each version adds a capability without breaking the existing ones. v5 is the biggest leap: from one complete agent to a system of coordinated agents.
What this module does NOT cover
- ❌ Tool use fundamentals —
@tool, Pydantic schemas, and the tool execution loop are not re-taught. That's M2. The workers in this module use tools, but the design principles are still M2's - ❌ Function calling patterns — Parallel calls, routing, and retry are not re-taught. That's M3. Those patterns apply inside each worker and between workers — but the mechanics are the same
- ❌ State machines from scratch — StateGraph, nodes, and edges are not re-taught. That's M4. Every worker and the supervisor use StateGraph, but we assume you know how to build them
- ❌ Planning or reflection from scratch — Intelligent planning and quality gates are not re-taught. That's M5. The supervisor uses planning to decompose tasks, and the workers use reflection to validate — but you already have the base implementation
- ❌ Memory from scratch — Checkpointing and long-term memory are not re-taught. That's M6. The multi-agent system can use per-agent checkpointing — but you already know the mechanics
- ❌ MCP from scratch — How to create servers and clients is not re-taught. That's M7. The workers connect to MCP servers, but we assume you know how to configure them
- ❌ Multi-agent with non-LangGraph frameworks — There are alternatives (CrewAI, AutoGen, etc.) that implement multi-agent with different abstractions. This module uses LangGraph exclusively, consistent with the guide's stack. M10 mentions alternatives
- ❌ Systems with 10+ agents and governance — Enterprise-grade multi-agent with governance layers, permission models, audit trails, and cross-cloud orchestration is advanced production territory. M10 touches the principles, but the full implementation is out of scope
- ❌ Autonomous agents that create other agents — Self-replicating agents, dynamic agent spawning, and meta-agents that design other agents are active research topics, not production ones. This module covers established, proven patterns
The boundary is clear: M8 = how an agent becomes a team of agents that coordinate. M4 = how you build an agent. M5 = how it thinks. M6 = how it remembers. M7 = how it accesses tools.
Evidence of success
By the end of this module, you'll know you succeeded if:
- ✅ You can evaluate a use case with the decision framework and argue whether it needs multi-agent or whether one agent is enough — and your argument includes trade-offs of quality, cost, and complexity
- ✅ You can implement a Supervisor that decomposes a task into sub-tasks, assigns them to workers, monitors progress, re-assigns if a worker fails, and aggregates results into a coherent output
- ✅ You can implement Handoffs between agents with explicit state transfer — the receiving agent has exactly the context it needs, no more and no less
- ✅ You can implement Subagents with isolated context — the sub-agent doesn't pollute the main agent's context window, and the result flows back cleanly
- ✅ You can implement a Router that classifies inputs and directs them to the right agent, both with deterministic rules and with LLM-based classification
- ✅ You can design the state model of a multi-agent system: what gets shared, what gets isolated, how information flows between agents, and how results get aggregated
- ✅ Your Research Agent v5 works end-to-end: the Supervisor receives a query, decomposes it, the Researcher searches, the Analyst analyzes, the Writer writes, and the Supervisor validates — 4 coordinated agents producing a better result than one agent alone
Quick self-assessment
Ask yourself these questions after completing the module:
- "If someone asks me to design a multi-agent system, can I name the 4 patterns and explain when to use each one?" → If yes, you have the design vocabulary
- "If a worker fails mid-execution, does my supervisor handle the error and re-assign, or does everything crash?" → If it handles the error, your orchestration is production-ready
- "Can I explain to a colleague why my system has 4 agents instead of 1, with concrete numbers on quality and cost?" → If yes, you understand the why, not just the how
- "If I add a fifth agent (e.g. a Fact-Checker), does my architecture absorb it without rewriting everything?" → If yes, your design is extensible
If you answered yes to all four → you're ready for Module 9 (Testing and Evaluating Agents). If you answered no to any of them → reinforce the corresponding capsule before moving on.
Summary
- From one agent to a team: M4-M7 built an individually complete agent — state machine, planning, memory, MCP tools. M8 transforms it into a system of specialized agents that coordinate to solve complex tasks
- Specialization produces quality: A Researcher that only searches is more precise than a generalist agent. A Writer that only writes produces better reports. Focused system prompts + fewer tools = better performance per agent
- 4 fundamental patterns: Supervisor (central coordination), Handoffs (peer-to-peer transfer), Subagents (isolated delegation), Router (classification + direction). Each with clear trade-offs. In practice they get combined
- Multi-agent isn't free: 3x more LLM calls, accumulated latency, distributed debugging. The value comes when specialization produces quality a single agent can't reach. Use the decision framework before adding agents
- Shared vs isolated state: The most important design decision. Shared state is simple but causes context bloat. Isolated state is clean but makes coordination harder. Hybrid approaches for the real world
- Composition over isolation: Real patterns combine Supervisor + Subagents, Router + Handoffs, and hybrid variants. Capsule 07 teaches composition — where the real complexity of multi-agent shows up
- Research Agent v5: 4 agents — Supervisor coordinates, Researcher searches (MCP: web + papers), Analyst analyzes, Writer synthesizes (MCP: filesystem). Each with its own StateGraph, tools, and context. The result is a system, not an agent
- Testing is the next step: With 4 coordinated agents, manual debugging is impossible. M9 (Testing and Evaluation) comes immediately after to tackle systematic evaluation of multi-agent systems
Resources
- LangGraph Multi-Agent Tutorial — Official LangGraph tutorial for multi-agent systems. Supervisor, handoffs, and subgraphs with step-by-step implementation
- LangGraph Multi-Agent Concepts — LangGraph's conceptual documentation on multi-agent: patterns, state management, and communication between agents
- Building Effective Agents — Anthropic — Anthropic's perspective on agent orchestration. Coordination patterns, delegation, and failure handling
- Multi-Agent Systems Blog — LangChain — Analysis of multi-agent patterns in production: when to use each pattern, trade-offs, and lessons learned
- OpenAI: Orchestrating Agents — OpenAI's guide to multi-step agents and coordination. Complements the LangGraph perspective with OpenAI's approach
- AutoGen: Multi-Agent Conversation Framework — Microsoft's framework for multi-agent. A useful reference for comparing approaches different from LangGraph's