Subagent

Also known as: sub-agent

On this page 7

A subagent (also written sub-agent) is an AI agent that another agent, the parent or orchestrator, creates to perform a delegated subtask in its own separate context and then report a condensed result back. In AI agents, subagents are the basic unit of delegation: a coding agent may launch one to search a repository, a research agent may launch several to read sources in parallel, and the parent keeps control of the overall goal.

The defining property is context isolation. The subagent starts with a focused brief instead of the full parent conversation, works through its own agent loop with its own tools, and returns only what the parent needs. This keeps the parent’s context window clean and lets work proceed in parallel.

How a subagent is launched and returns its result

A subagent follows a spawn, execute, report cycle that is managed by the agent harness. The parent decides that a piece of work can be separated, writes a brief, and calls a delegation tool; the harness starts a new model session with that brief as its task.

Inside its own session, the subagent runs a normal agent loop: it reasons, calls tools, observes results and repeats until it meets its stopping condition. The intermediate steps, file contents and failed attempts stay in the subagent’s own context and are discarded or summarized when it finishes.

The table below lists the elements that a well-defined subagent invocation contains.

ElementPurposeTypical content
Task briefStates the goal and scopeObjective, inputs, constraints, definition of done
System prompt or roleSets behavior and expertiseReviewer, researcher, test writer
Tool allowlistLimits what the subagent can doRead-only search, or file edits in one folder
Model choiceBalances cost and capabilitySmaller model for search, larger for reasoning
Output contractDefines what returns to the parentSummary, structured JSON, list of file paths
LimitsBounds runaway behaviorMaximum turns, time or token budget
Elements of a subagent invocation

The output contract matters most for reliability. A parent that receives a free-form narrative must interpret it again, while a parent that receives a structured result with fixed fields can validate it and combine it with the results of other subagents.

Types of subagents and delegation patterns

Subagents differ mainly in how they are defined, how long they live and how they run relative to the parent. Many agent frameworks support several of these patterns at once.

PatternHow it worksTypical use
Predefined specialistConfigured in advance with a role and toolsCode reviewer, security checker
Ad hoc workerCreated on the fly with a custom briefOne-off research or file search
Parallel fan-outSeveral subagents run at the same timeReading many sources or modules
Sequential pipelineEach subagent consumes the previous outputPlan, implement, test, review
Background subagentRuns while the parent continuesLong builds or test suites
Nested subagentsA subagent launches its own subagentsLarge hierarchical tasks
Common subagent patterns

Parallel fan-out delivers the clearest speed gains, because independent subtasks finish in the time of the slowest one rather than the sum of all. Nested delegation is often restricted or capped at one level, since each additional layer multiplies cost and makes failures harder to trace.

A subagent is defined by its subordinate relationship to a parent, which distinguishes it from peer agents and from simple tool calls. The comparison below separates terms that are often used loosely.

ConceptRelationship to callerHas own reasoning loopContext
SubagentSubordinate, returns a resultYesSeparate, starts from a brief
Tool callFunction executed for the agentNoNone of its own
Agent handoffControl transfers to another agentYesOften shares the conversation
Peer in a multi-agent systemEqual participant, negotiatesYesOwn context, shared messages
Agent skillPackaged instructions loaded in placeNo separate loopRuns in the caller’s context
Subagent and neighboring concepts

The difference from a handoff is important in practice. After a handoff, the new agent takes over the user interaction; after a subagent finishes, control returns to the parent, which remains responsible for the final answer. The subagent is therefore the worker role in the orchestrator-worker pattern.

When to use a subagent

A subagent is worth its overhead when a subtask is well bounded, context-heavy and independent of the parent’s ongoing reasoning. Each spawn adds latency, a fresh system prompt and a summarization step, so delegating trivial work usually costs more than it saves.

SituationDelegate to a subagentReason
Searching a large codebase for usagesYesRaw search output would flood the parent context
Reading ten independent documentsYes, in parallelWall-clock time drops sharply
Editing one line the parent already seesNoSpawn overhead exceeds the work
Task needs the full conversation historyUsually noRebuilding context in a brief is lossy
Independent review of finished workYesA fresh context reduces confirmation bias
Risky action needing narrow permissionsYes, with restricted toolsLimits the blast radius of mistakes
Decision guide for delegating to a subagent

Good practice is to write the brief as if for a capable colleague with no background: state the goal, the relevant files or facts, what is out of scope and exactly what to return. The parent should then verify returned claims that matter, rather than trusting a summary it cannot inspect.

Risks and common mistakes with subagents

Most subagent failures come from information lost at the boundary between parent and child. The subagent knows only what its brief contains, and the parent knows only what the subagent reports.

  • Underspecified briefs cause subagents to solve a different problem than the one intended.
  • Overconfident summaries can report success for work that was only partly done.
  • Conflicting parallel edits occur when two subagents modify the same files.
  • Cost multiplication follows from spawning many subagents that each reload large contexts.
  • Excessive permissions let a subagent take actions its narrow task never required.
  • Prompt injection in content a subagent reads can steer it unless outputs are treated as data.

Mitigations include least-privilege tool sets, isolated workspaces for parallel writers, explicit turn and budget limits, and agent observability that records each subagent trajectory so failures can be traced to the right step.

The idea in brief

A subagent is like a helper sent on an errand. A main AI assistant has a big job. It hands one small part to a helper with clear instructions. The helper goes off and does the work alone.

When the helper is done, it brings back a short report instead of every detail. The main assistant stays focused and does not get buried in notes. Several helpers can also work at the same time. That makes big jobs faster and keeps the main assistant clear-headed.

A practical scenario

A developer asks a coding agent to rename a widely used configuration option across a repository with about 1,200 source files. Instead of reading every file itself, the parent agent launches three read-only subagents in parallel: one searches application code, one searches tests and one searches documentation. Each returns a short list of file paths and line numbers, roughly 40 lines in total instead of thousands of lines of search output.

The parent then makes the edits, runs the test suite, and launches a fourth subagent with a fresh context to review the finished change. The reviewer finds two configuration examples in documentation that still use the old name. The final change is complete, and the parent context stays small enough to continue working on the developer’s next request in the same session.