工具调用：一条 echo 请求怎样变成配对结果

#你将得到什么

第 05 章结束时，模型已经能提出一条完整的 ToolCall。这一章切换到局部的 echo fixture， 用最短工具观察 schema、Registry 和 executor：

const echoCall: ToolCall = {
  type: "toolCall",
  id: "call-1",
  name: "echo",
  arguments: {
    value: "Pi",
    ignored: "drop me",
  },
};

这条对象记录了模型的请求：调用 echo，把 "Pi" 交给它。id: "call-1" 会一路 进入执行结果，让下一轮模型知道结果回答的是哪次调用。它不延续第 05 章的 README Provider 运行；两章只复用“结果沿用原 call id”这条配对规则。

完成这一章后，下面的调用会正常返回：

const result = await executeToolCall(echoCall, tools);

忽略每次运行都会变化的 timestamp，result 是：

{
  role: "toolResult",
  toolCallId: "call-1",
  toolName: "echo",
  content: [{ type: "text", text: "Pi" }],
  details: { source: "echo" },
  isError: false,
}

模型传来的 ignored 没有进入工具参数，也没有进入结果。echo 只收到 schema 声明的 字段 { value: "Pi" }。

这条成功路径经过三个对象：schema 检查参数，ToolRegistry 找到本次运行允许使用的 工具，executeToolCall() 按顺序调用它们并生成 ToolResultMessage。

echoCall
  id=call-1, name=echo
  arguments={ value: "Pi", ignored: "drop me" }
        │
        ▼
tools.get("echo")
        │
        ▼
echo.schema.parse(arguments)
  → { value: "Pi" }
        │
        ▼
echo.execute({ value: "Pi" })
  → content=[text("Pi")], details={ source: "echo" }
        │
        ▼
ToolResultMessage
  toolCallId=call-1, toolName=echo, isError=false

随后我们会改变这条调用的参数或查找结果，观察参数错误、未知工具和工具异常怎样得到 同一种配对结果。先把正常路径中的三个部件建立起来。

实现只修改：

packages/pi-course/src/tool.ts

#echo 同时带着描述和可执行函数

先写出刚才使用的 echo。它有名称、给模型看的说明、参数 schema 和本地执行函数：

const echoSchema = objectSchema({
  value: stringValue,
});

const echo: Tool<{ value: string }, { source: string }> = {
  name: "echo",
  description: "Echo one value",
  schema: echoSchema,
  async execute({ value }) {
    return {
      content: [text(value)],
      details: { source: "echo" },
    };
  },
};

const tools = new ToolRegistry([echo]);

模型无法直接调用 execute。Provider 只会收到 name、description 和参数的 JSON Schema。真正执行时，程序从同一个 Registry 中找到 echo，调用 echo.schema.parse()，再把解析后的值交给 echo.execute()。

echo.execute() 除了参数，还会收到本次调用的身份与控制信号；它返回给 executor 的对象 则同时携带模型正文和程序细节。先把这两个对象写完整：

export interface ToolContext {
  callId: string;
  signal?: AbortSignal;
  reportProgress?(content: TextContent[]): void;
}

export interface ToolOutput<D = unknown> {
  content: TextContent[];
  details?: D;
  isError?: boolean;
}

执行开头的 echoCall 时，ToolContext.callId 是 "call-1"。signal 与 reportProgress 由调用者按需提供。echo 返回的 content 是 [text("Pi")]，D 则把 details 的类型固定为 { source: string }；省略 isError 表示 executor 最后写入 false。

Tool 把 Provider 可见的描述、运行时 schema 和本地函数放在同一个对象里：

export interface Tool<P, D = unknown> {
  name: string;
  description: string;
  schema: Schema<P>;
  execute(
    parameters: P,
    context: ToolContext,
  ): Promise<ToolOutput<D>>;
}

P 是工具真正接收的参数类型，D 是 details 的类型。模型生成的 ToolCall.arguments 仍是 unknown；只有 schema.parse() 成功后，executor 才得到 P，也只有 execute() 返回后才得到 ToolOutput<D>。

