What are subagents?
A subagent is a second instance of an AI agent, called by the main agent to do one bounded piece of work. It runs in a context window of its own and hands back a result instead of a transcript. Anthropic's documentation defines them as "specialized AI assistants that handle specific types of tasks". Each one "runs in its own context window with a custom system prompt, specific tool access, and independent permissions".
The isolation is the whole mechanism. A subagent "starts with a fresh, isolated context window", and "doesn't see your conversation history, the skills you've already invoked, or the files Claude has already read". The main agent writes a short delegation message describing the task. The subagent works from that alone, and only its final answer comes back. Forty files read, three searches run, two dead ends. None of that reaches the main context window.
The same shape appears under the same name across the tools that have adopted it:
- Claude Code defines a subagent as a Markdown file with YAML frontmatter. Only
nameanddescriptionare required. Optional fields such astools,model,permissionModeandmaxTurnsconfigure how it runs. Project-level definitions live in.claude/agents/, personal ones in~/.claude/agents/. - VS Code puts it in one sentence: a subagent "works in its own context and returns a focused result to the main agent". A local subagent "doesn't inherit the main conversation history". Each invocation is stateless.
- LangChain frames it as a supervisor pattern. In its words, "a central main agent (often referred to as a supervisor) coordinates subagents by calling them as tools", and subagents "return results to the main agent, not the user".
Claude Code and LangChain also offer the opposite of isolation, a fork, which inherits the parent's conversation instead of starting clean. It is the same delegation machinery with the context switch flipped, and it trades focus for continuity.
In plain words
Picture the difference between doing a job with a colleague watching over your shoulder and handing them a brief. In the second case they disappear, read forty documents, run into two dead ends, and come back with one paragraph. You get the paragraph. You never see the forty documents, which is the point. It is also the risk, because you never see the dead ends either.
When it matters
- Side work whose output you will never read again. Searching a large codebase, scanning logs, comparing three libraries. The findings matter, the five hundred lines that produced them do not. Keeping those out of the main window is what holds context rot off on a long task.
- Constraints you want enforced rather than requested. A subagent can be given a read-only tool list, a cheaper model, or a turn limit. That is a structural guarantee, not an instruction the model may drift away from.
- Work that genuinely splits. Several independent investigations can run at once. Two reviewers can check separate concerns, correctness and performance, and their findings get combined at the end.
- Judgements that have to be uninformed. This one is less obvious, and it is the reason we reach for subagents most often. If you want to know whether a text stands on its own, the reader must not have seen the brief that produced it. Isolation there is the product, not a side effect.
What this looks like in practice
Two patterns from our own engineering, both measured on our own work rather than a client's.
Splitting a job by role beat one agent doing all of it. We replaced a single-agent Czech translation step with a two-stage subagent pipeline. The first subagent translates the English source and is allowed to leave English terminology standing. The second does a separate style pass, covering calques, sentence length and quotation spacing, with no shared context between the two. It mirrors a newsroom's split between author, editor and proofreader. A manual test run against an already published article surfaced 11 issues, 5 of them the same recurring calque. A follow-up validation with ten parallel no-context subagents judged the corrected article better than the original single-agent output, with one or two remaining nitpicks of the kind a human editor would also catch.
Splitting a job by scope kept a large change inside a workable window. A 30,000-line MCP upgrade was completed while keeping context to roughly 150,000 tokens, by spreading the work across about five parallel subagents instead of one long-running agent. Two details did most of that work. The orchestrator drafts and iterates on a Markdown plan before spawning any dev or review subagents. That guards against a dev agent reacting to review feedback by coding straight away, instead of first sorting it into important and unimportant. The agents also write spec, plan and progress into separate, git-untracked files, so an interrupted run resumes from the files rather than from the conversation. One observed ceiling came with it. Output degrades into hallucination somewhere around 500,000 tokens of context. The rule of thumb we took from that is to stay under about half of the available window.
Common mistakes
- Treating a delegation as a cheap call. Anthropic's own measurements put agents at "about 4× more tokens than chat interactions" and multi-agent systems at "about 15× more tokens than chats". A subagent's requests count against the same usage limits as the main conversation. The pattern pays for itself when the task is valuable enough to carry that multiple, and not otherwise.
- Splitting work that does not split. The same Anthropic write-up is blunt about the limit. "Most coding tasks involve fewer truly parallelizable tasks than research", and "LLM agents are not yet great at coordinating and delegating to other agents in real time". Work with heavy interdependencies, or where every part needs the same context, gets slower and worse when you divide it.
- Expecting a conversation by default. In VS Code a local subagent is stateless. You cannot send it a follow-up, and the next question starts a new one from zero. Claude Code can resume a subagent on request, and a resumed one keeps "their full conversation history, including all previous tool calls, results, and reasoning". That is a deliberate extra step, though. Write the delegation message as if it is the only thing the subagent will ever see.
- Reading separate contexts as independent verification. Running the same question past two isolated subagents feels like a second opinion. VS Code's documentation says plainly what you actually get: "Separate contexts can surface different issues, but don't guarantee unbiased or correct conclusions." Isolation removes shared context. It does not remove shared priors from the same model.
- Forgetting that only the final message survives. LangChain documents the failure mode. A subagent may "perform tool calls or reasoning but doesn't include results in its final message", and "the supervisor only sees the final output". Work that was done but not reported is, from the main agent's position, work that did not happen.
- Ignoring the ceilings. They are real and they are low. By default Claude Code allows nesting up to three layers below the main conversation, and fails at 20 concurrently running subagents with
Concurrent subagent limit reached. VS Code caps nesting at five and disables subagent-spawned subagents by default.
Related articles:
- What's an agent? - The thing a subagent is a scoped-down copy of.
- What is a context window? - The budget a subagent exists to protect.
- What is context rot? - What happens on a long task when nothing is delegated away.
- What are agentic workflows? - The wider pattern subagent delegation is one building block of.
- What is agentic memory? - How state survives between runs, since it does not survive inside a subagent.
- What is an AI agent sandbox? - The other way to bound what an agent can reach.
Want to stay one step ahead?
Don't miss our best insights. No spam, just practical analyses, invitations to exclusive events, and podcast summaries delivered straight to your inbox.