Building Multi Agent Systems
Introduction: Building Agent Teams
In the previous lessons, you learned how to build powerful single agents by managing state, connecting external MCP servers, and creating custom tools. These techniques allow you to create agents that can handle complex tasks with specialized capabilities. However, some problems are so multifaceted that even a well-equipped single agent struggles to handle them optimally. Just as software development teams divide work among specialists — backend engineers, frontend developers, and database administrators — your agent systems can benefit from the same division of labor.
In this lesson, you'll learn how to design multi-agent systems in which specialized agents coordinate to solve complex problems. You'll discover how to define sub-agents with specific roles, configure a main orchestrator agent that delegates work, and observe how these agents communicate through the SDK's internal Agent tool. By the end of this lesson, you'll understand how to build agent hierarchies that leverage each specialist's unique strengths, creating systems that are more capable than any single agent could be.
The Sub-Agent Concept
A sub-agent is a specialized agent designed to excel at a specific type of task. Rather than creating one generalist agent that tries to do everything, you create multiple focused agents, each optimized for its particular domain. The main agent, often called an orchestrator, coordinates these specialists by delegating appropriate tasks to each one.
Consider a code review workflow. A single agent could analyze code, fix bugs, and write documentation, but this approach has limitations. The agent might use an expensive model like Sonnet for all tasks, even simple documentation that could be handled by the faster, cheaper Haiku model. It might also struggle to maintain focus, mixing analysis concerns with implementation details. A multi-agent approach solves these problems by creating three specialists: an analyzer that uses Sonnet with Read and Grep tools to deeply understand code structure, a fixer that uses Sonnet with Read and Write tools to implement high-quality corrections, and a documenter that uses Haiku with Read and Write tools to efficiently generate clear documentation. Each agent focuses on what it does best, using the right model and tools for its specific role.
Multi-agent architectures shine when tasks have distinct phases that require different capabilities, when different subtasks benefit from different models or tool sets, when you want to optimize costs by using cheaper models for simpler tasks, or when you need clear separation of concerns for maintainability. The orchestrator agent doesn't need to know how to do everything — it just needs to know which specialist to call for each type of work.
Defining Sub-Agents with AgentDefinition
Before you can create a multi-agent system, you need to define each sub-agent using the AgentDefinition class. This class allows you to specify everything that makes each agent unique: its role, its instructions, the tools it can use, and which model powers it.
The AgentDefinition takes four key parameters that shape the agent's behavior and capabilities:
description: A brief label that helps the orchestrator understand what this agent does — think of it as the agent's job titleprompt: The system instructions that define how this agent should approach its work, similar to thesystem_promptyou've used in previous lessons but specific to this sub-agent's roletools: A list of tool names this agent is allowed to use, giving you fine-grained control over each agent's capabilities. If omitted, the agent will inherit all tools available to the orchestratormodel: Which Claude model powers this agent. You can specify"haiku"or"sonnet"just like you do for the main agent. There's also a special"inherit"option that makes the sub-agent use whatever model the orchestrator is using.
In this example, the analyzer agent is configured as:
- A code analysis specialist
- With
ReadandGreptools for examining code structure - Powered by
Sonnetfor deep reasoning
Let's define two more specialists to complete our code review team.
Defining the Fixer and Documenter Agents
The fixer and documenter agents complete our specialized team, each optimized for their specific roles in the code improvement workflow.
The fixer agent is designed to implement corrections:
- Focuses on identifying and fixing issues efficiently through its prompt
- Has access to
Readfor examining code andWritefor making changes - Uses
Sonnetbecause generating correct, high-quality code fixes requires sophisticated reasoning about code semantics and potential side effects
The documenter agent takes a different approach:
- Has
ReadandWritetools like the fixer - Uses the
Haikumodel instead ofSonnet - This is a strategic choice because documentation generation is primarily a text generation task that doesn't require the same level of complex reasoning as code analysis or bug fixing
Haikuis faster and more cost-effective, making it perfect for this role
This demonstrates one of the key advantages of multi-agent systems: you can optimize each agent's model choice based on the complexity of its specific task. Now that we have all three specialists defined, we can configure the orchestrator that will coordinate them.
Configuring the Orchestrator
With your sub-agents defined, you now configure the main orchestrator agent that will coordinate them. This happens through the agents parameter in ClaudeAgentOptions, which creates a registry of available specialists to which the orchestrator can delegate work.
The configuration establishes the orchestrator's capabilities and its team of specialists:
model="haiku": The orchestrator's job is primarily coordination and delegation, which doesn't require the reasoning power ofSonnet. The orchestrator needs to understand the task, decide which specialist to call, and synthesize their results — tasks thatHaikuhandles efficiently.max_turns=15: Allows for extended conversations since multi-agent workflows often require multiple back-and-forth exchanges as specialists complete their work and report backallowed_tools: Pre-approves the tools the orchestrator itself may use without a permission prompt; each sub-agent uses the tools in its ownAgentDefinition, so the fixer'sWriteworks even though the orchestrator could be limited toAgentalone.permission_mode="acceptEdits": Set to automatically enable other file editing toolsagents: This dictionary maps string keys toAgentDefinitionobjects, creating a registry of specialists. The keys you choose here become the identifiers the orchestrator uses when delegating work, so descriptive names like"analyzer","fixer", and"documenter"make it clear which specialist handles which type of work.env: Claude Code runs sub-agents in the background by default and lets the orchestrator move on before they finish. SettingCLAUDE_CODE_DISABLE_BACKGROUND_TASKSto"1"in the agent's environment makes each delegation complete before the next step, which is what the rest of this lesson observes.
However, defining sub-agents and registering them isn't enough — you also need to tell the orchestrator how to use them.
Orchestration Through System Prompts
The system_prompt in a multi-agent system defines the delegation strategy and workflow. Unlike previous lessons, where the system prompt simply guided a single agent's behavior, here it tells the orchestrator which specialists to call and in what order.
The system prompt establishes the orchestrator's identity as a Lead Developer and defines its goal: improving code quality. More importantly, it provides explicit instructions for the delegation workflow. The phrase "you MUST follow this strict process" creates a strong directive that the orchestrator should follow these steps in order. The numbered list specifies exactly which specialist to call at each stage, using the same keys defined in the agents dictionary. The instruction to "Report back after each step" ensures the orchestrator communicates progress to the user, making the multi-agent workflow transparent. This system prompt is deliberately prescriptive because orchestration requires clear coordination — without explicit instructions, the orchestrator might skip specialists, call them in the wrong order, or try to do the work itself instead of delegating. The prompt essentially defines a workflow in which analysis happens first to understand what needs fixing, then fixes are applied to resolve identified issues, and finally documentation is added to make the improved code maintainable. To understand how this delegation actually works, we need to look at the Agent tool.
Observing Delegation with the Agent Tool
When the orchestrator delegates work to a sub-agent, the Claude Agent SDK uses an internal tool called Agent (older Claude Code releases named it Task) to make the delegation happen. Understanding how this works helps you observe and debug multi-agent interactions.
This enhanced version of display_response checks if a tool being used is named "Agent". When it detects a Agent tool call, it prints the input parameters, which reveal exactly how the orchestrator is delegating work. The Agent tool's input typically includes parameters like subagent_type (which specialist to call), description (a brief summary of what to do), and prompt (detailed instructions for the sub-agent). By displaying these parameters, you can see which specialist is being called, what task they're being given, and what specific instructions they're receiving. This visibility is valuable because it helps you verify that the orchestrator is following the delegation strategy you defined in the system prompt, shows you how the orchestrator translates high-level goals into specific instructions for each specialist, and helps you debug issues by revealing exactly what instructions each sub-agent received. Now let's see the complete multi-agent system in action.
Running the Multi-Agent System
With all the pieces in place — the three specialized sub-agents defined, the orchestrator configured with its delegation strategy, and the display_response helper ready to observe the workflow — you're ready to execute the multi-agent system. The agents will work on a Python file that contains several types of issues, making it an ideal candidate for demonstrating how different specialists handle different aspects of code improvement.
Here's the file that the agents will improve:
This code has no input validation, risks a ZeroDivisionError when the list is empty, uses an inefficient manual loop instead of the built-in sum() function, lacks type hints and docstrings, and has an unresolved TODO comment. These issues span multiple categories — bugs, code quality, and documentation problems — making it perfect for demonstrating how the analyzer identifies problems, the fixer resolves them, and the documenter adds comprehensive documentation.
To run the multi-agent system, you create the client with your configured options and issue a simple, high-level query:
The query is deliberately high-level — it doesn't specify how to improve the file or what steps to take because the orchestrator's system prompt handles that coordination. The orchestrator will ensure the work flows through the analyzer, fixer, and documenter in sequence, with each specialist using its specific tools and model to handle its part of the workflow. Let's observe how this unfolds.
Observing the Orchestrator's Preparation
When you run the complete example, the orchestrator begins by stating its plan. It does not open the file itself: the analyzer owns that step, so the orchestrator goes straight to delegation.
The orchestrator starts by explaining its approach in one sentence and immediately moves to the first delegation. Notice the reasoning it gives — it starts with the analyzer because the fixer needs its findings. This demonstrates an important aspect of multi-agent systems: the orchestrator isn't just blindly following a checklist — it understands the dependencies between the steps and sequences the specialists accordingly. It also doesn't duplicate work; reading the file is the analyzer's job, so the orchestrator leaves it to the specialist. This shows the orchestrator is following its instructions to work methodically through analysis, fixing, and documentation phases. Now let's observe how it delegates to the analyzer.
Observing the Analyzer Delegation
The orchestrator delegates to the analyzer specialist with detailed instructions about what to investigate.
The orchestrator calls the Agent tool to delegate to the analyzer. The Agent tool input reveals the delegation details: description provides a brief summary of the task, subagent_type: analyzer specifies which specialist to call, and the prompt contains the full instructions — the categories to check (correctness bugs, error handling, naming, readability, structure, performance, and style), the format of the report (line number, severity, and a concrete fix for each issue), and an explicit boundary: do not modify the file. The orchestrator even anticipates a missing file and tells the analyzer how to recover. By providing this level of detail, the orchestrator guides the analyzer to conduct a thorough investigation across all relevant quality dimensions. The analyzer will now use its Read and Grep tools to examine the code.
Observing the Analyzer's Work
The analyzer specialist uses its tools to examine the code and produces a report of the issues it found, which the orchestrator summarizes.
The analyzer uses its Read tool to examine the file contents and identifies eight issues in the ten-line file. The orchestrator reports back that Step 1 is complete and summarizes the findings — the main one is the ZeroDivisionError on empty input in calculate_average, followed by missing input validation, the unresolved TODO in process_data, a pass-through wrapper, missing type hints and docstrings, and a PEP 8 blank-line violation. While the analyzer's detailed report isn't shown in full here, the orchestrator's summary confirms that the analysis covered bugs, structure, and documentation. The orchestrator explicitly announces that the fixer comes next, demonstrating it's following the strict process defined in its system prompt. Now let's observe how it delegates the fixing work.
Observing the Fixer Delegation
With the analysis complete, the orchestrator moves to the second phase by delegating to the fixer specialist with highly detailed instructions based on the analyzer's findings.
The orchestrator calls the Agent tool with subagent_type: fixer and provides an exceptionally detailed prompt. The prompt translates the analyzer's findings into a numbered list of six specific fixes to implement. Each item is concrete and actionable — raise a ValueError on empty input instead of letting a ZeroDivisionError happen, materialize the input so iterators work, replace the loop with sum(), remove the TODO and the redundant variable, add type hints and docstrings, fix the blank lines. The prompt prioritizes the critical bug at the top, pins down constraints the analyzer didn't decide (keep the public function names, no __main__ block or tests), and asks for a short summary of what changed. This demonstrates the orchestrator's coordination skill: it synthesizes information from the analyzer and translates it into clear, prioritized instructions for the fixer. The fixer doesn't need to re-analyze the code; it receives an explicit checklist of what to fix. Now the fixer will use its Read and Write tools to apply these corrections.
Observing the Fixer's Work
The fixer specialist reads the current code, applies the corrections, and writes the improved version back to the file.
The fixer uses Read to examine the current code, then Write to apply the six fixes from the checklist. The orchestrator confirms Step 2 is complete with a bullet-by-bullet account of what changed, and explicitly announces that the documenter comes next, demonstrating it continues to follow the strict process. At this point, the code has been transformed — calculate_average raises a ValueError on empty input and accepts any iterable, the manual loop became sum(numbers) / len(numbers), process_data is a one-line call with the TODO gone, and type hints, docstrings, and PEP 8 spacing are in place. Note the orchestrator's honesty: the fixer did not run the code, so it plans a verification step of its own at the end. Now the orchestrator delegates to the documenter to add the final layer of documentation.
Observing the Documenter Delegation
With the code functionally correct and well-structured, the orchestrator moves to the final phase by delegating to the documenter specialist to complete the documentation.
The orchestrator calls the Agent tool with subagent_type: documenter and provides focused instructions about what documentation to add: a module-level docstring describing the module's purpose, and accurate, complete function docstrings with Args, Returns, and Raises sections. Importantly, the prompt acknowledges that the fixer already wrote docstrings (note "make sure each function's docstring is accurate and complete"), instructing the documenter to review and complete rather than blindly overwrite, and it draws a firm boundary — do not change any executable code, names, or signatures. This is where using Haiku for the documenter pays off, as documentation is primarily a text generation task that doesn't require Sonnet's reasoning capabilities. The documenter will now use its Read and Write tools to complete the documentation.
Observing the Documenter's Work and Final Summary
The documenter specialist reads the fixed code, adds the documentation, writes the enhanced version, and the orchestrator verifies the results before providing a summary of the entire workflow.
The documenter uses Read to examine the fixed code, then Write to add the module docstring and complete the Args and Returns sections that were missing. After the documentation is complete, the orchestrator performs a verification step by reading the final version one more time to confirm the results — exactly the check it promised after the fixer's work, since no specialist ran the code. This demonstrates good orchestration practice — verifying work completion before declaring success. The orchestrator then provides a final summary organized into sections for each phase. For Step 1, it recaps the eight issues found. For Step 2, it lists the five fixes applied. For Step 3, it details what the documenter added. The summary closes with a Not done section that is just as valuable as the rest: the analyzer suggested tests, the fixer was told to stay minimal, so the orchestrator reports the gap and offers to add them. This demonstrates the power of multi-agent coordination — each specialist focused on what it does best while the orchestrator ensured they worked together in the right sequence and reported the outcome honestly.
Extending Sub-Agents with MCP Tools
The multi-agent code review system you just built demonstrates how specialized agents coordinate through built-in tools like Read, Write, and Grep. But what if your sub-agents need capabilities from custom tools or external MCP servers? Perhaps your analyzer needs to search API documentation, or your documenter needs to query a knowledge base.
To enable sub-agents to use MCP tools, you must follow one critical rule: the orchestrator's allowed_tools must include any MCP tools that sub-agents will use. The orchestrator acts as a gatekeeper — if an MCP tool isn't in its allowed_tools, no sub-agent can use it, even if the tool is specified in the sub-agent's configuration.
Let's enhance our code review system with a documentation researcher that uses MCP tools:
The orchestrator's allowed_tools includes both its own tools (Read, Write, Grep) and the MCP tools that the researcher sub-agent needs. The researcher can now use these MCP tools to fetch API documentation and inform the code review process with authoritative information about best practices.
Summary: Mastering Multi-Agent Coordination
You've now mastered the art of designing sophisticated multi-agent systems that coordinate specialized agents to solve complex problems. The pattern is clear: define each sub-agent using AgentDefinition with its specific description, prompt, tools, and model; register these specialists in the agents parameter using descriptive keys; configure the orchestrator's delegation strategy through a detailed system_prompt; and observe the delegation through the Agent tool to understand the workflow. Sub-agents can access built-in tools and MCP tools, allowing you to equip specialists with external capabilities. Multi-agent systems excel when tasks have distinct phases, when different subtasks benefit from different models or tool sets, when you want to optimize costs, and when you need clear separation of concerns.
In the upcoming practice exercises, you'll design your own multi-agent systems for different domains, experiment with orchestration strategies, and build workflows that leverage each agent's unique strengths to create solutions more powerful than any single agent could achieve alone!
