Subagents and delegation
When it makes sense to split a task among several agents with their own context, how to give them clear assignments, and how to bring their results together without losing control.
Before you start
- Context engineering for agentsTechnique
What information the agent receives at each moment, why more is not always better, and how to give it just enough: the essentials up front and the rest when it needs them.
Published - Verification and evaluationTechnique
How to check that the agent did the job right without taking its word for it: give it ways to verify itself, review both the result and the process, and compare setups honestly.
Published
Key idea: a subagent is a helper agent with its own context window. It does part of the work and returns only a summary. It keeps the main context clean and lets work run in parallel, but only if each part is well defined.
The problem
Ask an agent to review a large change and watch its context fill up: it reads dozens of files, explores dependencies, runs tests. By the time it needs to decide, what matters is buried under the details of the exploration.
A subagent solves this the way a team would: the person in charge hands an investigation to someone else, who works independently and comes back with a one-page report. The person in charge doesn’t need to see everything that was read; they need the conclusions.
How it works
- The main agent delegates part of the task with a specific assignment.
- The subagent works in its own context, with its own instructions and often a limited set of tools.
- It returns a summary to the main agent. All its exploration stays out of the main context.
- The main agent integrates the results and decides what to do.
Subagents can work in sequence (one investigates and another implements with that information) or in parallel (several review different aspects at the same time).
In Claude Code, for example, a subagent is defined in a Markdown file in .claude/agents/ that sets its name, its description, the tools it can use, and its instructions. Codex and other clients offer similar mechanisms.
Practical example
A read-only reviewer subagent, in Claude Code’s format:
---
name: security-reviewer
description: Reviews changes for security problems. Use it after modifying code that handles external input, authentication, or permissions.
tools: Read, Grep, Glob
---
You are a security reviewer. Review the given diff and look for:
- unvalidated external input;
- secrets in the code;
- permissions broader than needed.
Do not modify files. Return a list of findings, each with file,
line, severity, and why it is a problem. If you find nothing,
say so explicitly.
Notice three decisions:
- Limited tools: it can only read and search. Even if it makes a mistake, it can’t break anything.
- A narrow assignment: it knows exactly what to look for and what not to do.
- A defined output format: the main agent knows what it will receive, including the “no findings” case.
That last point matters a lot: what a subagent returns is everything the main agent will know about its work. Ask for facts with evidence (file, line, command output), not just opinions.
Common mistakes
- Delegating small tasks. Coordination has a cost: more calls, more time, and more tokens. If the task fits comfortably in one agent, don’t split it.
- Parallelizing work that depends on itself. If one part needs the result of another, running them in parallel produces incompatible results.
- Several subagents editing the same files. Their changes will collide. If several must edit, have them work on different files or on separate copies of the repository, for example with Git worktrees.
- Believing the summary without checking. A summary can leave out doubts or errors. The main agent is still responsible for verifying the final result.
- Vague assignments. “Review the code” produces vague reports. Apply what you saw in Task framing: goal, boundaries, and output format.
When to use it
When a task has truly independent parts —investigating three modules, reviewing security and performance separately— or when a long exploration would fill the main context with details you won’t need later. For small or sequential tasks, a single agent is simpler and usually enough.
Next step
This is the last topic in the path. With these pieces —clear tasks, just-enough context, state outside the model, project instructions, Skills, contained tools, verification, hooks, and delegation— you can design a complete harness for your project.
Sources
Accessed on 2026-10-05.
Related content
- Skills: reusable procedures for agentsTechnique
A folder with instructions, and optionally scripts and references, that teaches the agent one specific kind of task. It is only loaded when needed.
Published - Tools and permissionsTechnique
What a tool is, how an agent uses one, and how to decide what it can do without asking, what needs your approval, and what is off limits.
Published