智能体重试一次工具调用，结果却创建了两个一样的订单、发了两条重复的通知——这类乱子的根源是缺少幂等设计。幂等指同一个操作，执行一次和执行多次，最终效果完全一样。它是让 AI 智能体敢于放心重试、重跑的基础保障。
类比电梯按钮：连按三下，电梯也只会来一次。按钮就是天然的幂等设计。
做两遍和做一遍结果一样
为什么智能体特别需要幂等？因为大模型和工具的调用天然不稳定：网络超时、返回中断、响应超长，都会触发重试。如果每个操作都不幂等，重试一次就多一份副作用，任务跑一百步，重复产物可能到处都是。幂等让「重试」从一个危险动作变成一个常规动作。
哪些操作天生幂等，哪些不是？查询类操作天然幂等：读文件、搜索资料，做十遍结果都一样。创建和发送类操作不幂等：写一条记录、发一封通知，做两遍就是两份。设计重点全在后者。
网络会重发，设计要接得住
不幂等的操作要靠额外机制变得幂等。最常用的是幂等键：每次业务操作带一个唯一编号，服务端先查这个编号做过没有，做过就直接返回上一次的结果，不再重复执行。智能体发起工具调用时，为「写报告文件」「建任务清单」这类动作生成稳定编号，重复到达的调用就会被自动拦下。
另一个思路是把创建改成「有则更新」：写文件时用固定文件名覆盖写，而不是追加写；更新记录时按主键 upsert。这样重跑一万遍，留下的也只有一份。
常用的防重复手法
归纳起来三种。固定键：以任务编号加步骤号做幂等键，来自同一环节的重复调用命中同一把锁。先查后做：执行前先查目标是否已存在，存在就跳过。可覆盖写：产物用固定路径覆盖，不产生新副本。三种手法在扣子（Coze）的工作流里都能用变量和查重节点拼出来，通义千问、文心一言的插件机制里也内置了类似参数。
手法选型看场景：高频重试的调用用固定键最稳；低频长任务用先查后做就够；产物类操作统一用覆盖写，简单省事。
三种手法，按场景对号入座：
| 防重复手法 | 怎么做 | 适合什么场景 |
|---|---|---|
| 固定键 | 以任务编号加步骤号做幂等键，重复调用命中同一把锁 | 高频重试的调用 |
| 先查后做 | 执行前先查目标是否已存在，存在就跳过 | 低频长任务 |
| 可覆盖写 | 产物用固定路径覆盖，不产生新副本 | 产物类操作 |
类比哪里失效：机器不嫌重复
人类对重复动作有天生的警觉，同一件事别人交代两遍，你会追问「是要做两遍还是说重了」。机器没有这层警觉，收到指令就执行，所以防重复必须由设计承担，不能指望「它应该会自己发现」。
失效的还有「口头取消」：人可以喊停，系统里已发出的重试不会自动消失，取消逻辑要显式实现，比如维护一个作废编号清单。
放心重试的判断标准
给智能体加任何会留下痕迹的操作前，先问一句：这个动作被重复执行，会发生什么？答案是多份副本，就该补幂等；答案是什么都不变，就可以放心让它重试。
幂等设计自查
- 查询类操作随便重试，无需处理
- 创建发送类操作必须有幂等键或先查后做
- 产物统一固定路径覆盖写，不追加不复制
把最近一次智能体任务里的写操作列出来，逐条对照这三行，缺口一目了然。
相关词条：幂等为谁服务，见什么是评测套件？Agent 能力的考卷；重跑前怎么先回放，参考什么是回放调试？重看每一步，一次讲明白；流程改动如何可控，见什么是工作流的版本化？流程改动可控；失败后怎么补救，看什么是失败补偿？做一半怎么收场。
幂等设计快问快答三则
- 幂等和重试是一回事吗？：不是。重试是「再做一遍」的动作，幂等是「做再多遍也不乱」的性质，重试安全的前提恰恰是幂等。
- 给每个调用都加幂等键会不会太麻烦？：只需给有副作用的操作加，查询和读取不用，实际要处理的面比想象中小。
- 大模型自己的输出需要幂等吗？：生成文本本身无害，需要处理的是「把生成结果落库、发送」的下游动作，幂等设计盯的是这些环节。
