Harness Engineering

外观

第 11 章 Research Brief：Tool Use 与工具协议 ​

研究目标 ​

为“Tool Use 与工具协议”建立可追溯的接口边界：读者需要把模型提出的工具调用候选、应用实际执行的请求、可关联的结果或错误，以及仍然未知的外部效果区分开来。本章承接第 8 章的 Skill 接口和第 10 章的工作流状态，但不把工具描述、参数 Schema 或模型输出误作授权、执行完成或验证成功的证明。

本章将提出原创的工具契约（Tool Contract）工作模型。它用于审查一项工具调用是否具备足够的输入约束、关联信息、结果表示和失败边界；它不是任何厂商的 API 结构、MCP 服务器配置、授权策略或审计后端。

本章要回答的问题 ​

  1. “模型提议调用工具”与“应用已执行工具”之间缺少哪些不可省略的步骤？
  2. 工具定义中的名称、说明、输入 Schema、输出约束和效果提示分别解决什么，又不能证明什么？
  3. 为什么每一个结果或错误都要能关联到具体调用，而不能只向模型返回一段未标识的自然语言？
  4. 参数满足 Schema 后，为什么仍可能因目标不存在、权限不足、过期上下文、业务规则或副作用风险而不能执行？
  5. 工具返回“错误”、协议返回“错误”、超时、取消和“效果是否发生不明”应如何区分？
  6. 什么必须交给第 12 章的运行环境与权限、第 14 章的人类批准、第 17 章的结果验证和第 18 章的重试恢复，而不是由本章的接口字段假装解决？

一手来源与允许用途 ​

ID来源明确表达的内容本章允许用途禁止外推
REF-036当前 MCP Tools 草案规定服务器可通过 tools/list 暴露工具，客户端用 tools/call 调用；工具定义含名称、说明、输入 Schema 和可选输出 Schema，并区分工具结果中的 isError 与协议级异常。版本化 Schema Reference（2025-11-25）给出 readOnlyHint、destructiveHint、idempotentHint 与 openWorldHint，且明确它们只是提示，不能被不受信任服务器当成可靠行为断言。用一个开放协议实例说明：发现、调用、结构化输入/输出、结果错误和描述性提示是不同接口层；提示字段不能替代信任或授权判断。当前草案或版本化 Schema 是跨产品稳定标准、所有 MCP 实现兼容、具体消息字段、缓存/分页/协商行为或人类确认流程适用于其他协议。
REF-037OpenAI 的 Function Calling 指南将工具调用描述为应用与模型之间的多步流程：提供工具、接收调用、在应用侧执行、回传结果、继续响应。该文档展示名称、JSON 编码参数和 call_id 的结果关联。用作产品限定例子说明：模型的调用输出需要被应用解析、校验、路由并与结果关联；同一轮可能出现零个、一个或多个调用。所有模型或 SDK 都使用 call_id、JSON 字符串、相同轮次顺序、严格模式或同样的执行责任。
REF-038Anthropic 的工具定义文档说明其客户端工具使用名称、说明与 input_schema，并可提供符合 Schema 的输入样例；该产品还提供不同的 tool_choice 选择策略。用作另一种产品限定例子，说明工具说明应表达何时使用、参数含义和限制，且 Schema 示例本身需要符合该 Schema。描述长度、命名规则、tool_choice、严格校验、模型版本或任何 Anthropic 选项是通用工具协议。
REF-039JSON Schema 官方规范将 Core 与 Validation 分为不同规范部分，并提供针对纯验证的 Core/Validation dialect。说明本章把 JSON Schema 视为可选的输入/输出形状描述语言；后续示例可在明确版本时使用它表达结构约束。Schema 验证自动证明业务正确、资源存在、授权、无副作用、幂等性、结果可信或任务已完成。

来源陈述与本书模型的分界 ​

来源可支持的最小事实 ​

  • MCP 的当前 Tools 草案提供一种“发现工具、按名称及参数调用、返回内容与错误表示”的协议实例；其中注解是提示，而非可信行为证明。
  • OpenAI Function Calling 的当前指南把应用侧执行与结果回传放在模型调用之外，并以调用标识关联输出。
  • Anthropic 的当前工具定义文档把名称、说明、输入 Schema 和输入样例作为该产品客户端工具定义的一部分。
  • JSON Schema 的 Core/Validation 规范可作为描述数据形状与验证词汇的基础；其存在不改变业务、权限或副作用事实。

以上只支持各自协议或产品的限定陈述。它们不共同定义一个跨厂商 Tool API，也不提供默认的授权、审计、重试、沙箱或验证机制。

本书工程扩展：Tool Contract ​

本书建议把一次可审查的工具交互拆为四层工件：

  1. 工具描述（Tool Descriptor）： 稳定工具名、用途、非用途、输入/输出形状、已知限制、效果类别与版本；描述为模型和审查者提供意图边界，但不是权限授予。
  2. 调用请求（Invocation Request）： 唯一调用关联标识、选择的工具版本、已解析参数、请求上下文摘要、授权/批准快照引用及风险分类。模型候选只有经过这些字段检查后才成为可执行请求。
  3. 调用记录（Invocation Record）： 路由决定、开始/结束时间、执行环境引用、观察到的原始结果或错误、效果状态和关联标识。它服务于追踪，不等同于第 10 章的完整 State Record。
  4. 结果信封（Result Envelope）： succeeded、rejected、failed、timed_out、cancelled 或 effect_unknown 等本书分类，以及可供后续判断的证据、限制和下一步候选。分类不替代第 17 章的验证接受结论。

