LangGraph 生產部署實戰：你的 AI Agent 如何活過第一個月

你的 LangGraph agent 在本機跑得很順——回應精準、流程流暢、demo 完美。然後你把它推上 production，三天後 server 重啟，所有 agent state 歸零，客戶任務全部消失。或者更糟：agent 陷入無限迴圈，20 分鐘燒掉 $200 的 API 費用，你到帳單來才發現。

這不是假設情境。我們在部署自己的 agent 系統時，每一個地雷都親自踩過。這篇指南把從 demo 到 production 的每個致命轉折點攤開，讓你不用重複我們的學費。

TL;DR

• MemorySaver 是測試專用，server 重啟即消失。上 production 前第一件事：換成 PostgresSaver 或 RedisSaver
• Guardrail 不是外掛 middleware，而是 graph 內部的一等公民節點，分 input / processing / output 三層植入
• Checkpoint 不只是備份，是 time travel debug 的基礎——可以 replay 任何失敗執行，不破壞原始記錄
• LangGraph 和 CrewAI 不是競品，而是互補：CrewAI 做 prototype，LangGraph 做 production
• 成本地雷有三層：LLM token 累積、checkpoint I/O write-amplification、agent 無限迴圈失控
• 文末附 15 項 production readiness checklist，上線前逐項對照

注意：本文所有效能數據為自測或引用來源明確標示的案例，不同環境會有差異。

---

你以為 LangGraph 是「複雜版 LangChain」，但它其實是 agent 的作業系統

先破除三個最常見的誤解。

誤解一：LangGraph 是 LangChain 的升級版。 不是。LangChain 的 LCEL（LangChain Expression Language）是線性的 chain 組合——輸入進去、一路往下、輸出出來。LangGraph 是 stateful graph，每個節點可以有條件分支、迴圈、並行，而且每一步都保存狀態。它們在不同抽象層運作：LCEL 適合「固定流程的 prompt chain」，LangGraph 適合「需要判斷、回退、記憶的 agent workflow」。

誤解二：LangGraph 和 CrewAI 是競品。 它們解決不同的問題。CrewAI 把 agents 當「角色」（researcher、writer、reviewer），用 role-based 的方式讓它們協作；LangGraph 把 agents 當「節點」，用 graph 的方式控制執行流。CrewAI 適合快速 prototype，20 行程式碼就能跑起來；LangGraph 適合需要精確控制每一步的生產系統。業界最常見的路徑是：CrewAI 驗證概念 → LangGraph 上 production。兩者可以共存。

如果你正在做框架選型，推薦搭配閱讀AI Agent 框架比較指南，有更完整的多框架對照。

誤解三：GitHub star 數低代表不成熟。 LangGraph 的 GitHub star 數約 25,000-30,000，相對較低。但看 PyPI 下載數據：LangGraph 月下載量超過 3,870 萬次（來源：pypistats.org，2026 年 4 月）。這個反差是「工程採用型工具」的典型特徵——企業大量使用但不會去按 star。AppFolio（Realm-X）、Exa、NVIDIA 都已公開採用 LangGraph 作為生產 agent 基礎設施；Uber、LinkedIn、Klarna 亦有公開案例。判斷框架成熟度，看 download 趨勢和企業案例，不看 star 數。

---

上 production 前必須做的第一件事：把 MemorySaver 換掉

這是我們踩過的第一個地雷，也是社群討論中出現頻率最高的生產事故。

MemorySaver 是 LangGraph 內建的 checkpoint 儲存後端，開箱即用，本地開發體驗極好。問題在於：它是 in-process 記憶體。Python process 重啟、server 部署更新、容器重建——任何一個動作都會讓所有 agent state 瞬間消失。

官方文件明確標注 MemorySaver 為 development only。但因為本地測試完全正常，大量開發者直接帶著它上 production，直到第一次 server 重啟後才發現問題。

遷移到 PostgresSaver 的最小步驟

