AgentTool — 代理工具详解#

AgentTool 是一个 面向 Agent 的增强工具接口，提供了：

UI 友好的展示（label）
参数容错（prepareArguments）
可中断、可流式更新的执行（execute 的 signal 和 onUpdate）
细粒度并发控制（executionMode）

它与 AgentState 中的 tools 数组紧密结合，并且浅拷贝策略让工具对象自身可以安全地在外部被修改，同时数组结构本身受 setter 保护。

AgentTool（代理的工具）— “五要素法”#

一个工具包含这五样东西：

label — 显示名字（给人看的，如”查天气”)
prepareArguments（可选）— 参数预处理（模型给的参数不标准时，你帮他修一下）
execute — 真正干活的方法（核心！）
executionMode（可选）— 执行模式（串行还是并行）
还从基础 Tool 继承 name 和 schema（工具标识和参数格式）

`execute` 的参数（四个参数）#

toolCallId — 这次调用的唯一ID
params — 校验后的参数（类型安全）
signal — 取消信号（可以中途停止）
onUpdate — 进度回调（干到一半时回报）

记忆口诀：名标预执模，干活传四宝（ID、参数、信号、回调）。

五要素详解#

1. 显示名称：`label`#

UI 友好的展示名称，给人看的。例如：

“查天气”
“搜索文件”
“执行命令”

2. 参数预处理：`prepareArguments`（可选）#

当模型生成的参数不完全符合预期时，预处理函数可以修正：

缺失的默认值
类型转换（如字符串转数字）
参数补全（如添加上下文相关的隐式参数）

3. 执行方法：`execute`（核心）#

真正干活的方法，支持四个参数：

参数详解：

参数	类型	作用
`toolCallId`	`string`	本次调用的唯一标识符
`params`	`Record<string, any>`	经校验和预处理后的参数
`signal`	`AbortSignal`	取消信号，用于中断执行
`onUpdate`	`(update: any) => void`	进度回调，流式输出中间结果

4. 执行模式：`executionMode`（可选）#

细粒度并发控制：

"sequential" — 串行执行，必须等前一个工具完成
"parallel" — 并行执行，多个工具同时执行（默认）

5. 基础属性：`name` 和 `schema`#

从基础 Tool 接口继承：

name — 工具的唯一标识符（字符串）
schema — 参数格式定义（Schema 对象）

可中断执行机制#

signal 参数提供中断能力：

1
async function execute(
2
  toolCallId: string,
3
  params: Record<string, any>,
4
  signal: AbortSignal,
5
  onUpdate: (update: any) => void
6
) {
7
  // 检查是否已取消
8
  if (signal.aborted) {
9
    throw new Error('Tool execution aborted');
10
  }
11

12
  // 长时间操作时定期检查
13
  for (const chunk of dataStream) {
14
    if (signal.aborted) break;
15
    // 处理数据
16
    onUpdate({ progress: '50%' });
17
  }
18
}

流式进度更新#

onUpdate 回调支持实时反馈：

1
// 执行过程中汇报进度
2
onUpdate({
3
  stage: 'downloading',
4
  progress: 30,
5
  message: '正在获取数据...'
6
});
7

8
// 完成时返回结果
9
onUpdate({
10
  stage: 'complete',
11
  result: finalResult
12
});

与 AgentState 的集成#

AgentTool 放在 AgentState.tools 数组中：

集成点	说明
数组防护	State 的 setter 会浅拷贝 tools 数组
并发控制	`executionMode` 决定该工具与其他工具的执行顺序
状态追踪	`pendingToolCalls` Set 记录执行中的工具 ID

一句话对比#

AgentState：代理的”状态卡”，记着配置、聊天记录和正在干嘛。
AgentTool：代理的”技能卡”，写着技能叫什么、怎么准备参数、怎么执行、能否并行。

与其他核心类型的关系#

类型	关系	交互点
`AgentState`	容器关系	tools 数组的元素
`AgentLoopConfig`	配置关系	beforeToolCall / afterToolCall 钩子控制执行
`AgentMessage`	结果记录	工具执行结果写入对话历史

完整工作流：

1
用户请求 → AgentState（tools列表）
2
         → AgentLoopConfig（beforeToolCall）
3
         → AgentTool.execute
4
         → AgentLoopConfig（afterToolCall）
5
         → AgentState（messages记录）

音乐

音乐

AgentTool — 代理工具详解#

AgentTool（代理的工具）— “五要素法”#

`execute` 的参数（四个参数）#

五要素详解#

1. 显示名称：`label`#

2. 参数预处理：`prepareArguments`（可选）#

3. 执行方法：`execute`（核心）#

4. 执行模式：`executionMode`（可选）#

5. 基础属性：`name` 和 `schema`#

可中断执行机制#

流式进度更新#

与 AgentState 的集成#

一句话对比#

与其他核心类型的关系#

支持与分享

音乐

文章目录

音乐

音乐

AgentTool 代理工具详解

AgentTool — 代理工具详解#

AgentTool（代理的工具）— “五要素法”#

execute 的参数（四个参数）#

五要素详解#

1. 显示名称：label#

2. 参数预处理：prepareArguments（可选）#

3. 执行方法：execute（核心）#

4. 执行模式：executionMode（可选）#

5. 基础属性：name 和 schema#

可中断执行机制#

流式进度更新#

与 AgentState 的集成#

一句话对比#

与其他核心类型的关系#

支持与分享

音乐

文章目录

`execute` 的参数（四个参数）#

1. 显示名称：`label`#

2. 参数预处理：`prepareArguments`（可选）#

3. 执行方法：`execute`（核心）#

4. 执行模式：`executionMode`（可选）#

5. 基础属性：`name` 和 `schema`#