工具与集成：让模型建议成为可核对的业务动作

调用API成功不一定意味着业务完成；HTTP超时也不一定意味着业务失败。工具设计应让模型知道可以请求什么，让系统决定谁可以做，让用户知道最终发生了什么。读工具与写工具必须区别处理。

封装业务能力，不暴露整套后台

Nubank将确定顺序的跨系统调用封装为复合工具，并限制返回字段；模型负责需要哪些事实，代码负责固定依赖。这样减少模型重复规划的机会，同时把维护接口变化的责任放到工程层。论文§4.3.2

领域工具不应无限变大。查配送状态可在内部查询物流与订单并合并；是否需要调查代收人仍依赖客户回答，不宜藏进查询工具里。一个工具最好对应一个可解释的业务能力与明确的结果语义。接口字段采用实际业务对象，不让模型生成身份、角色或未经读取的资源ID。

{
  "name": "check_delivery",
  "input": {"order_ref": "demo-order-42"},
  "output": {
    "status": "delivered",
    "observed_at": "2026-10-07T09:00:00Z",
    "receipt_available": true,
    "fact_id": "demo-delivery-42"
  }
}

此为原创教学契约。后台用会话身份检查订单归属；模型不传客户凭据。工具描述应说明用途、前置条件、输入枚举、空结果与失败含义，给一个合法例和一个不适用例。公共规则另行规定：写动作需确认、超时先核对、没有成功证据不得宣称完成。

工具装载、技能与权限分别检查

同一个工具可能从聊天、后台任务或工作流进入，入口应明确装载哪些工具：先给目录再按需加载，或预装有限工具。Skill说明怎么做，Schema说明参数结构，身份与对象权限由执行层决定。不能因为模型学过“保存纪要”就允许写任何客户，也不能因为Prompt要求先学工具，就认定执行层强制该步骤。

对“转录生成纪要并保存CRM”，模型可产出可编辑Markdown，应用负责关联客户、保存和返回记录ID。生成成功而应用写入失败，是保存未完成，不需要重新生成整篇。验收分别检查无权工具隐藏、绕过目录调用拒绝、合法格式但错误客户拒绝、保存失败恢复；有公开代码不能代替目标环境的权限测试。反例和Twenty固定版本的机制见工具、权限与安全专题。

财务对账先按相同粒度、期间与币种标准化，再full outer join保留两侧；差异只是待解释事实，解释需要重新取凭证。GL Reconciler的Reader抽取、Critic内部重取证、Resolver成稿各有不同能力，但已披露工作包存在校验接线与执行能力缺口。签认、报告生成与记账是三个完成对象，不能因角色分好、报告写出就认定已授权调整。

写动作先确定提案，再确定执行

以合成调价任务为例，用户请求100→105。先读商品版本并生成提案，用户确认该提案后，执行层重新检查角色、范围、价格规则与当前版本。确认不是对未来任意变化的永久授权。

POST /price-proposals/demo-p7/apply
Idempotency-Key: demo-task-42-price-p7
If-Match: "product-version-8"

{"confirmation_ref":"demo-confirm-7"}

服务验证confirmation_ref绑定用户、提案内容与有效时间；对象与新价格来自已保存提案，不从模型本次文本重新解释。版本已变则返回冲突，让用户看新的方案。契约应同时定义重复请求与相同键不同载荷：前者返回已知结果，后者拒绝，避免复用键掩盖不同动作。

调价还要防两种失效：预览后价格变化却仍按旧方案覆盖，以及执行记录显示成功但真实目录价格未改变。前者需要版本冲突检查，后者需要后台回读与对账；都应进入工具契约和测试，不能只核助手的成功答复。

区分失败类型，才知道能否重试

同一幂等键必须跨网络重试保持一致；它不能解决所有事务问题。更新商品与审计记录若在同一数据库，可设计同事务提交；调用外部系统则需要操作日志、结果查询和恢复流程。PostgreSQL隔离级别提供并发行为的基础，但不能替外部业务API保证原子性。事务隔离文档

应用可使用明确状态：proposed → confirmed → executing → applied，另有conflict、result_unknown、failed和cancelled。不要在发请求前就把状态记为applied。补偿也不是简单反向调用：若100→105后又有人调到110，直接“恢复100”可能覆盖新工作，应核对对象版本与补偿权限。

部分业务已执行时，按对象核对后只恢复缺失步骤。例如价格已变、通知失败，应保存提案、确认、商品版本与执行回执，回读价格后仅恢复通知；未知状态不能再提交新调价。补偿也需检查当前版本和授权，不能覆盖后来修改。这些恢复步骤需在自己的接口验证；固定示例的局部检查不能证明生产恢复有效。

如何验证工具可交付

读工具检查身份、对象归属、缺数据、过期与返回最小化；写工具检查取消、重复确认、重复请求、同键异载荷、版本冲突、超时后成功、超时后失败和恢复。用离线Mock验证契约与状态转换，再在授权测试环境证明真实API语义。文档中的伪代码不能代替后者。

观察记录至少关联任务ID、工具名、契约版本、参数摘要、身份引用、请求ID、耗时、结果类别及最终业务记录；敏感字段按需要遮蔽。模型的自然语言说明可帮助排查，但审计以执行层记录为准。

协议标准或MCP可以统一连接方式，不能自动提供业务授权、幂等或合格结果。先完成工具契约，再决定采用现有API、内部适配层还是通用协议。下一阶段的评测应同时检查模型选工具是否正确与工具自身是否遵守契约，两类错误分别修复。

第07章的商品操作图已把编辑、确认、保存和回读连起来：这里再核对每个检查真正落在哪个程序。模型给候选，应用维护提案与确认，后台执行与回读；本地revision不替代后台object_version。

参考资料

• Nubank v2 §4.3.2：复合工具与返回字段收缩。
• Commerce固定源码：预览、执行与角色边界；已有局部探针支持特定价格与台账接缝，不代表生产系统缺陷。
• 工具安全专题：Twenty与GL工作包固定版本、权限及校验接线的具体范围。
• PostgreSQL事务隔离文档：并发控制基础，不承诺外部API原子性。
• 本章接口、状态与恢复步骤为教学设计，未在真实后端验证。

继续使用

上一章：检索与证据 · 下一章：设计可信评测 · 五篇阅读目录。相关工具：动作契约与失败恢复。

案例延伸：Nubank客服：比较底层API与复合工具的粒度；Siemens模拟：查看可执行工具边界如何进入实验。