Spring AI遇到429或超时后为什么重复执行工具？重试边界与幂等完整排查

文章摘要AI接口出现429、超时或连接中断后开发者通常会增加自动重试。但在Tool Calling场景中如果重试包裹了整个Agent流程退款、发送邮件、创建工单、写数据库等工具可能被重复执行。更隐蔽的情况是模型请求超时但工具其实已经完成客户端重试后模型再次发起相同工具调用。本文从模型层、Agent层、工具层和HTTP层四个重试边界出发给出幂等键、状态机、结果查询和可重试错误分类的完整方案。一、典型事故用户说给客户创建一个售后工单执行链路模型选择create_ticket → 工具创建工单成功 → 返回模型时连接超时 → Agent整体自动重试 → 再次调用create_ticket → 创建第二个工单从用户视角只发了一次请求系统却产生两个业务对象。如果工具是退款支付发券发邮件删除数据创建订单后果会更严重。二、为什么“重试一次”会跨越多个层级一个AI请求可能同时存在网关重试 HTTP客户端重试 Spring AI Provider重试 Resilience4j重试 Agent步骤重试 工具SDK重试 消息队列重投如果每层都重试3次最坏情况不是3次而可能是乘法放大。例如网关2次 × 应用3次 × 工具SDK3次 18次潜在调用必须明确每层的职责。三、四种重试边界1. 模型调用重试适合429暂时性5xx连接建立失败无副作用的模型请求。风险如果模型调用发生在工具执行后重试可能重新生成工具调用。2. Agent步骤重试适合结构化输出解析失败计划校验失败可恢复的推理错误。风险整个步骤可能包含多个工具副作用。3. 工具调用重试适合只读查询明确幂等写入服务端支持幂等键。4. 业务流程重试适合有持久化状态机可以查询当前执行状态能从检查点继续。不能简单重新运行整个流程。四、哪些错误可以自动重试通常可重试429 rate_limit_exceeded 502 503 504 连接被拒绝 短暂DNS失败 读超时且确认无副作用通常不可直接重试400参数错误 401认证失败 403权限不足 404资源不存在 insufficient_quota 内容安全拒绝 业务校验失败状态未知最危险的是请求超时超时只说明客户端没有按时收到结果并不说明服务端没有执行。写操作超时后应该先查询执行状态 → 再决定是否重试五、幂等键必须在模型之外生成不要让模型自己生成随机幂等键。模型可能每次重试都生成不同值。正确做法业务请求进入 → 应用生成operationId → 同一个业务动作的所有重试复用例如StringidempotencyKeyString.join(:,tenantId,conversationId,requestId,create_ticket);如果一次请求中允许创建多个工单还要加入业务对象标识或步骤编号。六、工具服务端如何实现幂等表结构CREATETABLEtool_idempotency(idempotency_keyVARCHAR(200)PRIMARYKEY,tool_nameVARCHAR(100)NOTNULL,request_hashVARCHAR(128)NOTNULL,statusVARCHAR(30)NOTNULL,result_jsonTEXT,created_atTIMESTAMPNOTNULL,updated_atTIMESTAMPNOTNULL);状态PROCESSING SUCCEEDED FAILED_RETRYABLE FAILED_FINAL执行流程收到请求 → 插入PROCESSING → 已存在则读取状态 → SUCCEEDED直接返回历史结果 → PROCESSING返回处理中 → 可重试失败按规则执行伪代码TransactionalpublicToolResultexecute(Stringkey,ToolRequestrequest){OptionalIdempotencyRecordexistingrepository.findById(key);if(existing.isPresent()){returnrestore(existing.get(),request);}repository.insertProcessing(key,hash(request));try{ToolResultresultdoExecute(request);repository.markSucceeded(key,result);returnresult;}catch(RuntimeExceptionex){repository.markFailed(key,ex);throwex;}}七、相同幂等键但参数不同怎么办攻击或代码错误可能发送相同key 不同参数例如第一次退款100元第二次使用同一个key退款200元。服务端必须比较request_hash。如果不同返回409 Conflict不能把第二次请求当成第一次的成功结果。八、模型返回的tool_call_id能不能当幂等键不建议单独使用。tool_call_id通常只在一次模型响应中唯一。Agent整体重试后模型可能生成新的ID。更稳定的是业务operationId 工具名 步骤ID可以把tool_call_id作为追踪字段而不是唯一业务幂等依据。九、重试应该包裹哪一层错误Retry(nameai)publicStringrunAgent(Stringmessage){returnagent.run(message);}如果agent.run()内部执行写工具整个流程会重跑。更安全模型只读推理调用 → 可重试 工具写操作 → 幂等执行 最终回答生成 → 可重试但复用工具结果将流程持久化PLANNED TOOL_EXECUTED ANSWER_GENERATING COMPLETED最终回答失败后从TOOL_EXECUTED继续不再重复执行工具。十、检查点设计publicrecordAgentCheckpoint(StringexecutionId,Stringstate,StringtoolName,StringtoolResultLocation,intmodelAttempt,inttoolAttempt){}执行模型选工具 → 保存计划 → 工具执行 → 保存结果 → 模型生成回答任何一步失败都从最近检查点恢复。十一、只读工具是否可以随便重试只读工具通常风险较低但仍可能有外部API计费强限流数据查询压力非稳定快照重复下载大文件。建议设置最大重试次数 指数退避 随机抖动 总超时 并发限制十二、指数退避与Jitter固定间隔1秒、1秒、1秒大量实例会同时重试造成惊群。推荐1秒 2秒 4秒并加入随机抖动。Resilience4j示例resilience4j:retry:instances:aiModel:max-attempts:3wait-duration:1senable-exponential-backoff:trueexponential-backoff-multiplier:2retry-exceptions:-java.io.IOException-java.util.concurrent.TimeoutException异常列表需要按实际Provider SDK调整。十三、429的Retry-After要不要遵守如果响应提供Retry-After: 10应优先遵守。但还要区分rate_limit_exceeded → 等待后重试 insufficient_quota → 不重试两者都可能是HTTP 429。十四、熔断器应该包在哪里建议在模型Provider适配层设置熔断业务Service → ModelGateway → Circuit Breaker → Provider不要用一个熔断器同时覆盖模型向量库所有工具否则其中一个工具失败会关闭整个AI系统。按依赖隔离openai-chat qdrant-search order-tool mail-tool十五、降级策略模型不可用Sol → Terra → Luna → 规则模板RAG不可用生成回答 → 降级为关键词搜索结果写工具不可用自动执行 → 创建待办 → 转人工降级不能绕过审批和权限。十六、需要记录哪些指标model_retry_count tool_retry_count agent_restart_count idempotency_hit_count idempotency_conflict_count unknown_execution_status_count circuit_breaker_open_count fallback_model_count duplicate_business_object_count重点告警同一operationId出现多个业务对象十七、完整排查清单□ 是否同时存在多层重试 □ 重试是否包裹整个Agent □ 写工具是否支持幂等键 □ 相同业务动作是否复用同一个key □ 是否保存request_hash □ 超时后是否先查询状态 □ 最终回答失败是否重复执行工具 □ tool_call_id是否被误作唯一幂等键 □ 429是否区分限流与额度不足 □ 熔断器是否按依赖隔离 □ 是否有检查点和状态机总结Tool Calling场景中最大的错误不是“没有重试”而是在错误的边界重试生产级方案应该做到模型调用可重试 工具写操作幂等 业务流程有检查点 超时先查状态 最终回答复用工具结果只有把模型推理和业务副作用分开自动重试才不会变成重复执行。