Subagents are how big agent jobs stay reliable.
A single agent carrying a whole task in one context window gets worse as that window fills. Splitting the job is not multi-agent theater. It is how you keep each step checkable.
The short version
5 things that decide this
- 01One agent working a long job in one context window degrades as that window fills. Earlier instructions get crowded out by later output.
- 02A subagent is a separate context window with a narrow tool set and one job. It returns a result, not a transcript, to the agent that called it.
- 03Splitting a job by task, not by title, is what makes each step verifiable on its own instead of buried inside one long run.
- 04Not every job needs subagents. A short task with one clear tool call is slower and no safer split into pieces.
- 05The Claude Agent SDK ships subagents as a primitive: a name, a tool list and a system prompt, callable from the main loop.
A full context window is where agents start guessing
Give one agent a job with twenty steps and it runs them in the same context window from start to finish. Every file it reads, every command it runs, every tool result it gets back stays in that window. Each step needs to see what came before.
That window is not free. Fill it with fifteen steps of file contents and command output. Step sixteen reasons against a window where the original instructions are old and recent noise is fresh. That is when an agent starts skipping a check, or repeating a fix it already tried.
The instinct is to write a better prompt. That buys a little room. It does not fix the shape of the problem: one window, one growing pile of context, one place for the reasoning to slip.
A subagent is a fresh window with one job
A subagent gets its own context window, a narrow set of tools, and one job to do. It does not inherit the parent agent's history. It reads what it needs, does the work, and hands back a result: a summary, a diff, a pass or fail. The parent never sees the subagent's intermediate steps, only the answer.
That handoff is the whole benefit. The parent's context stays small because it is holding results, not transcripts. Each subagent's context stays small because its job is narrow. Neither window fills with the other's noise.
Narrow tools matter as much as the fresh window. A subagent scoped to "read files and report findings" cannot also delete a table, because it was never given that tool. The scope is not a suggestion in the prompt. It is what the agent is physically able to call.
- Parent agentHolds the plan and each subagent's result. No raw transcripts.
- Research subagentRead-only tools. Returns a summary, not a file dump.
- Change subagentWrite tools, scoped to one directory. Returns a diff.
- Verify subagentRuns tests only. Returns pass, fail, and why.
Each box is a separate context window. The parent never fills up with another box's detail.
Split by task, not by job title
"Researcher" and "writer" subagents sound organized and usually are not the right cut. The useful split follows what has to be verified independently. A step that reads and reports, a step that changes something, a step that checks the change worked.
A read-only research subagent can run with no write access at all. That removes a whole category of mistake by construction, not by instruction. A change subagent scoped to one directory cannot touch a config file three folders over, even if it gets confused about the task. A verify subagent that only runs tests cannot talk itself out of a failure. Reporting the result is its entire job.
Each of those steps is checkable on its own: right file found, correct diff produced, tests actually run. A single agent doing all three in one window gives you one pass or fail at the end. There is no seam to inspect when it fails.
Not every job earns a subagent
A task that is one clear tool call, read this file and summarize it, gains nothing from a fresh context window and a handoff. It adds a round trip and a place for detail to get lost on the way back. That job was never going to fill the window in the first place.
The tell is whether the parent agent would otherwise accumulate context it does not need for the next decision. If the answer is no, one agent in one window is the simpler build. Splitting a small job into subagents for its own sake is the same mistake as one giant agent, aimed the other way. Extra machinery, standing in for a decision about the actual shape of the work.
Questions this raises
01What is a subagent in the Claude Agent SDK?
A subagent is a named, scoped agent the SDK's main loop can call. It has its own system prompt, its own limited tool list, and its own context window. It runs independently, then returns a result to the calling agent rather than sharing its full transcript. The primitive exists because a single agent's context window degrades as a long job fills it with intermediate output.
02When should I split an agent job into subagents?
Split when the job has steps that need independent verification. Research, a change, and a check are the common shape. Also split when one agent's context would otherwise fill with detail the next step does not need. A short task with one clear tool call does not benefit. Splitting it adds a handoff with nothing to gain from it.
03Does using subagents mean building a multi-agent system?
Not in the sense that term usually means. Multiple named agents debating each other add coordination cost most tasks do not need. Subagents called from one parent loop are different. Each has a scoped tool set and one job. That keeps a single agent's context small and each step checkable, not a separate architecture.
