a
上周我们线上出过一次重复操作:Agent 调"创建工单"接口,第一次请求在网关超时(客户端 30 秒没拿到响应,服务端其实已经写成功),编排层按"超时即可重试"的策略又发了一次,结果生成两张工单,还被下游自动派给了两个人。复盘之后我们把幂等性重新分了一遍层,结论是:写在 prompt 里的约束不算数,写在编排层里的才算。
一、三层各自的职责,别混
1. 模型层(prompt / 工具描述):只能告诉模型"这个工具不该重复调",最多降低概率。模型看不到网络状态,也拿不到上一次调用的真实结果,所以它无法做出幂等判断。把"不要重复创建"写进系统提示是必要的,但它是软约束。
2. 编排层(agent runtime):这是幂等键应该产生的地方。一次用户意图生成一个 idempotency_key,贯穿该意图下所有重试和子调用;重试策略、超时语义、错误分类都在这一层定义。我们现在的做法是 key = hash(会话ID + 用户消息ID + 工具名),同一意图重放时 key 不变。
3. 工具服务层:按 key 落库去重,命中已存在的 key 时返回首次执行的结果而不是报错。这一步必须由服务端做,客户端做不了(客户端可能在超时后直接重启)。服务端返回结构里要带 first_result=true/false,编排层据此判断"这次是重放"。
二、超时的语义是"未知",不是"失败"
这是我们踩的坑。超时只说明没收到响应,写入可能已经成功。因此写类型工具的超时处理不能是"重试",而应该是:先查状态(用同一个 key 查询),确认确实没落地,再决定重试或放弃。只读型工具可以放心重试,写型工具必须走"查询-再决定"。
三、哪些错误码才允许重试
我们现在的白名单:429(限流)、502/503/504、连接超时、DNS 失败。明确不重试:400/401/403/404/409/422。409 冲突尤其要注意:它往往说明"上一次其实成功了",这时候应当查而不是重试。之前我们一律重试 5xx,把 502 之后服务端已经落库的情况也重试了。
四、幂等键的生命周期与 TTL
key 的 TTL 要大于"最坏情况下人能忍受的重复窗口"。我们按 24 小时存,覆盖人工复核的时间;短了会出现"用户第二天重发导致两次下单",长了会占空间但也有个度。存 key 的表要能按 key 查到首次响应的完整 body,否则重放时只能返回空壳。
五、可观测性
每次工具调用都要落一条记录:request_id、idempotency_key、attempt(第几次)、工具名、错误分类、耗时、是否命中重放。没有 attempt 字段,复盘时根本分不清"用户点了两次"还是"编排层重试了两次"。我们补上这个字段之后,重复操作的问题基本能在一小时内定位。
想抛给大家的问题:多智能体协作时,idempotency_key 由谁生成?我们现在是主 Agent 生成、子 Agent 继承,但主 Agent 自己也可能是被另一个主 Agent 调起来的,链一长 key 就容易漂。有没有更稳的做法,比如把 key 绑在"任务ID"而不是"消息ID"上?
一、三层各自的职责,别混
1. 模型层(prompt / 工具描述):只能告诉模型"这个工具不该重复调",最多降低概率。模型看不到网络状态,也拿不到上一次调用的真实结果,所以它无法做出幂等判断。把"不要重复创建"写进系统提示是必要的,但它是软约束。
2. 编排层(agent runtime):这是幂等键应该产生的地方。一次用户意图生成一个 idempotency_key,贯穿该意图下所有重试和子调用;重试策略、超时语义、错误分类都在这一层定义。我们现在的做法是 key = hash(会话ID + 用户消息ID + 工具名),同一意图重放时 key 不变。
3. 工具服务层:按 key 落库去重,命中已存在的 key 时返回首次执行的结果而不是报错。这一步必须由服务端做,客户端做不了(客户端可能在超时后直接重启)。服务端返回结构里要带 first_result=true/false,编排层据此判断"这次是重放"。
二、超时的语义是"未知",不是"失败"
这是我们踩的坑。超时只说明没收到响应,写入可能已经成功。因此写类型工具的超时处理不能是"重试",而应该是:先查状态(用同一个 key 查询),确认确实没落地,再决定重试或放弃。只读型工具可以放心重试,写型工具必须走"查询-再决定"。
三、哪些错误码才允许重试
我们现在的白名单:429(限流)、502/503/504、连接超时、DNS 失败。明确不重试:400/401/403/404/409/422。409 冲突尤其要注意:它往往说明"上一次其实成功了",这时候应当查而不是重试。之前我们一律重试 5xx,把 502 之后服务端已经落库的情况也重试了。
四、幂等键的生命周期与 TTL
key 的 TTL 要大于"最坏情况下人能忍受的重复窗口"。我们按 24 小时存,覆盖人工复核的时间;短了会出现"用户第二天重发导致两次下单",长了会占空间但也有个度。存 key 的表要能按 key 查到首次响应的完整 body,否则重放时只能返回空壳。
五、可观测性
每次工具调用都要落一条记录:request_id、idempotency_key、attempt(第几次)、工具名、错误分类、耗时、是否命中重放。没有 attempt 字段,复盘时根本分不清"用户点了两次"还是"编排层重试了两次"。我们补上这个字段之后,重复操作的问题基本能在一小时内定位。
想抛给大家的问题:多智能体协作时,idempotency_key 由谁生成?我们现在是主 Agent 生成、子 Agent 继承,但主 Agent 自己也可能是被另一个主 Agent 调起来的,链一长 key 就容易漂。有没有更稳的做法,比如把 key 绑在"任务ID"而不是"消息ID"上?