Skip to main content

子智能体

在概览层面梳理 Claude Code 子智能体的概念、隔离上下文委派与定义方法。

更新 2026-08-10 6 分钟阅读 在 GitHub 上编辑 ↗

子智能体

Claude Code 的子智能体是在独立的上下文窗口中处理旁支任务、只把结果摘要返回主对话的委派工作者。

背景参考
本页是关于 Claude Code 本身 的背景资料，也就是 MoAI-ADK 所依托的平台。MoAI-ADK 的使用方法请见 智能体指南，亲手创建智能体的实战流程则在构建者智能体指南中继续展开。
信息
一句话总结：子智能体在自己的上下文中处理探索·验证这类旁支工作、只返回摘要，是让主对话保持干净的委派帮手。
用比喻理解
子智能体是用自己书桌的同事。把会弄乱我书桌（主对话上下文）的大量调查·日志·搜索结果交给同事，他会在自己的书桌上处理，只递给我一页结果摘要。这样我的书桌保持干净，我也能只专注于核心脉络。

什么是子智能体

子智能体是专责某类工作的特化 AI 工作者。当出现会让主对话被搜索结果、日志、文件内容淹没的旁支任务时，那项工作由子智能体在自己的上下文窗口 (own context window) 中处理，只把结果摘要送回。

每个子智能体独立拥有以下要素。

组成要素说明
系统提示子智能体文件的正文直接充当角色指令
工具访问权限可用允许/拦截列表限制可用工具
独立权限继承主对话权限，并可施加额外限制
模型选择可选 haiku 这类快而便宜的模型降低成本

Claude 通过查看各子智能体的 description 判断何时委派。因此把说明写清楚，就是良好委派的起点。

Claude Code 包含以下内置子智能体。

智能体特点
Explore只读代码库探索 (自 CC 2.1.198 起继承主会话模型，上限为 opus — 此前固定为 Haiku)；thoroughness 选项可选 quick/medium/very-thorough
Plan规划模式调研 (只读)
general-purpose全工具访问，既可探索又可修改

Explore 与 Plan 跳过主会话的 CLAUDE.md 和 git status，运行得更快更轻。

核心约束：子智能体不能孵化子智能体

最初的结构性约束是子智能体不能孵化其他子智能体 (subagents cannot spawn other subagents) — 委派只从主对话下沉一级。此后默认值已改变（见下文），扁平层级如今是配置选择而非运行时保证。

v2.1.219 之后：嵌套默认启用（深度 3）

嵌套于 v2.1.172 引入，在 v2.1.217–2.1.218 短暂默认关闭后，自 v2.1.219 起默认启用 — 按变更日志，子智能体默认可嵌套孵化至深度 3。要禁用嵌套，请设置 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1。

配置行为使用
子智能体定义中含 Agent（frontmatter tools: 列表）允许嵌套默认最深至深度 3（按变更日志）；CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 可调整，=1 为禁用
省略 Agent 工具禁止嵌套扁平编排 — 唯一的扁平层级保证

这一约束也是 MoAI-ADK 编排设计的根基。只有编排器（主会话）能调用子智能体，被调用的智能体在未触及深度上限时可再向他人委派。因此采用编排器直接调用每个阶段的扁平结构，而非层级式智能体链（MoAI 的基本原则）。

flowchart TD
    M[主对话
编排器] --> A[子智能体 A
探索]
    M --> B[子智能体 B
验证]
    M --> C[子智能体 C
实现]
    A -.->|条件: 有 Agent 工具时
