Sub-agents
Sub-agents are separate agents a main agent delegates to, each with its own context, instructions and tools. Learn when they help, how to brief them and their costs.
Overview
A sub-agent is an agent that a main agent starts to handle one part of a task. The sub-agent begins with a fresh, empty context. It receives a brief, its own instructions and often a reduced set of tools. It does its job in its own loop and then returns a short result. The main agent sees only that result, not the hundreds of files, search results or log lines the sub-agent read along the way.
A manager preparing a decision might say to an analyst: "Read these forty reports and give me one page on the main risks." The analyst reads everything. The manager reads one page and keeps their attention on the decision. Sub-agents give a main agent the same leverage.
Sub-agents matter because context is the scarcest resource an agent has. Every file read and every tool output takes space and can distract the model. Delegating noisy, bounded work keeps the main thread clean, lets specialists work with tailored instructions and permissions, and allows several pieces of work to run at once.
What it is
A sub-agent is defined by what it receives, what it may do and what it returns.
| Property | What it means | Benefit |
|---|---|---|
| Fresh context | Starts without the main conversation's history | Large reading jobs do not fill the main window |
| Brief | A task description written by the main agent | Focuses the work on one goal |
| System prompt | Standing instructions for that kind of sub-agent | Specialised behaviour, such as a reviewer's checklist |
| Tool set | An allow-list or deny-list of tools | Lower risk, for example read-only reviewers |
| Model choice | Can differ from the main agent | Use a smaller, faster model for simple searches |
| Return value | A final message, ideally structured | The main agent gets a compact summary |
| Parallelism | Several sub-agents can run at once | Shorter wall-clock time |
In Claude Code, for example, sub-agents are Markdown files with front matter. The body becomes the sub-agent's system prompt:
---
name: code-reviewer
description: Reviews changed code for bugs, security and style. Use after code changes.
tools: Read, Grep, Glob
model: sonnet
---
You are a careful code reviewer. Report problems as a numbered list
with file, line, severity and a suggested fix. Do not edit files.
Where it came from
Splitting work between a coordinator and helpers is an old idea in software, from manager and worker processes to multi-agent systems research. With language-model agents, it became a practical answer to limited context windows.
In June 2025 Anthropic described its multi-agent research system, in which a lead agent plans and starts several sub-agents that search in parallel. On Anthropic's internal research evaluation, the multi-agent set-up outperformed a single agent by 90.2 percent. The same write-up reported that multi-agent runs used about fifteen times as many tokens as a chat, and that vague briefs caused sub-agents to duplicate each other's work.
In July 2025 Claude Code added custom sub-agents that users define as files in a project or home directory. Other frameworks offer the same idea under names such as handoffs, agents as tools or supervisor graphs, for example the OpenAI Agents SDK and LangGraph.
How it works
1. Decide to delegate
The main agent, or the developer's design, decides that a sub-task is worth its own context. Good candidates are wide searches, reading many documents, reviewing a diff, running and reading long test output, or exploring an unfamiliar part of a codebase.
2. Write the brief
The brief is the sub-agent's only knowledge of the task. A good brief states the goal, the scope and boundaries, the sources or tools to use, what has already been tried, and the exact format of the result. The sub-agent does not see the main conversation unless it is passed in.
3. Run in isolation
The runtime starts the sub-agent with its system prompt, the brief and its permitted tools. It works in its own loop. Some runtimes let sub-agents run in the background or in parallel, with limits on how many run at once and how deeply sub-agents may start further sub-agents.
4. Return a compact result
The sub-agent ends with a final message. Only that message goes back to the main agent. A structured result, such as a list of findings with file paths and line numbers, is easier to act on than prose.
5. Continue or combine
The main agent uses the result, starts more sub-agents if needed, and combines the findings. Where several sub-agents worked in parallel, it checks for overlaps or conflicts. This is the orchestrator-workers pattern in its simplest form.
Key concepts and terms
| Term | Meaning |
|---|---|
| Sub-agent | An agent started by another agent to handle part of a task |
| Main agent | The agent that holds the user conversation and delegates |
| Brief | The task description passed to a sub-agent |
| Context isolation | The sub-agent's work stays out of the main context |
| Tool restriction | Limiting which tools a sub-agent may call |
| Fan-out | Starting several sub-agents in parallel |
| Fan-in | Combining their results |
| Spawn depth | How many levels of nested sub-agents are allowed |
| Handoff | Passing control of the conversation to another agent |
| Agent as tool | Calling an agent like a function and getting its result |
| Background sub-agent | A sub-agent that runs while the main agent continues |
A worked example
This is an illustrative scenario. A coding agent has implemented a new "export to CSV" feature that touches six files.
- The main agent starts a reviewer sub-agent with read-only tools. Brief: "Review the diff on the current branch for security, error handling and style. Return at most ten findings as file, line, severity, fix."
- At the same time it starts a test sub-agent with permission to run the test command only. Brief: "Run the full test suite. Return failing test names and the first ten lines of each error."
- The reviewer reads the six files and twelve related ones, about 4,000 lines in total. It returns four findings, one marked high: user-supplied column names go into the file without escaping, which allows formula injection in spreadsheets.
- The test sub-agent runs 1,312 tests, which produce about 9,000 lines of output. It returns one failure, a time-zone assertion, with the error lines.
- The main agent's context grows by only about 40 lines from the two reports.
- It fixes the escaping, corrects the time-zone handling, and asks the test sub-agent to run again. All tests pass.
- It reports to the user with the change, the review findings and how each was handled.
Strengths and limitations
Strengths:
- Keeps the main context lean and focused on the decision.
- Specialised prompts improve quality on reviews, searches and tests.
- Narrow tool sets reduce risk.
- Parallel runs shorten wall-clock time on broad tasks.
- Separate transcripts make each piece of work easy to inspect.
Limitations:
- Extra token cost, since each sub-agent rereads what it needs.
- Poor briefs lead to wasted or duplicated work.
- Sub-agents lack context the main agent has unless it is passed explicitly.
- Coordination adds latency and complexity.
- Parallel sub-agents editing the same files can conflict.
How it compares with alternatives
| Approach | Use it when | Trade-off |
|---|---|---|
| Single agent | The task fits comfortably in one context | Simplest and cheapest, but context fills on big jobs |
| Sub-agents | A bounded part benefits from a fresh, focused context | Better focus, extra cost |
| Orchestrator-workers | Many parallel parts need dynamic assignment | Powerful, harder to coordinate |
| Skills | The main agent needs a procedure, not a separate context | Cheap, but work still fills the main context |
| A2A delegation | The helper is an independent agent owned by another team or vendor | Works across organisations, more protocol overhead |
Practical guidance and best practices
- Delegate work that is noisy and bounded: wide searches, long reads, reviews and test runs.
- Write briefs that state the goal, scope, tools, what is already known and the result format.
- Give each sub-agent the fewest tools it needs; reviewers usually need read-only access.
- Ask for short, structured results with references such as file paths or URLs.
- Use smaller, faster models for simple search sub-agents where quality allows.
- Split parallel work so sub-agents do not edit the same files.
- Limit nesting depth and the number of concurrent sub-agents.
- Track cost per sub-agent type, and remove ones that do not improve results; see cost and latency budgets.
Common mistakes
- A one-line brief such as "look into the bug", which leads to guessing and duplication.
- Delegating tiny tasks where the overhead costs more than the work.
- Giving every sub-agent full write access by default.
- Expecting a sub-agent to know what was said earlier in the main conversation.
- Asking for free-form essays instead of structured findings.
- Starting many parallel sub-agents on overlapping scopes.
Frequently asked questions
What is a sub-agent?
It is an agent started by a main agent to handle one part of a task in its own fresh context. It works with its own instructions and tools and returns a compact result to the main agent.
Why use sub-agents instead of one big agent?
To keep the main context focused, to use specialised instructions and narrower permissions, and to run independent work in parallel. One agent that reads everything itself quickly fills its context with detail it no longer needs.
Do sub-agents share memory with the main agent?
Not automatically. A sub-agent receives its system prompt, the brief and any project instruction files the runtime adds. It does not see the main conversation, and only its final message comes back.
Do sub-agents cost more?
Usually yes. Each sub-agent reads what it needs on its own, so total token use rises, sometimes sharply for multi-agent research. The benefit is better results and a cleaner main context, so measure whether it pays off for your task.
Can sub-agents start their own sub-agents?
In some runtimes, yes, up to a configured depth. Deep nesting makes cost and behaviour harder to follow, so most teams keep it shallow.
What makes a good sub-agent brief?
A clear objective, explicit boundaries, guidance on which tools or sources to use, relevant facts already known and a precise output format. Write it as if for a capable colleague who has not seen the conversation.
Glossary
- Delegation: handing part of a task to another agent.
- Brief: the instructions written for one delegated task.
- Context window: the amount of text a model can consider at once.
- Isolation: keeping a sub-agent's working context separate.
- Allow-list: the set of tools a sub-agent may use.
- Fan-out and fan-in: starting parallel work and combining results.
- Transcript: the full record of a sub-agent's run.
- Nesting: sub-agents starting further sub-agents.
- Supervisor: an agent that coordinates other agents.
Summary
Sub-agents let a main agent hand bounded, noisy work to focused helpers that start with a clean context, tailored instructions and narrow tools, and return only a compact result. They improve focus and quality and allow parallel work, at the price of more tokens and some coordination. Delegate wide searches, reviews and test runs, write precise briefs, restrict tools, ask for structured results and measure whether each sub-agent earns its cost.
Related
It belongs to Coding and computer agents in my stack, under Agentic AI. Others in the same group: