How to build a multi-agent system with Claude

A single Claude session handles one context window, one task, one thread of reasoning at a time. Most real business problems are bigger than that.

Multi-agent systems solve this by running multiple Claude instances in parallel, each with a focused role, coordinated by an orchestrator that decomposes the task and integrates the results.

The pattern mirrors how engineering teams work: a tech lead breaks work into tickets, engineers execute in parallel, and the lead reviews and integrates.

This guide covers how to build one, from architecture selection through production deployment.

Key takeaways

• Start with a single-agent solution. Introduce multiple agents only when the task genuinely exceeds what one agent can do. Most use cases do not need multi-agent systems.
• The core pattern is one orchestrator, multiple subagents. The orchestrator decomposes the task, dispatches isolated worker agents through typed tool calls, and integrates results. Everything else is variation on this pattern.
• Four architecture topologies exist. Orchestrator-subagent, peer-to-peer, hierarchical, and pipeline. Each has a specific sweet spot.
• Claude offers three native multi-agent options: Claude Code Agent Teams (experimental), the Claude Agent SDK (production-ready), and custom orchestration via the Anthropic API directly.
• The most common failure modes are context blowout, agent loops, and state loss. All three are preventable with circuit breakers, structured output schemas, and explicit state management.
• Cost scales with agent count and context size. A four-agent system can easily consume 10x the tokens of a single-agent solution. Budget and monitor accordingly.

When to build a multi-agent system

Before designing any multi-agent architecture, answer this question honestly: does the task actually require multiple agents?

Build multi-agent when:

• The task is genuinely too large for a single context window
• Subtasks are independent and can run in parallel to save wall-clock time
• Different subtasks benefit from specialized system prompts and roles
• Cross-validation between agents improves reliability and catches errors
• The workflow requires parallel research across multiple sources

Stay single-agent when:

• The task fits comfortably in one context window
• Subtasks are sequential and dependent on each other’s outputs
• Token cost is a primary constraint
• The overhead of coordination exceeds the benefit of specialization
• You are still validating the use case and need a simple baseline

Gartner reports that 85% of AI projects fail to deliver expected business value. Multi-agent complexity is a common multiplier on that failure rate when introduced before the simpler approach has been validated.

For a broader look at when to use AI agents at all, see what is agentic AI and how AI agents work.

The four architecture topologies

1. Orchestrator-subagent (the default)

One orchestrator agent receives the task, decomposes it into subtasks, dispatches specialized worker agents via tool calls, and integrates their outputs into a final result.

Best for: Most production use cases. Research and report generation, content pipelines, code review systems, multi-step analysis.

The structure:

User Request
     │
     ▼
┌─────────────┐
│ Orchestrator│  ← Decomposes task, manages state, integrates results
└──────┬──────┘
       │ tool calls
  ┌────┴────┬────────┐
  ▼         ▼        ▼
Agent A   Agent B  Agent C
(research)(analysis)(format)

2. Peer-to-peer

Multiple agents communicate directly with each other, passing work and context without a central coordinator. More flexible, harder to debug.

Best for: Tasks where the workflow is emergent rather than predefined. Collaborative brainstorming, iterative refinement, debate and critique patterns.

3. Hierarchical

Multiple levels of orchestrators, each managing a subset of agents. A top-level orchestrator delegates to mid-level coordinators, which delegate to worker agents.

Best for: Large-scale workflows with genuinely complex subtask decomposition. Document analysis across hundreds of files, enterprise-scale research programs.

4. Pipeline

Agents process a task sequentially, each one’s output becoming the next one’s input. Less parallel, but simpler to reason about and debug.

Best for: Tasks with clear sequential stages: research, then analysis, then synthesis, then formatting.

For a survey of the broader frameworks that support these patterns, see AI agent frameworks and multi-agent systems.

Three ways to build multi-agent systems with Claude

Option 1: Claude Code Agent Teams (experimental)

Claude Agent Teams lets one session act as team lead while spawning independent teammates that share a task list and communicate directly.

