How to Build a Multi-Agent System: A Practical Guide to the Supervisor Pattern

Once you've grasped the concept of "coordinating multiple AIs" in What is a multi-agent system?, the next question is how to actually build one. This article walks through a 5-step practical process for beginners, using the 2026 de facto standard: the supervisor pattern.

Before getting into frameworks, here is the most important principle: "build with a single agent first, and add agents minimally only after you hit a limit." Starting with a crowd is usually over-engineering. The second half shows minimal, readable code that follows the official Claude Agent SDK and OpenAI Agents SDK documentation, plus how to split roles and the failures people actually run into. The same thinking applies if you connect tools through MCP.

Note: the code follows the official Claude Agent SDK and OpenAI Agents SDK documentation (checked October 4, 2026). These SDKs change quickly, so confirm parameter names in each official doc before running anything. Every figure in this article names its source.

1. Before you build: do you really need multi?

The first gate isn't technical — it's a judgment call. Multi-agent is powerful, but it doesn't help every job. If none of the following apply, build with a single agent first.

As noted in the previous article, using multi-agent on a one-track process costs you. In a Google Research study (published January 2026, comparing 180 configurations), every multi-agent variant tested did 39–70% worse than a single agent on a task requiring strict sequential reasoning (PlanCraft). Costs rise too: in its write-up of its own research agent, Anthropic reports that agents use about 4× the tokens of a chat, and multi-agent systems about 15×. Start from the premise that more agents do not mean more intelligence.

2. The base shape: the supervisor pattern

If you're unsure which pattern to use, starting with the supervisor pattern is the safe choice. The major SDKs document it as a core pattern. In the Claude Agent SDK, the main agent calls subagents through the Agent tool; in the OpenAI Agents SDK, the equivalent is "agents as tools," where a manager agent calls specialist agents as tools.

The mechanics are simple. The supervisor receives the overall task, breaks it into subtasks, delegates them to specialist workers, and aggregates the results. The supervisor needn't know how a worker does its job — only which worker to call and in what output format. The expertise lives in the workers.

Note that in the OpenAI Agents SDK, a handoff means something narrower than the general passing of work in Step 4: a triage agent passes the conversation itself to a specialist, who then answers the user directly. No supervisor remains, so treat it as a different pattern from the supervisor (Section 6 covers when to use which).

3. Build it in 5 steps

Assemble a minimal supervisor setup in five steps. The rule of thumb: start with 2-3 workers, then add more only as measurement justifies it.

4. Minimal code ①: Claude Agent SDK (Python)

First, build one supervisor plus two workers (a researcher and a reviewer) with Anthropic's Claude Agent SDK. Setup is just pip install claude-agent-sdk and the ANTHROPIC_API_KEY environment variable (official quickstart; the SDK doesn't load .env files automatically). The code follows the official Subagents page. For the SDK as a whole, see our Claude Agent SDK guide.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition, ResultMessage

