Supervisor Hierarchies and Subagents in Claude

1.Supervisor hierarchies: a lead agent and its subagents

A multi-agent system runs several LLM instances, each with its own conversation context, coordinated through code. The most common topology, and the one Anthropic recommends as a starting point for teams new to multi-agent work, is the orchestrator-subagent pattern. It is a hierarchy: a lead agent creates specialized subagents for specific subtasks and manages them. Other coordination patterns exist, such as agent swarms and message-bus architectures, but the hierarchy has the simplest coordination model.

Anthropic's Research feature shows what this looks like in practice. The lead agent analyzes the query, works out a strategy and creates subagents to explore different aspects in parallel. Each subagent acts as an intelligent filter: it searches repeatedly and returns a condensed result, and the lead agent compiles the final answer. This works because search is a form of compression. Each subagent uses its own context window to explore, then passes back only the most important tokens.

Claude Managed Agents expresses the hierarchy as configuration. A coordinator agent lists, in a multiagent roster, the agents it is allowed to delegate to:

---
name: Engineering Lead
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
multiagent:
  type: coordinator
  agents: # paths: ant apply substitutes {type: agent, id, version}
    - ./reviewer.md
    - ./test-writer.md
---

You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.

The supervisor does the same three things in every version: it breaks the task down, delegates the pieces and combines the results. Workers never see the whole picture, and the coordinator never sees the workers' raw exploration. The docs also list escalation as a pattern that works well: consult a more capable agent or model for a subset of complex subtasks.

Sources12

2.What subagents add to task execution

The Claude Agent SDK gives you subagents in three ways. You can pass them programmatically in the agents parameter of your query() options, write them as markdown files in .claude/agents/ directories, or rely on the built-in general-purpose subagent, which Claude can call through the Agent tool without you defining anything. Here is the programmatic form:

                "code-reviewer": AgentDefinition(
                    # description tells Claude when to use this subagent
                    description="Expert code review specialist. Use for quality, security, and maintainability reviews.",
                    # prompt defines the subagent's behavior and expertise
                    prompt="""You are a code review specialist with expertise in security, performance, and best practices.

When reviewing code:
- Identify security vulnerabilities
- Check for performance issues
- Verify adherence to coding standards
- Suggest specific improvements

Be thorough but concise in your feedback.""",
                    # tools restricts what the subagent can do (read-only here)
                    tools=["Read", "Grep", "Glob"],
                    # model overrides the default model for this subagent
                    model="sonnet",
                ),

The most important benefit is context isolation. Each subagent runs in its own conversation. Its intermediate tool calls and results stay inside it, and only its final message goes back to the parent. A research subagent can explore dozens of files, and the parent receives a short summary instead of every file the subagent read. The other benefits come from fields in the definition above.

Subagents also bring parallelism. Several can run at the same time, so independent subtasks finish in the time of the slowest one rather than the sum of all of them. A code review can run a style checker, a security scanner and a test-coverage checker simultaneously. The Claude Code docs add cost control to the list of benefits: you can send tasks to faster, cheaper models such as Haiku.

Sources34

3.The cost side: when more agents make things worse

Every benefit above has a price. Each extra agent is another possible point of failure, another set of prompts to maintain and another source of unexpected behaviour. Anthropic has seen teams build separate agents for planning, execution, review and iteration, only to lose context at every handoff and spend more tokens coordinating than doing the work. In Anthropic's testing, multi-agent implementations typically used 3 to 10 times more tokens than a single agent for the same task. The overhead comes from duplicated context, coordination messages and summaries at each handoff. Measured against plain chat, agents used about 4 times the tokens and multi-agent systems about 15 times. Some teams spent months building elaborate architectures, then found that better prompting of a single agent got the same results.

Anthropic names three situations where multiple agents consistently beat one. The first is context pollution: one subtask fills the context with material the next subtask does not need. The second is parallelizable work: a larger search space can be covered at once. The third is specialization: an agent with too many tools, often 20 or more, or tools from unrelated domains, starts choosing the wrong one, and adding tools makes existing tasks worse. Outside those three situations, coordination costs usually outweigh the benefits.

Be precise about what parallelism buys. Concurrent subagents finish faster than the same subagents run one after another. Compared with a single agent, though, a multi-agent system often takes longer overall because it does far more total computation. Its main benefit is thoroughness, not speed. The fit also depends on the domain: tasks where all agents need the same context, or with many dependencies between agents, suit multi-agent systems poorly today. Most coding tasks have fewer truly parallel pieces than research does.

Sources152

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.A subagent's tool results flow back into the parent conversation, so delegating a file-heavy task still fills the main context.Why is that wrong?

   Everything the subagent does in between stays in its own conversation. Only its final message returns, so the parent gets a concise summary.

   Covered in What subagents add to task execution

2. 2.Splitting work across parallel agents makes a job both cheaper and faster than a single agent.Why is that wrong?

   Multi-agent systems typically use 3 to 10 times more tokens and often take longer overall. What they buy is broader coverage.

   Covered in The cost side: when more agents make things worse

3. 3.A Managed Agents coordinator can delegate to agents that are coordinators themselves, building a hierarchy as deep as you like.Why is that wrong?

   Managed Agents allows only one level. Referencing an agent that has its own multiagent.agents roster fails the create or update request with a validation error.

   Covered in Supervisor hierarchies: a lead agent and its subagents

Practise it for real

Run an Agent SDK query in which Claude delegates to subagents you defined, then change what one subagent is allowed to do.

1. 1.Save the documented Python example, which calls query() with a code-reviewer and a test-runner in agents and allowed_tools set to Read, Grep, Glob and Agent, and run it in a repository that has an authentication module.

   Why: No code in the example picks a subagent. Claude chooses from each subagent's description, which is agent behaviour rather than workflow routing.

   You should see: The script prints the final result message. The review work happens inside the subagent's own conversation, and only its final message returns to the main agent.

2. 2.Delete the tools line from the code-reviewer definition and run the script again.

   Why: If tools is omitted, the subagent inherits every tool available to subagents, so the read-only restriction is gone.

   You should see: code-reviewer is no longer limited to Read, Grep and Glob. Put the line back to restore the guarantee that it can analyze but not modify.

3. 3.Add model="haiku" to the test-runner definition.

   Why: Sending a narrow subtask to a cheaper, faster model is one of the documented cost levers for subagents.

   You should see: test-runner runs on Haiku, while the main agent and code-reviewer keep their own models.