# Subagents: An Agent That Works Apart and Returns Only the Result

> A subagent is an assistant with its own context window: it handles one task and returns only the result. How it is defined, what it sees and when to use one.

*Tags: ai, agents, context, claude-code*

---


> [!info] Quick Definition
> A **subagent** is a specialized agent to which a main agent delegates a task. It has its own context window, its own instructions and its own permissions, and it returns to the main agent only the final result, not all the intermediate work.


## Why do they exist?

An agent that does everything in one [[context-window|context window]] accumulates material: files read, commands run, intermediate results. When the session is long, that buildup starts to take the space needed for reasoning. Every tool that runs adds its result to the context, and that context is measured in [[tokens|tokens]]. When it nears the limit, the agent has to summarize what came before and may lose details.

A subagent relieves that pressure. Anthropic describes it this way: subagents use isolated context windows and send only the relevant information back to the orchestrator. The task of exploring fifty files happens in its own context. The main agent gets back a paragraph with the conclusion. The rest stays where it was born. It is the same principle a person applies when delegating research: the one who investigates reads a lot, the one who decides receives the summary.

## How is one defined?

In Claude Code, a subagent is a Markdown file with YAML frontmatter. The frontmatter holds the configuration and the body is its system prompt:

```markdown
---
name: accessibility-reviewer
description: Reviews screens against the accessibility guide. Use it when asked to check contrast, focus or labels.
tools: Read, Glob, Grep
model: sonnet
---

You are an accessibility reviewer. Read the screen you are given and
return a list of findings with severity and WCAG criterion.
```

The main fields are `name` and `description`, which are required. The description is the hint the main agent uses to decide when to delegate. `tools` limits which tools it can use, and `model` picks the model. The files can live in the project (`.claude/agents/`) or in the user's profile.

## What does it see and what does it return?

According to the Claude Code documentation, each subagent "runs in its own context window with a custom system prompt, specific tool access, and independent permissions". It has its own context window, with a custom system prompt, specific tool access and independent permissions. It does not see the main agent's history or what it already read. What it knows is what is in its system prompt and in the message with which the task was delegated, plus basic environment details. That is why the message has to stand on its own: if a fact is missing, the subagent has no way to guess it.

When it finishes, it returns its final message to the main agent, not its tool calls or its intermediate reasoning. Inside, the subagent runs its own [[agent-loop|agent loop]]: think, use a tool, observe and repeat until done. If the subagent explores a lot, the main agent receives only the conclusion. A subagent can also run in the [[background-agents|background]]: the main agent keeps working and gets the result when it finishes. Claude Code also ships built-in subagents, such as Explore, designed to search and analyze code without modifying it.

## Why does it matter to a designer?

Because delegation changes how a workflow is organized, and that has design consequences. A team can split responsibilities: one subagent checks accessibility, another checks tokens, another drafts microcopy, and the main agent integrates the results. Each has its own permissions and criteria, and it is easier to review what each one did.

The same care you apply to agent interfaces applies here: each subagent needs a clear name, a description that says when to use it and only the tools it needs.

## When is it NOT a good idea?

- When the task is short and takes two or three steps. The cost of delegating outweighs the benefit.
- When the subagent needs almost the whole history of the main agent. Without seeing it, it may work with incomplete information.
- When the intermediate result is needed to decide right away. Waiting for the summary adds latency.
- When every subagent has broad permissions without review. More agents with more permissions increase risk.

## Example

Illustrative example: a team wants to know which components use colors outside the tokens. Doing it in the main session would fill the context with dozens of files. The main agent delegates to a read-only subagent with the `Read`, `Glob` and `Grep` tools. The subagent walks the library and returns a table of nine components with the file and the line. The main session stays clean, and the team fixes the nine cases in the next task.

## What permissions should a subagent have?

A subagent inherits the idea of independent permissions, and that is useful: you can give it read-only access to explore and leave writing to the main agent, with review. According to the documentation, the `tools` field limits the available tools and `disallowedTools` works as a deny list (anything not on that list stays allowed). The principle of least privilege applies as in any system: a subagent that explores does not need to edit, and one that drafts does not need to run commands. When you delegate, write in the message what it must return and in which format, so the result is easy to review and compare with others.

## What you can do tomorrow

Write the delegation message for your next long task before you launch it. Include three things: what it must investigate, what it must return and in which format. If you cannot write it in three lines, the task is not ready to delegate. When the subagent returns its result, compare a sample with what you check by hand. If they match in the sample, trust the rest with a little more ease.

## Common mistakes

- Giving every subagent all the tools. Limit them to what they need.
- Writing vague descriptions that stop the main agent from knowing when to delegate.
- Expecting the subagent to know decisions made in the main session. It does not see them.
- Using subagents for everything. They multiply coordination.
- Not reviewing the subagent's result before acting on it.

## Sources

- [Subagents in Claude Code, official documentation](https://code.claude.com/docs/en/sub-agents)
- [Subagents in the Agent SDK, official documentation](https://platform.claude.com/docs/en/agent-sdk/subagents)
- [Building agents with the Claude Agent SDK, Anthropic Engineering](https://anthropic.com/engineering/building-agents-with-the-claude-agent-sdk)


---

Source: https://www.fernandoux.com/en/wiki/ai/subagents/