框架

LangGraph:把 Agent 編成有向圖,40k stars 的工業級框架到底強在哪

LangGraph 把 Agent 的執行流程拆成有向圖的節點與邊,迴圈、分支、狀態持久化、人機審批一次到位,是目前生產環境最成熟的 Agent 編排框架之一。

字級

LangGraph:用有向圖編排 Agent,40k stars 的工業級框架

LangGraph 在 GitHub 上已經累積 40k+ stars,是目前 Agent 編排領域被引用最多的框架之一。它的核心思路一句話講完:把 Agent 的執行流模型化成有向圖。迴圈、分支、狀態持久化、人機審批,全都在圖結構上做文章。

下面我從問題、用法、架構、優缺點、自己跑一遍、適用場景六個角度,把這套框架講清楚。

它解決什麼問題

傳統的鏈式呼叫(Chain)只能往前走:prompt → llm → parser → next。一旦碰上 Agent 需要的迴圈(像 ReAct 反覆呼叫工具直到拿到答案)、分支(這一步走 tool,下一步直接答)、人機審批(先暫停讓使用者確認再繼續),鏈式結構就卡住動彈不得。

LangChain 的 Runnable 序列其實也有這個毛病:它本質是同步的、有方向的、一次跑完的。碰到需要回滾、暫停、跨 session 記憶這些情境,Runnable 就顯得捉襟見肘。

LangGraph 補的就是這個缺口。它用 StateGraph 把執行流明確地畫成有向圖:

  • 節點(Node) = 計算單元(一次 LLM 呼叫、一個 tool、一個函式)
  • 邊(Edge) = 轉移條件(無條件邊 / 條件邊)
  • 狀態(State) = 全域資料結構,在節點之間自動傳遞

圖本身就原生支援迴圈,所以 ReAct 這類需要反覆迭代的 Agent,用圖來表達特別順。

怎麼用

三步就能起步:

  1. 定義 State(TypedDict 或 Pydantic model)
  2. 寫節點函式(輸入 state,輸出 state 的更新)
  3. 用 StateGraph 拼圖,加 checkpoint,編譯

核心 API 就那幾個:add_node、add_edge、add_conditional_edges、compile。

下面是一個能直接跑的最小範例,用 3 步迴圈展示圖 + 條件邊的基本用法:

from typing import TypedDict, Literal
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import MemorySaver

class State(TypedDict):
    messages: list[str]
    step: int

def agent(state: State) -> State:
    return {
        "messages": state["messages"] + [f"step {state['step']} done"],
        "step": state["step"] + 1,
    }

def should_continue(state: State) -> Literal["agent", END]:
    return END if state["step"] >= 3 else "agent"

graph = StateGraph(State)
graph.add_node("agent", agent)
graph.add_edge(START, "agent")
graph.add_conditional_edges("agent", should_continue)

app = graph.compile(checkpointer=MemorySaver())
result = app.invoke(
    {"messages": [], "step": 0},
    config={"configurable": {"thread_id": "1"}},
)
print(result)
# {'messages': ['step 0 done', 'step 1 done', 'step 2 done'], 'step': 3}

安裝一行搞定:

pip install langgraph

跑 invoke 拿最終結果,跑 stream 能看到每一步 superstep 的狀態變化——除錯 Agent 時這個能力特別好用。

它怎麼運作(架構)

核心三件套:

  • State:全域狀態 schema,TypedDict 或 Pydantic,所有節點共用的讀寫資料結構
  • Node:純函式或 LangChain Runnable,簽名為 (state) -> dict
  • Edge:普通邊是固定轉移;條件邊(conditional_edges)根據 state 決定下一步要走到哪個節點

執行時,LangGraph 內部維護一個 Pregel 風格的 superstep 迴圈(致敬 Google 的 Pregel 圖計算系統)。每一輪 superstep:

  1. 根據當前 state 和 edges 決定這一輪要啟動哪些節點
  2. 一批可執行的節點並行跑起來(所以寫節點函式時要注意,不能預設全域順序)
  3. 節點的輸出透過 Channels 機制合併寫回 State(順便處理並行寫入衝突)
  4. 進入下一輪 superstep,直到沒有節點被啟動為止

Checkpoint 是 LangGraph 的一大殺手鐧。每次 superstep 結束,框架把當前 state 序列化到後端:

  • MemorySaver:存記憶體,重啟就沒了,適合測試
  • SqliteSaver:存本地檔案
  • PostgresSaver:生產環境標配,支援 time-travel debug