# 開發環境（別帶上 production）
from langgraph.checkpoint.memory import MemorySaver
checkpointer = MemorySaver()

# 生產環境
from langgraph.checkpoint.postgres import PostgresSaver

# 使用你現有的 Postgres 連線字串
DB_URI = "postgresql://user:pass@localhost:5432/mydb"
checkpointer = PostgresSaver.from_conn_string(DB_URI)

# 初始化 schema（首次執行）
checkpointer.setup()

# 把 checkpointer 傳給 graph
graph = builder.compile(checkpointer=checkpointer)

就這樣。Schema 初始化是一次性動作，之後每個 node 執行完都會自動寫入 checkpoint。如果你已經有跑著的 Postgres 實例（多數 backend 服務都有），不需要額外開一個資料庫。

實務經驗：我們在遷移時犯的錯誤是忘記呼叫 checkpointer.setup()。沒有 error message，agent 就是靜靜地不存 checkpoint。建議在部署腳本裡把 setup 寫成啟動流程的一部分。

---

PostgresSaver、RedisSaver、DynamoDB：不同場景的 checkpointer 選法

換掉 MemorySaver 之後，下一個問題是：要選哪個 production checkpointer？除了三大主流選項，還有一個常被忽略的輕量選擇：

維度	SQLiteSaver	PostgresSaver	RedisSaver	DynamoDB Saver
持久性	磁碟持久化（單檔）	磁碟持久化、支援 ACID	預設記憶體，需設 AOF/RDB 持久化	全託管持久化
查詢能力	基本 SQL 查詢	完整 SQL 查詢歷史 state	有限查詢（key-value）	按 partition key 查詢
讀寫延遲	低（本地磁碟）	中等（磁碟 I/O）	極低（記憶體讀寫）	低且穩定（SLA 保證）
適合場景	個人/低頻場景、單機部署	需要歷史回查、審計軌跡	高吞吐短期 session	AWS 生態、serverless 架構
設定複雜度	極低（零基礎設施）	低（多數服務已有 Postgres）	中（需要 Redis 實例）	中（IAM 權限配置）
大 state 風險	單檔大小限制	⚠️ write-amplification	記憶體佔用上升	單項目 400KB 限制

決策建議

• 個人/低頻場景選 SQLiteSaver：個人使用的 agent、一天跑不到 100 次任務，不需要 Postgres。SQLiteSaver 零基礎設施需求，單機部署完全夠用，是 MemorySaver 到 PostgresSaver 之間的輕量中間站。
• 多數情況選 PostgresSaver：你的 backend 服務大概率已經有 Postgres，不需要額外引入新的基礎設施。支援完整 SQL 查詢，適合 debug 和審計。
• 高吞吐即時場景選 RedisSaver：聊天機器人、即時客服等需要毫秒級回應的場景。但要注意設定 Redis 持久化（AOF 或 RDB），否則 Redis 重啟也會丟失資料。
• 全 AWS 架構選 DynamoDB：如果你的服務已經在 AWS 上且使用 serverless 架構（Lambda），DynamoDB Saver 是最自然的選擇。但需注意 DynamoDB 單項目 400KB 的硬性限制。若 agent state 包含大型 payload，同樣建議採用 Pointer State Pattern：state 只存 S3 reference，實際內容存在 S3 Bucket，避免觸碰 size 上限。

PostgresSaver 的 write-amplification 警告

當 graph state 很大（例如包含大量文件內容），PostgresSaver 會遇到效能問題。原因是 PostgreSQL 的 TOAST 機制：每次 checkpoint 更新都寫入完整 state blob，即使只有一個欄位變更。

解法是 Pointer State Pattern——state 裡只存 reference ID，實際的大型 payload 存在獨立的 object storage（如 S3）：

from typing import TypedDict

class AgentState(TypedDict):
    """State 只存指標，不存完整文件內容"""
    query: str
    document_ids: list[str]      # 只存 ID，不存文件全文
    result_ref: str               # 指向 S3 的 reference
    current_step: str

