外观
工具调用如何保证幂等，避免重复副作用？
3 分钟速学卡
30 秒口述： 幂等不是让模型“不要重复”，而是由执行系统用稳定业务幂等键、唯一约束和结果记录保证同一意图多次提交只产生一次业务副作用。Agent 在超时未知时不能直接换新 key 重试，应先按原 key 查询执行状态，再决定返回结果、继续等待或受控重试。对扣款、发信和创建工单，我还会分离计划与执行、持久化请求指纹和回执，并监控重复抑制与未知状态。
- 本质： 幂等由执行端用稳定业务键和持久化回执保证，不靠模型自律。
- 核心机制： 重试沿用同一业务 key；结果要区分成功、失败和未知。
- 关键判断： 同 key 不同参数应拒绝；高风险副作用分离计划、审批与执行。
- 项目落地： 故障演练：发信接口实际成功但响应超时，Agent 用新 key 重试造成双发。止损是关闭自动重试并查询首个 key，长期加入 outbox、唯一键、状态查询和重复率告警。
- 边界与坑： “HTTP 重试一次就好。” 首次可能已成功；“用 request_id 当幂等键。” 每次重试若产生新 request_id 就无法识别同一业务意图。
目录
面试官为什么问
考察分布式系统基本功、重试语义和 Agent 不确定性下的业务安全。
小白先看懂
取号机为同一业务给出唯一号码；即使窗口因网络问题收到两次相同申请，也只按号码办理一次，并可查询第一次的回执。若重新取号再提交，防重复就失效。
号码对应 idempotency key，窗口台账对应唯一约束与结果表。类比边界是不同业务对“同一意图”的定义不同。
主题教学图片
图：教学图片｜工具调用如何保证幂等，避免重复副作用？
替代文本： 围绕“工具调用如何保证幂等，避免重复副作用？”组织的中文教学图，通过分区、箭头和标签解释核心机制。
读图结论： 超时不换 key；先查询，再决定是否重试。
这张图片用于建立主题机制的直觉。精确公式、参数、失败分支和事实边界仍以正文与 Mermaid 为准。
图片生成记录： model=gpt-image-2，generated=2026-07-15，prompt_version=v1，reviewed=2026-07-16，review_basis=user-confirmed；查看生成 Prompt。
图：技术调用流程｜超时未知下的幂等重试
替代文本： Agent 生成稳定幂等键后请求工具，执行端先查唯一记录；首次执行写回结果，重复请求复用结果，超时则按原键查询状态。
图表加载中…
读图结论： 幂等依赖稳定业务键和执行端持久化，超时重试必须沿用原键。
“恰好一次”通常是业务效果语义，不是网络消息只发送一次。未知状态必须成为显式结果类型。
核心原理
幂等键应绑定业务主体与意图，如 tenant + order + operation + semantic_version，并有合理有效期。请求参数摘要不同却复用同一 key 时应拒绝，避免错误复用结果。
项目和生产视角
故障演练： 发信接口实际成功但响应超时，Agent 用新 key 重试造成双发。止损是关闭自动重试并查询首个 key，长期加入 outbox、唯一键、状态查询和重复率告警。
常见错误回答
- “HTTP 重试一次就好。” 首次可能已成功。
- “用 request_id 当幂等键。” 每次重试若产生新 request_id 就无法识别同一业务意图。
- “数据库事务能防所有重复。” 跨系统副作用还需业务键、回执和补偿。
递进追问
- 幂等键由客户端还是服务端生成？
- 同 key 不同参数怎么处理？
- 超时未知与明确失败有什么区别？
- 消息队列消费如何保证业务幂等？
关联阅读
总结
一句话记忆： 幂等由执行端用稳定业务键和持久化回执保证，不靠模型自律。
- 重试沿用同一业务 key；
- 结果要区分成功、失败和未知；
- 同 key 不同参数应拒绝；
- 高风险副作用分离计划、审批与执行。