如何將 AI 代理部署至正式環境：從示範到可恢復、可觀測、可回滾的上線指南

上線路線圖：先定義邊界，再逐項驗收

AI Agent 如何部署至生產環境，關鍵並非增加模型或編排的複雜程度，而是確保任務失敗時可判斷、可恢復，變更時可驗證、可回滾。建議依次定義任務及完成條件、選定部署模式、建立執行環境與狀態儲存、落實安全邊界、開展具代表性的任務評測，再以小流量進行灰度發佈，並安排值班與回滾。

先明確訂定觸發條件、輸入、允許呼叫的工具、最終業務結果、逾時處理和人手確認節點。若固定流程已能滿足需求，就不必為了「Agent 化」而引入多 Agent。工作流程與 Agent 之間的取捨，可參考 Anthropic 對 Agent 建構方式的討論。系統介面整合和工具權限詳見 AI Agent 如何對接企業現有系統。

選擇部署模式：按限制條件作取捨

下表用於比較架構限制，並不代表效能或價格方面的結論；候選平台的功能、配額與維運責任，應按其現行文件核對。

透過模型 API 進行推理時，部署對象通常是應用程式執行環境、受控工具和狀態服務；是否自建推理環境，則另按延遲、資料邊界、模型可用性和維運要求評估。可參考 Kubernetes Deployment 文件中的滾動更新與修訂版本回復機制，但這不代表 Agent 必須部署在 Kubernetes。

最小生產架構：連接請求、執行、狀態與可觀測性

调用方 → 鉴权入口/请求校验 → 任务执行器（同步短任务或异步任务 ID）
      → Agent 运行逻辑 → 模型端点/受控工具 → 状态存储与结果核验
      → 日志、指标、追踪与告警

短任務可等待結果；若超出呼叫端的等候時限，或需要跨程序復原，則可傳回任務 ID，由用戶端查詢狀態或接收完成通知。應定義任務狀態、取消語義、逾時邊界和結果讀取權限。

系統整合不在此重複詳述，請參閱前述 AI Agent 如何對接企業現有系統。值班與工程協作職責可參考 FDE 的工程交付職責與協作界線，具體責任須在專案中明確訂定。

發佈產物準備：讓變更可重現

將程式碼、相依套件鎖定檔、執行映像檔、環境設定、提示詞範本、模型與工具設定版本納入變更紀錄。在建置過程中驗證相依套件；分隔開發、測試和生產環境；透過受控設定機制注入憑證，不寫入程式碼儲存庫或一般日誌。模型 API 金鑰、工具服務憑證和業務身分須分別管理。

發佈檢查清單至少應確認：

• 已驗證執行入口、健康檢查、資源限制與關閉訊號處理；
• 相依套件版本、映像檔摘要和設定變更均可追溯；
• 提示詞、工具契約、模型識別碼及關鍵參數均有版本紀錄；
• 迴歸測試樣本與評估結果能對應至發佈版本；
• 回復目標版本可啟動，並能讀取目前的狀態格式，或明確拒絕處理。

長任務復原：檢查點不代表業務操作恰好執行一次

可復原性涉及任務紀錄、執行狀態和業務副作用三個層面：任務是否正在排隊、執行或等待人手處理；已執行至哪些步驟；外部系統寫入是否成功。只儲存對話文字未必足以還原執行時的狀態，只有檢查點也無法證明外部寫入操作的結果。

以 LangGraph 為例，文件區分按執行緒儲存執行狀態的 checkpointer 與跨執行緒共用資料的 store。程序重新啟動後要恢復執行，需要適用的持久化後端，並驗證寫入、讀取、隔離、保留及故障復原；記憶體型儲存器不能作為跨重新啟動持久化的依據。詳見 LangGraph 持久化文件。

重試策略要區分單次嘗試逾時、可重試錯誤，以及重試次數用盡後的處理方式。具有副作用的工具應設計冪等鍵或去重機制，重試前先查詢業務結果：呼叫逾時不代表未有寫入。無法確認時，應轉交人手核對或執行補償流程；檢查點、佇列和重試本身並不構成端到端 exactly-once 保證。參見 LangGraph 故障處理文件。

安全控制：為高風險操作設定阻擋條件

發佈前至少驗證：

