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.
| Element | Purpose | Typical content |
|---|---|---|
| Task brief | States the goal and scope | Objective, inputs, constraints, definition of done |
| System prompt or role | Sets behavior and expertise | Reviewer, researcher, test writer |
| Tool allowlist | Limits what the subagent can do | Read-only search, or file edits in one folder |
| Model choice | Balances cost and capability | Smaller model for search, larger for reasoning |
| Output contract | Defines what returns to the parent | Summary, structured JSON, list of file paths |
| Limits | Bounds runaway behavior | Maximum turns, time or token budget |
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.
| Pattern | How it works | Typical use |
|---|---|---|
| Predefined specialist | Configured in advance with a role and tools | Code reviewer, security checker |
| Ad hoc worker | Created on the fly with a custom brief | One-off research or file search |
| Parallel fan-out | Several subagents run at the same time | Reading many sources or modules |
| Sequential pipeline | Each subagent consumes the previous output | Plan, implement, test, review |
| Background subagent | Runs while the parent continues | Long builds or test suites |
| Nested subagents | A subagent launches its own subagents | Large hierarchical tasks |
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.
Subagents compared with related agent concepts
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.
| Concept | Relationship to caller | Has own reasoning loop | Context |
|---|---|---|---|
| Subagent | Subordinate, returns a result | Yes | Separate, starts from a brief |
| Tool call | Function executed for the agent | No | None of its own |
| Agent handoff | Control transfers to another agent | Yes | Often shares the conversation |
| Peer in a multi-agent system | Equal participant, negotiates | Yes | Own context, shared messages |
| Agent skill | Packaged instructions loaded in place | No separate loop | Runs in the caller’s context |
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.
| Situation | Delegate to a subagent | Reason |
|---|---|---|
| Searching a large codebase for usages | Yes | Raw search output would flood the parent context |
| Reading ten independent documents | Yes, in parallel | Wall-clock time drops sharply |
| Editing one line the parent already sees | No | Spawn overhead exceeds the work |
| Task needs the full conversation history | Usually no | Rebuilding context in a brief is lossy |
| Independent review of finished work | Yes | A fresh context reduces confirmation bias |
| Risky action needing narrow permissions | Yes, with restricted tools | Limits the blast radius of mistakes |
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.