A subagent is a helper AI that a main AI agent sends off to do one part of a job in its own separate workspace, then brings back a short summary. The main agent stays focused, because all the searching and reading the helper did never fills up the main conversation.
Think of asking a colleague to read a 300-page report and come back with one page of notes. Your desk stays clear, you get what you need, and you never see the 299 pages they skimmed. A subagent is that colleague. The catch is the same too: you only know what made it into the notes.
In a sentence: “The coding agent sent a subagent to search the whole codebase, and it came back with the three files that mattered.”
What does a subagent do?
The plain point: it takes one side task, works on it apart from the main chat, and reports back.
You will often meet the term in coding agents such as Claude Code. Its documentation says: “Subagents are specialized AI assistants that handle specific types of tasks.” and “Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions.”1 A context window is the amount of text an AI can hold in view at once, so a separate one means the helper starts fresh and its working notes stay out of yours.
When the helper finishes, only its summary comes back. The same documentation says to use one “when a side task would flood your main conversation with search results, logs, or file contents you won’t reference again”, because the subagent “returns only the summary.”2
The idea is not tied to one product. Google lists subagents among the features its Antigravity CLI kept from Gemini CLI.3
How is a subagent different from similar terms?
The plain point: a subagent is a worker; a skill is know-how; a multi-agent system is the whole team.
| Term | How it differs |
|---|---|
| AI agent | Differs: the main AI that plans and acts on your goal. A subagent is an agent it starts for one part of the job. |
| Skill | Differs: instructions the AI loads into its own workspace. A subagent runs in a separate workspace. |
| Multi-agent system | Differs: the whole setup of several agents working together. Subagents are one common way to build it. |
| Plugin | Differs: an installable package. It can contain ready-made subagents along with skills and connectors. |
Anthropic puts the skill and subagent difference this way: “Use Skills to teach expertise that any agent can apply; use subagents when you need independent task execution with specific tool permissions and context isolation.”4
Why use subagents, and what is the catch?
The plain point: they keep the main chat clean and can be limited, but you only see their summary.
Claude Code lists the reasons as to “Preserve context”, “Enforce constraints” by limiting which tools a subagent can use, “Reuse configurations”, “Specialize behavior” and “Control costs” by sending tasks to faster, cheaper-to-run models.2 The tool limit is the useful part for safety: a helper that only needs to read files can be given no power to change them.
The catch, in this site’s reading: a summary is a choice about what to leave out, and the helper does not know everything the main agent needs. Details can get lost on the way back, and when something goes wrong it is harder to see where. Multi-agent: when it helps and when it does not sets out that reasoning.
Use a subagent for a side task that would bury your main conversation in detail, like searching many files, and give it only the tools it needs. If the detail matters, ask it to quote what it found rather than just summarise.
Questions people ask
Does a subagent see my whole conversation?
Usually not. In Claude Code, “Each subagent starts with a fresh, isolated context window”, and gets what the main agent passes it; a special “fork” option copies the conversation so far instead.2
Can a subagent start its own subagents?
In Claude Code, yes, within a limit: “By default, a subagent can spawn subagents of its own, up to three layers below the main conversation.”2
Do subagents use more of my usage?
They can. Each one does its own reading and writing. Anthropic measured that its multi-agent research system, which runs many subagents, used “about 15× more tokens than chats”.5
Where to go next
- Teams of agents: what is a multi-agent system?
- When splitting work pays off: multi-agent: when it helps and when it does not.
- Subagents next to skills, MCP and plugins: skills vs MCP vs plugins.
- Giving agents clear jobs: how to prompt AI agents.
- The words: the AI glossary.
QUICK CHECK · 3 QUESTIONS
Pick an answer to see if you got it. Nothing is recorded.
1. What does a subagent send back to the main agent?
- A short summary of what it found
- Every file and search result it looked at
- Nothing; it only works in the background
Show the answer
Answer: A short summary of what it found. The page quotes Claude Code’s docs: the subagent does the work in its own context and returns only the summary.
2. Why use a subagent for a big search?
- It makes the main AI forget the conversation
- It keeps all the search results out of your main conversation
- It removes the need for any instructions
Show the answer
Answer: It keeps all the search results out of your main conversation. The page says subagents preserve context by keeping exploration out of the main conversation.
3. What is the main catch of working through subagents?
- They cannot use any tools
- They can only run one at a time
- You only see their summary, so details can get lost
Show the answer
Answer: You only see their summary, so details can get lost. In the site’s reading, a summary is a choice about what to leave out, so details can be lost and problems are harder to trace.
Related terms: Rate limit · Schema / structured output · Semantic search · Tool use · Vector database · Vibe coding
- 1Claude Code Docs, Create custom subagents, undated, read at source 19 Oct 2026“Subagents are specialized AI assistants that handle specific types of tasks.” and “Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions.” ↑
- 2Claude Code Docs, Create custom subagents, read at source 19 Oct 2026“Use one when a side task would flood your main conversation with search results, logs, or file contents you won’t reference again: the subagent does that work in its own context and returns only the summary.” ↑a“Preserve context by keeping exploration and implementation out of your main conversation”, “Enforce constraints by limiting which tools a subagent can use”, “Reuse configurations across projects”, “Specialize behavior with focused system prompts”, “Control costs by routing tasks to faster, lower-cost models like Haiku”. ↑b“Each subagent starts with a fresh, isolated context window.” Claude Code Docs, Extend Claude Code, read at source 19 Oct 2026: a subagent gets “Whatever context the lead agent passes in the prompt”, and “For a fork, Claude Code loads the parent’s conversation so far, system prompt, and tools instead.” ↑c“By default, a subagent can spawn subagents of its own, up to three layers below the main conversation.” ↑d
- 3Google for Developers, An important update: Transitioning Gemini CLI to Antigravity CLI, 19 May 2026, read at source 19 Oct 2026the features carried over include “Subagents, and Extensions (now as Antigravity plugins)”. ↑
- 4Anthropic, Skills explained: How Skills compares to prompts, Projects, MCP, and subagents, 5 Mar 2026, read at source 13 Oct 2026 (as cited on this site’s skills vs MCP vs plugins page): “Use Skills to teach expertise that any agent can apply; use subagents when you need independent task execution with specific tool permissions and context isolation.”↑
- 5Anthropic, How we built our multi-agent research system, 13 Jun 2025, read at source 19 Oct 2026“multi-agent systems use about 15× more tokens than chats”. ↑
Claude Code Docs, Create custom subagents and Extend Claude Code, read at source 19 Oct 2026.
The comparisons and examples on this page (the colleague reading a report, the codebase search) are this site’s own ways of explaining, not claims from these sources.
Free printable AI cheat sheets, and AI news every week.
Sixteen one-page AI guides and checklists in one free PDF, no sign-up. And if you want to keep up, the newsletter covers what changed in AI each week, in plain English, with the sources.
SUBSCRIBE FREE ↗ GET THE CHEAT SHEET PACK