這樣每次 checkpoint 的寫入量大幅降低。根據 Azguards Technolabs 針對 LangGraph PostgresSaver 的 write-amplification 深度分析，採用 Pointer State Pattern 可將每次 superstep 的資料負載從約 100KB 降至約 150 Bytes（降幅達 99.8%）。實際效果因 state 大小與 Postgres 配置而異。

---

LangGraph guardrail 為什麼比 middleware 更強：三層植入架構解析

傳統做法是在 agent 外面包一層安全過濾——像是呼叫 Llama Guard API 做內容審查，或用正則表達式擋掉敏感詞。這種 middleware 方式有兩個根本限制：它看不到 graph 的內部狀態，而且只能在「進出口」攔截。

LangGraph 的 guardrail nodes 完全不同。它們是 graph 內部的一等公民節點，和你的業務邏輯節點一樣，存取完整的 graph state，透過 conditional edges 決定執行流向。

版本說明：本文描述的 guardrail nodes 架構模式適用於 LangGraph OSS（開源版本），可在任何自架環境實作。LangGraph Platform（LangGraph Cloud）在此基礎上提供額外的宣告式 guardrail 配置介面，但核心的 graph node 機制兩者相同。

三層架構

Input Guardrail → [業務邏輯節點群] → Output Guardrail
                        ↑
                  Processing Guardrail
                  （在執行中監控 state 變化）

• Input Guardrail：在 agent 開始工作前過濾。例如：檢查用戶輸入是否包含 prompt injection 模式、是否超出服務範圍。
• Processing Guardrail：在 agent 執行過程中監控。例如：檢查 state 累積的 token 數是否逼近上限、agent 是否偏離原始任務。
• Output Guardrail：在 agent 回應用戶前審查。例如：確認輸出不包含 PII（個人識別資訊）、回應符合品牌語調。

概念範例

from langgraph.graph import StateGraph

def input_guardrail(state):
    """檢查輸入安全性"""
    if detect_prompt_injection(state["user_input"]):
        return {**state, "blocked": True, "block_reason": "prompt_injection"}
    return {**state, "blocked": False}

def output_guardrail(state):
    """檢查輸出合規性"""
    if contains_pii(state["agent_response"]):
        return {**state, "agent_response": redact_pii(state["agent_response"])}
    return state

builder = StateGraph(AgentState)
builder.add_node("input_guard", input_guardrail)
builder.add_node("agent", agent_node)
builder.add_node("output_guard", output_guardrail)

# conditional edge：被攔截就直接回覆，不進入 agent
builder.add_conditional_edges(
    "input_guard",
    lambda s: "blocked" if s["blocked"] else "proceed",
    {"blocked": "output_guard", "proceed": "agent"}
)
builder.add_edge("agent", "output_guard")

為什麼這比 middleware 好？因為 guardrail node 可以讀取完整的 graph state——它知道 agent 已經做了哪些步驟、累積了什麼資訊、當前任務的完整上下文。這讓它能做「語境感知」的過濾，而不只是字串比對。

實戰建議：不需要一開始就配滿三層。多數場景下，先配 output guardrail（防止 agent 輸出不當內容）就能覆蓋 80% 的風險。Processing guardrail 等到 agent 複雜度上升後再加。

---

Time travel：用 LangGraph checkpoint 在生產環境重現並修復任何 agent 失敗

Checkpoint 不只是「agent 掛掉後能恢復」。根據實際運行經驗，它最大的價值在 production incident debug。

Checkpoint 的運作機制

LangGraph 的 checkpoint 設計是「每個 node 執行後自動快照 graph state」。不是定期備份，不是手動觸發，是每一步都存。這意味著你有一條完整的執行時間線：

Node A → checkpoint_1 → Node B → checkpoint_2 → Node C（失敗）→ checkpoint_3

agent 在 Node C 失敗後，你可以：

