Building Multi Agent Systems

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 Task 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.

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.

Before you can create a multi-agent system, you need to define each sub-agent using the AgentDefinition type. This type allows you to specify everything that makes each agent unique: its role, its instructions, the tools it can use, and which model powers it.

import type { AgentDefinition } from "@anthropic-ai/claude-agent-sdk";

// Analyzer Agent: Uses Sonnet for deep reasoning and Read/Grep tools to explore the codebase
const analyzerAgent: AgentDefinition = {
  description: "Code analysis specialist",
  prompt: "You are a code analyzer. Review code for issues, patterns, and improvements.",
  tools: ["Read", "Grep"],
  model: "sonnet",
};

The AgentDefinition object takes four key properties 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 title.
• prompt: The system instructions that define how this agent should approach its work, similar to the systemPrompt you've used in previous lessons but specific to this sub-agent's role.
• tools: An array 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 orchestrator.
• model: Which Claude model powers this agent. You can specify "haiku", "sonnet", or "opus" 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 Read and Grep tools for examining code structure
• Powered by sonnet for deep reasoning

Let's define two more specialists to complete our code review team.

The fixer and documenter agents complete our specialized team, each optimized for their specific roles in the code improvement workflow.

// Fixer Agent: Uses Sonnet for high-quality code generation and Read/Write tools to apply fixes
const fixerAgent: AgentDefinition = {
  description: "Bug fixing specialist",
  prompt: "You are a bug fixer. Identify and fix code issues efficiently.",
  tools: ["Read", "Write"],
  model: "sonnet",
};

// Documenter Agent: Uses Haiku for speed/cost efficiency, perfect for generating text/docs
const documenterAgent: AgentDefinition = {
  description: "Documentation specialist",
  prompt: "You are a documentation writer. Create clear, comprehensive documentation.",
  tools: ["Read", "Write"],
  model: "haiku",
};

The fixer agent is designed to implement corrections:

• Focuses on identifying and fixing issues efficiently through its prompt
• Has access to Read for examining code and Write for making changes
• Uses sonnet because generating correct, high-quality code fixes requires sophisticated reasoning about code semantics and potential side effects

The documenter agent takes a different approach:

• Has Read and Write tools like the fixer
• Uses the haiku model instead of sonnet
• 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
• haiku is 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.

With your sub-agents defined, you now configure the main orchestrator agent that will coordinate them. This happens through the agents property in Options, which creates a registry of available specialists to which the orchestrator can delegate work.

import type { Options } from "@anthropic-ai/claude-agent-sdk";

const options: Options = {
  model: "haiku",
  maxTurns: 15,
  allowedTools: ["Read", "Write", "Bash", "Grep"],
  permissionMode: "acceptEdits",
  // Register the sub-agents in the orchestrator's agent registry using descriptive keys
  agents: {
    analyzer: analyzerAgent,
    fixer: fixerAgent,
    documenter: documenterAgent,
  },
};

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 of sonnet. The orchestrator needs to understand the task, decide which specialist to call, and synthesize their results — tasks that haiku handles efficiently.
• maxTurns: 15: Allows for extended conversations since multi-agent workflows often require multiple back-and-forth exchanges as specialists complete their work and report back.
• allowedTools: Acts as a global allow-list for the entire multi-agent system — sub-agents can only use tools that appear in this list.
• permissionMode: "acceptEdits": Set to automatically enable file editing tools.
• agents: This object maps string keys to AgentDefinition objects, 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.

However, defining sub-agents and registering them isn't enough — you also need to tell the orchestrator how to use them.

The systemPrompt 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.

const options: Options = {
  model: "haiku",
  maxTurns: 15,
  allowedTools: ["Read", "Write", "Bash", "Grep"],
  permissionMode: "acceptEdits",
  agents: {
    analyzer: analyzerAgent,
    fixer: fixerAgent,
    documenter: documenterAgent,
  },
  // Define the orchestration strategy and workflow for the orchestrator via the system prompt
  systemPrompt:
    "You are a Lead Developer. Your goal is to improve code quality.\n" +
    "When asked to improve a file, you MUST follow this strict process:\n" +
    "1. Delegate to 'analyzer' to find issues\n" +
    "2. Delegate to 'fixer' to resolve them\n" +
    "3. Delegate to 'documenter' to add docs\n" +
    "Report back after each step.",
};

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 object. 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 Task tool.

