工具调用 Tool Calling

来源、课程身份与适用边界

“工具调用 Tool Calling”以Anthropic 公开全文《Building effective agents》建立工程总纲，并用Claude Platform《How tool use works》核对本章机制。

这不是一本名为《AI Agent 开发实战》的官方出版物，也不存在官方十四章目录。平台把公开工程文章、官方开发文档和原始论文重组为 14 个工程单元；下列 112 个节点是站内课程地图。正文、代码、图表、实验与练习均为独立教学重写，模型、API、协议或安全边界变化时必须重新验证。

本单元的八个工程坐标

• 工具调用 Tool Calling：这是“实现工具定义、模型选择、参数验证、应用执行、结果回灌和停止原因状态机”的第 1 个工程坐标；必须进入机制解释、运行轨迹或故障证据，不能只停在目录。
• 光说「我要查天气」没用，得真给它一部能打的电话：这是“实现工具定义、模型选择、参数验证、应用执行、结果回灌和停止原因状态机”的第 2 个工程坐标；必须进入机制解释、运行轨迹或故障证据，不能只停在目录。
• 第一步：给小特一份「工具说明书」——工具定义 / Schema：这是“实现工具定义、模型选择、参数验证、应用执行、结果回灌和停止原因状态机”的第 3 个工程坐标；必须进入机制解释、运行轨迹或故障证据，不能只停在目录。
• 第二步：LLM 看完说明书，产出一个「结构化调用」：这是“实现工具定义、模型选择、参数验证、应用执行、结果回灌和停止原因状态机”的第 4 个工程坐标；必须进入机制解释、运行轨迹或故障证据，不能只停在目录。
• 第三步：程序解析 + 按名字找到函数 + 真去执行：这是“实现工具定义、模型选择、参数验证、应用执行、结果回灌和停止原因状态机”的第 5 个工程坐标；必须进入机制解释、运行轨迹或故障证据，不能只停在目录。
• 第四步：把结果回填给模型，它接着办；出错了也要回填：这是“实现工具定义、模型选择、参数验证、应用执行、结果回灌和停止原因状态机”的第 6 个工程坐标；必须进入机制解释、运行轨迹或故障证据，不能只停在目录。
• 动手一：拆开一份工具说明书，看每个字段管什么：这是“实现工具定义、模型选择、参数验证、应用执行、结果回灌和停止原因状态机”的第 7 个工程坐标；必须进入机制解释、运行轨迹或故障证据，不能只停在目录。
• 动手二：执行成功 vs 出错，两条路怎么走：这是“实现工具定义、模型选择、参数验证、应用执行、结果回灌和停止原因状态机”的第 8 个工程坐标；必须进入机制解释、运行轨迹或故障证据，不能只停在目录。

术语与运行合同

工具定义、tool_use、tool_result、工具注册表、stop_reason。

本页不变量是：模型只生成调用请求，应用始终负责验证、授权、执行和返回真实结果。任何“成功”结论都要保存工具版本、描述、input_schema、tool_use、权限、执行日志、tool_result 与 stop_reason；模型自评、最终措辞和单次 demo 都不能替代环境事实。

工程机制与反证实验

描述决定是否选对

边界重叠的工具会让模型猜测，名称和描述要同时写适用与不适用场景。

动手验证：用相邻意图构建工具选择混淆矩阵。

schema 不等于权限

参数形状正确后仍要检查主体、资源范围和操作风险。

动手验证：提交合法但越权的资源 ID，确认执行器拒绝。

注册表阻断任意执行

模型名称不能进入 eval、shell 或任意反射，应只匹配显式白名单。

动手验证：请求未知工具，确认返回错误且零副作用。

错误也必须回灌

可恢复错误要用匹配 ID 的 tool_result 返回，下一轮才能改参数或换工具。

动手验证：注入缺字段错误，检查模型是否按错误提示修复。

从架构到故障重放

最小可运行切片

async function execute(call: ToolUse, actor: Actor) {
  const tool = registry.get(call.name);
  if (!tool) return toolError(call.id, "unknown_tool");
  const args = tool.schema.parse(call.input);
  await policy.authorize(actor, tool, args);
  try {
    return toolResult(call.id, await tool.run(args));
  } catch (error) {
    return toolError(call.id, classify(error));
  }
}

切片只表达“实现工具定义、模型选择、参数验证、应用执行、结果回灌和停止原因状态机”的核心合同。生产实现还要补齐持久化、超时、密钥隔离、结构化日志、幂等和批量评测；如果不能重新取得工具版本、描述、input_schema、tool_use、权限、执行日志、tool_result 与 stop_reason，代码跑通也不能证明机制正确。

练习与答案

本章回顾

• “工具调用 Tool Calling”解决的是实现工具定义、模型选择、参数验证、应用执行、结果回灌和停止原因状态机。
• 核心不变量是模型只生成调用请求，应用始终负责验证、授权、执行和返回真实结果。
• 首要反例是执行器用反射运行任意工具名，并把未经业务校验的参数直接交给函数。
• 最小证据包包含工具版本、描述、input_schema、tool_use、权限、执行日志、tool_result 与 stop_reason。

阅读导航

← ReAct：推理与行动循环 · 记忆系统 Memory →