options = ClaudeAgentOptions(
    model="claude-opus-5-5",  # the supervisor (main agent)
    system_prompt=(
        "You coordinate a research report. Delegate research to researcher and fact-checking "
        "to reviewer, and write the final text yourself. When delegating, always state the "
        "goal, the output format, and the scope."
    ),
    allowed_tools=["Agent", "WebSearch", "WebFetch"],  # tools that run without a prompt
    agents={
        "researcher": AgentDefinition(
            description="Gathers primary sources. Use when facts or figures are needed.",
            prompt="Find primary sources for the question and return bullet points with source URLs. Never fill gaps with guesses.",
            tools=["WebSearch", "WebFetch"],  # the only tools this role has
            model="sonnet",
            maxTurns=15,
        ),
        "reviewer": AgentDefinition(
            description="Fact-checks drafts. Always use before finalizing text.",
            prompt="Check each claim in the draft against its source and list every sentence that lacks support.",
            tools=["WebFetch"],
            model="sonnet",
            maxTurns=10,
        ),
    },
    max_turns=30,         # cap on round trips for the whole run
    max_budget_usd=5.0,   # spend cap (the SDK's estimate)
    env={"CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "1"},  # workers can't spawn their own
)


async def main():
    try:
        async for message in query(
            prompt="Find three official statistics on workplace use of generative AI and write a short report",
            options=options,
        ):
            if isinstance(message, ResultMessage):
                print(message.subtype, message.total_cost_usd)
                print(message.result)
    except Exception as error:
        print(f"Stopped early: {error}")  # hitting a cap also lands here


asyncio.run(main())

Five things to notice:

• Workers go in agents as AgentDefinition entries. The supervisor reads each worker's description to decide whom to call and when, so describe concretely what the role does and when to use it.
• Listing tools means the role gets only those tools. That's why the reviewer has no write tools. allowed_tools, by contrast, lists tools that run without a permission prompt; it doesn't restrict anything (official Python reference).
• Put caps in three places. A per-role maxTurns, an overall max_turns, and a spend cap with max_budget_usd. When an overall cap is hit, the result subtype becomes error_max_turns or error_max_budget_usd and the run stops (agent loop docs).
• Stop the nesting. Subagents can spawn subagents of their own. Setting the CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH environment variable to 1 makes workers do the work themselves. CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS (default 20) limits how many run at once.
• AgentDefinition fields are camelCase. Writing max_turns instead of maxTurns raises a TypeError at construction time (an official note). The supervisor uses the current claude-opus-5-5; the workers use the alias "sonnet", so the code keeps working when a new version ships.

The official docs point out that Opus 5 delegates to subagents more readily than earlier models, and recommend setting depth, concurrency, and spend limits in addition to prompt instructions. An instruction only changes how Claude asks for help; only the limits reliably stop a run.

5. Minimal code ②: OpenAI Agents SDK (Python)

In OpenAI's Agents SDK, the same shape turns specialist agents into tools with as_tool() and passes them to the supervisor's tools (official "agents as tools"). Setup is pip install openai-agents plus the OPENAI_API_KEY environment variable (official quickstart). If you omit model, the SDK's default model is used; that default changes between SDK versions, so check the Models page.

import asyncio
from agents import Agent, Runner, WebSearchTool

researcher = Agent(
    name="Researcher",
    instructions="Find primary sources for the question and return bullet points with source URLs. Never fill gaps with guesses.",
    tools=[WebSearchTool()],
)
reviewer = Agent(
    name="Reviewer",
    instructions="Check each claim in the draft you receive against its source and list every sentence that lacks support.",
)

manager = Agent(
    name="Manager",
    instructions=(
        "You coordinate a research report. Delegate research to research and fact-checking "
        "to review, and write the final text yourself."
    ),
    tools=[
        researcher.as_tool(
            tool_name="research",
            tool_description="Gather primary sources with citations",
            max_turns=10,  # cap on this role's round trips
        ),
        reviewer.as_tool(
            tool_name="review",
            tool_description="Fact-check a draft",
        ),
    ],
)


async def main():
    result = await Runner.run(
        manager,
        input="Find three official statistics on workplace use of generative AI and write a short report",
        max_turns=10,  # exceeding it raises MaxTurnsExceeded
    )
    print(result.final_output)


asyncio.run(main())

What the two SDKs share, and where they differ:

• Workers don't know the parent's conversation. An agent called through as_tool() doesn't automatically inherit the parent run's conversation state (official docs). The Claude Agent SDK works the same way: the only thing a subagent receives from the parent is the Agent tool's prompt. Put file paths, error messages, and decisions into the request itself.
• The cap is Runner.run(..., max_turns=). Exceeding it raises MaxTurnsExceeded. Passing error_handlers={"max_turns": ...} lets you return a controlled answer instead of an exception (Running agents).
• With handoffs you'd write Agent(..., handoffs=[billing_agent, refund_agent]). The receiving agent takes over the conversation and, by default, sees the entire previous conversation history. If there's information it shouldn't get, narrow it with an input_filter.

6. Splitting roles: good and bad splits

The split is harder than the code. Anthropic writes that each subagent needs an objective, an output format, guidance on the tools and sources to use, and clear task boundaries (same write-up). Here are splits that meet those four conditions and splits that don't.

The same write-up gives a guide to how many agents to use. Anthropic embedded scaling rules in its research supervisor's prompt: simple fact-finding needs one agent with 3–10 tool calls, direct comparisons 2–4 subagents with 10–15 calls each, and complex research might use more than 10 subagents. Those numbers are for research work, so in your own job start at the small end and add only after measuring.

For supervisor versus handoff, OpenAI's docs give a clear rule. If you want one agent to own the final answer or to combine several specialists' outputs, use the supervisor (agents as tools). If routing is itself the job and the chosen specialist should answer the user directly (triaging support requests, for example), use a handoff. You can combine the two.

7. Common failures and fixes

Where people stumble is predictable. Below are failures Anthropic says actually happened with its research agent, plus the points both SDKs' official docs warn about.

The shared lesson: "prompts, tool design, and the eval harness decide success more than the framework does." OpenAI's docs likewise list investing in good prompts, monitoring and iterating, specialized agents, and evals. Over a flashy architecture, the discipline of building small, measuring, and adding only when it pays off is what's fastest in the end.

Summary

Building a multi-agent system isn't scary if you start with the supervisor pattern from a minimal setup. Let's recap.

"Build small, measure, then add." Keep that discipline and a multi-agent system becomes a powerful partner for complex work. For the concept, see What is a multi-agent system?; for building a single one, How to build an AI agent.

FAQ