这些字段是本书的审查模型，并非 MCP、OpenAI、Anthropic 或 JSON Schema 的字段清单。具体系统可使用不同协议、标识格式、日志介质和错误码。

必须保持分离的判断 ​

判断可由什么支持不可由什么替代
参数形状是否合格指定版本的 Schema 与应用侧解析/校验模型的自然语言解释、工具名称或“严格模式”字样
是否允许执行第 12 章的环境、凭证、最小权限和策略检查Schema、工具描述、模型选择或历史成功记录
是否需要人类确认第 14 章定义的风险、责任与批准规则工具注解、模型自述或调用已被构造
效果是否已经发生可关联的系统观察、回读或审计证据超时、连接断开、模型未收到结果或结果文本的语气
结果是否满足任务第 17 章的验收规则与证据工具返回 succeeded 或 HTTP/协议层不报错

章节范围与非目标 ​

本章讨论工具描述、请求/结果关联、输入输出形状、错误层次、效果不确定性和调用证据。它不：

  • 实现 MCP 客户端或服务器、OpenAI/Anthropic SDK、真实工具路由器、浏览器自动化、文件写入或网络 API；
  • 定义 Sandbox、凭证来源、主机隔离、网络允许列表、实际权限与密钥轮换（第 12 章）；
  • 定义人类批准 UI、责任归属或组织升级政策（第 14 章）；
  • 将“工具已返回”解释为业务验证、评估通过、发布完成或外部副作用已经发生（第 17、18 章）；
  • 把第 10 章的 Workflow Contract、状态迁移和恢复规则浓缩成一个工具字段，也不把第 8 章 Skill 的说明文件当作单次调用协议。

计划正文结构 ​

  1. 从模型候选到受控请求： 区分模型提出、应用解析、策略判断、执行与结果回传。
  2. 工具描述与 Schema： 解释名称、用途、非用途、输入/输出形状和版本；说明 Schema 验证的边界。
  3. 调用关联与结果信封： 用调用关联标识把请求、观察、结果、错误和回读证据连接起来。
  4. 错误、超时与效果不确定性： 区分可见失败、协议失败、拒绝、取消、超时和未知效果；不提供跨产品重试配方。
  5. 效果类别与安全交接： 说明只读、可逆写入、不可逆写入和开放世界操作需要不同证据与后续章节机制，但不在本章实现权限系统。
  6. 教学案例： 为“修改书稿元数据”设计预览、授权引用、执行、回读验证与不确定效果的停止路径；案例是本书模型，不操作本仓库文件。

拟议图示、示例与验证边界 ​

  • 图示： 计划一张调用序列图：Agent candidate → Schema / policy gate → Tool adapter → external target → Result Envelope → evaluator，并明确显示“拒绝”“超时”和“效果未知”不会绕过第 12、14、17、18 章。图源尚未创建。
  • 最小示例： 后续可实现纯内存 assessToolInvocation：输入 Tool Contract、调用请求和注入的环境/批准摘要，输出 allowed、rejected、requires_approval 或 effect_unknown 的教学判断。它不调用工具、不访问网络、不检查真实权限，也不写入文件。
  • 计划测试： 至少覆盖未知工具、参数形状不合格、只读请求允许、写入请求缺批准、请求与结果关联冲突、超时后的效果未知和验证前不能标为完成。测试只证明教学函数的输入输出。
  • 计划案例： “修改书稿元数据”只使用虚构对象和预期观察，说明预览不等于写入、回读不等于评估接受，以及缺少效果证据时必须停止或升级。

风险、待核验事项与写作要求 ​

  • TODO(verify)： 2026-07-16 Technical Review 已重新访问 REF-036 至 REF-038；Fact Check 与任何示例实现当天仍须复读。不得沿用本 Brief 中的字段、默认值、模型名称、选项或强制性措辞。
  • TODO(verify)： 若正文使用 MCP 的草案版本、分页、缓存、任务、授权或通知细节，重新定位对应版本页面；本 Brief 不为这些动态条目建立永久保证。
  • TODO(verify)： 若正文写入 OpenAI 或 Anthropic 的工具选择、严格模式、并发、流式事件、内置工具或计费行为，补充写作日的精确官方来源并限定到产品和版本。
  • TODO(verify)： 若后续案例涉及真实文件、Git、浏览器、数据库、MCP、队列或外部 API，分别记录实际环境、权限、批准、执行命令、回读证据和未验证范围。
  • 工具输出可包含不完整、过时、恶意或与任务无关的内容；后续正文必须把输出当作待解释的输入，而非自动可信事实。

Research 完成检查 ​

  • [x] 每条来源事实均记录了具体来源、允许用途与外推禁区。
  • [x] 区分了工具描述、调用请求、调用记录、结果信封与第 10 章状态模型。
  • [x] 明确区分 Schema 形状校验、执行授权、效果观察和任务验证。
  • [x] 为后续图示、纯内存示例、测试与教学案例定义了未实施边界。
  • [x] 为协议和产品动态内容保留了写作日重新核验要求。

从同一套 Markdown 书稿生成。

版本与许可证以仓库 Release 和出版说明为准。