Sub-Agent vs. Agent Team
When one AI agent is enough, when to hand pieces to sub-agents, and when a team of agents that talk to each other is worth the extra cost. With examples, a 3-question decision framework and how each looks in Claude Code.
Start with one agent. Add sub-agents when the work splits into pieces that do not need to know about each other. Use an agent team only when one agent's discovery changes what another agent should do.
Picking the wrong pattern wastes tokens and can make results worse: Anthropic reports that multi-agent setups typically use 3 to 10 times more tokens than one agent doing the same job.
The two patterns at a glance
Sub-agents: hub and spokes
Main agent↓ one task each · ↑ one summary each
Sub-agents do not talk to each other
Agent team: a shared room
Team lead↓ assigns and collects
↔ teammates message each other directly
A helper the main agent starts for one task. It works in its own separate context, then hands back a summary. Think of a freelancer you brief, who delivers and leaves.
Several agents that stay active for the whole job, share a task list and message each other. Think of a war room where everyone hears what the others found.
The sub-agent
Key traits
- Short-lived: created for one task and finished when it reports back.
- Isolated context: starts fresh, without your conversation history, so its searches and logs do not clutter the main conversation.
- Hierarchical: the main agent decides what to delegate and combines the results.
- Reports back to the caller: its job is to return a result, not to hold an ongoing discussion with other helpers.
- Lean on context: only the summary returns to the main agent, which keeps the main conversation small. The sub-agent still spends tokens of its own while it works.
Use sub-agents when
- The pieces are independent: the work splits into parts that do not depend on each other.
- You want to protect the main context: a side task would produce lots of output (search results, logs, file contents) the main agent does not need to keep.
- A piece needs a specialist: different instructions, a restricted tool set, or a cheaper, faster model.
Examples
- Parallel research: a research agent starts 5 sub-agents, each searching one kind of source (papers, patents, news, government reports, technical blogs). Each returns a summary and the main agent combines them.
- Code review: three sub-agents review the same change in parallel, one for security, one for performance, one for standards. Each returns its own report.
- Travel booking: a main travel agent gives one sub-agent the hotel search (dates, area, rating) and another the flight search. Each works alone and returns options.
Rule of thumb: if a task does not need to know what the other tasks are doing, give it to a sub-agent.
The agent team
Key traits
- Long-lived: teammates stay active for the whole project or task.
- Many-way communication: teammates message each other directly, not only the lead.
- Shared state: a shared task list and messages mean one agent's finding can change another agent's work.
- A coordinator, not a boss: in Claude Code one session is the team lead that creates tasks and combines results, but teammates claim work and settle details among themselves.
- Higher cost: every teammate is a separate agent with its own context, so token use grows with each teammate you add.
Use an agent team when
- Agents must agree: outputs have to be aligned before the work can continue.
- Findings affect each other: what one agent discovers changes what another should do.
- The work needs rounds of review: several specialists pass the work back and forth until it is right.
- You want competing views: different stakeholders, or competing theories about a bug that the agents try to disprove.
Examples
- Building a feature: a developer agent and a UX agent add dark mode to an app. The UX agent explains edge cases while the developer builds and checks back. Each needs to know what the other did.
- Content production: a writer drafts, an editor returns notes, an SEO agent suggests changes, and the loop repeats until the piece is ready.
- Budget negotiation: agents represent finance, tech and marketing, each defends its priorities and answers the others until they reach a split everyone accepts.
Rule of thumb: if one agent's discovery changes what another agent should do, use an agent team.
Side-by-side comparison
| Criterion | Sub-agent | Agent team |
|---|---|---|
| Lifetime | Temporary, ends with its task | Stays for the whole job |
| Context | Own window, summary returns to the caller | Own window each, plus a shared task list |
| Communication | Task in, result out | Teammates message each other |
| Coordination | Main agent manages everything | Lead plus self-coordination |
| Token cost | Lower | Higher, grows with each teammate |
| Complexity | Simple | Complex |
| Think of it as | A freelancer | A war room |
Decide in 3 questions
- Do you need more than one agent at all? Start with one. Add complexity only when you can show one agent is not enough. Often a clearer prompt for a single agent solves the problem.
- Are the tasks independent? If they do not need to talk to each other, use sub-agents. If a finding in one task changes another task, use an agent team.
- Split by context, not by job title. The common mistake is splitting by role (planner, builder, tester). Instead ask what information each task needs. If two tasks need the same information, one agent should handle both.
Why role splits backfire: Anthropic found that agents split by software role (planner, implementer, tester, reviewer) spent more tokens coordinating than doing the actual work.
How each looks in Claude Code
Claude Code has both patterns built in. Sub-agents work out of the box; agent teams are an experimental feature you switch on.
A custom sub-agent: save as .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.Put the file in .claude/agents/ for one project or ~/.claude/agents/ for all your projects. Only name and description are required. Claude delegates to it when a task matches the description, or you can ask for it by name. Claude Code also ships built-in sub-agents such as Explore (read-only search) and Plan.
Turn on agent teams: add to settings.json
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}Then ask for a team in plain language
Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.- Team size: start with 3 to 5 teammates. Token cost grows with every teammate, and three focused teammates often beat five scattered ones.
- One file, one owner: two teammates editing the same file overwrite each other. Give each teammate its own set of files.
- Start with research and review: reviewing a change or investigating a bug shows the value of a team without the conflicts of parallel coding.
Experimental limits: agent teams are off by default, need an interactive session, allow one team per session, and the lead cannot be changed. While teams are on, Claude may start teammates where it would otherwise start sub-agents; set the variable back to 0 to stop that.
Warnings worth knowing
Step-by-step tasks
Google Research tested 180 agent setups. On tasks that need strict step-by-step reasoning, every multi-agent setup they tested made results worse, by 39% to 70%, because passing messages between agents breaks the chain of reasoning. The same study found big gains on work that splits cleanly, such as one finance task that improved by 81%.
Writing code in parallel
Sub-agents that write code at the same time make their own assumptions, and those assumptions often clash when the pieces are merged, which is hard to debug. A safer split: let sub-agents explore and answer questions while the main agent writes the code.
Common mistakes
- Vague task descriptions: agents duplicate each other's work.
- No output format: every agent needs a clear goal and a defined format for what it returns.
- A team for a simple job: it burns tokens with nothing to show for it.
Before you add another agent
Sources: Claude Code docs "Create custom subagents" and "Orchestrate teams of Claude Code sessions" (code.claude.com); Anthropic, "Building multi-agent systems: when and how to use them" (January 2026) and "How we built our multi-agent research system"; Google Research, "Towards a science of scaling agent systems" (January 2026); Cognition, "Don't Build Multi-Agents". Checked November 2026.
Want your team to use this at work?
I'm Abdulaziz Alshamsi, a certified AI trainer and consultant in Abu Dhabi. I train government and company teams to use AI in their daily work. Message me to discuss a session for your team.