190 lines
8 KiB
Markdown
190 lines
8 KiB
Markdown
---
|
|
title: "Subagents in the SDK"
|
|
aliases: [subagents, sdk-subagents, agent-spawning]
|
|
tags: [agent-sdk, subagents, parallelization, context-isolation, python, typescript]
|
|
sources: [raw/Subagents in the SDK.md]
|
|
created: 2026-04-17
|
|
updated: 2026-04-17
|
|
---
|
|
|
|
# Subagents in the SDK
|
|
|
|
Subagents are separate agent instances spawned by a main agent to handle focused subtasks. Core use cases: context isolation, parallel execution, specialized instructions, and tool restriction.
|
|
|
|
## Three Ways to Create Subagents
|
|
|
|
| Method | When to use |
|
|
|--------|-------------|
|
|
| **Programmatic** (`agents` param in `query()`) | Recommended for SDK apps — full control, dynamic config |
|
|
| **Filesystem-based** (`.claude/agents/*.md`) | Static definitions, loaded at startup |
|
|
| **Built-in `general-purpose`** | Available automatically when `Agent` is in `allowedTools` — no definition needed |
|
|
|
|
Programmatic agents take precedence over filesystem agents with the same name.
|
|
|
|
## Benefits
|
|
|
|
### Context Isolation
|
|
Each subagent runs in a **fresh conversation**. Only the final message returns to the parent — not intermediate tool calls or reasoning. Parent receives a concise summary, not every file the subagent read.
|
|
|
|
### Parallelization
|
|
Multiple subagents run concurrently. Example: `style-checker`, `security-scanner`, and `test-coverage` can run simultaneously during a code review.
|
|
|
|
### Specialized Instructions
|
|
Each subagent has its own system prompt with domain-specific knowledge — without bloating the main agent's prompt.
|
|
|
|
### Tool Restrictions
|
|
Limit subagents to specific tools. A `doc-reviewer` with only `Read` + `Grep` can analyze but never modify files.
|
|
|
|
## AgentDefinition Fields
|
|
|
|
| Field | Type | Required | Notes |
|
|
|-------|------|----------|-------|
|
|
| `description` | string | Yes | Tells Claude when to use this subagent — write clearly |
|
|
| `prompt` | string | Yes | Subagent's system prompt |
|
|
| `tools` | string[] | No | If omitted, inherits all parent tools |
|
|
| `model` | `sonnet\|opus\|haiku\|inherit` | No | Defaults to main model |
|
|
| `skills` | string[] | No | Skills available to this subagent |
|
|
| `memory` | `user\|project\|local` | No | Python only |
|
|
| `mcpServers` | array | No | MCP servers by name or inline config |
|
|
|
|
> **Important:** Subagents cannot spawn their own subagents — never include `Agent` in a subagent's `tools`.
|
|
|
|
## Python Example
|
|
|
|
```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(
|
|
# Agent tool is required — Claude invokes subagents through it
|
|
allowed_tools=["Read", "Grep", "Glob", "Agent"],
|
|
agents={
|
|
"code-reviewer": AgentDefinition(
|
|
description="Expert code review specialist. Use for quality, security, and maintainability reviews.",
|
|
prompt="""You are a code review specialist with expertise in security, performance, and best practices.
|
|
When reviewing code:
|
|
- Identify security vulnerabilities
|
|
- Check for performance issues
|
|
- Verify adherence to coding standards
|
|
- Suggest specific improvements""",
|
|
tools=["Read", "Grep", "Glob"], # read-only
|
|
model="sonnet",
|
|
),
|
|
"test-runner": AgentDefinition(
|
|
description="Runs and analyzes test suites. Use for test execution and coverage analysis.",
|
|
prompt="You are a test execution specialist. Run tests and provide clear analysis of results.",
|
|
tools=["Bash", "Read", "Grep"],
|
|
),
|
|
},
|
|
),
|
|
):
|
|
if hasattr(message, "result"):
|
|
print(message.result)
|
|
|
|
asyncio.run(main())
|
|
```
|
|
|
|
## What Subagents Inherit
|
|
|
|
| Receives | Does NOT receive |
|
|
|----------|-----------------|
|
|
| Own system prompt + Agent tool prompt | Parent's conversation history or tool results |
|
|
| Project CLAUDE.md | Skills (unless listed in `AgentDefinition.skills`) |
|
|
| Tool definitions (parent's or restricted subset) | Parent's system prompt |
|
|
|
|
The only channel from parent → subagent is the **Agent tool's prompt string**. Include file paths, error messages, or decisions directly in that prompt.
|
|
|
|
## Invocation
|
|
|
|
- **Automatic**: Claude matches tasks to subagents based on `description` field
|
|
- **Explicit**: Mention by name in prompt — `"Use the code-reviewer agent to check auth module"`
|
|
|
|
## Dynamic Agent Configuration
|
|
|
|
Factory pattern for runtime customization:
|
|
|
|
```python
|
|
def create_security_agent(security_level: str) -> AgentDefinition:
|
|
is_strict = security_level == "strict"
|
|
return AgentDefinition(
|
|
description="Security code reviewer",
|
|
prompt=f"You are a {'strict' if is_strict else 'balanced'} security reviewer...",
|
|
tools=["Read", "Grep", "Glob"],
|
|
model="opus" if is_strict else "sonnet", # more capable model for high-stakes
|
|
)
|
|
```
|
|
|
|
## Detecting Subagent Invocation
|
|
|
|
Subagents are invoked via the `Agent` tool. Detect by checking `tool_use` blocks where `name` is `"Agent"` (or `"Task"` for SDK < v2.1.63). Messages from inside a subagent include `parent_tool_use_id`.
|
|
|
|
```python
|
|
for block in message.content:
|
|
if getattr(block, "type", None) == "tool_use" and block.name in ("Task", "Agent"):
|
|
print(f"Subagent invoked: {block.input.get('subagent_type')}")
|
|
|
|
if hasattr(message, "parent_tool_use_id") and message.parent_tool_use_id:
|
|
print(" (running inside subagent)")
|
|
```
|
|
|
|
## Resuming Subagents
|
|
|
|
Resumed subagents retain full conversation history. Flow:
|
|
|
|
1. Capture `session_id` from `ResultMessage` during first query
|
|
2. Parse `agentId` from message content (appears in Agent tool results)
|
|
3. Pass `resume: sessionId` in second query's options
|
|
4. Include agent ID in prompt
|
|
|
|
```typescript
|
|
// Resume example (TypeScript)
|
|
for await (const message of query({
|
|
prompt: `Resume agent ${agentId} and list the top 3 most complex endpoints`,
|
|
options: { allowedTools: ["Read", "Grep", "Glob", "Agent"], resume: sessionId }
|
|
})) {
|
|
if ("result" in message) console.log(message.result);
|
|
}
|
|
```
|
|
|
|
Transcripts persist independently of the main conversation and are cleaned up after `cleanupPeriodDays` (default: 30 days).
|
|
|
|
## Common Tool Combinations
|
|
|
|
| Use case | Tools |
|
|
|----------|-------|
|
|
| Read-only analysis | `Read`, `Grep`, `Glob` |
|
|
| Test execution | `Bash`, `Read`, `Grep` |
|
|
| Code modification | `Read`, `Edit`, `Write`, `Grep`, `Glob` |
|
|
| Full access | Omit `tools` field |
|
|
|
|
## Troubleshooting
|
|
|
|
| Problem | Fix |
|
|
|---------|-----|
|
|
| Claude not delegating to subagents | Add `Agent` to `allowedTools`; use explicit name in prompt; write clearer `description` |
|
|
| Filesystem agents not loading | Restart session — agents are loaded at startup only |
|
|
| Windows long prompt failures | Keep prompts concise (<8191 chars) or use filesystem-based agents |
|
|
|
|
## Key Takeaways
|
|
|
|
- `Agent` tool **must** be in `allowedTools` — subagents are invoked through it
|
|
- Subagents **cannot** spawn sub-subagents (no `Agent` in subagent's `tools`)
|
|
- Context isolation means only the **final message** returns to parent — include all needed context in the Agent tool prompt
|
|
- `description` field drives automatic delegation — write it carefully
|
|
- Dynamic factory functions enable runtime customization (different models per security level, etc.)
|
|
- Tool name changed from `"Task"` → `"Agent"` in v2.1.63 — check both for compatibility
|
|
|
|
## Related Articles
|
|
|
|
- [[wiki/agent-sdk/agent-loop|Agent Loop]] — how turns, tool execution, and context management work
|
|
- [[wiki/agent-sdk/configure-permissions|Configure Permissions]] — permission modes and subagent inheritance
|
|
- [[wiki/agent-sdk/agent-skills-plugins|Agent Skills & Plugins]] — loading skills into subagents
|
|
- [[wiki/agent-sdk/hosting-production|Hosting in Production]] — multi-agent deployment patterns
|
|
- [[wiki/agent-sdk/sdk-hooks|SDK Hooks]] — intercept tool calls including Agent tool invocations
|
|
|
|
## Sources
|
|
|
|
- [Subagents in the SDK](https://code.claude.com/docs/en/agent-sdk/subagents) — official Anthropic docs
|