这条调用要保持一个配对规则：executor 收到 call-1/echo，无论成功还是失败，返回的 消息都继续使用 toolCallId: "call-1" 和 toolName: "echo"。结果可以报告错误，但 不能让原调用从 transcript 中悬空。

#同一个 schema 做两件不同的事

把 echoSchema 展开，可以看到两种能力：

export interface Schema<T> {
  parse(value: unknown): T;
  jsonSchema?: Record<string, unknown>;
}

jsonSchema 会进入第 05 章的 Provider 请求。parse() 留在本地，executor 每次执行 前都会调用它。前者告诉模型应该生成什么，后者检查模型实际生成了什么。

对于只接收 value: string 的 echo，模型看到的定义是：

{
  type: "object",
  properties: {
    value: { type: "string" },
  },
  required: ["value"],
  additionalProperties: false,
}

这份描述能引导模型生成 { "value": "Pi" }。模型输出仍来自进程外，程序不能因为 请求里已经带过 schema 就跳过运行时检查。

同一个 echoSchema 收到开头的 arguments：

echoSchema.parse({
  value: "Pi",
  ignored: "drop me",
});

输出是一个新对象：

{ value: "Pi" }

parse() 只遍历 schema 声明的字段，因此 ignored 被过滤。原始 arguments 没有被 修改。echo.execute() 只会看到返回的新对象。

#validator 是可调用函数，也是带元数据的对象

echoSchema 的 shape 写成 { value: stringValue }。objectSchema() 既要调用 stringValue 检查实际字段，也要读取它的 JSON Schema 和可选标记。Validator<T> 因而 是函数类型与元数据对象的交叉类型：

export type Validator<T> = ((value: unknown) => T) & {
  jsonSchema?: Record<string, unknown>;
  optional?: boolean;
};

& 表示同一个值同时满足两边：它可以像函数一样接收 unknown 并返回 T，也可以通过 属性暴露 jsonSchema 与 optional。stringValue 就是这样一个值：

export const stringValue: Validator<string> = Object.assign(
  (value: unknown) => {
    if (typeof value !== "string") {
      throw new Error("必须是 string");
    }
    return value;
  },
  { jsonSchema: { type: "string" } },
);

连续观察它的三个表面：

console.log(stringValue("Pi"));
console.log(JSON.stringify(stringValue.jsonSchema));
console.log(stringValue.optional);

Pi
{"type":"string"}
undefined

第一行执行 validator，得到经过检查的字符串。第二行读取同一个值上的 Provider 描述。 第三行是 undefined，所以 objectSchema() 会把 value 放进 required。

类型推导也从这份 shape 开始。把实现体折叠后，objectSchema() 的签名逐个取得 validator 的 ReturnType：

export declare function objectSchema<
  TShape extends Record<string, Validator<unknown>>,
>(shape: TShape): Schema<{
  [TKey in keyof TShape]: ReturnType<TShape[TKey]>;
}>;

对 { value: stringValue } 来说，键仍是 value，而 ReturnType<typeof stringValue> 是 string，所以 echoSchema.parse() 的结果类型是 { value: string }。这正是前面 Tool<{ value: string }> 中的参数类型。

课程还提供两个可选字段 validator：

const requestSchema = objectSchema({
  value: stringValue,
  label: optionalString,
  limit: optionalPositiveInteger,
});

optionalString 接受字符串或 undefined。optionalPositiveInteger 接受大于等于 1 的 整数或 undefined。两者的 .optional 都是 true，所以 label 和 limit 不进入 JSON Schema 的 required 数组；它们的返回类型也分别进入最终对象。

用测试中的完整值调用 parse()：

requestSchema.parse({
  value: "Pi",
  label: "answer",
  limit: 2,
  ignored: "drop me",
});

得到：

{
  value: "Pi",
  label: "answer",
  limit: 2,
}

省略可选字段时，返回对象保留字段名，值为 undefined。null、数组、value: 1 和 limit: 0 分别在对象检查或字段 validator 中被拒绝。