When the orchestrator delegates work to a sub-agent, the Claude Agent SDK uses an internal tool called Task to make the delegation happen. Understanding how this works helps you observe and debug multi-agent interactions.

The TypeScript SDK provides a streaming interface through the query() function that returns an async iterable of SDKMessage objects. To observe delegation, you need to inspect these messages for tool usage, particularly looking for the Task tool:

import {
  query,
  type SDKMessage,
} from "@anthropic-ai/claude-agent-sdk";

async function displayResponse(stream: AsyncIterable<SDKMessage>) {
  for await (const message of stream) {
    // Check if this is an assistant message
    if (message.type === "assistant") {
      for (const block of message.message.content ?? []) {
        // Display text responses
        if (block.type === "text") {
          console.log("\n💬 Claude Response:");
          console.log(block.text);
        }
        // Display tool usage, especially Task delegations
        else if (block.type === "tool_use") {
          console.log(`\n🔧 [Tool: ${block.name}]`);
          // Display input if tool is Task
          if (block.name === "Task" && block.input) {
            for (const [key, value] of Object.entries(block.input)) {
              console.log(`${key}: ${value}`);
            }
          }
        }
      }
    }
  }
}

This helper function processes the message stream and checks if each message is from the assistant using message.type === "assistant". For each content block in message.message.content, it distinguishes between text responses (which it displays with a chat emoji) and tool usage (which it displays with a tool emoji). When it detects a Task tool call, it prints the input parameters, which reveal exactly how the orchestrator is delegating work. The Task tool's input typically includes properties 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.

With all the pieces in place — the three specialized sub-agents defined, the orchestrator configured with its delegation strategy, and the displayResponse helper ready to observe the workflow — you're ready to execute the multi-agent system. The agents will work on a TypeScript 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:

function calculateAverage(numbers: number[]): number {
  let total = 0;
  for (const num of numbers) {
    total = total + num;
  }
  return total / numbers.length;
}

function processData(data: number[]): number {
  // TODO: Add error handling
  const result = calculateAverage(data);
  return result;
}

This code has no input validation, risks a division by zero when the array is empty, uses an inefficient manual loop instead of the built-in reduce() function, lacks comprehensive JSDoc comments, has an unresolved TODO comment, and doesn't export its functions for reuse. 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 call the query() function with your configured options and issue a simple, high-level prompt:

import { query } from "@anthropic-ai/claude-agent-sdk";

async function main() {
  // Run the agent
  const stream = query({
    prompt: "Please improve the sample.ts file.",
    options,
  });

  await displayResponse(stream);
}

main();

The prompt 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 query() function returns a stream of messages that you pass to displayResponse() to observe the workflow. 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.

When you run the complete example, the orchestrator begins by explaining its plan before delegating to specialists.

💬 Claude Response:
I'll help you improve the sample.ts file. Let me start by delegating to the analyzer to find issues.

The orchestrator starts by explaining its approach and immediately announces it will delegate to the analyzer. Unlike some workflows where the orchestrator might use its own tools first to gather information, this orchestrator trusts the analyzer specialist to handle the investigation phase completely. This demonstrates an important aspect of multi-agent systems: the orchestrator can choose different coordination strategies — it might prepare by gathering information itself, or it might immediately delegate to specialists who are better equipped for the task. After confirming its plan, the orchestrator explicitly states it will follow the strict three-step process defined in its system prompt. 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.

The orchestrator delegates to the analyzer specialist with detailed instructions about what to investigate.

🔧 [Tool: Task]
description: Analyze sample.ts file for issues
subagent_type: analyzer
prompt: Please analyze the sample.ts file for any code quality issues, bugs, anti-patterns, or improvements. Use the Read and Grep tools to examine the file thoroughly. Provide a detailed report of:
1. Code quality issues
2. Performance problems
3. Type safety issues
4. Best practice violations
5. Any other improvements needed

Return a comprehensive analysis with specific line numbers and recommendations.

The orchestrator calls the Task tool to delegate to the analyzer. The Task tool input reveals the delegation details: subagent_type: analyzer specifies which specialist to call, the description provides a brief summary of the task, and the prompt contains comprehensive instructions organized as a numbered list of what to analyze. This structured prompt ensures the analyzer knows exactly what to look for — code quality issues, performance problems, type safety issues, best practice violations, and any other improvements. The prompt also explicitly instructs the analyzer to use its Read and Grep tools and to provide specific line numbers in its report. 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 tools to examine the code.

The analyzer specialist uses its tools to examine the code and produces a comprehensive report categorizing all the issues it found.

