Agent Workflow Recovery Workflow Setup：實現原理與實作指南

什么是 Agent Workflow Recovery Workflow

Agent workflow recovery workflow 是一套在 agent 執行過程中，當工作流程因錯誤、逾時或外部中斷而失敗時，能夠自動或手動恢復到一致狀態的機制。它不是單一工具，而是結合了狀態持久化、檢查點（checkpoint）、重試邏輯和補償操作（compensation）的系統設計。

很多開發者剛開始做 agent 時，只專注於 forward path──定義工具、編排步驟、處理正常結果。但一旦遇到網路抖動、LLM 輸出格式異常、工具呼叫逾時，整個工作流程就會卡住或產生髒數據，這時候 recovery workflow 就變成剛需。

为什么重要：一个真实场景

假設你建立了一個客服 agent，它負責：接收使用者問題 -> 搜尋知識庫 -> 呼叫 CRM 以取得訂單資訊 -> 產生回應。如果搜尋知識庫這步逾時（例如第三方 API 掛了），沒有 recovery workflow，agent 可能直接報錯，使用者得不到任何回應。更糟的是，CRM 呼叫已經發出並改變了訂單狀態（例如標記為「處理中」），此時失敗導致狀態不一致，後續人工幹預會很困難。

有了 recovery workflow，超時後可以：① 重試 2 次搜尋；② 如果仍失敗，降級走本地快取；③ 如果快取也沒有，則標記步驟失敗並告知用戶“部分資訊不可用”，同時記錄上下文以供後續人工審查。整個過程不會破壞 CRM 狀態，因為補償操作會在降級前回滾 CRM 呼叫。

筆記型電腦螢幕上顯示 agent recovery workflow 的 setup 檢查清單，包含 checkpoint、idempotency、compensation 等步驟

Agent Workflow Recovery Workflow Setup 實作步驟

1. 定义检查点（Checkpoint）

在 workflow 的每個關鍵步驟（通常是對外部系統有副作用的操作前後）插入檢查點。將目前 agent 的完整上下文（狀態、已執行步驟、中間結果）序列化到持久性存儲，如資料庫或物件儲存。

桌面上攤開的筆記，比較不同的 recovery 策略（重試、降級、人工介入），旁邊有咖啡和鍵盤

# 示例：在步骤前后保存 checkpoint
import json, boto3
s3 = boto3.client('s3')

def save_checkpoint(session_id, step_name, context):
    data = {
        'session_id': session_id,
        'step': step_name,
        'context': context,  # 包含所有变量、工具调用历史
        'timestamp': datetime.utcnow().isoformat()
    }
    s3.put_object(Bucket='agent-checkpoints', Key=f'{session_id}/{step_name}.json', Body=json.dumps(data))

最容易做錯的地方：只儲存輕量狀態忽略工具呼叫歷史。恢復時 LLM 不知道之前說過什麼，會重複呼叫或產生矛盾。必須保存完整的 conversation history 和 tool call results。

2. 实现幂等性（Idempotency）

每個可能產生副作用的工具呼叫都需要冪等鍵。例如，發送郵件 API 應該支援 deduplication key，這樣重試不會發送兩次。如果不做冪等，重試本身就變成故障源。

3. 设计恢复策略

常见的恢复策略有三种：

自動重試：對於瞬時錯誤（網路逾時、429 Too Many Requests），最大重試 3 次，指數退避。
降級路徑：如果關鍵工具不可用，是否有替代工具或快取資料？例如搜索失败改用本地索引。
人工介入：對於無法自動復原的失敗（如資料校驗不通過），將 session 狀態儲存並推送到人工佇列，同時向使用者傳回適當的錯誤訊息。

4. 注册补偿操作（Compensation）

如果某個步驟失敗，已經執行的前序步驟可能需要回溯。例如，已經建立了訂單但後續付款失敗，需要自動取消訂單。補償操作需要與正向步驟一一對應，並在 workflow 啟動時註冊。

compensation_map = {
    'create_order': 'cancel_order',
    'deduct_inventory': 'restore_inventory',
}

def execute_compensation(session_id, failed_step):
    # 反向遍历已执行步骤，执行对应补偿
    for step in reversed(executed_steps):
        if step in compensation_map:
            invoke_tool(compensation_map[step], session_id)

失敗場景：補償操作本身也可能失敗。設計時需要考慮 compensation 的重試和最終一致性，或記錄失敗讓維運手動處理。

最容易踩的坑

過度依賴自動重試：有些錯誤（如工具不存在、參數錯誤）重試也不會成功，浪費時間和資源。應該根據錯誤類型分類，只對瞬態錯誤重試。
忽略上下文視窗：儲存的檢查點包含大量 LLM 對話歷史，恢復時可能超出 context window limit。需要做摘要或截斷。
調試困難：recovery 觸發時日誌散落各處，很難追蹤。建議引入 trace ID 貫穿所有步驟，集中日誌。

備用方案：當 Recovery Workflow 本身失敗時

如果 recovery workflow 的鷹架（如 checkpoint 儲存不可用、補償操作也失敗），需要最外層的全域兜底：

fallback to manual：將錯誤詳情和上下文發送到維運通知（如 Slack、PagerDuty），保留 session 資料以便人工恢復。
最終狀態記錄：不管復原是否成功，總是要把最終狀態（成功、失敗、部分成功）寫到一個死信佇列（DLQ）或稽核表，方便事後分析。
漸進式退化：如果 checkpoint 寫入失敗，考慮是否仍可繼續執行（例如降級為不儲存狀態，僅記錄日誌）。

整個 recovery workflow 的設計原則是：保證最終一致性，絕不產生幽靈狀態。不要追求完美恢復，而是保證可觀測、可補償、可回滾。

下一步

如果你正在從普通開發者轉型為 agent 工程師，理解 recovery workflow 只是第一步。更有系統的學習需要你深入掌握 agent 的 context 管理、權限模型、llm evals 以及生產化部署。