How to enable:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Best for: Development workflows where parallel code review, debugging, and architecture tasks need to run simultaneously. Still experimental; not recommended for unattended production deployment.

For more detail on this capability, see Claude Code parallel agents and Claude Code subagents guide.

Option 2: Claude Agent SDK (production-ready)

The Claude Agent SDK in TypeScript and Python is the production-ready path. You define orchestrators and subagents programmatically, control system prompts, manage state explicitly, and wire in MCP tools.

Install:

npm install @anthropic-ai/sdk   # TypeScript
pip install anthropic            # Python

Best for: Custom production workflows where you need full control over agent behavior, state management, and tool access.

Option 3: Direct API orchestration

Build your own orchestration logic using the Anthropic API directly. Maximum flexibility, maximum complexity. You manage the agent loop, the tool dispatch, the state, and the context management yourself.

Best for: Teams with strong engineering resources who need behavior that the SDK does not support, or who want to integrate Claude into an existing orchestration framework.

Step-by-step: building an orchestrator-subagent system

This walkthrough builds a four-agent content research and writing system.

Step 1: Define the task decomposition

Before writing code, map the task to agents on paper. Identify:

• What the orchestrator decides (which subtasks, in what order, with what inputs)
• What each subagent does (one specific function per agent)
• How outputs flow between agents
• What the final integration step looks like

Example decomposition for a market research report:

Step 2: Write tight system prompts for each agent

Each agent’s system prompt is its operating manual. It must be specific, bounded, and structured.

Example research agent system prompt:

You are a research specialist. Your only job is to find relevant
factual information on the given topic.

Output format (JSON):
{
  "findings": [
    {"claim": string, "source": string, "confidence": "high"|"medium"|"low"}
  ],
  "gaps": [string],
  "recommended_followup": [string]
}

Do not write prose. Do not analyze or interpret findings.
Do not make recommendations. Only return the JSON object.

Structured output formats are critical. Agents that return unstructured prose create parsing problems and hallucination risks in downstream agents.

Step 3: Implement the communication protocol

Define how agents pass information. Two patterns:

Tool-based dispatch (recommended): The orchestrator calls subagents as tools. Subagents receive typed inputs and return typed outputs. Clean, debuggable, and easy to retry individual calls.

Message-based dispatch: Agents communicate by appending to a shared message thread or external state store. More flexible for peer-to-peer patterns; harder to audit.

For most orchestrator-subagent systems, tool-based dispatch is the right choice. It makes the call graph explicit and each agent call independently retryable.

Step 4: Add retries and circuit breakers

Multi-agent systems fail in ways single agents do not. The two most common failure modes:

Agent loops: An agent calls a tool, the tool returns an error, the agent calls the tool again, infinitely. Implement a maximum retry count (3 is typical) and a hard stop with a meaningful error when it is exceeded.

Context blowout: A long conversation history fills the context window and the agent starts ignoring earlier instructions or producing degraded outputs. Implement context compression or window management before you hit the limit.

MAX_RETRIES = 3

def call_agent_with_retry(agent_fn, input_data):
    for attempt in range(MAX_RETRIES):
        try:
            result = agent_fn(input_data)
            if validate_output(result):
                return result
        except Exception as e:
            if attempt == MAX_RETRIES - 1:
                raise RuntimeError(f"Agent failed after {MAX_RETRIES} attempts: {e}")
    raise RuntimeError("Agent produced invalid output after max retries")

For more on the memory and context management challenges in agentic systems, see AI agent memory and context and how to prevent AI agent memory bloat.

Step 5: Implement logging and evaluation

Multi-agent systems are hard to debug without visibility into the full call graph. Log:

• Every agent call with inputs, outputs, and latency
• Every tool invocation within an agent session
• Token usage per agent per call
• Any retries or circuit breaker triggers

Build a simple evaluation harness that runs your system against known test cases before each deployment.

Step 6: Control costs

