Agent 上線部署實作課：別一次全量，先讓新版本證明自己

今日主題：Agent 上線部署與漸進式發佈

2026-10-25 | 資料來源：LangGraph 生產部署檢查清單、Agent 部署策略、影子部署與金絲雀評測、LLM 漸進式發佈、生產環境 Agent 可靠性檢視

前言

一般服務上線，流程大家都很熟：寫好程式、跑過測試、部署、觀察錯誤率，沒問題就收工。但 Agent 不一樣。它的輸出不是決定性的，同一個輸入換一天跑可能得到不同答案；它還會動手，透過工具寄信、下單、改資料，錯一次的代價遠大於回傳一則錯誤訊息。

所以 Agent 的上線問題從來不是「能不能部署」，而是「新版本憑什麼值得全部流量」。答案是一套漸進式發佈：讓新版本先在不傷人的位置證明自己，再一步一步拿到更多流量，任何一步出問題都能立刻退回來。

一、為什麼 Agent 上線特別難

第一，成功難以只用狀態碼衡量。服務回傳 HTTP 200，不代表 Agent 的答案變好了，也可能是它選錯工具、少查關鍵資料，卻包裝得很像正確答案。只看錯誤率的上線儀表板，對 Agent 幾乎是盲的。

第二，副作用不可逆。傳統服務出錯可以重試、可以補償，但 Agent 一旦寄出信件或送出訂單，就很難假裝沒發生過。發佈策略必須把「不執行副作用的驗證階段」放在最前面。

第三，版本不只是程式碼。提示詞、模型、工具綱要、檢索用的資料來源，任何一項改動都可能改變行為。只給程式碼打版本號，出了問題根本不知道該退回哪一項。

二、五階段漸進發佈

第一階段：離線回放

先用固定的黃金測試集跑新版本，確認任務完成率沒有退步；再抽樣真實生產流量回放，補上測試集沒覆蓋到的輸入分佈。這一關不過，連影子模式都不必談。

第二階段：影子模式

如圖一，候選版接收真實流量的副本，但它的輸出只記錄、不對外生效，尤其絕對不執行副作用。比對的重點是品質、延遲、成本與工具選擇是否偏離舊版。影子模式的代價是多花一次模型呼叫，換來的是零使用者暴露。

第三階段：建議模式

候選版的產出先交給人確認，確認後才執行。這一步把「判斷對不對」的責任交回給人，適合涉及金錢、外部溝通或不可逆操作的任務，也是人類在迴路最划算的落點。

第四階段：金絲雀發佈

如圖二，從 1% 流量開始，逐步放大到 5%、25%，最後全量。關鍵細節是分流要穩定：同一位使用者在同一個階段內應該固定落在同一版本，否則對話風格忽變忽換，使用者回饋根本無法歸因。

第五階段：全量與留守

全量不代表舊版可以立刻刪除。舊版要留守一段時間，作為回滾目標；確認新版穩定後，才清理舊版與舊設定。

三、四個發佈閘門

每一階段晉級之前，都要同時通過四個閘門，缺一不可：

- 品質閘門：任務完成率、輸出評分、拒絕率，退步就停住。

- 延遲閘門：看 p95 與 p99，不是平均值，因為語言模型的延遲分佈非常偏斜，平均值會把長尾藏起來。

- 成本閘門：每請求的 Token 數與金額。換模型或改提示詞都可能讓成本在全量後才爆發，必須在金絲雀階段就先算清楚。

- 安全與副作用閘門：危險工具呼叫率、人工介入率、異常軌跡比例。數字一異常，優先降級而不是先找原因。

閘門的數值要先寫下來、寫進自動化，而不是等到事故發生時才臨時討論。凌晨兩點的回滾，不應該等任何人起床批準。

四、版本化與回滾設計

把提示詞、模型、工具綱要與設定打包成一個不可變的發佈單元，每個單元有自己的版本號。改提示詞就是新版本，不是「順手改一行」。這樣回滾才有意義：退回的是整個經過驗證的組合，而不是某個被改過一半的狀態。

回滾本身也要演練。沒演練過的回滾流程，事故時等於不存在。每次回滾後要寫下事後檢討，並且把觸發回滾的真實案例補進黃金測試集，讓同一種失敗下次在離線階段就被攔下來。


def route_version(user_id, rollout_pct):
    # Stable bucketing: same user stays on the same version
    bucket = hash(user_id) % 100
    return "candidate" if bucket < rollout_pct else "stable"

def rollout_gate(metrics, thresholds):
    # All four gates must pass before expanding traffic
    checks = {
        "quality": metrics.task_success >= thresholds.task_success,
        "latency": metrics.p99_ms <= thresholds.p99_ms,
        "cost": metrics.cost_per_request <= thresholds.cost_per_request,
        "safety": metrics.risky_tool_rate <= thresholds.risky_tool_rate,
    }
    return all(checks.values()), checks