A single agent has its own context, its own attention, its own work to do. For complex tasks, multiple agents working in parallel can be dramatically faster than sequential. Or dramatically wasteful — depending on how the orchestration is designed.
This page covers the patterns.
Three different things to research; each can be a subagent. Results return; main agent synthesizes.
For research-heavy tasks, parallelism is real speedup.
Three independent files to modify; three subagents in parallel. Each completes; main agent moves on.
For tasks that decompose cleanly, real parallel work.
One subagent handles backend; another handles frontend; another handles tests. Each has its own focus.
Some work is exploratory and produces lots of intermediate context. Doing it in a subagent keeps the parent context clean.
The "research in subagent; report in main" pattern.
Step B needs Step A's results. Spawning subagents doesn't help if work is inherently sequential.
For 2-minute tasks, the orchestration overhead exceeds the gain.
If subagents constantly need to communicate, they're not really parallel.
If the subagent is doing the same thing the main agent could, just sequentially, it's overhead.
Main agent decomposes the task; spawns N subagents; collects results; synthesizes.
Common for: research, multi-file refactors, parallel analysis.
Different subagents for different specializations. Each has its own skill set.
Common for: code review (different reviewers); multi-stage pipelines; complex workflows.
Subagents may spawn their own sub-subagents. Tree of work.
Rarely needed; usually two levels are enough. Too deep = coordination overhead.
Sometimes a subagent is used not for parallelism but for context isolation. The parent dispatches; waits; gets a clean result.
Useful when the work would be context-heavy but the result is concise.
Each subagent's task should be self-contained. The prompt has everything needed; no implicit context from the parent.
Subagents return their work as text. Should be concise — long results bloat parent context.
What can each subagent decide? When does it return for parent decision?
If a subagent fails, what does the parent do? Retry? Different approach? Report?
Main agent: "Research X across these 3 sources"
↓ Spawn 3 subagents, one per source
↓ Each subagent investigates its source
↓ Returns summary
↓ Main agent synthesizes
Main agent: identify files needing changes
↓ Spawn subagent per file
↓ Each modifies its file
↓ Returns "done" or specific issues
↓ Main agent verifies
Main agent: "Review this PR"
↓ Spawn:
- Subagent for security review
- Subagent for style review
- Subagent for test coverage
↓ Each returns its findings
↓ Main agent aggregates
Main agent: "Should we do A, B, or C?"
↓ Spawn subagent for each
↓ Each explores its option in depth
↓ Returns trade-offs
↓ Main agent recommends
Subagents have their own tool access. Configure per subagent type if needed.
Each subagent has its own context, its own tokens. Multi-agent uses more tokens than sequential. Worth it for the speedup; not free.
Some patterns need subagents to coordinate. Anthropic SDK has some support; specific tools (CrewAI, AutoGen) provide more.
For most needs in Claude Code: simple fan-out without inter-subagent communication.
Subagents return text. Structured output makes synthesis easier:
Subagent reports:
- Key finding: X
- Supporting evidence: Y
- Recommended action: Z
Built-in support for spawning subagents. Each subagent has its own subagent_type and prompt.
For building multi-agent systems on the Claude API. Programmatic agent construction.
LangChain's multi-agent framework. Graph-based agent orchestration.
Multi-agent framework with role-based agents.
Multi-agent framework with conversation patterns.
For Claude Code, the built-in Agent tool covers most needs. For complex agent systems, the SDK or one of the frameworks.
Subagents for everything; even tiny tasks. Overhead exceeds benefit.
Subagents called serially, one after another. No real parallelism.
Defeats parallelism; turns into expensive serialization.
Subagents return huge results; parent agent spends most of its tokens parsing them.
Subagent fails; parent doesn't notice; produces wrong result.
Subagents spawning subagents spawning subagents. Coordination overhead explodes.
For multi-agent design: