← back to the archiveCover illustration for “Subagent: a helper agent with its own fresh context”
TERM7mo ago·Published · Updated ·by Andy Padia

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.

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.

#field-guide#agents#claude-code#coding-agents

Sources

  1. code.claude.com/docs/en/sub-agents
  2. anthropic.com/research/multi-agent-research-system
← older drop
Chain-of-thought: getting models to reason step by step
newer drop →
Agentic workflow: model steps chained by your code

related drops

explore all 557 drops →
← back to the archiveday 175