AI 代理失敗復原：重試、檢查點和人員批准

AI 代理失敗復原會根據錯誤類別，以及外部副作用是否可能已完成，決定失敗的步驟應停止、重試、對賬、等待批准、補償，還是從檢查點恢復。

只有操作合約保證重複執行安全時，自動重試才是安全的做法。逾時並不能證明操作失敗。

回應前先分類失敗

工具應公開穩定的錯誤碼。不要要求模型從「發生錯誤」之類的文字推斷重試是否安全。

一次邏輯寫入只使用一個操作 ID

在影響重大的呼叫前先建立操作紀錄。儲存操作、租戶、資源、正規化輸入雜湊、冪等鍵、狀態、嘗試次數、供應商參照和結果。

同一邏輯副作用的每次重試都應重用相同的冪等鍵，並拒絕以不同參數重用。Stripe 的冪等請求文件示範伺服器端合約如何針對重複的鍵傳回已儲存結果。其保留規則是供應商特有的，因此你的時間窗應涵蓋最長而實際可行的恢復路徑。

如果供應商不支援冪等性，操作數據表可以防止兩個本機 worker 有意啟動同一操作，但無法判定供應商執行操作後遺失的回應。此時應加入供應商查詢、webhook 或由人員執行的對賬步驟。

為已驗證的進度建立檢查點

應在系統驗證外部副作用後建立檢查點，而不是在模型聲稱操作已完成後建立。儲存供應商識別碼或操作參照。恢復執行時，先載入檢查點和權威後端狀態，再次呼叫模型。

持久執行指南說明工作流程歷史、確定性重播和持久等待。失敗復原則補上每個狀態的操作選擇。

指定一個重試負責方

HTTP 用戶端、佇列、工作流程引擎、模型 SDK、工具和供應商都可能重試。每種失敗類別只指定一個負責方，並把每次嘗試計入同一操作。

設定最大嘗試次數、經過時間、backoff 和終止結果。遇到驗證、授權和政策失敗時停止。對模型呼叫，應決定重試會使用相同的提示和工具，還是建立新的決定。這項差異會改變評估，因此必須記錄。

對賬未知結果

寫入逾時時：

1. 把操作標記為 unknown，而不是 failed；
2. 以冪等鍵、供應商參照或預期業務狀態查詢；
3. 如果副作用存在，便把操作標記為已完成；
4. 只有供應商確認操作沒有發生時才重試；
5. 無法確定任何一種結果時，要求人員審查。

不要以成功訊息隱藏未知狀態。對賬仍在進行時，用戶可能需要避免重複發出請求。

在高影響嘗試前加入批准

批准應綁定操作、資源、參數、執行者和到期時間。恢復執行時重新檢查授權。「繼續」這類籠統的批准不應涵蓋已修改的付款或刪除參數。

Railway 的代理刪除事故促使其把 API 刪除改為保留 48 小時的軟刪除。可復原的副作用能減輕復原壓力，但仍需要限定範圍的身份和審計記錄。

區分取消和補償

取消會阻止日後的工作，但無法撤銷已寄出的電郵、已完成的付款或已在外部發佈的內容。補償是另一項操作，例如把發票作廢或恢復軟刪除的資源。

補償需要自己的授權、冪等性、操作紀錄和失敗路徑。多個外部系統沒有共用 transaction 時，不要把補償描述為自動 rollback。

撰寫人員可以執行的操作手冊

每個高影響工作流程都應記錄：

• 如何停止新的執行和正在運作的 worker；
• 要撤銷哪一項憑證；
• 如何找出範圍內的任務和操作；
• 如何分類未知結果；
• 哪些重試安全；
• 哪些副作用可以補償；
• 誰負責批准復原，以及如何驗證完成。

把操作手冊連接至追蹤和操作查詢。可觀察性指南列出從頭到尾追蹤事故所需的識別碼。

在各個時間點演練失敗

分別在呼叫前、供應商收到呼叫後、成功但回應送達前、檢查點後、批准期間和取消期間注入失敗。使用沒有本機狀態的全新 worker 恢復執行，再驗證副作用次數和最終業務狀態。

下方提示會在不接觸生產環境的情況下，設計最能揭示問題的演練。如果操作手冊無法區分「失敗」和「可能已成功」，應先修正這個分支，再提高自主程度。