SpyBara
Go Premium

agent-sdk/subagents.md 2026-06-16 21:57 UTC to 2026-06-17 17:02 UTC

87 added, 75 removed.

2026
Tue 30 23:02 Mon 29 23:02 Sat 27 01:01 Fri 26 23:00 Thu 25 23:58 Wed 24 22:02 Tue 23 22:00 Mon 22 23:59 Fri 19 22:58 Thu 18 22:00 Wed 17 17:02 Tue 16 21:57 Mon 15 23:02 Sat 13 21:59 Fri 12 22:00 Thu 11 23:01 Wed 10 23:57 Tue 9 06:34 Mon 8 06:52 Sat 6 06:24 Fri 5 06:45 Thu 4 06:52 Wed 3 06:53 Tue 2 06:51

SDK 中的子代理

定义和调用子代理以隔离上下文、并行运行任务，以及在 Claude Agent SDK 应用程序中应用专门的指令。

子代理是您的主代理可以生成的独立代理实例，用于处理专注的子任务。 使用子代理来隔离专注子任务的上下文、并行运行多个分析，以及应用专门的指令，而不会使主代理的提示词过于复杂。

本指南说明如何使用 agents 参数在 SDK 中定义和使用子代理。

概述

您可以通过三种方式创建子代理：

  • 以编程方式：在您的 query() 选项中使用 agents 参数（TypeScript、Python）
  • 基于文件系统：在 .claude/agents/ 目录中将代理定义为 markdown 文件（请参阅将子代理定义为文件）
  • 内置通用代理：Claude 可以随时通过 Agent 工具调用内置的 general-purpose 子代理，无需您定义任何内容

本指南重点介绍编程方法，这是 SDK 应用程序的推荐方法。

定义子代理时，Claude 根据每个子代理的 description 字段确定是否调用它。编写清晰的描述，说明何时应使用子代理，Claude 将自动委派适当的任务。您也可以在提示词中按名称显式请求子代理（例如，"使用代码审查员代理来..."）。

使用子代理的好处

上下文隔离

每个子代理在其自己的新对话中运行。中间工具调用和结果保留在子代理内部；只有其最终消息返回到父代理。请参阅子代理继承的内容以了解子代理上下文中的确切内容。

示例： research-assistant 子代理可以探索数十个文件，而这些内容都不会在主对话中累积。父代理收到的是简洁的摘要，而不是子代理读取的每个文件。

并行化

多个子代理可以并发运行，因此独立的子任务完成时间为最慢的一个，而不是所有任务的总和。

示例： 在代码审查期间，您可以同时运行 style-checker、security-scanner 和 test-coverage 子代理，而不是按顺序运行。

专门的指令和知识

每个子代理都可以有定制的系统提示词，具有特定的专业知识、最佳实践和约束。

示例： database-migration 子代理可以具有关于 SQL 最佳实践、回滚策略和数据完整性检查的详细知识，这些在主代理的指令中将是不必要的噪音。

工具限制

子代理可以限制为特定工具，降低意外操作的风险。

示例： doc-reviewer 子代理可能只能访问 Read 和 Grep 工具，确保它可以分析但永远不会意外修改您的文档文件。

创建子代理

使用 agents 参数直接在代码中定义子代理。此示例创建两个子代理：一个具有只读访问权限的代码审查员和一个可以执行命令的测试运行器。Claude 通过 Agent 工具调用子代理，因此在 allowedTools 中包含 Agent 以自动批准子代理调用，无需权限提示。

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(
# Auto-approve these tools, including Agent for subagent invocation
allowed_tools=["Read", "Grep", "Glob", "Agent"],
agents={
"code-reviewer": AgentDefinition(
# description tells Claude when to use this subagent
description="Expert code review specialist. Use for quality, security, and maintainability reviews.",
# prompt defines the subagent's behavior and expertise
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

Be thorough but concise in your feedback.""",
# tools restricts what the subagent can do (read-only here)
tools=["Read", "Grep", "Glob"],
# model overrides the default model for this subagent
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.

Focus on:
- Running test commands
- Analyzing test output
- Identifying failing tests
- Suggesting fixes for failures""",
# Bash access lets this subagent run test commands
tools=["Bash", "Read", "Grep"],
),
},
),
):
if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

AgentDefinition 配置

字段 类型 必需 描述
description string 是 何时使用此代理的自然语言描述
prompt string 是 代理的系统提示词，定义其角色和行为
tools string[] 否 允许的工具名称数组。如果省略，继承所有工具
disallowedTools string[] 否 要从代理的工具集中移除的工具名称数组。MCP 服务器级别的模式也被接受：mcp__server 或 mcp__server__* 移除来自该服务器的每个工具，mcp__* 移除来自任何服务器的每个 MCP 工具
model string 否 此代理的模型覆盖。接受别名，如 'fable'、'opus'、'sonnet'、'haiku'、'inherit'，或完整的模型 ID。如果省略，默认为主模型
skills string[] 否 在启动时预加载到代理上下文中的 skills 名称列表。未列出的 skills 仍可通过 Skill 工具调用
memory 'user' | 'project' | 'local' 否 此代理的内存源
mcpServers (string | object)[] 否 此代理可用的 MCP 服务器，按名称或内联配置
initialPrompt string 否 当此代理作为主线程代理运行时自动提交为第一个用户轮次。当代理作为子代理调用时忽略
maxTurns number 否 代理停止前的最大代理轮数
background boolean 否 调用时将此代理作为非阻塞后台任务运行
effort 'low' | 'medium' | 'high' | 'xhigh' | 'max' | number 否 此代理的推理工作量级别
permissionMode PermissionMode 否 此代理内工具执行的权限模式