🔧 [Tool: Grep]

🔧 [Tool: Read]

🔧 [Tool: Grep]

💬 Claude Response:
Great! The analyzer found several important issues. Now let me delegate to the fixer to resolve these problems.

The analyzer uses its Grep tool to search for patterns in the codebase, then Read to examine the file contents in detail, and Grep again to investigate specific concerns. The orchestrator reports back that the analysis is complete and summarizes the finding — several important issues were discovered. While the detailed report isn't shown in full here, the orchestrator's response confirms that the analyzer successfully identified critical bugs like division by zero, validation gaps, performance issues with the manual loop, type safety concerns, and best practice violations. This comprehensive analysis provides the foundation for the next phase. The orchestrator explicitly announces it's moving to delegate to the fixer, demonstrating it's following the strict process defined in its system prompt. Now let's observe how it delegates the fixing work.

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.

🔧 [Tool: Task]
description: Fix all identified issues in sample.ts
subagent_type: fixer
prompt: Based on the analysis report, please fix the sample.ts file by addressing the following issues:

1. **CRITICAL**: Fix the division by zero bug - add validation for empty arrays in calculateAverage
2. Add validation for NaN/Infinity values in calculateAverage
3. Add proper error handling to processData function
4. Use reduce() instead of manual loop summation
5. Add export statements to both functions
6. Use readonly modifier for array parameters
7. Improve overall code quality and safety

Use the Read tool to first examine the current file, then use the Write or Edit tool to make the necessary improvements. Ensure the refactored code:
- Handles edge cases properly
- Includes meaningful improvements
- Maintains type safety
- Is production-ready

Return a summary of all changes made.

The orchestrator calls the Task tool with subagent_type: fixer and provides an exceptionally detailed prompt. The prompt translates the analyzer's findings into a numbered list of seven specific fixes to implement. Each item is concrete and actionable — add validation for empty arrays, handle NaN/Infinity values, add error handling, replace the loop with reduce(), add exports, use readonly modifiers, and improve overall quality. The prompt prioritizes critical bugs like division by zero at the top and includes instructions about ensuring production-ready code quality. 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.

The fixer specialist reads the current code, applies all the necessary corrections, and writes the improved version back to the file.

🔧 [Tool: Read]

🔧 [Tool: Write]

💬 Claude Response:
Excellent! Now let me delegate to the documenter to add comprehensive documentation.

The fixer uses Read to examine the current code, then Write to apply all seven fixes from the detailed checklist. The orchestrator confirms the fixes are complete and explicitly announces it's moving to delegate to the documenter, demonstrating it continues to follow the strict process. At this point, the code has been transformed — it now includes proper error handling for empty arrays and division by zero, validation for NaN/Infinity values, the efficient reduce() function instead of a manual loop, readonly modifiers for immutability, export statements for reusability, improved error handling in processData(), and overall production-ready quality. The code is functionally correct and well-structured. Now the orchestrator delegates to the documenter to add the final layer of comprehensive documentation.

With the code functionally correct and well-structured, the orchestrator moves to the final phase by delegating to the documenter specialist to enhance the documentation.

🔧 [Tool: Task]
description: Add documentation to sample.ts
subagent_type: documenter
prompt: Please add comprehensive documentation to the sample.ts file. The file should now have:

1. Add a file-level JSDoc comment explaining the module's purpose
2. Add detailed JSDoc comments for calculateAverage function including:
   - Description of what it does
   - @param documentation for the numbers parameter
   - @returns documentation explaining the return value
   - @throws documentation for all error cases
   - Usage examples
3. Add detailed JSDoc comments for processData function including:
   - Description of what it does
   - @param documentation
   - @returns documentation
   - @throws documentation
   - Note about error handling behavior
4. Add inline comments explaining important validation logic
5. Consider adding a note about floating-point precision if relevant

Use the Read tool first to see the current state of the file, then use Edit or Write to add professional, comprehensive documentation that follows TypeScript/JSDoc best practices.

Return a summary of all documentation added.

The orchestrator calls the Task tool with subagent_type: documenter and provides detailed instructions about what documentation to add. The prompt is organized as a numbered list covering file-level JSDoc comments, function documentation with specific JSDoc tags (@param, @returns, @throws), usage examples, inline comments, and considerations for floating-point precision. The prompt explicitly instructs the documenter to follow TypeScript/JSDoc best practices, ensuring the documentation meets professional standards. The goal is to make the code self-documenting — documentation so clear that developers can understand and maintain the code easily. This is where using haiku for the documenter pays off, as documentation enhancement 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 add comprehensive documentation.

