AgentTool 解析

定位

AgentTool 是把“启动一个子 agent”这件事包装成标准 tool interface 的模块。

文件：

• src/tools/AgentTool/AgentTool.tsx

关键判断

AgentTool 是 Tool，不是特殊内核入口

它通过 buildTool({...}) 构建，和其他工具遵守同一套接口：

• call()
• description()
• checkPermissions()
• mapToolResultToToolResultBlockParam()
• UI render methods

这说明 agent 调用从架构上被降维成了“一个可调工具”。

输入参数（核心）

• description
• prompt
• subagent_type
• model
• run_in_background
• name
• team_name
• mode
• isolation
• cwd

这些参数本质上共同定义了：

• 任务内容
• agent 类型
• 执行策略
• 隔离环境
• 权限与会话策略

call() 的主要职责

1. 解析这是不是 teammate spawn

如果同时带 team_name 和 name，可能会进入 spawnTeammate() 路径。

2. 解析是不是 fork path

当 subagent_type 为空并且 fork gate 开启时，走 fork 逻辑。

fork 的特点是：

• 继承父上下文
• 继承父 system prompt
• 继承父 exact tool pool
• 目的是最大化 prompt cache 命中

3. 解析是否走 remote

如果 effectiveIsolation === 'remote'，则：

• 检查 remote eligibility
• teleportToRemote()
• registerRemoteAgentTask()

4. 解析同步 / 异步

如果满足后台条件：

• run_in_background === true
• agent 定义要求 background
• fork experiment 强制 async
• 某些 mode 强制 async

则注册后台任务并异步运行；否则同步运行。

与 runAgent 的关系

AgentTool.call() 不直接实现 agent loop。 它的主要职责是：

• 做路由决策
• 做上下文 / tool pool / worktree / metadata 准备
• 最终调用 runAgent()

输出策略

异步 agent

返回 async_launched，告诉父 agent：

• agentId
• outputFile
• 不要重复干它正在干的事
• 完成后会自动通知

同步 agent

收集完整 agent 输出后，拼装成 completed 结果。

remote agent

返回 remote_launched，带 taskId / sessionUrl / outputFile

关键设计取舍

优点

• 把复杂 agent 调度统一包进 Tool 框架
• 同步 / 异步 / remote / fork 都走统一入口
• 容易被主循环分发和权限系统接管

代价

• AgentTool.call() 很重，职责很多
• 分支多，容易膨胀成超大 orchestrator 文件

待继续阅读

• agentToolUtils.ts
• forkSubagent.ts
• runAgent.ts