文章摘要Checkpoint能保存Agent運(yùn)行狀態(tài)卻不能自動保證外部工具只執(zhí)行一次。生產(chǎn)環(huán)境最危險的故障窗口是工具已經(jīng)成功創(chuàng)建訂單、發(fā)送郵件或發(fā)放優(yōu)惠券但進(jìn)程在寫入Checkpoint之前崩潰?；謴?fù)后狀態(tài)仍顯示該Step未完成Executor會再次調(diào)用工具造成重復(fù)訂單、重復(fù)通知和重復(fù)扣款。反過來如果系統(tǒng)先把Step標(biāo)記為成功再調(diào)用外部工具進(jìn)程可能在工具執(zhí)行前崩潰恢復(fù)后Agent會錯誤地跳過從未執(zhí)行的操作。無論“先執(zhí)行后保存”還是“先保存后執(zhí)行”跨數(shù)據(jù)庫和外部系統(tǒng)都無法僅靠本地事務(wù)實(shí)現(xiàn)原子提交。本文從Checkpoint語義、Step Ledger、冪等鍵、外部操作ID、Intent記錄、UNKNOWN狀態(tài)、Outbox、Inbox、租約、重試、補(bǔ)償和恢復(fù)對賬等方面逐層排查給出副作用工具安全恢復(fù)的完整方案。一、最典型的重復(fù)調(diào)用窗口Agent執(zhí)行S4向區(qū)域負(fù)責(zé)人發(fā)送銷售報告時序1. Executor調(diào)用郵件服務(wù) 2. 郵件服務(wù)返回SENT 3. 進(jìn)程崩潰 4. Step成功狀態(tài)尚未寫入數(shù)據(jù)庫 5. Agent從上一個Checkpoint恢復(fù) 6. S4仍然是READY 7. 再次發(fā)送郵件Checkpoint沒有錯它忠實(shí)保存了最后一次成功提交的狀態(tài)。問題在于外部副作用 和 本地狀態(tài)提交 之間 存在不可消除的故障窗口二、Checkpoint保證了什么Checkpoint通常保證保存圖狀態(tài)保存下一步節(jié)點(diǎn)保存變量與Artifact引用支持進(jìn)程重啟后恢復(fù)支持人工中斷支持歷史狀態(tài)和重放。Checkpoint通常不保證外部API與數(shù)據(jù)庫原子工具僅執(zhí)行一次重放不會觸發(fā)副作用Provider調(diào)用不會重復(fù)業(yè)務(wù)系統(tǒng)冪等舊審批仍有效。三、至少一次執(zhí)行是現(xiàn)實(shí)默認(rèn)值分布式環(huán)境中最可靠的假設(shè)是Step可能被執(zhí)行多次 事件可能被投遞多次 回調(diào)可能被接收多次目標(biāo)不是追求不現(xiàn)實(shí)的“絕對只調(diào)用一次”而是實(shí)現(xiàn)至少一次執(zhí)行 業(yè)務(wù)冪等 效果只發(fā)生一次四、錯誤方案一先執(zhí)行工具再保存成功優(yōu)點(diǎn)工具失敗不會誤標(biāo)成功。風(fēng)險工具成功 →Checkpoint失敗 →恢復(fù)后重復(fù)執(zhí)行五、錯誤方案二先保存成功再執(zhí)行工具風(fēng)險成功狀態(tài)已提交 →進(jìn)程崩潰 →工具未執(zhí)行 →恢復(fù)后跳過這會造成“幽靈成功”。六、正確思路Intent—Execute—Reconcile推薦三階段記錄執(zhí)行意圖 ↓ 調(diào)用外部工具 ↓ 記錄結(jié)果并對賬狀態(tài)機(jī)NOT_STARTED → INTENT_RECORDED → EXECUTING → SUCCEEDED EXECUTING → UNKNOWN → RECONCILING → SUCCEEDED / FAILED七、Step執(zhí)行模型publicrecordStepExecution(StringrunId,intplanVersion,StringstepId,StepStatusstatus,intattempt,StringidempotencyKey,StringinputHash,StringexternalOperationId,StringoutputArtifactRef,StringerrorCode,InstantleaseUntil,longrowVersion){}八、Step狀態(tài)publicenumStepStatus{PENDING,READY,INTENT_RECORDED,EXECUTING,SUCCEEDED,FAILED,UNKNOWN,RECONCILING,WAITING_APPROVAL,CANCELLED}九、冪等鍵必須穩(wěn)定同一業(yè)務(wù)操作的所有重試必須使用同一Key。publicStringbuildIdempotencyKey(StringtenantId,StringrunId,intplanVersion,StringstepId,StringoperationGroup){returnsha256(String.join(|,tenantId,runId,String.valueOf(planVersion),stepId,operationGroup));}錯誤做法每次重試生成隨機(jī)UUID這樣外部系統(tǒng)無法識別重復(fù)請求。十、什么情況下可以換新冪等鍵只有確認(rèn)業(yè)務(wù)意圖已經(jīng)變化原操作明確失敗且不可恢復(fù)人工批準(zhǔn)新操作Replan生成新的業(yè)務(wù)動作輸入Hash發(fā)生變化舊操作已補(bǔ)償并關(guān)閉。普通網(wǎng)絡(luò)重試不能換Key。十一、輸入Hash審批和冪等都要綁定具體輸入。publicrecordToolIntent(StringidempotencyKey,StringtoolName,StringtoolVersion,StringinputHash,StringapprovalTokenId,InstantcreatedAt){}如果Plan修訂后郵件收件人變化舊Intent不能繼續(xù)使用。十二、外部系統(tǒng)支持冪等時請求POST /orders Idempotency-Key: 8dbf...外部服務(wù)保存tenant idempotency_key → operation_result重復(fù)請求返回原結(jié)果不再創(chuàng)建新訂單。十三、外部系統(tǒng)不支持冪等時可以增加Tool GatewayAgent → Tool Gateway → 外部系統(tǒng)Gateway負(fù)責(zé)冪等表-請求鎖-外部操作ID-結(jié)果緩存-狀態(tài)查詢-審計(jì)-補(bǔ)償。十四、冪等表createtabletool_operation(tenant_idvarchar(64)notnull,idempotency_keyvarchar(128)notnull,run_idvarchar(128)notnull,plan_versionintegernotnull,step_idvarchar(128)notnull,tool_namevarchar(128)notnull,tool_versionvarchar(64)notnull,input_hashvarchar(128)notnull,statusvarchar(32)notnull,external_operation_idvarchar(128),result_refvarchar(512),error_codevarchar(64),created_at timestamptznotnull,updated_at timestamptznotnull,primarykey(tenant_id,idempotency_key));十五、Intent記錄必須先提交TransactionalpublicToolOperationprepare(StepExecutionstep,ToolRequestrequest){ToolOperationexistingrepository.find(request.tenantId(),request.idempotencyKey()).orElse(null);if(existing!null){validateSameIntent(existing,request);returnexisting;}returnrepository.save(ToolOperation.intent(request));}提交后才能調(diào)用外部工具。十六、同Key不同輸入必須拒絕if(!existing.inputHash().equals(request.inputHash())){thrownewIdempotencyConflictException(request.idempotencyKey());}否則同一個Key可能錯誤復(fù)用舊結(jié)果。十七、執(zhí)行工具publicToolOperationexecute(ToolOperationoperation,ToolRequestrequest){if(operation.status()ToolOperationStatus.SUCCEEDED){returnoperation;}if(operation.status()ToolOperationStatus.EXECUTING!leaseExpired(operation)){thrownewOperationInProgressException(operation.idempotencyKey());}ToolOperationclaimedrepository.claim(operation,workerId,leaseDuration);try{ExternalToolResultresultclient.execute(request,operation.idempotencyKey());returnrepository.markSucceeded(claimed.id(),result.externalOperationId(),result.resultRef());}catch(TimeoutExceptionex){returnrepository.markUnknown(claimed.id(),TIMEOUT_AFTER_SEND);}catch(Exceptionex){returnrepository.markFailed(claimed.id(),classify(ex));}}十八、為什么超時應(yīng)進(jìn)入UNKNOWNHTTP超時只代表客戶端沒有收到結(jié)果不代表服務(wù)端沒有執(zhí)行如果直接標(biāo)記FAILED并重試可能重復(fù)副作用。UNKNOWN必須進(jìn)入對賬流程。十九、外部操作ID外部系統(tǒng)返回order_id message_id payment_id job_id必須保存?；謴?fù)時優(yōu)先使用external_operation_id查詢狀態(tài)而不是再次創(chuàng)建。二十、沒有外部操作ID怎么辦可使用冪等Key查詢-業(yè)務(wù)唯一鍵-請求時間窗口-收件人主題內(nèi)容Hash-訂單業(yè)務(wù)號-人工核對。但可靠性低于原生外部操作ID。二十一、恢復(fù)時決策矩陣本地SUCCEEDED直接復(fù)用結(jié)果INTENT_RECORDED尚未確認(rèn)執(zhí)行 →領(lǐng)取租約后執(zhí)行EXECUTING且租約未過期其他Worker仍可能運(yùn)行 →等待EXECUTING且租約過期不能直接重做 →查詢外部狀態(tài)UNKNOWN執(zhí)行ReconcileFAILED按錯誤類別決定重試、補(bǔ)償或人工二十二、對賬服務(wù)publicReconciliationResultreconcile(ToolOperationoperation){OptionalExternalStatusstatusexternalStatusClient.find(operation.externalOperationId(),operation.idempotencyKey());if(status.isEmpty()){returnReconciliationResult.unresolved();}returnswitch(status.get().state()){caseSUCCEEDED-markSucceededFromExternal(operation,status.get());caseFAILED-markFailedFromExternal(operation,status.get());caseRUNNING-ReconciliationResult.stillRunning();};}二十三、工具結(jié)果與Checkpoint提交工具操作成功寫入Tool Ledger后Agent再推進(jìn)StepToolOperationSUCCEEDED ↓ StepExecutionSUCCEEDED ↓ Artifact引用保存 ↓ Checkpoint提交即使最后一步失敗恢復(fù)時也能從Tool Ledger發(fā)現(xiàn)成功結(jié)果。二十四、雙重事實(shí)來源不要只依賴圖Checkpoint。需要Checkpoint 保存當(dāng)前計(jì)算狀態(tài) Step Ledger 保存步驟業(yè)務(wù)狀態(tài) Tool Operation Ledger 保存外部副作用事實(shí)恢復(fù)時三者對賬。二十五、Checkpoint的提交邊界建議在Plan凍結(jié)后 Step領(lǐng)取后 Tool Intent提交后 Tool結(jié)果寫入后 Step成功后 審批結(jié)果后 Reviewer決策后保存。但Checkpoint越密集存儲和延遲越高需要按風(fēng)險調(diào)整。二十六、讀工具與寫工具不同只讀工具重復(fù)查詢通常只增加成本。策略Query Cache-短TTL-允許重試-結(jié)果版本。寫工具重復(fù)會產(chǎn)生業(yè)務(wù)影響。策略強(qiáng)制冪等-審批-Intent-對賬-補(bǔ)償-審計(jì)。二十七、LLM調(diào)用也可能重復(fù)恢復(fù)后重復(fù)模型調(diào)用會增加成本-得到不同結(jié)果-改變計(jì)劃-改變Tool參數(shù)?？杀４鎚odel_call_id input_hash model_profile structured_output對于確定的已完成Planner或Reviewer調(diào)用可直接復(fù)用輸出。二十八、模型調(diào)用緩存與業(yè)務(wù)冪等不同模型緩存解決重復(fù)計(jì)算工具冪等解決重復(fù)效果不能混為一談。二十九、Pending Writes并行節(jié)點(diǎn)中部分節(jié)點(diǎn)成功、一個節(jié)點(diǎn)失敗。恢復(fù)時應(yīng)復(fù)用已成功節(jié)點(diǎn)的寫入避免全組重跑。如果框架支持Pending Writes要確認(rèn)哪些狀態(tài)已保存-哪些Tool副作用已記錄-Reducer是否冪等-恢復(fù)從哪個Superstep開始。三十、租約避免兩個Worker同時領(lǐng)取同一Step。updateagent_step_executionsetstatusEXECUTING,lease_owner:worker,lease_until:leaseUntil,row_versionrow_version1whererun_id:runIdandstep_id:stepIdandstatusin(READY,INTENT_RECORDED)and(lease_untilisnullorlease_untilnow());受影響行數(shù)為1才領(lǐng)取成功。三十一、租約過期不代表任務(wù)沒執(zhí)行Worker可能仍在運(yùn)行但心跳失敗-外部工具已成功-網(wǎng)絡(luò)分區(qū)-GC暫停。所以過期后進(jìn)入Reconcile不直接重復(fù)調(diào)用。三十二、重試分類publicenumFailureCategory{TRANSIENT_BEFORE_SEND,TRANSIENT_AFTER_SEND,PERMANENT_INPUT,PERMISSION,RATE_LIMIT,UNKNOWN_OUTCOME,BUSINESS_REJECTED}BEFORE_SEND可安全重試。AFTER_SEND先對賬。PERMANENT_INPUTReplan或人工。PERMISSION重新授權(quán)不自動重試。三十三、補(bǔ)償無法實(shí)現(xiàn)原生冪等的業(yè)務(wù)可以設(shè)計(jì)補(bǔ)償重復(fù)創(chuàng)建訂單 →取消重復(fù)訂單但補(bǔ)償不是完美回滾郵件無法真正撤回-通知已被閱讀-價格可能變化-外部系統(tǒng)可能拒絕取消。優(yōu)先冪等補(bǔ)償作為第二道防線。三十四、審批與冪等綁定Approval Token綁定plan_hash step_id input_hash idempotency_key expires_at恢復(fù)后如果輸入變化舊審批不得繼續(xù)使用。三十五、Replay與副作用時間旅行或Checkpoint重放可能重新觸發(fā)模型-API-Interrupt-工具。Replay模式必須明確publicenumReplaySideEffectMode{DISABLED,RECORDED,SANDBOX,LIVE_WITH_NEW_APPROVAL}生產(chǎn)默認(rèn)不允許Live副作用重放。三十六、OutboxStep狀態(tài)變化后需要通知UI、審計(jì)和監(jiān)控。狀態(tài)更新與Outbox同事務(wù)TransactionalpublicvoidcompleteStep(StepExecutionstep,ToolOperationoperation){stepRepository.markSucceeded(step.id(),operation.resultRef());outboxRepository.save(AgentEvent.stepSucceeded(step,operation));}三十七、Inbox工具回調(diào)和事件消費(fèi)者可能重復(fù)。createtableevent_inbox(consumer_namevarchar(128)notnull,event_idvarchar(128)notnull,processed_at timestamptznotnull,primarykey(consumer_name,event_id));三十八、自動化測試崩潰點(diǎn)注入至少測試Intent提交前崩潰 Intent提交后、發(fā)送前崩潰 發(fā)送后、響應(yīng)前崩潰 響應(yīng)后、Tool Ledger前崩潰 Tool Ledger后、Step成功前崩潰 Step成功后、Checkpoint前崩潰每個點(diǎn)都驗(yàn)證業(yè)務(wù)效果只發(fā)生一次。三十九、測試同Key同輸入重復(fù)調(diào)用返回同一外部操作ID和結(jié)果。四十、測試同Key不同輸入必須報沖突不能復(fù)用。四十一、測試UNKNOWN模擬服務(wù)端成功、客戶端超時?；謴?fù)后通過查詢狀態(tài)標(biāo)記成功不再次創(chuàng)建。四十二、測試雙Worker兩個Worker同時領(lǐng)取同Step只能一個成功。四十三、測試審批過期舊審批Token過期后恢復(fù)不能執(zhí)行副作用。四十四、監(jiān)控指標(biāo)agent_step_recovery_total{ state } agent_tool_idempotency_hit_total{ tool } agent_tool_idempotency_conflict_total{ tool } agent_tool_unknown_total{ tool } agent_tool_reconciliation_total{ result } agent_duplicate_side_effect_total{ tool } agent_step_lease_expired_total agent_checkpoint_after_tool_lag_seconds agent_replay_side_effect_blocked_total四十五、告警duplicate_side_effect 0 UNKNOWN長時間未解決 同Key不同輸入 租約過期率異常 Tool成功到Step提交Lag過高 恢復(fù)后工具調(diào)用量激增 審批已過期但嘗試執(zhí)行四十六、最終排查清單□ 不把Checkpoint等同于Exactly Once □ 所有寫工具有穩(wěn)定冪等鍵 □ 同一操作重試不更換Key □ 冪等鍵綁定輸入Hash □ Tool Intent先提交再執(zhí)行 □ 外部操作ID被持久化 □ 超時后進(jìn)入UNKNOWN而非直接FAILED □ UNKNOWN先對賬再重試 □ Step Ledger與Tool Ledger獨(dú)立存在 □ Tool成功后可恢復(fù)原結(jié)果 □ 兩個Worker通過租約和樂觀鎖互斥 □ 租約過期不會直接重復(fù)副作用 □ 審批綁定Plan、輸入和冪等鍵 □ Replay默認(rèn)禁止真實(shí)副作用 □ Outbox和Inbox都支持冪等 □ 崩潰點(diǎn)注入覆蓋全部提交窗口 □ 重復(fù)副作用率是零容忍指標(biāo)總結(jié)Agent從Checkpoint恢復(fù)后重復(fù)調(diào)用工具不是Checkpoint失效而是系統(tǒng)錯誤地把“狀態(tài)恢復(fù)”當(dāng)成了“副作用只執(zhí)行一次”。可靠方案必須同時具備Checkpoint Step Ledger Tool Intent 穩(wěn)定冪等鍵 外部操作ID UNKNOWN對賬 審批綁定恢復(fù)時Executor不能只問“Checkpoint里這個Step完成了嗎”還要問這個業(yè)務(wù)意圖是否已經(jīng)提交 外部系統(tǒng)是否已經(jīng)產(chǎn)生效果 現(xiàn)有結(jié)果能否安全復(fù)用只有回答完這三個問題Agent才能在崩潰、重試和重放中保持業(yè)務(wù)效果一致。