AgentTool：子 Agent 调度器

AgentTool 是 Claude Code 的核心调度组件，它将“任务拆分、子 Agent 执行与生命周期管理”封装为正式工具，标志着该框架从单线程代码助手向多任务 Agent 系统的架构升级。它通过受控的派发机制、独立的上下文裁剪与完整的工作流绑定，解决了复杂任务场景下的并行处理与主线程上下文污染问题。

AgentTool 是 Claude Code 最有代表性的工具之一。它解决的不是“读文件”或者“跑命令”这种单点能力，而是：

当主线程模型觉得一个任务太大、太杂、太适合并行时，如何把一部分工作拆给另一个 Agent 去做。

这也是 Claude Code 和普通代码助手的核心分水岭之一。很多 AI 工具只有一个主线程模型一直往下跑，而 Claude Code 明确支持：

• 研究型子任务
• 后台执行
• 多 Agent 协作
• 本地 / 远程子 Agent

tools/AgentTool/AgentTool.tsx 一上来就把核心参数暴露出来了：

const baseInputSchema = z.object({
  description: z.string().describe('A short (3-5 word) description of the task'),
  prompt: z.string().describe('The task for the agent to perform'),
  subagent_type: z.string().optional(),
  model: z.enum(['sonnet', 'opus', 'haiku']).optional(),
  run_in_background: z.boolean().optional(),
})

这几个字段已经很说明它的定位：

• description：给子任务一个简短标题
• prompt：真正交给子 Agent 的工作内容
• subagent_type：选择专门类型的 Agent
• model：必要时换模型
• run_in_background：放后台跑

也就是说，AgentTool 本质上是一个任务派发器。

在 Claude Code 的总工具池里，它被放在最前面：

export function getAllBaseTools(): Tools {
  return [
    AgentTool,
    TaskOutputTool,
    BashTool,
    ...
  ]
}

这不一定代表“最常调用”，但说明 Anthropic 把它视为第一层核心能力。因为一旦有了 AgentTool，其他工具就不再只是“主线程自己用”，而是可以被子 Agent 继续调用。

它在系统里的位置：

看 AgentTool.tsx 的导入就能看出来，这个工具背后其实串着很多子系统：

import { enhanceSystemPromptWithEnvDetails, getSystemPrompt } from '../../constants/prompts.js'
import { assembleToolPool } from '../../tools.js'
import { runAgent } from './runAgent.js'
import { registerAsyncAgent } from '../../tasks/LocalAgentTask/LocalAgentTask.js'
import { registerRemoteAgentTask } from '../../tasks/RemoteAgentTask/RemoteAgentTask.js'

这意味着 AgentTool 至少做了 4 件事：

1. 重新生成子 Agent 的 system prompt
2. 重新裁剪一套工具池
3. 决定是本地任务还是远程任务
4. 把子 Agent 挂到任务系统里

所以它的真实含义更接近：

用 Claude Code 的运行时框架，再启动一个受控的、带任务上下文的工作线程

如果只是简单 fork 一个模型，系统很快就会失控。Claude Code 通过几层机制约束它：

• 子 Agent 有自己的输入 schema
• 子 Agent 会重新组装 prompt
• 子 Agent 的工具池是单独过滤的
• 子 Agent 会被挂进任务系统，支持状态、输出、停止、通知

所以 AgentTool 不是一个“自由分身器”，而是一个受控派单器。

调用链可进一步细看：

Claude Code 不是让子 Agent 偷偷在后台跑，而是把它们做成了正式任务：

• 可查看输出
• 可后台执行
• 可停止
• 可恢复

这就是为什么 AgentTool 后面紧跟着就是 TaskOutputTool。两者天然是一组：

• AgentTool 负责派活
• TaskOutputTool 负责取结果

可以把一个典型路径理解成这样：

1. 主线程发现“这个问题需要深入查某个子系统”
2. 主线程调用 AgentTool
3. 子 Agent 自己去搜索、读文件、推理、执行
4. 子 Agent 给出压缩后的结论
5. 主线程拿这个结论继续向前推进

这和“主线程自己执行所有搜索”相比，最大的优势是：

• 减少主上下文污染
• 容易并行
• 更适合做重研究、重排查类任务

• 和 TaskOutputTool 配合：读取子 Agent 输出
• 和 SendMessageTool 配合：多 Agent 模式下互相通信
• 和 BashTool、Read、Edit 配合：子 Agent 自己继续完成任务
• 和 SkillTool 配合：某些 skill 会在独立子 Agent 中执行

不是。 它是明确的工具调用，带 schema、任务生命周期和结果回注。

也不是。 子 Agent 的 prompt、工具池、运行模式都可能不同。

不够准确。 它更像“把另一个 Agent 作为正式运行时对象挂进系统”。

• AgentTool 不是单点能力工具，而是 Claude Code 封装任务拆分、子进程执行与生命周期管理的调度中枢。
• 通过独立 schema、prompt 重裁、工具池隔离与 Task 系统绑定，子 Agent 被严格约束为受控派单对象，而非自由分身。
• 与 TaskOutputTool 天然成对，形成“主线程派发 → 上下文隔离处理 → 结果回流”的标准化工作流。
• 核心业务价值在于降低主上下文污染、开启原生并行能力，为研究型与重排查类任务提供架构级支撑。