在 Python SDK 中，这些字段名称使用 camelCase 以匹配线路格式。有关详细信息，请参阅 AgentDefinition 参考。

基于文件系统的定义（替代方案）

您也可以在 .claude/agents/ 目录中将子代理定义为 markdown 文件。有关此方法的详细信息，请参阅 Claude Code 子代理文档。以编程方式定义的代理优先于具有相同名称的基于文件系统的代理。

子代理继承的内容

子代理的上下文窗口从新开始（无父对话），但不是空的。从父代理到子代理的唯一通道是 Agent 工具的提示词字符串，因此请直接在该提示词中包含子代理需要的任何文件路径、错误消息或决策。

子代理接收 子代理不接收
其自己的系统提示词（AgentDefinition.prompt）和 Agent 工具的提示词 父代理的对话历史或工具结果
项目 CLAUDE.md（通过 settingSources 加载） 预加载的 skill 内容，除非在 AgentDefinition.skills 中列出
工具定义（从父代理继承，或 tools 中的子集） 父代理的系统提示词

调用子代理

自动调用

Claude 根据任务和每个子代理的 description 自动决定何时调用子代理。例如，如果您定义了一个 performance-optimizer 子代理，其描述为"用于查询调优的性能优化专家"，当您的提示词提到优化查询时，Claude 将调用它。

编写清晰、具体的描述，以便 Claude 可以将任务匹配到正确的子代理。

显式调用

要保证 Claude 使用特定的子代理，请在您的提示词中按名称提及它：

"Use the code-reviewer agent to check the authentication module"

这绕过自动匹配并直接调用命名的子代理。

动态代理配置

您可以根据运行时条件动态创建代理定义。此示例创建一个安全审查员，具有不同的严格级别，对严格审查使用更强大的模型。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition


# Factory function that returns an AgentDefinition
# This pattern lets you customize agents based on runtime conditions
def create_security_agent(security_level: str) -> AgentDefinition:
is_strict = security_level == "strict"
return AgentDefinition(
description="Security code reviewer",
# Customize the prompt based on strictness level
prompt=f"You are a {'strict' if is_strict else 'balanced'} security reviewer...",
tools=["Read", "Grep", "Glob"],
# Key insight: use a more capable model for high-stakes reviews
model="opus" if is_strict else "sonnet",
)


async def main():
# The agent is created at query time, so each request can use different settings
async for message in query(
prompt="Review this PR for security issues",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Grep", "Glob", "Agent"],
agents={
# Call the factory with your desired configuration
"security-reviewer": create_security_agent("strict")
},
),
):
if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

检测子代理调用

子代理通过 Agent 工具调用。要检测何时调用子代理，请检查 tool_use 块，其中 name 是 "Agent"。来自子代理上下文内的消息包含 parent_tool_use_id 字段。

消息结构在 SDK 之间有所不同。在 Python 中，内容块直接通过 message.content 访问。在 TypeScript 中，SDKAssistantMessage 包装 Claude API 消息，因此内容通过 message.message.content 访问。

此示例遍历流式消息，记录何时调用子代理以及后续消息何时源自该子代理的执行上下文。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition, ToolUseBlock


async def main():
async for message in query(
prompt="Use the code-reviewer agent to review this codebase",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Glob", "Grep", "Agent"],
agents={
"code-reviewer": AgentDefinition(
description="Expert code reviewer.",
prompt="Analyze code quality and suggest improvements.",
tools=["Read", "Glob", "Grep"],
)
},
),
):
# Check for subagent invocation. Match both names: older SDK
# versions emitted "Task", current versions emit "Agent".
if hasattr(message, "content") and message.content:
for block in message.content:
if isinstance(block, ToolUseBlock) and block.name in (
"Task",
"Agent",
):
print(f"Subagent invoked: {block.input.get('subagent_type')}")

# Check if this message is from within a subagent's context
if hasattr(message, "parent_tool_use_id") and message.parent_tool_use_id:
print("  (running inside subagent)")

if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

恢复子代理

子代理可以恢复以继续中断的地方。恢复的子代理保留其完整的对话历史，包括所有先前的工具调用、结果和推理。子代理从停止的地方继续，而不是重新开始。

