Tool Idempotency

不做幂等: 重试导致重复操作
幂等 key 不稳定: 相同操作生成了不同的 key
缓存不清理: 幂等缓存无限增长

Tool Idempotency 是确保工具执行多次和执行一次效果相同的特性。它防止重试导致的重复操作（如重复扣款、重复发送）。

#concept #evergreen #ai

[!info] related notes

所属 MOC: Tool Calling Engineering MOC

相关: 幂等性, Tool Error Handling

一句话定义

Tool Idempotency 是确保工具执行多次和执行一次效果相同的特性。网络超时重试时，如果工具不幂等，可能重复扣款、重复发送邮件。

工具	天然幂等	说明
无副作用查询	通常	重试不改变业务状态，但数据变化会使返回值不同
写入 (INSERT)	❌	重复写入会创建多条
更新 (UPDATE)	取决于操作	SET x=1 与 x=x+1 不同，还需考虑触发器和外部副作用
删除 (DELETE)	取决于目标身份	重复删除同一稳定资源通常不增加效果；返回码可不同，目标复用与触发器另论
发送邮件	❌	重复发送
扣款	❌	重复扣款

通用持久协议见幂等性。工具适配层负责把稳定 operation_id 传到数据库或外部提供方，并把成功、失败与未知结果区分开。

原来的内存字典示例无法提供该保证：先查再执行存在并发窗口；进程重启丢记录；执行后写缓存前崩溃仍会重复。仅对 tool.idempotent 缓存，也不会让本来非幂等的支付/发信工具获得保护。

不能仅以 tool_name + args + user_id 的散列当操作身份：同一用户两次有意购买相同商品会被错误合并。参数摘要用于检查同 key 是否绑定同一内容，不替代业务操作 ID。幂等性关注副作用，不保证每次响应相同；缓存更不能替代实时权限检查。