1. 恢復：從 checkpoint_2 重新執行 Node C（不重跑 A 和 B）
2. 重現：replay 整個執行序列，觀察每一步的 state 變化
3. 分支：從 checkpoint_1 fork 出一條新路徑，測試不同的處理策略

Time Travel 的 production 用法

官方稱之為 time travel——不只是回到過去，而是「回到過去的某個決策點重新分支」。

# 取得特定 thread 的所有 checkpoint
config = {"configurable": {"thread_id": "failed-task-123"}}
history = list(graph.get_state_history(config))

# 找到失敗前的最後一個正常 checkpoint
target_checkpoint = history[2]  # 例如：Node B 完成後的狀態

# 從該 checkpoint fork 出新的執行
fork_config = {
    "configurable": {
        "thread_id": "debug-fork-001",
        "checkpoint_id": target_checkpoint.config["configurable"]["checkpoint_id"]
    }
}

# 用修改後的 state 重新執行
result = graph.invoke(None, fork_config)

這在 incident response 中的價值是：你可以在不影響正式資料的情況下重現問題。原始的失敗執行記錄完整保留（可用於事後分析），同時你在 fork 出來的分支上測試修復方案。

關鍵差異：傳統 debug 方式是「讀 log 猜問題」；time travel 是「回到失敗現場親眼看每一步的 state」。這在多步驟 agent 中差異巨大——因為 agent 的失敗原因通常不在報錯的那一步，而是在前面幾步的 state 就已經偏差了。

---

CrewAI 做 prototype，LangGraph 上 production：兩者如何搭配而非競爭

「LangGraph 和 CrewAI 哪個比較好？」是一個假問題。它們在不同的抽象層運作，解決不同的需求。

維度	CrewAI	LangGraph
核心隱喻	Agent 是「角色」（role-based）	Agent 是「節點」（graph-based）
上手時間	20 行程式碼可跑	需要理解 state/node/edge 原語
State 管理	內建但有限	完整 stateful graph + checkpoint
控制精細度	中（框架管理流程）	高（你定義每條 edge）
Production 就緒	適合內部工具	適合面對客戶的系統
最佳場景	快速 POC、role-based 協作	複雜控制流、可審計系統

實際的搭配策略

1. 驗證階段用 CrewAI：快速確認「這個 multi-agent 架構能解決問題嗎？」不用花時間在 graph 設計上。
2. 確認可行後遷移 LangGraph：把 CrewAI 的角色定義轉化為 LangGraph 的 node 定義，加入 checkpoint、guardrail、structured state。
3. 不需要遷移的場景：如果你的 agent 只在內部使用、不需要 state 持久化、不需要精確的 error recovery——CrewAI 可能就是最終方案。

LangGraph 的 Multi-Agent 拓撲

LangGraph 原生支援多種 multi-agent 模式：

• Supervisor：一個 supervisor agent 分配任務給 worker agents，收集結果後統一回覆。適合「一個入口、多個專業能力」的場景。
• Swarm：agents 之間直接溝通（handoff），沒有中央協調者。適合「每個 agent 知道何時該把任務交給誰」的場景。
• Hierarchical：多層 supervisor，適合大型系統。

選擇拓撲的關鍵問題：「是否需要一個節點看到所有 agents 的輸出？」如果是，用 Supervisor；如果每個 agent 能獨立判斷下一步，用 Swarm。

---

LangGraph production 的隱藏成本：三種費用你可能沒有計算進去

多數開發者在估算成本時只算 LLM API 費用。但 LangGraph production agent 的真實成本有三層：

第一層：LLM Token 累積（context drift）

Agent 執行多步驟任務時，每一步都會把之前的 context 帶入下一步。10 步之後，context window 可能從 500 tokens 膨脹到 15,000+ tokens。這不只是費用問題——超長 context 會導致 context drift：agent 開始「遺忘」早期的約束條件，輸出品質下降。

控制手段：

