Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Subagent

Pattern

A reusable solution you can apply to your work.

Understand This First

  • Agent – a subagent is an agent with a delegated scope.
  • Decomposition – effective subagent use requires decomposing the task well.

Context

At the agentic level, a subagent is a specialized agent delegated a narrower role by a parent agent or by a human. Where a primary agent handles the overall task (understanding the goal, planning the approach, coordinating the work) a subagent handles a specific piece: searching the codebase, running a focused refactoring, or researching a technical question.

Subagents apply the same principle as decomposition in software design: break a large task into smaller, more manageable pieces. The difference is that each piece is handled by its own agent instance, often with its own context window, its own tools, and its own focused prompt.

Problem

How do you handle tasks that are too large or too varied for a single agent conversation to manage well?

Complex tasks (migrating a large codebase, implementing a feature that touches many modules, or researching a design decision across multiple documentation sources) can overwhelm a single agent’s context window. The conversation becomes too long, the agent loses track of earlier context, and the quality of its work degrades. Simply making the conversation longer doesn’t help, because context window quality degrades before the window is technically full.

Forces

  • Context window limits constrain how much a single agent can hold in working memory.
  • Task breadth means some work naturally spans multiple concerns that benefit from isolation.
  • Specialization allows each subagent to focus deeply on one aspect without being distracted by others.
  • Coordination overhead: managing multiple agents requires effort and introduces the possibility of conflicting changes.

Solution

Decompose a large task into bounded subtasks, and assign each subtask to a separate agent instance. Each subagent gets a focused prompt, relevant context, and access to the tools it needs. The results from subagents are collected and integrated by the parent agent or the human director.

Effective subagent delegation follows a few principles:

Define clear boundaries. Each subagent should have a well-defined input (what it receives), task (what it does), and output (what it produces). Ambiguous boundaries lead to duplicated or conflicting work.

Provide focused context. A subagent searching for all uses of a deprecated function doesn’t need the project’s architectural history. Give it the function signature and the codebase. A subagent making an architectural recommendation needs different context entirely.

Expect independent operation. A subagent should be able to complete its task without consulting the parent on every step. If it requires constant guidance, the subtask wasn’t well-defined.

Subagent use falls into three broad categories:

Exploration. A subagent maps unfamiliar territory: scanning a repository’s structure, locating relevant files, or reading documentation. This keeps the parent agent’s context clean for the work that follows. The parent dispatches the explorer, receives a summary, and proceeds without having consumed tokens on the search itself.

Parallel processing. Multiple subagents work simultaneously on independent tasks. One agent writes the API, another writes the UI, a third writes the tests. This multiplies throughput when the tasks don’t depend on each other’s output. See Parallelization.

Specialist roles. A subagent is configured for a specific kind of work: code review, test execution, debugging, or research. The specialist gets a tailored prompt and sometimes a different (faster, cheaper) model, since not every subtask needs the most capable model available. A test runner subagent, for instance, can use a lighter model to execute tests and report only failures, saving both cost and parent context.

Some harnesses support subagents natively: the parent agent can spawn a child agent, give it a task, and receive its results. Others require the human to manage subagents manually by opening parallel conversations or threads.

Tip

When a task is sprawling and your agent is losing coherence, consider splitting the work into subagent tasks. A good signal that you need subagents: the agent starts contradicting its own earlier output or forgetting constraints it acknowledged earlier in the conversation.

Warning

It’s tempting to break every task into a swarm of specialist subagents. Resist the impulse. The parent agent is perfectly capable of debugging or reviewing its own output, provided it has tokens to spare. Subagents add coordination overhead, and each dispatch is a point where context can be lost or miscommunicated. Use them when a subtask would genuinely crowd out the parent’s working memory, not as a reflex.

How It Plays Out

A developer needs to update a logging library across a large codebase. Rather than asking one agent to find and update all call sites in a single long session, she uses three subagents: one to search for all uses of the old logging API, one to design the replacement pattern, and one to apply the changes file by file. Each subagent operates in a fresh context focused on its specific task. The developer coordinates the results.

A primary agent is tasked with implementing a new feature. It spawns a subagent to research the existing code structure, another to propose a data model, and a third to write the implementation once the first two have reported back. Each subagent’s output becomes input for the next, creating a pipeline of focused work.

Example Prompt

“Search the entire codebase for all uses of the deprecated logging API and list them. I’ll use that list to plan the next steps with a separate agent for each module.”

Consequences

The primary value of subagents is preserving the parent’s context. Every file read, every search result, every dead-end exploration consumes tokens. Subagents absorb that cost in their own disposable context windows, returning only the summary the parent needs. This keeps the parent sharp for the decisions that matter most.

Subagents also enable parallelization: multiple subagents can work simultaneously on independent subtasks. And because subagents don’t need the full project context, they can often run on faster, cheaper models, reducing both latency and cost for token-heavy work like searching, testing, or reviewing.

The tradeoff is coordination. Subagent results must be integrated, and conflicts between subagents’ work must be resolved. The human (or parent agent) takes on a management role, which requires understanding the overall architecture well enough to decompose the task and merge the results coherently.

  • Depends on: Agent – a subagent is an agent with a delegated scope.
  • Enables: Parallelization – independent subagents can run simultaneously.
  • Uses: Context Window – subagents are a response to context window limitations.
  • Uses: Thread-per-Task – each subagent typically runs in its own thread.
  • Depends on: Decomposition – effective subagent use requires decomposing the task well.
  • Uses: Model – subagents can run on cheaper, faster models for token-heavy subtasks.