《Agent Runtime 工程化》第三章 最小 Agent Loop：3.3 工具调用 roundtrip

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

作者：陈堂会

章节：第三章 最小 Agent Loop / 3.3 工具调用 roundtrip

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

第三章 最小 Agent Loop：3.3 工具调用 roundtrip

一次工具调用 roundtrip 包含六步：

1. Runtime 把工具描述和上下文发给模型。
2. 模型返回 tool call。
3. Runtime 校验工具名和参数。
4. Runtime 判断是否允许执行。
5. Tool Executor 执行工具，得到 result。
6. Runtime 把 result 注入消息历史，再请求模型下一步。

最容易出问题的是第 3 步和第 6 步。第 3 步如果放松，模型会把'路径''命令''URL'这些危险输入带进系统。第 6 步如果处理粗糙，模型会误解工具结果，尤其是失败结果。

工具结果应该结构化，至少包含：

• callId：对应哪个 tool call；
• toolName：哪个工具；
• status：成功、失败、被拒绝、超时、取消；
• content：给模型看的观察；
• metadata：给 trace 和调试看的信息；
• truncated：是否截断。

给模型看的 content 要短，但给 trace 的 metadata 要足够。两者不要混在一起。例如 read_file 成功后，模型需要文件片段；trace 还需要绝对路径的脱敏形式、读取行号、文件大小、是否命中缓存。这样一来，模型上下文保持干净，工程排障也不丢证据。

一个更贴近实现的 ToolResult 可以这样写：

type ToolResult = {
  callId: string;
  toolName: string;
  status: "ok" | "error" | "denied" | "timeout" | "cancelled";
  content: string;
  : {
    : ;
    : ;
    : ;
    : ;
  };
};