• 設定 context 截斷策略：只保留最近 N 步的 state，或摘要化早期 context
• 使用 max_tokens 限制單次 LLM 呼叫的回應長度

第二層：Checkpoint I/O 成本

每個 node 執行後都寫一次 checkpoint。如果你的 graph 有 10 個 node，每個任務就產生 10 次資料庫寫入。在高吞吐場景下（例如每天處理 1,000 個任務），就是每天 10,000 次 DB write。

如果 state 很大（前面提到的 write-amplification 問題），每次寫入可能是數 MB。解法同樣是 Pointer State Pattern，把大 payload 移出 state。

第三層：Agent 失控成本

這是最危險的。社群有開發者回報：agent 陷入無限迴圈，20 分鐘內燒掉 $200 的 API 費用。

必要的保護機制：

# 設定 recursion_limit 防止無限迴圈
graph = builder.compile(
    checkpointer=checkpointer,
)

# 在 invoke 時設定
result = graph.invoke(
    input_data,
    config={
        "recursion_limit": 25,  # 最多 25 步
    }
)

recursion_limit 是你的第一道防線。超過設定的步數，LangGraph 會拋出 GraphRecursionError，停止執行。建議根據你的業務場景設定合理的上限——通常 15-30 步足夠覆蓋正常執行，超過很可能是陷入迴圈了。

成本估算公式（粗估）：單次任務成本 ≈（平均步數 × 每步 token 數 × token 單價）+（平均步數 × 單次 checkpoint 寫入成本）。先算最差情況（recursion_limit × 最大 token 數），確認你能接受。

---

Agent 在 production 卡住了：一套實際可用的 debug SOP

Agent 在 production 卡住的時候，你不能像開發環境一樣設中斷點慢慢查。你需要一套可以在 5 分鐘內定位問題的流程。

Step 1：用 LangSmith 定位卡死的 node

LangSmith 是 LangGraph 的官方 observability 平台。接入後，每次 agent 執行都會產生一條完整的 trace，顯示每個 node 的輸入、輸出、執行時間。

看什麼：

• 哪個 node 沒有返回（執行時間異常長）
• 哪個 node 的輸出和預期不符（state 已經損壞）
• 是否有 node 重複執行（迴圈的徵兆）

Step 2：判斷失敗類型

生產環境的 agent 失敗通常是三種之一：

1. Silent failure（靜默失敗）：agent 跑完了，但 state 已經損壞。常見原因是 untyped state——state 缺少 type definition，錯誤的資料格式沒有被攔截，一路帶到後面的 node 才出問題（或根本沒出錯，只是結果不對）。

2. 無限迴圈：agent 在兩個 node 之間反覆跳轉。通常是 conditional edge 的邏輯沒有覆蓋所有情況，某個條件永遠為 true。

3. 外部依賴超時：agent 呼叫外部 API（LLM、資料庫、第三方服務）沒有回應。

Step 3：用 Time Travel 重現問題

# 取得失敗任務的執行歷史
config = {"configurable": {"thread_id": "stuck-task-456"}}
history = list(graph.get_state_history(config))

# 逐步檢查每個 checkpoint 的 state
for state in history:
    print(f"Step: {state.metadata.get('step', 'N/A')}")
    print(f"State: {state.values}")
    print("---")

找到 state 開始「偏差」的那一步——通常問題的根因不在最後一個 node，而是在前面幾步就已經種下。

Step 4：選擇應對方式

失敗類型	應對方式
Silent failure	加 TypedDict 強制型別檢查；加 processing guardrail 監控 state 完整性
無限迴圈	檢查 conditional edges 邏輯；設定 recursion_limit
外部超時	設定 per-node timeout；加 retry with exponential backoff；fallback 到 human escalation

# 防止 silent failure：用 TypedDict 定義 state schema
from typing import TypedDict, Annotated
from langgraph.graph.message import add_messages

class AgentState(TypedDict):
    messages: Annotated[list, add_messages]
    current_step: str
    error_count: int
    task_complete: bool