Multi-agent systems multiply token consumption. A four-agent system processing a complex task can easily consume 10x to 40x the tokens of a single-agent approach.

Cost control mechanisms:

• Model mixing: Use Claude Haiku for cheaper subagent tasks (data extraction, formatting, simple classification) and reserve Claude Sonnet or Opus for the orchestrator and complex reasoning steps
• Context compression: Summarize earlier conversation history before passing context to downstream agents
• Output capping: Set maximum output token limits per agent based on what the task actually requires
• Budget alerts: Set per-run token budgets and alert when they are exceeded

Production failure modes and how to prevent them

A working example: four-agent code review system

Task: Review a pull request for correctness, security vulnerabilities, test coverage, and style.

Agents:

• Orchestrator: Receives the PR diff, assigns review tasks, integrates feedback into a structured review
• Security agent: Analyzes for common vulnerability patterns (injection, auth bypass, data exposure)
• Logic agent: Reviews for correctness, edge cases, and algorithmic issues
• Style agent: Checks against coding standards and documentation requirements

Why multi-agent here: The four review dimensions are genuinely independent. A single agent reviewing all four dimensions in one pass produces less focused analysis than four specialized agents, each with a tight system prompt for one dimension. The runs can execute in parallel, reducing wall-clock time.

Why not for a simple linting check: A single agent with a linting system prompt handles this more efficiently. The coordination overhead is not justified.

Need help building a multi-agent system on Claude?

Building the architecture is one challenge. Getting it to production-grade quality with proper retry logic, cost controls, evaluation harnesses, and MCP integrations is where most teams need experienced help.

Phos AI Labs is an embedded AI consulting firm for mid-market businesses.

We identify the right AI problems, build the strategy, handle implementation, and train your team until AI is how the business actually runs.

For multi-agent development, we work alongside LOW/CODE Agency, one of the first Anthropic partners worldwide, with a CCA-F certified team and 450+ implementation projects.

Together, we determine whether multi-agent architecture is actually warranted and, when it is, build it to production standard.

• Strategy before systems: We tell you honestly when a single agent solves the problem before building a system you do not need.
• AI Foundations that hold: We design multi-agent architectures your team can own, iterate on, and maintain.
• Real team training: We build your engineers’ ability to work with agentic systems, not just deploy them.
• Private AI Workspace: We design company-wide AI environments with multi-agent workflows connected to your actual systems via MCP.
• AI-Native Operations design: We rebuild workflows with orchestrated AI agents that compound value across the business.
• Honest judgment, every time: We tell you when the simpler approach is the right approach.
• We stay until it compounds: We are not done when the system deploys. We are done when it runs reliably.

400+ engagements. Clients include Zapier, Coca-Cola, Medtronic, Sotheby’s, Dataiku, and American Express.

Talk to the team at Phos AI Labs about your multi-agent use case.

FAQs

What is a multi-agent system with Claude?

A multi-agent system with Claude runs multiple Claude instances in parallel, each with a focused role, coordinated by an orchestrator.

It enables tasks that exceed a single context window or benefit from specialized agents.

When should I use a multi-agent system instead of a single agent?

Use multi-agent when the task is too large for one context window, when subtasks can run in parallel, or when different subtasks benefit from specialized prompts.

Use a single agent for everything else.

What is the difference between Claude Agent Teams and the Claude Agent SDK?

Claude Agent Teams (experimental) lets one Claude Code session spawn teammates.

The Claude Agent SDK is a production-ready library for custom orchestrator-subagent systems. Use Agent Teams for development; SDK for production.

What are the most common multi-agent failure modes?

Agent loops, context blowout (context window fills and output degrades), state loss (orchestrator loses track of subtasks), and cost explosion.

All four are preventable with circuit breakers, context compression, explicit state stores, and budget caps.

How much does a multi-agent system cost to run?

A four-agent system can consume 10x to 40x the tokens of a single-agent approach.

Mix models (Haiku for simpler tasks, Sonnet or Opus for reasoning) and compress context to control costs.