这时推导结果是 { value: string; label: string | undefined; limit: number | undefined }。 练习脚手架已经声明上述类型关系；Lab 6.1 只需完成运行时遍历和 JSON Schema 生成。

npm run build -w @pi/course
node --test --test-name-pattern="validator" \
  packages/pi-course/dist/test/06-*.test.js

#Registry 保存这一次允许使用的工具

创建 new ToolRegistry([echo]) 后，这个 Registry 只包含一项允许动作：echo。 它使用自己的 Map<string, Tool> 保存对象，不写入模块级全局变量。

tools
  "echo" → echo Tool

调用者可以为另一个产品入口创建不同的 Registry，例如只注册 read，或者同时注册 echo 和 upper。两个实例不会共享工具。Registry 因而明确了交给这次运行的动作 空间。

四个方法分别提供不同视角：

tools.definitions() 不包含 execute。函数不能进入网络请求，模型也不需要看到本地 实现。对开头的 echo，它返回：

[
  {
    name: "echo",
    description: "Echo one value",
    parameters: {
      type: "object",
      properties: { value: { type: "string" } },
      required: ["value"],
      additionalProperties: false,
    },
  },
]

Registry 不会自己调用模型。本章已有的 tools 可以先交出这份 Provider 输入：

const availableTools = tools.definitions();

availableTools 就是上面显示的数组，类型为 ToolDefinition[]。它可以直接成为第 05 章 AgentContext.tools 的值，再由 Provider adapter 翻译成 wire tools。第 07 章会用同一个 tools 构造实际模型请求；这里先固定 Registry 交出的对象，不提前引入尚未出现的 model、options 或局部消息数组。

tools.get("echo") 则返回完整的 echo 对象，包括同一份 schema 和 execute()。模型 可见的定义与 executor 能找到的实现由同一张表产生。

重复注册 echo 会抛出 Tool 已存在：echo。静默覆盖会让 Provider 已经看到的定义与 真正执行的函数在运行中发生变化，所以 Registry 在写入前检查名称。

工具没有提供 jsonSchema 时，definitions() 使用 { type: "object" } 作为最小 参数描述。objectSchema() 会提供前面看到的精确版本。

npm run build -w @pi/course
node --test --test-name-pattern="Registry" \
  packages/pi-course/dist/test/06-*.test.js

#executor 按固定顺序完成 echoCall

schema 与 Registry 准备好后，executeToolCall() 负责一次完整调用：

export async function executeToolCall(
  call: ToolCall,
  registry: ToolRegistry,
  context: Omit<ToolContext, "callId"> = {},
): Promise<ToolResultMessage>

开篇的 executeToolCall(echoCall, tools) 省略第三个参数，所以 context 使用空对象。调用者 要传取消或进度回调时，它才携带 signal 与 reportProgress。

1. registry.get(call.name)
2. tool.schema.parse(call.arguments)
3. tool.execute(parsed, { ...context, callId: call.id })
4. 把 ToolOutput 写成 ToolResultMessage

第一步找到开头注册的 echo。第二步把 { value: "Pi", ignored: "drop me" } 变成 { value: "Pi" }。第三步才进入 echo.execute()，所以工具产生副作用之前已经拿到经过检查的参数。

ToolContext 还会把调用身份和运行控制交给工具：

{
  ...context,
  callId: call.id,
}

外部 context 可以携带 signal 和 reportProgress。executor 原样传递它们，并在最后 写入 callId，因此调用者不能用 context 覆盖模型的 call id。signal 到达工具只说明 取消请求已经传递；工具仍要主动观察 signal，才能及时停止自己的工作。

#content 给模型，details 给程序

echo 返回的 ToolOutput 是：

{
  content: [{ type: "text", text: "Pi" }],
  details: { source: "echo" },
}

executor 保留这两个字段。content 会作为 ToolResultMessage 的正文进入下一轮模型 上下文；details 保存 UI、日志或调用方需要的结构化信息。模型不需要读取 details 才能理解结果，程序也不必从正文 "Pi" 中反向解析来源。

