Subagent

When a task has a piece of work that needs its own focus — a big chunk of context to search through, a specialized set of tools, or a risk of cluttering the main conversation — a main agent can delegate that piece to a subagent instead of doing it inline. The subagent gets a specific instruction, does its work (often in its own isolated context), and returns a result to the main agent, which continues the overall task.

The appeal is mostly about context management: pulling a large, noisy sub-task (like reading through many files, or exploring an unfamiliar API) into a subagent's own context keeps that noise out of the main agent's context, so the main agent's reasoning stays focused on the overall goal rather than the details of how one piece got done.

Subagents are usually configured with a narrower toolset or a specific system prompt tuned for their sub-task, and they're typically short-lived — spawned for one job and discarded once it reports back, rather than persisting as an ongoing collaborator.

How it works

The diagram shows a main agent dispatching work to subagents A and B — one-directional, since the arrangement here is a strict hierarchy: the main agent delegates and the subagents execute and report back, rather than subagents dispatching work of their own. In Claude Code specifically, subagents are one level deep only — a subagent it spawns cannot itself spawn further subagents — which keeps the delegation tree simple to reason about, though other agent frameworks may allow deeper nesting.

Example

A coding agent asked to 'update the API docs to match the current code' might spawn a subagent whose only job is to read through the source files and summarize every public function's current signature, then hand that summary back — keeping the main agent's context focused on writing the docs rather than full of raw file contents.

How it differs

Common misconceptions

FAQ