Advanced · ~2 min read #subagent #multi-agent #context

Subagent

A helper agent with its own context

A helper agent that the main agent delegates a subtask to; it runs with its own context window, instructions and tool set and returns only its result.

Definition

If an agent researches "where does authentication happen?" in a large codebase by itself, every one of the dozens of files it reads lands in its own context. A subagent takes that job instead: it starts with a clean, separate context window, does the search, maybe spends tens of thousands of tokens, and hands the main agent only its final message — a dense summary. The intermediate steps stay inside the subagent's context.

Three core benefits: - Context isolation — the main agent's window stays clean; context rot and early compaction are pushed back. - Parallelism — independent subtasks run at the same time; total time is that of the slowest subtask. - Specialization — each subagent can have its own system prompt, a restricted tool set and, if useful, a cheaper model.

Claude Code ships built-in subagents (read-only Explore, Plan and general-purpose); you define your own as a Markdown file under .claude/agents/. In the Claude Agent SDK you pass them via the agents parameter and the model invokes them through the Agent tool.

There's a price. According to Anthropic's post on its multi-agent research system, agents typically use about 4× more tokens than chat, and multi-agent systems about 15×. A subagent doesn't see the main conversation (unless explicitly configured to); describe the task poorly and it will do the wrong job perfectly.

Analogy

Like a project manager handing work to a research team. If the manager read every report personally, their desk would drown in paper and they'd lose the big picture. Instead they tell three people: "you take competitors, you take pricing, you take regulation — bring me a page each."

Each works for hours at their own desk; only the summaries reach the manager. But if the briefing is bad — say nobody mentioned which market — the team researches the wrong country and returns a flawless report.

Real-world example

You ask Claude Code to "review this PR for security, performance and test coverage." The main agent launches three subagents in parallel:

- security-reviewer: hunts for vulnerabilities with only Read, Grep and Glob. - perf-reviewer: looks for wasteful queries on hot paths. - test-runner: runs the tests with Bash and reports coverage.

Each reads dozens of files; the main agent gets a short list of findings from each. Its context holds three summaries, not hundreds of lines of source. It merges the findings into a single review.

Code examples

                                            Claude Code · .claude/agents/security-reviewer.md
                                            markdown
                                        
---
name: security-reviewer
description: Reviews code changes for security vulnerabilities. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are an application security specialist. Review the given
changes for injection, authorization bypass, secret leakage and
unsafe deserialization.

For each finding: file:line, risk level, a short explanation and
a suggested fix. If there are no findings, say so explicitly.

                                            Claude Agent SDK · defining subagents in code
                                            python
                                        
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition


async def main():
    async for message in query(
        prompt="Review the authentication module for security issues",
        options=ClaudeAgentOptions(
            # Subagents are invoked through the Agent tool
            allowed_tools=["Read", "Grep", "Glob", "Agent"],
            agents={
                "security-reviewer": AgentDefinition(
                    # The main agent uses this to decide when to delegate
                    description="Security review specialist. Use for security questions.",
                    prompt="You are a security expert. Report findings with file:line.",
                    tools=["Read", "Grep", "Glob"],   # read-only
                    model="sonnet",                   # cheaper model
                ),
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

When to use

Read-heavy work with a short result — searching a codebase, inspecting logs, scanning docs
Independent subtasks that can run in parallel — multi-angle reviews, multi-source research
Steps that need different permissions or expertise — a read-only reviewer, an agent that only runs tests
Keeping the main conversation's context clean across a long session

When not to use

Small, quick jobs — spinning up a subagent and writing a briefing costs more than the job itself
Tightly coupled steps — if each step needs every detail of the previous one, a summary won't do
Parallel work that writes to the same files — subagents can overwrite each other's changes
Tight token budget and low task value — multi-agent setups multiply token usage

Common pitfalls

An incomplete briefing

A subagent doesn't see the main conversation. Spell out the goal, constraints, relevant file paths and expected output format in the task message; references like “the bug we discussed above” mean nothing to it.

Trusting the summary blindly

The main agent only sees the subagent's final message. If the subagent misunderstood or skipped something, the summary may not show it. Ask for verifiable evidence like file:line for critical claims.

Splitting everything into subagents

Each subagent builds context from scratch with its own system prompt, tool definitions and reads. Unnecessary splitting pushes total cost and time above a single agent.

Over-privileged subagents

If you don't list tools, a subagent may inherit every available tool. Don't give a reviewing subagent write or shell access; restrict it with the tools field.