TypedDict 不能防止所有 silent failure，但能在大多數情況下讓錯誤的資料格式在編輯器和 runtime 層面被發現。

---

LangGraph 版本穩定性：1.0 的「zero breaking changes」承諾

LangGraph 在 2025 年 10 月達到 1.0 里程碑，核心 API（state、node、edge 原語）承諾不做破壞性變更。這對 production 系統的意義重大：你不需要擔心升級版本後現有的 graph 定義失效。

2.0 的新功能（guardrail nodes、rate limiting 等）是增量式新增，不影響現有 API，官方保持向後相容。這種版本策略是「工程基礎設施」而非「快速迭代 SDK」的做法——你投入的架構決策不會因為框架更新而需要全部重寫。

已有企業案例驗證這個穩定性承諾的價值：AppFolio Realm-X（不動產管理 AI 助手）、Exa（多 agent 研究系統）、NVIDIA（官方發布 1,000 並發擴展指南）。

---

把你的 LangGraph agent 推上 production 前，對照這 15 項

以下 checklist 整合了前面所有章節的要點。建議在上線前逐項確認，未通過的項目至少要有明確的 fallback 計畫。

State Backend（3 項）

• MemorySaver 已替換：使用 SQLiteSaver（低頻個人場景）、PostgresSaver、RedisSaver 或 DynamoDB Saver，不使用 MemorySaver
• State schema 有 TypedDict：所有 state 欄位都有型別定義，防止 silent failure
• 大 state 場景已評估：如果 state 包含文件內容或大型 payload，已實施 Pointer State Pattern

Safety & Cost Control（4 項）

• 設定 recursion_limit：根據業務場景設定合理上限（建議 15-30），防止無限迴圈
• 配置 per-node timeout：每個 node 有執行時間上限，避免單一外部 API 卡住整個 graph
• 實作 guardrail nodes：至少配置 output guardrail，防止 agent 輸出不當內容
• LLM API key 有費用告警：在 OpenAI/Anthropic dashboard 設定月度費用上限或告警閾值

Observability（3 項）

• LangSmith tracing 已接入：每次 agent 執行都有完整 trace 可查
• 關鍵 node 有 error logging：不只記錄最終結果，中間步驟的異常也要記錄
• 設定 agent 執行時間告警：超過預期執行時間自動告警（例如單次任務超過 2 分鐘）

Resilience（3 項）

• 測試 server 重啟後 checkpoint 恢復：實際重啟 server，確認 agent 能從最後一個 checkpoint 繼續
• 測試 node failure 的 retry 行為：模擬外部 API 失敗，確認 retry 邏輯正確
• 有 human escalation fallback 路徑：agent 無法處理的情況，有明確的轉人工機制

Cost Estimation（2 項）

• 估算最差情況 token 費用：recursion_limit × 最大 context length × token 單價
• 估算 checkpoint I/O 成本：每日任務量 × 平均步數 × 單次 write 成本（特別注意大 state 場景）

---

結論：Production 是另一個遊戲

LangGraph 從 demo 到 production 不是「多做一些設定」的差距，而是完全不同的思維模式。Demo 時你關心的是「agent 能不能完成任務」；production 時你關心的是「agent 失敗時會發生什麼」。

如果你只記住三件事：

1. Day 0 就換掉 MemorySaver。不要等到出事才遷移。
2. 設定 recursion_limit。這一行程式碼可能幫你省下幾百美元。
3. 接入 LangSmith。沒有 observability 的 production agent 就是盲飛。

LangGraph 2.0 已經具備生產就緒的核心能力——checkpoint、guardrails、time travel——但這些功能需要你主動配置。框架給你工具，但不會自動幫你設好護欄。

把上面的 15 項 checklist 逐一過完，你的 agent 就有了在 production 存活的基本條件。然後，持續監控、持續迭代，因為生產環境永遠會給你意料之外的驚喜。