本章进度 6 / 18
33%
正文已完成
L119写一份不会藏副作用的工具契约
为一个写操作工具交付用途、参数、返回、审批和幂等性说明。
现在把“工具描述”用于一次具体操作，检查你能否独立做出并修正结果。
建议先完成同主题的理解与判断；本页不会锁课，可以边做边回补。
- 按本课练习说明准备真实材料
- 保留练习与复盘记录
本课选择一个会改变外部状态的工具。完整契约不仅服务模型选工具，也服务安全审查、日志记录和失败恢复。
能编写一份让模型和审查者都能判断是否允许调用的工具契约。
核心概念
先把关键判断说清楚
审批证据进入参数
高风险调用应携带可验证 approval_id，而不是只在提示词里说“先确认”。
返回值支持下一步
成功返回资源 ID 和最终状态，失败返回分类错误，不能只给“操作失败”。
幂等键防止重复
网络超时时重试写操作，幂等键能让同一请求只生效一次。
案例拆解
发送客户邮件工具的契约
旧工具只接收 recipient、subject、body，超时重试曾发送两封。
- 01
增加 approved_draft_id，只有人工批准的草稿可发送。
- 02
增加 idempotency_key，同一键重复调用返回原 message_id。
- 03
失败区分 validation_error、permission_denied 和 transient_error。
案例结果
审批、重复发送和失败恢复都成为工具接口的一部分，而不是依赖 Agent 自觉。
提交前练习
现在轮到你
为一个发送、更新或创建类工具写契约。
完成本课需要：完成以下内容用于本课收口。
内容会自动保存在当前设备
查看参考答案与评分标准
参考答案
publish_article 仅发布已批准版本；参数 article_version_id、approval_id、idempotency_key；成功返回 public_url/version，失败返回明确错误码；审计记录操作者、批准人和内容哈希。
评分标准
- 副作用和禁区显式
- 工具端可验证批准与去重
- 返回足以支持恢复和审计
本课收口 · 学习证据
留下完整学习证据
读完内容、完成练习、通过理解检查并留下 12 字以上总结，才记为已验证。
你现在更接近哪一种状态？
尚有必填项未完成，请补齐后再继续。
资料来源
继续核对与延伸阅读
本课内容最近更新于 。
- Trustworthy agents in practice↗paper · 核对日期 2026-08-23
- JSON Schema Core Specification 2020-12↗standard · 核对日期 2026-08-23
- NIST AI Risk Management Framework↗standard · 核对日期 2026-08-23