
Subagent: a helper agent with its own fresh context
In short: A subagent is a helper that an AI agent starts for one bounded task, with its own context window and tools, and it returns only a short result to the caller.
A subagent is a secondary AI agent that a main agent starts to handle one bounded task, such as searching a codebase or reviewing a diff. It runs with its own context window, instructions and tool permissions, then returns a short result. The Claude Code documentation, read in November 2026, says only the relevant summary returns to the main conversation.
Subagent in plain words
You ask a colleague, "find where we handle refunds and tell me in two lines." They read forty files; you read two lines. Your head stays clear for the actual decision.
How it works
The main agent calls a task or delegation tool with a prompt. The harness starts a new agent session, optionally with a predefined role and a restricted tool list. The subagent works through its own loop and ends by returning a final message, which becomes a tool result in the main agent's context.
Several subagents can run at once. Anthropic's June 2025 account of its research system describes a lead agent that spawns subagents in parallel, each with its own context window, and reports that multi-agent systems used about 15 times more tokens than chat interactions.
Example
In Claude Code, a subagent is defined as a Markdown file with frontmatter:
---
name: test-runner
description: Runs the test suite and reports only failing tests with file and line.
tools: Bash, Read
---
Run the tests. Report failures concisely. Do not edit files.
Saved under .claude/agents/, it can be invoked automatically or by name.
Where you'll meet it
- Claude Code and other coding agents that support delegation
- Research agents that fan out searches
- Review or verification steps that should not share the author's context
- Custom agent SDK setups
What it changes for you
Subagents are a context-management tool first and a parallelism tool second. For developers, they are the simplest way to keep long sessions sharp. For teams, they let you package repeatable roles with narrow permissions, such as a read-only reviewer. For cost owners, every subagent is its own run of model calls, so delegation is paid for in tokens.
Subagent vs agent skill
A skill loads instructions into the current agent's context when relevant. A subagent runs separately and only returns its result.
Common mistake
My view: giving every subagent full tool access. A reviewer that can edit files is no longer an independent reviewer. Restrict tools to the job.
Related terms
Multi-agent system · Agent skills · Claude Code · Context window · Context rot
From the archive: Agent swarms need aggregation evals
Give each subagent only the tools its job needs, so a reviewer stays an independent reviewer.


