What are subagents?
A subagent is an AI agent that a lead agent calls for one task. It works in its own context window and returns a short result instead of its full work.
A subagent is an AI agent that another agent starts to do one self-contained task. It runs in its own context window, often with its own instructions and tool list, and hands back a result. The main agent never sees the subagent’s intermediate steps.
The Claude Code docs define subagents as “specialized AI assistants that handle specific types of tasks,” each with “its own context window with a custom system prompt, specific tool access, and independent permissions.” Other frameworks use different names for the same idea. The pattern is one piece of multi-agent systems and of agent orchestration.
Why use a subagent
The main reason is context. Anthropic describes subagents as handling “focused tasks with clean context windows.” A subagent may spend tens of thousands of tokens searching, then “returns only a condensed, distilled summary of its work (often 1,000-2,000 tokens).” The lead agent keeps a small context and avoids context rot.
The Claude Code docs list four more benefits:
- Restrict tools, so a reviewer can read code but not edit it.
- Reuse one configuration across projects.
- Give each subagent a focused system prompt for its domain.
- Send cheap tasks to faster, lower-cost models.
Parallelism is a sixth. In Anthropic’s research system, a lead agent launches 3 to 5 subagents at once, and Anthropic reports this cut research time by up to 90% on complex queries.
Subagent, handoff or tool
| Pattern | Who keeps control | What comes back |
|---|---|---|
| Subagent | The caller | A result, usually a summary |
| Handoff | The new agent takes over | Nothing; the conversation continues with it |
| Plain tool call | The caller | A function’s output, no model involved |
The OpenAI Agents SDK docs put the split this way: handoffs let one agent delegate by transferring the conversation, and the receiving agent by default sees the full prior history. Its Agent.as_tool option is for “structured input for a nested specialist without transferring the conversation.” That second form is the subagent pattern.
How a subagent is defined
In Claude Code, a subagent is a Markdown file with YAML frontmatter, according to the docs. The body becomes its system prompt. name and description are required; description tells the main agent when to delegate. tools is optional and, if omitted, the subagent inherits every tool available to subagents. model is optional too.
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---Files live in .claude/agents/ for a project or ~/.claude/agents/ for all projects. Claude Code also ships built-in subagents: Explore (read-only, for searching a codebase), Plan (read-only research during plan mode) and a general-purpose agent with every tool.
Two behaviors matter in practice. Foreground subagents block the main conversation until they finish; background ones run concurrently, and as of November 2026 a subagent started from the main conversation runs in the background unless configured otherwise. And by default a subagent can spawn subagents of its own, up to three layers below the main conversation.
When to use one, and when not to
The Claude Code docs say to use subagents when the task “produces verbose output you don’t need in your main context,” when you want tool restrictions, or when the work is “self-contained and can return a summary.” They say to stay in the main conversation when the task needs frequent back-and-forth, when phases share significant context such as planning, implementation and testing, when the change is quick, or when latency matters.
Cost is the other limit. Anthropic reports that agents use about 4 times the tokens of chat and multi-agent systems about 15 times. It also says domains where every agent needs the same context, or where agents depend heavily on each other, are a poor fit, and that most coding tasks have fewer parallelizable parts than research.
Common failures
Anthropic’s team found that vague delegation produced duplicated work and gaps. Each subagent needs an objective, an output format, guidance on tools and clear task boundaries. Early versions also spawned too many subagents for simple queries until the team put explicit effort rules in the prompts. Running subagents synchronously, so the lead waits on each one, created bottlenecks.
Tracing subagents
A subagent’s work is hidden from the lead agent by design, which also hides it from you unless it is traced. Capture each subagent run as a child of the call that started it, so you can see the task it was given, the tools it used and the summary it returned. See agent tracing for how spans nest across agent calls.
FAQ
What is a subagent?
A specialized agent that a main agent delegates a task to. The Claude Code docs describe each one as running in its own context window with a custom system prompt, specific tool access and independent permissions.
Why use subagents?
Mainly to keep the main context clean. Anthropic says a subagent can use tens of thousands of tokens exploring and still return only a condensed summary, often 1,000 to 2,000 tokens.
What is the difference between a subagent and a handoff?
With a subagent the caller keeps control and gets a result back. In the OpenAI Agents SDK, a handoff instead lets another agent take over the conversation.
Can a subagent call other subagents?
In Claude Code, yes, up to three layers below the main conversation by default. The docs say setting CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH to 1 turns nesting off.
When should you not use subagents?
When the task needs back-and-forth, when phases share a lot of context, or when latency matters. Anthropic also notes most coding tasks have fewer parallelizable parts than research.