A "subagent" is exactly what it sounds like: an agent that another agent can invoke as a tool. Instead of stuffing one system prompt with instructions for researching, coding, reviewing, and reporting — and letting every intermediate file dump pile into a single context window — you define narrow specialists and let a coordinating agent hand work to them. The subagent does its multi-step task in its own context and returns only its conclusion. For long-running enterprise agents, this is one of the most effective context-hygiene tools available.
Defining subagents with AgentDefinition
In the Claude Agent SDK (Python package claude-agent-sdk, npm package @anthropic-ai/claude-agent-sdk), subagents are declared through the agents option. Each entry is an AgentDefinition carrying three things: a description (which tells the main agent when this specialist is the right choice), a prompt (the subagent's own system instructions), and a tools list (what it is allowed to touch).
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition
options = ClaudeAgentOptions(
agents={
"code-reviewer": AgentDefinition(
description="Reviews code for bugs and style issues",
prompt="You are a meticulous code reviewer...",
tools=["Read", "Glob", "Grep"], # read-only specialist
),
},
allowed_tools=["Read", "Agent"], # Agent tool enables delegation
)The per-subagent tools list is a real permission boundary, and it is where subagent systems earn their keep in a security review. The coordinating agent might hold Write and Bash, while the reviewer it consults holds nothing but Read, Glob, and Grep. Delegation narrows authority instead of spreading it.
Invocation goes through the built-in Agent tool
Subagents are not called directly by your application code. The main agent invokes them through the SDK's built-in Agent tool, choosing a specialist based on the descriptions you wrote. That has one practical consequence people trip over: Agent must appear in your allowed_tools list for delegation to be auto-approved. Define beautiful specialists but forget to allow the Agent tool, and the coordinator can never actually use them.
Because selection is driven by the description field, treat those descriptions like tiny job ads. Vague descriptions ("helps with code") produce erratic delegation; specific ones ("reviews a diff for correctness bugs; use after any code change") produce predictable routing. This is the same discipline as writing good tool descriptions for ordinary tool use.
Tracing delegation with parent_tool_use_id
When a subagent runs, the messages generated inside its context carry a parent_tool_use_id field — the ID of the tool call in the main agent's transcript that spawned it. This is your observability thread. In a system where a coordinator fans work out to several specialists, you can group every message by parent_tool_use_id and reconstruct exactly which delegation produced which actions, which is what an audit or a debugging session actually needs. Messages with no parent_tool_use_id belong to the main agent; everything else hangs off a specific delegation.
parent_tool_use_id from day one. A subagent system without delegation tracing turns into "the agent did something, somewhere, via someone" the first time you have to explain an unexpected file change.Subagents on third-party platforms
The whole mechanism is client-side: the SDK runs the agent loop — coordinator and subagents alike — in your process, and only model calls leave the building. That means subagent systems work identically whichever endpoint serves the model: set CLAUDE_CODE_USE_BEDROCK=1 for Amazon Bedrock, CLAUDE_CODE_USE_VERTEX=1 for Google Cloud, CLAUDE_CODE_USE_FOUNDRY=1 for Microsoft Foundry, or CLAUDE_CODE_USE_ANTHROPIC_AWS=1 for Claude Platform on AWS. There is no feature gap to check here, unlike server-side agent features such as the MCP connector or Agent Skills, which skip Bedrock and Vertex entirely.
It is worth distinguishing this from the multiagent feature in Anthropic's hosted Managed Agents product, where a coordinator delegates to other persisted agent objects inside one hosted session. Same idea, different plumbing and different availability: Managed Agents is in beta on the first-party API and Claude Platform on AWS only, while SDK subagents run anywhere the SDK runs.
Where to go next
Pair subagents with the SDK's guardrails in Lifecycle Hooks and the Permission Model, and see how long-running delegation chains keep their state in Session Continuity: Resume, Fork, and JSONL Storage. For platform setup details, start with the Agent SDK on Bedrock.