What are subagents? Delegating AI work to a clean context
Subagents are helper agents an AI agent spawns with their own context window, tools and prompt. How they save context, what they cost, and how to define one.

A subagent is a helper agent that a main AI agent spawns to do one bounded job in its own context window, with its own system prompt and tool permissions, and that returns only a short result. The main agent never sees the files, logs or search results the subagent waded through, so its own context stays small and focused. Subagents are the most common, and least risky, form of multi-agent design in use today.
How do subagents work?
The main agent has a tool, usually called something like Task or Agent, that starts another agent loop. It passes a prompt describing the job. The subagent runs its own tool-calling loop from an empty conversation, then its final message comes back to the main agent as the tool result.
Claude Code’s subagent docs describe it in one sentence: each subagent “runs in its own context window with a custom system prompt, specific tool access, and independent permissions.” The docs list the reasons to use them: preserve context by keeping exploration out of the main conversation, enforce constraints by limiting tools, reuse configurations across projects, specialize behavior with focused prompts, and control cost by routing work to cheaper models.
Anthropic’s Effective context engineering for AI agents (September 29, 2025) gives the number I design around. A subagent might use tens of thousands of tokens exploring, but it “returns only a condensed, distilled summary of its work (often 1,000-2,000 tokens).” The detailed search context stays isolated inside the subagent.
OpenAI’s Agents SDK has the same idea under a different name: “agents as tools”, where a manager agent “keeps control of the conversation and calls specialist agents through Agent.as_tool().” The distinction it draws is useful. With agents as tools, the manager owns the final answer. With a handoff, the specialist takes over the conversation.
Why use subagents instead of one agent?
Because context is the scarce resource. A context window is finite, everything in it is billed on every turn, and models get worse at recalling details as it fills. Anthropic’s post calls that last effect context rot: as tokens grow, “the model’s ability to accurately recall information from that context decreases.” I wrote about the related problem of stale context dragging a session along in context inertia.
A subagent turns “read eight files to find where auth tokens are refreshed” into one tool call with a one-paragraph answer. Here is the arithmetic for that kind of exploration, with and without delegation.
# subagent_context.py: main-agent context with and without subagents.
# Python 3 stdlib only. Token sizes are assumptions; the 1,500-token summary sits
# inside the 1,000-2,000 range Anthropic gives for sub-agent returns (Sep 2025).
SYSTEM_AND_TASK = 8_000
FILES = [("auth.py", 9_000), ("session.py", 6_500), ("models.py", 12_000),
("routes.py", 7_500), ("tests/test_auth.py", 11_000), ("config.py", 3_000)]
SUMMARY = 1_500
WINDOW = 200_000
inline = SYSTEM_AND_TASK
delegated = SYSTEM_AND_TASK
print(f"{'step':<28}{'inline':>10}{'subagents':>11}")
for name, size in FILES:
inline += size + 300 # file contents plus the tool call that read it
delegated += SUMMARY + 200 # subagent's summary plus the delegation call
print(f"read {name:<23}{inline:>10,}{delegated:>11,}")
print(f"{'share of a 200k window':<28}{inline / WINDOW:>10.0%}{delegated / WINDOW:>11.0%}")
sub_spend = sum(size + 2_000 for _, size in FILES) # each subagent also pays its own prompt
print(f"{'tokens spent inside subagents':<28}{0:>10,}{sub_spend:>11,}")
Output (Python 3.13.11):
step inline subagents
read auth.py 17,300 9,700
read session.py 24,100 11,400
read models.py 36,400 13,100
read routes.py 44,200 14,800
read tests/test_auth.py 55,500 16,500
read config.py 58,800 18,200
share of a 200k window 29% 9%
tokens spent inside subagents 0 61,000
File sizes and overheads are made up; the shape is the point. With subagents, the main context grows by about 1,700 tokens per file instead of the whole file. The last line is the catch: the work didn’t disappear, it moved. The subagents spent 61,000 tokens of their own, so total spend went up, not down. What you buy is a main agent that still has room to think at turn 200, and one that is resending 18,000 tokens per turn instead of 59,000.
How do I define a subagent in Claude Code?
A subagent is a Markdown file with YAML frontmatter. Project subagents live in .claude/agents/, personal ones in ~/.claude/agents/. Only name and description are required; the body becomes the subagent’s system prompt. This is the example from the docs:
---
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.
The description matters most, because Claude decides when to delegate by matching the task against it. The tools line is the safety control: this reviewer can read and search but not edit or run commands. If you leave tools out, the subagent inherits everything. Per the docs, a subagent gets only its own prompt plus basic environment details, not the full Claude Code system prompt, so write the prompt as if it were the whole briefing. It is.
Claude Code ships built-in subagents too. Explore is a fast, read-only agent for searching a codebase, Plan is a read-only research agent used in plan mode, and general-purpose has every tool available for multi-step work. The docs also say subagents can spawn their own subagents, by default up to three layers below the main conversation, and that CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 turns nesting off.
When should a subagent not write code?
Walden Yan’s Don’t Build Multi-Agents (June 12, 2025) described how Claude Code used subagents at the time: they answer a narrowly defined question and don’t write code, because they lack the main agent’s context, and they don’t run in parallel with the main agent. He framed that restraint as the right call. The benefit, he wrote, is that the subagent’s investigation stays out of the main agent’s history, which lets sessions run longer.
I agree with the line he draws. A subagent that reads and reports can’t make a decision that conflicts with the main agent’s, because it makes no decisions that stick. A subagent that edits files can, and it made those edits without seeing why the main agent wanted them. When I do let helpers write, I give each one an isolated working copy, as in git worktrees for parallel agents, and review the diff before it merges.
Where do subagents go wrong?
Thin briefs. The subagent knows only what the delegation prompt says. Anthropic’s research system post (June 13, 2025) found that without an objective, an output format, tool guidance and clear boundaries, “agents duplicate work, leave gaps, or fail to find necessary information.”
Lossy summaries. The summary is all the main agent gets. If the subagent drops the one line number that mattered, the main agent can’t recover it without redoing the work. Ask for file paths and line numbers in the return format.
Over-delegation. Spawning an agent has fixed overhead: a fresh system prompt, tool definitions, and the first few exploratory calls. For a lookup the main agent could do in one grep, delegation costs more and is slower.
Too many tools. A subagent with every tool is a second main agent with less context. Scope it.
What I would do
- Use subagents for read-heavy, decision-light work: codebase search, log triage, documentation lookup, test-failure diagnosis.
- Write the return format into the subagent’s prompt: a short summary, then paths, line numbers and exact quotes. Aim for the 1,000 to 2,000 token range Anthropic cites.
- Give each subagent the narrowest tool list that works, and a cheaper model when the job is mechanical.
- Keep edits in the main agent, or isolate them in a separate worktree when parallel writing is worth it.
- Watch total token spend as well as the main context. Subagents trade money for focus; make sure the trade is worth it.
For the wider picture of agents coordinating with each other, read what a multi-agent system is and the orchestrator-worker pattern. Subagents are the controlled end of that range.
FAQ
What is the difference between an agent and a subagent?
A subagent is an agent started by another agent to do a scoped task. It has its own context window, prompt and tools, and it returns a result to its parent rather than talking to the user.
Do subagents share context with the main agent?
No, and that is the point. A subagent starts with only the delegation prompt and its own system prompt. The main agent sees only what the subagent returns.
Do subagents save tokens?
They save tokens in the main agent’s context, which keeps it focused and cheaper per turn. Total spend usually goes up, because each subagent pays for its own exploration and prompt.
Can subagents run in parallel?
They can. Anthropic’s research system spawns subagents that search in parallel, and that is how orchestrator-worker systems get their speed. Parallel subagents that only read are safe; parallel subagents that write need isolated working copies.
Sources
- Claude Code docs, Create custom subagents (read 2026-10-31)
- Anthropic, Effective context engineering for AI agents, September 29, 2025
- Anthropic, How we built our multi-agent research system, June 13, 2025
- Walden Yan, Cognition, Don’t Build Multi-Agents, June 12, 2025
- OpenAI Agents SDK, Agent orchestration (read 2026-10-31)