给 Agent 写操作加幂等键：工具重试为何会重复下单、扣款，怎么防

Agent 演示里最危险的从来不是答错而是“重复执行”。一次“创建订单”工具调用超时编排框架按策略自动重试结果同一笔订单下了两次、同一张卡扣了两次款——用户投诉、对账对不平你还很难在本地复现。问题的根子不在模型而在于工具调用默认是“至少一次”(at-least-once)语义可下单、扣款、发消息这类写操作必须做到“效果恰好一次”。下面拆解重试为什么会重复副作用以及怎么用幂等键把“至少一次”收敛成“对外表现为恰好生效一次”。现象重试把“至少一次”变成了“真的做了两次”先还原事故现场。Agent 调用创建订单的工具请求发出去服务端其实已经落库成功但响应在网络里丢了或超了时。编排层看到的是一次“失败”于是按重试策略又发一次——服务端第二次又老老实实建了一单。对 Agent 来说它只“想”下一单对系统来说却产生了两条真实副作用。这类问题有三个共同点一是触发条件是网络抖动、超时这种偶发因素本地几乎复现不出来二是越是加了“自动重试”来提健壮性的系统越容易踩三是它横跨 Agent、工具、后台三层单看任何一层的日志都像“正常”。所以靠“干脆别重试”来回避并不现实——重试是必要的健壮性手段真正该做的是让重试变得安全。原理用一个键锁住“这次意图只生效一次”幂等键(idempotency key)的思路很直接让调用方在发起写操作时带上一个代表“这次意图”的唯一键(据 Stripe 文档建议用 V4 UUID 或足够高熵的随机串)服务端第一次处理时把这个键连同处理结果一起存下来之后任何带同一个键的重复请求服务端都不再重新执行而是直接返回第一次存下的结果。关键在于“键绑定的是意图不是某一次请求”。同一次下单意图的所有重试共享同一个幂等键而用户真的想再下一单则是一个新意图、一个新键。这样“重试”和“新请求”就被明确区分开了。据 Stripe 文档其幂等结果会缓存一段时间(约 24 小时)再过期窗口内的重复请求都返回同一结果——包括第一次是失败时也返回同样的失败否则失败重试就可能绕过幂等又执行一次。把这套判断做扎实本质是给每个写操作补上“回滚、补偿、幂等、重试上限”这条链路。如果你在梳理自己系统里哪些动作还缺这层保护可以对着回滚与补偿清单逐条过一遍再往下决定每个工具要不要加幂等键、键放在哪一层生成。落地幂等键表 唯一约束 缓存首个结果工程上要有两道防线。第一道在应用层收到请求先查幂等键在不在在就直接回放旧结果。第二道是兜底的一道在数据库层给幂等键加唯一约束即使应用层判断存在并发漏洞数据库也会拒掉第二次插入。两道一起上才扛得住高并发和应用层 bug。-- 幂等键表:主键/唯一约束是最后一道防线createtableidempotency_keys(keytextprimarykey,-- 调用方带来的意图键scopetextnotnull,-- 操作类型,如 create_orderrequest_hashtextnotnull,-- 入参指纹,识别键相同但参数不同的串键response jsonb,-- 第一次的处理结果(成功或失败都存)statustextnotnulldefaultpending,created_at timestamptznotnulldefaultnow());应用层按“先占位、再执行、后回填”的顺序处理defcreate_order(key,payload):insdb.execute(insert into idempotency_keys(key, scope, request_hash, status) values (%s,create_order,%s,pending) on conflict(key) do nothing,(key,sha256(payload)))ifins.rowcount0:# 键已存在 这是一次重试rowdb.one(select * from idempotency_keys where key%s,(key,))ifrow.request_hash!sha256(payload):raiseConflict(同一幂等键被用于不同参数)# 防串键returnreplay(row)# pending 让客户端稍后再试;done 返回旧结果orderdo_create_order(payload)# 真正的副作用只在这条路径发生一次db.execute(update idempotency_keys set response%s, statusdone where key%s,(order,key))returnorder边界与取舍键的粒度要对齐“业务意图”不是“HTTP 请求”。同一意图的多次重试必须复用同一个键——键要由发起动作的那一层(Agent 编排层或前端)在意图产生时生成并一路透传而不是每次重发时新生成否则幂等形同虚设。存一个“pending”中间态是为了处理“第一次还没跑完、重试就到了”的并发第二次看到 pending 应让它等待或稍后重试而不是也冲进去执行。幂等结果要设过期。长期留着既占空间也会让“很久以后的同键新意图”被误判成重试过期窗口按你的对账周期来定。幂等不等于事务。副作用本身(建单、扣款)和幂等键从 pending 到 done 的写入应该在同一个事务里提交否则可能“单建了、键没记上”下次重试又建一单防线反而破了。技术结论写操作的健壮性不是靠“不重试”而是靠“重试安全”。给每个有副作用的 Agent 工具补一个由意图层生成、贯穿所有重试的幂等键应用层回放加数据库唯一约束两道防线再把幂等键写入和副作用放进同一事务——这套做完“至少一次”的调用语义才能对外稳定表现成“恰好生效一次”Agent 再怎么重试也不会重复下单、重复扣款。上线前最该盘一遍的就是还有哪些写操作工具裸奔在没有幂等保护的状态。