默认至深度3| X["嵌套子智能体
(受限)"]
    style X fill:#ffd,stroke:#c80

内置 Plan 子智能体单独存在的原因也在于此 —— 计划模式需要上下文时，在不绕过这一约束的前提下执行调研。

后台权限提示 (v2.1.186)

以后台运行子智能体（background: true）时，遇到需要权限的工具（例如 Bash、WebFetch）：

  • v2.1.186 之前：自动拒绝（无权限提示）
  • v2.1.186 之后：提示显示在主会话中（按 Esc 可仅拒绝该次调用）

因此在启动长时间后台任务之前，最好预先把所需工具加入 settings.json 的允许列表。

何时使用

子智能体在以下情形效果最大。

情形效果
并行探索同时调查多个文件·目录，只收集摘要
独立验证不受主对话偏见影响，在独立上下文中核查结果
上下文隔离把大量日志·搜索结果隔离在主对话之外
成本控制把简单任务路由到 haiku 这类快速模型

反之，若是一次回应就能完成的工作，或是跨多个步骤需要共享上下文的工作，不委派、在主对话中直接处理更好。

定义方法概览

子代理通过带有 YAML 前置元数据的 Markdown 文件来定义。既可以用 /agents 命令交互式生成，也可以直接手写文件。（CC 2.1.198 移除了 /agents 创建向导 — 让 Claude 代劳或直接编辑 .claude/agents/；官方文档中截至 2026-07 /agents 界面仍存在，请在实际 2.1.198 会话中确认。）

markdown 
---
name: code-reviewer
description: 评审代码质量与最佳实践
tools: Read, Glob, Grep
model: sonnet
---

你是代码评审员。被调用时分析代码，
就质量·安全·最佳实践给出具体且可执行的反馈。

必填字段

  • name —— 子智能体名称（委派时引用）
  • description —— 说明何时应当委派（Claude 仅凭此判断）

可选字段

字段功能
tools允许的工具（逗号分隔列表）
disallowedTools拦截的工具（可代替允许列表使用）
model模型选择：sonnet、opus、haiku、fable，或特定模型 ID；默认值 inherit（主会话模型）
permissionMode工具权限默认值（default、plan、acceptEdits、bypass）
maxTurns最大回合数限制
skills要加载的默认技能
mcpServers要连接的 MCP 服务器
hooks要调用的 Hook 事件
memory记忆范围（user、project、local）
background为 true 时后台运行
effort推理强度（low、medium、high、xhigh、max）
isolation: worktree在隔离的仓库副本中工作
color智能体视图中显示的颜色
initialPrompt子智能体首次孵化时的提示词

存放位置决定适用范围。

位置范围
.claude/agents/当前项目（纳入版本管理与团队共享）
~/.claude/agents/我的所有项目
插件的 agents/插件被启用之处

不能使用 AskUserQuestion

AskUserQuestion 这类用户交互工具不能在子智能体中使用（非对称边界）。这就是在 MoAI-ADK 中子智能体不能直接向用户提问、而是向编排器返回 blocker report 的原因。

/fork —— 会话分叉

可用 /fork <directive> 命令分叉当前会话。被分叉的子智能体：

  • 继承当前对话内容
  • 利用父级的提示缓存
  • 朝新方向探索

深入请看 MoAI 智能体指南

以上是 Claude Code 层面的子智能体概念。MoAI-ADK 在这套机制之上运营11 个智能体的目录 —— Manager 系列（manager-spec / manager-develop / manager-docs / manager-git / manager-design）负责 plan→run→sync 生命周期，Evaluator 系列（plan-auditor / sync-auditor）负责独立审计，builder-harness 负责生成挽具脚手架，super-advisor 负责高推理咨询，e2e-tester 负责网页/移动/桌面的 E2E 测试执行，Anthropic 内置的 Explore 负责只读探索。计划与审计相互分离 —— 制造者不自我检查 —— 是这份目录的核心设计。为每个智能体声明式地分配契合工作性质的模型与推理深度 (effort)，正是代币经济学"计划要深、实现要省、验证要独立"的原则。详情见下方的深入指南。

相关文档

参考资料

提示
创建子智能体时，请从"何时应当委派"的角度把 description 写具体。Claude 仅凭这段说明判断是否委派，说明含糊的话，再好的工具也不会被调用。