The documenter specialist reads the fixed code, adds comprehensive documentation, writes the enhanced version, and the orchestrator verifies the results before providing a detailed summary of the entire workflow.

🔧 [Tool: Read]

🔧 [Tool: Write]

💬 Claude Response:
Perfect! Let me verify the final result by reading the improved file:

🔧 [Tool: Read]

💬 Claude Response:
Perfect! ✅ I've successfully improved the sample.ts file. Here's a summary of all the improvements:

## **Improvements Summary**

### **1. Critical Bug Fixes** 🐛
- **Fixed division by zero**: Added validation to prevent `NaN` when processing empty arrays
- **Added NaN/Infinity validation**: Ensures calculated averages are always finite numbers

### **2. Code Quality Enhancements** ⚡
- **Replaced manual loop with `reduce()`**: More functional and idiomatic TypeScript
- **Added `readonly` modifiers**: Prevents accidental array mutations
- **Added `export` statements**: Makes functions reusable in other modules
- **Improved error handling**: Added try-catch with contextual error messages in `processData`

### **3. Comprehensive Documentation** 📚
- **File-level JSDoc**: Explains module purpose and floating-point precision limitations
- **Function documentation**: Detailed descriptions for both functions
- **Parameter docs**: Clear requirements for input arrays
- **Return type documentation**: Explains expected output values
- **Error documentation**: Both @throws cases clearly documented
- **Usage examples**: 4 examples for `calculateAverage` and 3 for `processData`
- **Inline comments**: Explain validation logic and design choices

### **Key Improvements Made:**
✅ Production-ready error handling  
✅ Type-safe with input validation  
✅ Follows TypeScript best practices  
✅ Professional JSDoc documentation  
✅ Clear error messages for debugging  
✅ Functional programming approach  
✅ Immutable input parameters  

The file is now robust, well-documented, and ready for production use!

The documenter uses Read to examine the fixed code, then Write to add comprehensive documentation throughout. After the documentation is complete, the orchestrator performs a verification step by reading the final version one more time to confirm the results. This demonstrates good orchestration practice — verifying work completion before declaring success. The orchestrator then provides an impressive final summary organized into sections for each category of improvement. For critical bug fixes, it highlights the division by zero fix and NaN/Infinity validation. For code quality enhancements, it lists six major improvements including the switch to reduce(), readonly modifiers, and export statements. For documentation, it details seven types of documentation added, including specific metrics like "4 examples for calculateAverage". The summary concludes with key improvements presented as a checklist with checkmarks, emphasizing that the code is now production-ready with enterprise-level quality. 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 to achieve a remarkable transformation.

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 allowedTools must include any MCP tools that sub-agents will use. The orchestrator acts as a gatekeeper — if an MCP tool isn't in its allowedTools, 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:

// Connect Context7 MCP server
const context7Config = {
  type: "stdio" as const,
  command: "npx",
  args: ["-y", "@upstash/context7-mcp"],
};

// Researcher sub-agent that uses MCP tools
const researcherAgent: AgentDefinition = {
  description: "Documentation researcher",
  prompt: "Search library documentation to help understand best practices.",
  tools: [
    "mcp__docs__resolve-library-id",
    "mcp__docs__get-library-docs",
    "Read",
  ],
  model: "haiku",
};

const options: Options = {
  model: "haiku",
  mcpServers: { docs: context7Config },
  // Orchestrator must allow MCP tools for sub-agents to use them
  allowedTools: [
    "Read",
    "Write",
    "Grep",
    "mcp__docs__resolve-library-id",
    "mcp__docs__get-library-docs",
  ],
  agents: {
    analyzer: analyzerAgent,
    fixer: fixerAgent,
    documenter: documenterAgent,
    researcher: researcherAgent,
  },
};

The orchestrator's allowedTools includes both its own tools (Read, Write, Grep) and the MCP tools that the researcher sub-agent needs. The MCP tools follow the naming pattern mcp__servername__toolname that you learned in Lesson 2. The researcher can now use these MCP tools to fetch API documentation and inform the code review process with authoritative information about best practices.

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 object literals with specific description, prompt, tools, and model properties; register these specialists in the agents property using descriptive keys; configure the orchestrator's delegation strategy through a detailed systemPrompt; and observe the delegation through the Task tool by inspecting the message stream 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!