• 外部文件、網頁和使用者輸入不能自行擴大工具權限；
• 工具服務每次均驗證身分、資源範圍和參數，高影響操作須經人手明確確認；
• 憑證按環境隔離並可輪替，日誌按敏感程度盡量減少記錄、進行去識別化處理，並設定保留期限；
• 審批記錄關聯請求、操作者、擬執行操作與最終業務結果；
• 越權、提示注入、重複提交和敏感資料外洩測試均有預期的拒絕結果。

OWASP Agentic AI 威脅與緩解措施資料可協助建立威脅清單，但不構成本系統安全或合規的證明。

評估關卡：同時檢視結果與過程

不要將 Agent 自稱「已完成」當作驗收依據。為每類任務定義可在環境中核實的成功條件，例如目標記錄狀態、輸出格式和禁止操作；保留執行軌跡，以找出規劃、工具呼叫或結果驗證中的失敗環節。可參考 Anthropic 的 Agent 評估方法說明。

樣本應涵蓋正常輸入、缺少欄位、資訊衝突、工具逾時、權限拒絕、重複請求和外部內容誘導。重要樣本可多次執行並記錄結果波動。發佈關卡可涵蓋任務結果、禁止操作、異常處理、復原演練和人手接管流程；門檻值應根據業務風險、既有基準和測試結果釐定。

監察：品質、延遲、復原與成本

為各項指標定義計算準則、收集位置、警報條件與負責人：

執行軌跡用於定位多步驟執行中的偏差，業務最終狀態則用於確認任務完成。日誌中需要脫敏的欄位、存取範圍與保留期限須按項目確定；上線初期先觀察基準水平，再按業務風險調整警報閾值。

灰度發佈、回滾與進行中任務處理

發佈前，對程式碼、提示詞、模型設定和工具契約的組合進行回歸測試；先以有限流量或低風險任務驗證，再逐步增加流量。設定停止條件，例如業務結果異常、越權測試失敗，或錯誤與延遲超出團隊界定的限值。

發生故障時，暫停接收新任務或停用高風險工具，清點執行中、等候中和已完成的任務，核實外部副作用，再回退至已驗證的版本。驗證舊版本是否與現有狀態格式相容；無法自動恢復的任務，則轉交人手處理或執行經批准的補償操作。採用 Kubernetes 時，可參考 Kubernetes Deployment 進行發佈；應用程式回退不會自動撤銷已完成的業務資料寫入。

教學演練：透過故障注入驗證恢復路徑

以下是教學演練設計，並非客戶案例或實測成績。將任務設定為「產生報告，經人手確認後寫入結果」，每次記錄預期、實際結果與證據：

演練應核對業務狀態、執行記錄與預期是否一致，並明確指定異常任務的負責人和處理路徑。

上線驗收清單

• 任務範圍、完成定義、禁止操作與人手確認節點已書面記錄。
• 部署方式與任務時長、恢復要求及團隊運維能力相符。
• 依賴項目、映像檔、提示詞、模型設定和工具契約均可追溯。
• 任務狀態、持久化與業務副作用均可分別核實，重試設有冪等性保障。
• 權限、提示注入、敏感日誌與人工審批均已通過測試。
• 評測涵蓋具代表性的任務、異常樣本、結果驗證和恢復情境。
• 指標定義、警報負責人、灰度發佈停止條件和值班流程已確認。
• 已演練版本回滾、進行中任務處理、狀態相容性與業務補償路徑。

常見部署問題

問：一定要用 Kubernetes 嗎？ 答：不一定。如果團隊現有的平台已能滿足任務時長、狀態恢復、網絡隔離和運維要求，就不必為了 AI 代理而增加叢集的複雜度。

問：部署 AI 代理是否需要自建模型？ 答：不一定。透過模型 API 進行推理時，通常只需部署應用程式執行環境、受控工具和狀態組件；如需自行部署推理服務，則應另行評估資料邊界、延遲、可用性與運維要求。

問：服務重新啟動後，任務會遺失嗎？ 答：這取決於任務記錄、執行狀態持久化，以及恢復流程的驗證情況。僅依賴程序記憶體，無法在重新啟動後恢復任務；還要核實外部寫入操作是否成功，以免重複執行。

問：如何防止重試造成重複寫入？ 答：為業務操作設計冪等鍵或去重記錄，並在重試前核對外部系統狀態。無法確認時，應暫停自動重試，改由人手核對或進入補償流程。

問：正式上線的成功率門檻應設為多少？ 答：沒有通用數值。應根據任務風險、業務基準和測試結果設定上線門檻與警報，同時驗收禁止操作、人手接管、恢復能力和業務結果。