工具可以显式返回 isError: true 表示领域失败，同时提供有用的 content 和 details。 这条路径没有抛异常。工具省略 isError 时，executor 写入 false。

测试中的 inspect 工具展示了完整 context。它收到 callId: "ctx"、同一个 signal 和 同一个 progress callback，先报告 progress:Pi，再返回：

{
  content: [text("done:Pi")],
  details: { phase: "domain-error" },
  isError: true,
}

这些值全部进入最终 ToolResultMessage；executor 不会因为 isError: true 丢掉 output。

#三种失败仍然回答原调用

成功路径已经闭合。现在分别替换 echoCall 的一个条件，观察 executor 停在哪一步。

#参数类型错误：parse 拦在 execute 前

把 arguments 改为：

{ value: 1 }

Registry 仍能找到 echo，stringValue 随后抛出 必须是 string。echo.execute() 没有 运行，executor 返回：

{
  role: "toolResult",
  toolCallId: "call-1",
  toolName: "echo",
  content: [text("Tool echo failed: 必须是 string")],
  details: { error: "必须是 string" },
  isError: true,
}

#未知工具：查找结束后不再解析

保留 id，把名称改成 missing：

{ ...echoCall, name: "missing", arguments: {} }

tools.get("missing") 返回 undefined。executor 不调用任何 schema 或 execute，直接 形成：

{
  role: "toolResult",
  toolCallId: "call-1",
  toolName: "missing",
  content: [text("Tool missing failed: 未知工具")],
  details: { error: "未知工具" },
  isError: true,
}

结果保留请求中的 name。把它改写成某个已注册工具名，会掩盖模型实际请求了未知动作。

#工具抛错：调用已经进入 execute

在独立 Registry 中注册一个会抛出 new Error("exploded") 的 echo，再执行原来的 echoCall。lookup 与 parse 都已经成功，异常发生在 execute 内。结果仍然配对：

{
  role: "toolResult",
  toolCallId: "call-1",
  toolName: "echo",
  content: [text("Tool echo failed: exploded")],
  details: { error: "exploded" },
  isError: true,
}

聚焦测试使用名为 boom 的工具隔离这条分支，执行规则相同。executor 把 Error 的 message 写进 content 和 details，只去掉 stack。通用脱敏属于更外层的日志与输出策略； 工具主动写进 message 的路径或秘密，在这里仍会原样保留。

三种失败都通过 Promise 正常返回 ToolResultMessage。第 07 章因此可以把每个结果按 call id 写回 transcript，不需要同时处理“返回消息”和“executor 向外抛错”两条通道。

npm run build -w @pi/course
node --test --test-name-pattern="执行器" \
  packages/pi-course/dist/test/06-*.test.js
node --test packages/pi-course/dist/test/06-*.test.js

#完成正常实现后再检查执行顺序

临时把 schema 验证移到 execute() 之后：

错误顺序：lookup → execute(raw arguments) → parse

当 echo 收到 { value: 1 } 时，工具已经开始运行，后面的 parse 无法撤销副作用。聚焦 测试中的 executionCount 会从 1 变成 2，第一处偏差出现在执行次数，而非错误文本。

#本章验收

npm run build -w @pi/course
node --test packages/pi-course/dist/test/06-*.test.js

echoCall.arguments
  → echoSchema.parse() 得到 { value: "Pi" }
  → echo.execute() 返回 content 与 details
  → ToolResultMessage 保留 call-1/echo

#可选迁移练习

#小结

同一个 Tool 是两条路径的共同来源：definitions() 取出模型可见的名称、说明与 JSON Schema，executor 则取得本地 schema 和 execute()。Registry 决定本次运行允许 哪组 Tool 进入这两条路径。

executor 把 lookup、parse 与 execute 的不同结局收束成一种 ToolResultMessage，因此 第 07 章可以始终按 call id 写回结果，再继续 Agent Loop。