如何為長時間執行的 AI 代理建立持久狀態

持久代理狀態是一份結構化紀錄，讓全新的 worker 可以恢復任務，而不會重複已完成的工作，亦不必依靠聊天記錄猜測。它應指出目前步驟、已完成的操作、待處理的訊號、重試狀態，以及下一個合法的狀態轉換。

狀態有別於記憶、業務數據、產物和審計記錄。若把五者全都當成向量儲存庫中的同一份文件，復原流程會變得含糊，存取控制也更難實施。

分開儲存五類資訊

發票狀態屬於業務狀態。工作流程正在等待財務批准這項事實，則屬於工作流程狀態。客戶偏好摘要可能屬於記憶，PDF 屬於物件儲存空間，而批准決定則屬於審計記錄。

較完整的代理架構指南說明這些儲存系統如何連接工具與持久執行機制。

儲存狀態機，而非文字摘要

使用明確的狀態和允許的轉換：

stateDiagram-v2
    [*] --> Created
    Created --> Running
    Running --> WaitingForApproval
    WaitingForApproval --> Running: approved
    WaitingForApproval --> Cancelled: rejected or expired
    Running --> RetryScheduled: retryable failure
    RetryScheduled --> Running
    Running --> Completed
    Running --> Failed

任務數據列可以包含 state、state_version、current_step、attempt、wake_at、approval_id 和時間戳記。已完成的副作用應透過操作紀錄參照，不應內嵌為模型自由撰寫的文字。

在程式碼中定義合法的狀態轉換，並拒絕過時的更新。模型可以建議轉換，但狀態層應判斷在沒有批准紀錄的情況下，waiting_for_approval 能否變成 completed。

讓並行 worker 安全地出現分歧

佇列可能重複傳送訊息，lease 可能過期，而速度較慢的 worker 可能在另一個 worker 已恢復同一任務後才完成。請透過版本欄加入樂觀並行控制，或使用包含擁有者和到期時間的 lease。狀態更新應帶有讀取時的版本；如果另一個 worker 已推進狀態，更新就應失敗。

把 lease 與工作流程狀態分開。當機的 worker 應失去其 lease，而不是把任務改為失敗狀態。下一個 worker 可以取得 lease、讀取持久狀態，然後恢復工作。

在副作用前後建立檢查點

寫入前先保存意圖，確認完成後再保存結果。如果逾時令結果未明，請轉至 reconciling 等狀態，而不是假設該步驟已失敗。

持久執行指南詳細說明冪等性和對賬。狀態儲存庫的職責是保留操作參照，並在結果尚未釐清時阻止不安全的狀態轉換。

把等待人員回應保存為一級紀錄

批准紀錄應包含確切操作、資源、所要求的範圍、請求者、批准者、到期時間、決定和政策版本。當工作流程在數小時後恢復時，請重新檢查批准是否適用於目前參數，以及其所代表的用戶是否仍有存取權限。

不要讓伺服器程序在等待期間保持休眠。請保存等待條件，並讓訊號或排程工作把下一個狀態轉換加入佇列。Temporal 的持久執行模型使用事件記錄和訊號處理這類等待，但同一設計也可以透過數據庫和佇列實現。

為狀態加入版本，避免遺下舊執行個體

長時間執行的任務可能跨越一次部署。請儲存工作流程定義版本，並為仍在進行的狀態設計遷移方案。新的 worker 應知道能否讀取舊的負載、遷移該負載，或繼續使用舊處理程式。

避免把整個模型情境放在一個沒有版本的 JSON blob 中。JSON 適合保存步驟專用的負載，但用於排程、授權、保留和操作的穩定欄位應明確定義並建立索引。

為每項紀錄訂立保留規則

工作流程狀態可在完成後壓縮。審計記錄可能需要保留更久。記憶應支援修正和刪除。產物需要到期時間和擁有權元數據。業務數據則遵循產品本身的政策。

刪除操作必須涵蓋所有參照。若移除用戶的記憶，卻把相同的個人數據留在提示、追蹤記錄和產物之中，刪除便不完整。請儲存參照和分類，讓清理流程可以找到每個副本。

使用空白程序測試恢復執行

在等待批准、供應商呼叫完成後，以及重試退避期間停止 worker，再透過沒有本機快取或對話物件的程序恢復工作。程序應從持久狀態和權威後端紀錄推導下一項操作。

下方提示會先完成這項清查，再提出變更建議。任何只出現在日誌內容或提示中的必要事實，都代表一項明確的持久性缺口。