当子代理完成时，Agent 工具结果包含一个包含 agentId: <id> 的文本块。内置的 Explore 和 Plan 代理 是一次性的，不返回 agentId，因此当您需要恢复时，请使用自定义代理或 general-purpose。要以编程方式恢复子代理：

  1. 捕获会话 ID：在第一个查询期间从消息中提取 session_id
  2. 提取代理 ID：从 Agent 工具结果文本中解析 agentId
  3. 恢复会话：在第二个查询的选项中传递 resume: sessionId，并在您的提示词中包含代理 ID

下面的示例定义了一个自定义 endpoint-finder 代理。第一个查询运行它并从 Agent 工具结果中捕获会话 ID 和代理 ID，然后第二个查询恢复会话以提出需要来自第一个分析的上下文的后续问题。

import asyncio
import re
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition, ToolResultBlock

AGENTS = {
"endpoint-finder": AgentDefinition(
description="Locates and catalogs API endpoints in a codebase.",
prompt="You find and document API endpoints. Report each endpoint's path, method, and handler.",
tools=["Read", "Grep", "Glob"],
)
}


def extract_agent_id(block: ToolResultBlock) -> str | None:
"""Extract agentId from an Agent tool result's text content."""
parts = block.content if isinstance(block.content, list) else [{"text": block.content}]
for part in parts:
if match := re.search(r"agentId:\s*([\w-]+)", part.get("text") or ""):
return match.group(1)
return None


async def main():
agent_id = None
session_id = None

# First invocation - run the endpoint-finder subagent
async for message in query(
prompt="Use the endpoint-finder agent to find all API endpoints in this codebase",
options=ClaudeAgentOptions(allowed_tools=["Read", "Grep", "Glob", "Agent"], agents=AGENTS),
):
# Capture session_id from ResultMessage (needed to resume this session)
if hasattr(message, "session_id"):
session_id = message.session_id
# Search tool results for the agentId trailer
for block in getattr(message, "content", None) or []:
if isinstance(block, ToolResultBlock):
agent_id = extract_agent_id(block) or agent_id
# Print the final result
if hasattr(message, "result"):
print(message.result)

# Second invocation - resume and ask follow-up
if agent_id and session_id:
async for message in query(
prompt=f"Resume agent {agent_id} and list the top 3 most complex endpoints",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Grep", "Glob", "Agent"], agents=AGENTS, resume=session_id
),
):
if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

子代理记录独立于主对话而持久存在：

  • 主对话压缩：当主对话压缩时，子代理记录不受影响。它们存储在单独的文件中。
  • 会话持久性：子代理记录在其会话内持久存在。您可以通过恢复同一会话在重启 Claude Code 后恢复子代理。
  • 自动清理：记录根据 cleanupPeriodDays 设置进行清理（默认：30 天）。

工具限制

子代理可以通过 tools 字段具有受限的工具访问：

  • 省略该字段：代理继承所有可用工具（默认）
  • 指定工具：代理只能使用列出的工具

此示例创建一个只读分析代理，可以检查代码但无法修改文件或运行命令。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition


async def main():
async for message in query(
prompt="Analyze the architecture of this codebase",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Grep", "Glob", "Agent"],
agents={
"code-analyzer": AgentDefinition(
description="Static code analysis and architecture review",
prompt="""You are a code architecture analyst. Analyze code structure,
identify patterns, and suggest improvements without making changes.""",
# Read-only tools: no Edit, Write, or Bash access
tools=["Read", "Grep", "Glob"],
)
},
),
):
if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

常见工具组合

用例 工具 描述
只读分析 Read、Grep、Glob 可以检查代码但不能修改或执行
测试执行 Bash、Read、Grep 可以运行命令并分析输出
代码修改 Read、Edit、Write、Grep、Glob 完整的读/写访问，无命令执行
完全访问 所有工具 从父代理继承所有工具（省略 tools 字段）

使用动态工作流进行扩展

子代理适用于每轮委派的几个任务。对于协调数十到数百个代理的运行，请使用 Workflow 工具，它将编排移到运行时在对话上下文外执行的脚本中。请参阅动态工作流以了解工作流与逐轮子代理委派的区别。

Workflow 工具在 TypeScript Agent SDK v0.3.149 及更高版本中可用。在 allowedTools 中包含 Workflow 以自动批准工作流运行。工具输入和输出架构列在 TypeScript 参考中。

故障排除

Claude 不委派给子代理

如果 Claude 直接完成任务而不是委派给您的子代理：

  1. 检查 Agent 调用是否被批准：在 allowedTools 中包含 Agent 以自动批准子代理调用。如果没有它，Agent 调用将转到您的 canUseTool 回调，或在 dontAsk 模式下被拒绝
  2. 使用显式提示：在您的提示词中按名称提及子代理（例如，"使用代码审查员代理来..."）
  3. 编写清晰的描述：准确解释何时应使用子代理，以便 Claude 可以适当地匹配任务

基于文件系统的代理未加载

在 .claude/agents/ 中定义的代理仅在启动时加载。如果在 Claude Code 运行时创建新的代理文件，请重启会话以加载它。

Windows：长提示词失败

在 Windows 上，具有非常长提示词的子代理可能因命令行长度限制（8191 个字符）而失败。保持提示词简洁或使用基于文件系统的代理来处理复杂指令。