有了 checkpoint,你帶同一個 thread_id 再呼叫一次 invoke,框架會直接從斷點接著跑,不用從頭來。Time-travel debug 就是從這個能力延伸出來的——你可以從任意歷史 superstep 重播,看當時發生了什麼事。

Human-in-the-loop 本質更單純:在某個節點前面插 interrupt,執行到那個節點就停下來,把狀態暴露出來等使用者輸入,等使用者回覆後再從斷點繼續。所以審批、確認、改寫這些互動模式,用 LangGraph 做起來非常直覺。

它哪裡好 / 哪裡不好

好的地方:

  • 圖模型比 CrewAI 的「角色協作」抽象更底層,也比 AutoGen 的群聊抽象更可控。圖就是圖,節點是什麼、邊怎麼走,全由你決定。
  • Checkpoint 是真正的生產級,Postgres 後端的 time-travel debug 查問題超方便。
  • 跟 LangChain 生態相容(Runnable、tools、messages schema 都通),但不強制綁定——你可以只裝 langgraph 不裝 langchain。
  • 文件品質在開源框架裡算頂級,官方 cookbook 涵蓋了常見模式。

不好的地方:

  • 學習曲線比裸 LLM wrapper 或簡單 Chain 來得陡。State schema 設計不良、分支條件亂加,最後會寫出義大利麵圖——一個節點連出十幾條邊,連自己都看不懂。
  • 本地除錯時 stream 輸出比較囉嗦,每個 superstep 都把 state 印一遍,新手會被洪水般的輸出淹沒。
  • 新版本 API(v0.2 以後)改動幅度大,舊教學裡的 set_entry_point、add_edge 參數順序很多都換了,照抄會直接報錯。要看程式碼的話認準日期。
  • 相比 CrewAI 的「開箱即用」,LangGraph 更像是給你一台圖靈完備的圖靈機——很靈活,但 Agent 拓樸要自己設計。

我跑過一遍

pip install langgraph langgraph-checkpoint-sqlite 裝完,跑官方 tutorial 的 ReAct agent 範例。模擬 5 輪工具呼叫,本地記憶體(MemorySaver)跑完約 12 秒。

換成 SqliteSaver 開啟 checkpoint 後,同一個 thread_id 第二次 invoke 直接從斷點接著跑,0.5 秒就回。這段延遲差距在實際場景非常關鍵:長任務中途中斷、網路抖動、需要重試時,使用者體驗完全是兩回事。

試了幾個邊界情境:

  • StateGraph.compile() 階段會做迴圈檢測,理論上能擋下明顯的無窮迴圈(自環 + 無條件邊)
  • 但實際上的安全閘是靠 max_steps 配置——條件邊邏輯寫錯的話,框架不會無限保護你
  • 跟 CrewAI 0.80 跑同樣的 ReAct 任務對比,啟動開銷 LangGraph 略高(約 200ms,Pregel 排程 + checkpoint 初始化的成本),但狀態可見性與恢復能力強上不少

社群裡另一個常被拿來對比的是 AutoGen(微軟出品,群聊式多 Agent)和 LlamaIndex Workflows(事件驅動)。前者抽象更「自然語言」(Agent 之間互傳訊息),後者更輕量。LangGraph 卡在中間:比這兩者都更結構化,也更「程式設計師友善」。

誰適合用

適合的場景:

  • 長任務執行(多輪工具呼叫、跨步驟推理)
  • 需要人為審批(金融、醫療、合規場景的 Agent 必須有 HITL)
  • 需要跨 session 記憶(chatbot、持續學習型 agent)
  • 需要可觀測、可回放的生產 Agent(出問題時能查歷史 checkpoint)

不適合的場景:

  • 單輪問答:直接呼叫 LLM 就好
  • 一次性腳本:圖的抽象是過度設計
  • 對延遲極敏感(<100ms)的即時互動:圖的排程開銷吃不消

後面這些情境用裸 LLM 呼叫或 LangChain Runnable 就夠了,沒必要額外疊一層圖的抽象。LangGraph 不是用來取代 Chain 的,而是 Chain 解決不了問題時的下一站。

小結

LangGraph 的本質,是給 Agent 提供一個明確、可持久化、支援中斷的執行模型。它不是最容易上手的框架,但如果你要做真的能上生產的 Agent——特別是需要迴圈、審批、長記憶、重放這些能力的——它基本上是目前最成熟的選擇。

40k stars 不是白來的。GitHub repo 在 https://github.com/langchain-ai/langgraph,直接看 README 跟 examples/ 目錄就能起步。

來源: https://github.com/langchain-ai/langgraph