用幂等键避免智能体重试产生重复操作
文章用无依赖的 Node.js 示例说明,网络超时可能发生在退款等操作已经生效之后,直接重试会重复执行。示例为每个逻辑请求分配稳定的幂等键,后续同键调用复用已保存的结果。
AI 深度解读
Agent 调用支付接口超时,并不代表扣款失败。请求可能已经执行,只是响应没回来;此时重试,就可能再扣一次。发邮件、退款、创建工单,也有同样的问题。
作者给出的方案是在工具执行层加入幂等控制:同一个业务请求无论调用几次,都只产生一次效果。他用无依赖的 Node.js 示例演示了请求去重、并发等待和失败重试,并表示测试已通过。不过,从内存里的演示走到生产环境,最难的部分是处理「操作已经完成,记录却没保存」的空档。
防重复操作,为什么不能靠模型自觉
原文描述了两种重复来源:网络超时触发 Agent 循环重试,以及模型觉得结果异常,主动再次调用工具。
两者都不能靠提示词彻底解决。即使模型完全遵守指令,它也无法仅凭一次超时判断远端是否执行成功。保护必须放在实际运行工具的代码里。
幂等(idempotency)的意思是,同一请求执行多次,效果等同于执行一次。作者的设计分三步:
- 为请求生成稳定的 key,标识业务动作,而非某一次尝试。
- 第一次调用执行工具,保存结果。
- 后续调用复用结果;如果第一次还没结束,就等待它完成。
作者还建议给返回结果加上 replay 标记,让模型知道操作此前已经发生。不过,示例代码没有实现这个标记。
这段 Node.js 代码实际保证了什么
请求 key 由用户、工具名和参数共同生成。下面的代码通过排序参数名,让顶层属性顺序不同的请求得到相同 key,再用 sha256 生成摘要:
const { createHash } = require("node:crypto");
function keyFor(user, tool, args) {
const canonical = JSON.stringify([user, tool, Object.keys(args).sort().map((k) => [k, args[k]])]);
return createHash("sha256").update(canonical).digest("hex");
}
要看的是 Object.keys(args).sort():它只排序了参数的第一层,原文没有处理嵌套对象的规范化问题。
执行层则把 Promise 放进 Map,让并发请求共享同一次执行:
// 生产环境中,Map 应替换为对 key 建有唯一索引的数据库表。
const store = new Map();
async function once(key, fn) {
const hit = store.get(key);
if (hit) return hit.promise; // 已完成或仍在运行:共享结果
const promise = (async () => {
try {
return await fn();
} catch (err) {
store.delete(key); // 失败后仍允许重试
throw err;
}
})();
store.set(key, { promise });
return promise;
}
关键是 if (hit) return hit.promise。这里保存的不只是完成后的结果,也包括正在执行的任务,因此第二个调用不会重新运行工具。
原文提供了三个测试,用 node --test idempotent.test.js 执行:
- 对用户
u1的charge_card请求,参数为amount: 20、order: "A1",先并发调用两次,再调用一次,断言扣款计数仍为1,返回结果包含id: "ch_1"。 - 金额
20和25得到不同 key;{ a: 1, b: 2 }与属性顺序相反的对象得到相同 key。 send_email向x@example.com发送时,第一次抛出timeout,第二次返回ok,执行次数为2。
这些测试验证了示例中的进程内行为。它们没有覆盖多实例竞争、服务重启或远端已经成功的超时。
换成数据库,还差哪一步
作者提出的生产要求包括:使用持久化存储,为 key 建唯一索引,设置覆盖最长重试窗口的过期时间,并保留结果直到重复请求不太可能再到达。
这些要求解决的是记录能否留存,但还有一个更棘手的执行顺序:
工具完成扣款,进程随即崩溃,结果尚未写入数据库。重启后查不到记录,重试仍可能再次扣款。
持久化去重记录,并不能单独保证外部操作只发生一次。
作者因此建议,把同一个 key 传给支持幂等的支付或消息服务,让下游也参与防重;同时在预发布环境连接真实数据库,在各个执行步骤杀死进程,再重试验证。
这里还缺少完整实现:数据库如何登记执行状态、其他实例如何等待,以及执行者消失后如何恢复,原文都没有展开。唯一索引是必要的约束,不能替代这些流程。
我的判断
作者最有价值的提醒是:把重复调用当成正常情况,在工具层提前处理。这比要求模型「不要重复操作」可靠,也比只限制 Agent 重试次数更接近问题所在。
但「失败就删除记录」需要附带前提。明确知道操作未发生时,允许重试没有问题;如果失败只是响应超时,远端是否成功仍然未知。直接删除 key,恰好可能重新制造开头的重复退款事故。原文提到可缓存支付被拒这类最终失败,却没有完整区分失败和结果未知。
请求 key 的设计也不能直接照搬。相同用户、工具和参数,未必总代表同一次业务请求。例如,用户可能确实要向同一地址再次发邮件。团队需要先定义业务动作的身份,再决定是否加入订单或发送任务的标识。
作者报告了测试通过,但没有给出生产事故减少、性能开销或替代方案的对照数据。把它作为设计入门很合适,把这段 Map 包装器视为完整的支付安全保证则不够。
能拿来做什么
- 给 Node.js 中执行扣款、退款、发邮件、创建工单和更新记录的 Agent 工具做一次盘点,逐个写清重复执行会造成什么后果,再确定保护范围。
- 定义业务请求 key 时,区分「同一次操作的重试」和「用户再次发起相同操作」,并检查参数规范化是否覆盖实际使用的嵌套结构。
- 接入支持幂等 key 的下游服务时,把同一个业务 key 贯穿调用链;对超时等结果未知的情况,先设计状态查询或核对流程。
- 在原文三个测试之外,加入真实数据库和进程中断测试,重点验证工具已执行、结果未落库时,再次调用会发生什么。