《Agent Runtime 工程化》第三章 最小 Agent Loop：3.2 tool schema 不是给模型看的摆设

书名：《Agent Runtime 工程化：从工具调用循环到可恢复执行系统》

作者：Neo

章节：第三章 最小 Agent Loop / 3.2 tool schema 不是给模型看的摆设

电子版系列：查看完整目录

第三章 最小 Agent Loop：3.2 tool schema 不是给模型看的摆设

工具 schema 有两个读者。模型用它决定怎么调用工具，runtime 用它判断调用是否合法。

以 read_file 为例：

import { z } from "zod";

const ReadFileInput = z.object({
  path: z.string().min(1),
  startLine: z.number().int().positive().optional(),
  endLine: z.number().int().positive().optional(),
});

type ReadFileInput = z.infer<typeof ReadFileInput>;

不要把 schema 发给模型后就放心。模型返回的参数必须再次校验。校验失败不该让程序崩溃，应当变成一条 observation：

function invalidArgs(call: ToolCall, reason: string): ToolResult {
  return {
    callId: call.id,
    ok: false,
    errorCode: "INVALID_ARGUMENTS",
    content: `工具参数不合法：${reason}`,
  };
}

这很关键。工具参数错了，并不总是任务失败；它可能只是模型需要重新规划的一次观察。

---

系列导航

前 5 篇

• 第三章 最小 Agent Loop：3.1 最小循环的四个接口
• 第三章 最小 Agent Loop：导读
• 第二章 TypeScript / Node Runtime 基础：2.8 验收标准
• 第二章 TypeScript / Node Runtime 基础：2.7 动手任务
• 第二章 TypeScript / Node Runtime 基础：2.6 资源清理比重试更重要

后 5 篇

• 第三章 最小 Agent Loop：3.3 工具调用 roundtrip
• 第三章 最小 Agent Loop：3.4 max steps 与 stop condition
• 第三章 最小 Agent Loop：3.5 三个最小工具
• 第三章 最小 Agent Loop：3.6 一个 mini-agent 的目录
• 第三章 最小 Agent Loop：3.7 常见失败