LangGraph 完整介紹：用「狀態圖」思維打造可靠的 AI Agent

📖 官方文件：LangGraph Overview
💻 GitHub：langchain-ai/langgraph（MIT License）
🎓 免費課程：LangChain Academy — Intro to LangGraph

前言

從 Rails 全端接觸到 AI Agent 開發後，我發現「怎麼把 Agent 的流程組織好」是個很實際的問題。如果只用一堆 if-else 去串起檢索、判斷、生成的邏輯，很容易就變成難以維護的義大利麵。接觸 LangGraph 後，發現原來可以用「狀態圖（State Graph）」的思維，把 Agent 的流程描述得清晰又可控。

這篇筆記整理我對 LangGraph 的理解，並用工程師熟悉的類比來解釋核心概念。

一句話定義

LangGraph 是一個 low-level 的 Agent 編排（orchestration）框架 + runtime，讓你用「有向圖」描述 Agent 的執行流程，並提供狀態管理、持久化、human-in-the-loop 等生產級能力。

它由 LangChain 團隊開發，但可以獨立使用（不需要 LangChain）。生產環境案例包括 Klarna、Uber、J.P. Morgan 等。

值得注意的是，LangGraph 定位非常「底層」—— 它不幫你抽象 prompt、不幫你決定架構，只專注在編排這件事。這給了你最大的控制權，但也代表你需要自己設計流程。

核心概念：把 Agent 想成「狀態機」

如果你有寫過 Rails 的 state machine（例如 AASM），LangGraph 的心智模型會很好理解：

三大基本元素

一個最小的 LangGraph 範例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

from langgraph.graph import StateGraph, MessagesState, START, END

# 1. Node（節點）：一個處理 state 的函數
def call_llm(state: MessagesState):
    return {"messages": [{"role": "ai", "content": "hello world"}]}

# 2. 建圖 + 加節點
graph = StateGraph(MessagesState)
graph.add_node(call_llm)

# 3. Edge（邊）：定義流程走向
graph.add_edge(START, "call_llm")
graph.add_edge("call_llm", END)

# 4. 編譯後就能執行
graph = graph.compile()
graph.invoke({"messages": [{"role": "user", "content": "hi!"}]})

概念上就是：定義節點 → 用邊連起來 → 編譯 → 執行。

為什麼 LangGraph 適合做 RAG / Agent

1. 混合「確定性步驟」和「LLM 決策步驟」

這是 LangGraph 最大的賣點。你可以在同一張圖裡同時擁有：

• 寫死的邏輯：處理需要可靠、可稽核的部分（例如檢索一定要走這個 pipeline）
• LLM 驅動的決策：處理需要彈性的部分（例如判斷要不要重新檢索）

對做檢索系統來說很直接 —— 像「query → 檢索 → 判斷結果夠不夠好 → 不夠就改寫 query 重試」這種帶迴圈的流程，用 graph 表達比一堆巢狀 if-else 清楚太多。

2. Conditional Edges — 帶迴圈的流程

傳統的 chain 是線性的（A→B→C），但 LangGraph 支援循環（cyclic）：

1
2
3
4
5
6

def should_continue(state):
    if state["retrieval_score"] < 0.7:
        return "refine_query"   # 分數太低 → 重新改寫 query
    return "generate_answer"    # 夠好 → 產生答案

graph.add_conditional_edges("retrieve", should_continue)

這正是 Agentic RAG 的核心 —— 讓系統「會反省」。標準 RAG 是「檢索一次就生成」，而 Agentic RAG 會評估檢索品質、必要時改寫查詢重試，大幅提升回答品質。

3. State 的累積與傳遞

State 是一個貫穿整張圖的物件（通常是 TypedDict）。每個節點回傳的 dict 會 merge 進 state。你可以自訂 reducer 決定合併方式 —— 例如 messages 用 append 累加，score 用覆蓋。

1
2
3
4
5
6
7

from typing import TypedDict, Annotated
from operator import add

class AgentState(TypedDict):
    messages: Annotated[list, add]   # 累加
    retrieval_score: float           # 覆蓋
    query: str

4. Checkpointing / Persistence（持久化）

每一步的 state 都能存到 checkpointer（記憶體 / Postgres / Redis），帶來三個關鍵能力：

• 失敗續跑：Agent 跑到一半掛了，可以從斷點恢復（像 Sidekiq 的 retry）
• 時間旅行：可以回到任一步的 state 重跑，超好 debug
• 長時間任務：支援跑幾小時甚至幾天的工作流

5. Human-in-the-loop（人類介入）

可以在任意節點「中斷（interrupt）」，等人類審核或修改 state 後再繼續。適合：

• 危險操作前要人工核可
• 客服場景中「轉真人」的判斷邏輯

6. First-class Streaming

原生支援 token-by-token 串流，還能串流出「Agent 現在在想什麼、正在呼叫哪個 tool」，對即時 UX 很有幫助。

支援的 Agent 架構

用同一套框架就能實作：

• Single agent — 單一 agent + tool loop
• Multi-agent — 多個 agent 協作
• Hierarchical — 主管 agent 分派任務給子 agent

LangGraph vs 其他框架

💡 選型建議：如果你只是要標準的「LLM + tool loop」，用 LangChain 的 prebuilt agent 就好；但如果你的流程複雜、需要迴圈、需要精細控制哪裡用 AI、哪裡用寫死邏輯，LangGraph 才是對的工具。

生態系工具

LangGraph 可以獨立使用，也能搭配 LangChain 的其他產品：

• LangSmith — 追蹤、評測、除錯、部署的觀測性平台
• LangChain — 提供 models / tools 的整合與 agent 抽象
• Deep Agents — 建在 LangGraph 之上的 agent harness（規劃、子 agent、檔案工具、context 管理）

核心概念總結

學習建議

以做 RAG + Agent 的角度，建議的切入點：

1. 先跑官方的 Agentic RAG 範例 —「檢索 → 評分 → 改寫 → 重試」的迴圈，最貼近實務
2. 理解 conditional edges — 這是取代巢狀 if-else 的關鍵
3. 玩 checkpointer — 對照現有系統怎麼處理長流程的中斷 / 恢復

延伸閱讀

• LangGraph 官方文件
• LangChain Academy: Intro to LangGraph（免費課程）
• Best open source AI agent frameworks 2026 — Firecrawl

📝 這是我在學習 AI Agent 開發過程中的整理筆記。
從 Rails 轉到 AI Agent，用熟悉的工程概念來理解新工具，學起來特別快 🚀

Written by Adora Xu ✨