LangGraph 架構總覽

源码版本1.2.9

一句話

LangGraph 是一個以 Channel + Pregel 循環 為內核的狀態機式 agent 編排框架:StateGraph 在建構層把節點/邊編譯成 Pregel 可執行體,執行時由 PregelLoop.tick 反覆執行「讀 channel → 排程任務 → 寫 channel → checkpoint」直到收斂,期間透過 StreamMux 多模式串流輸出、透過 interrupt/Command 實現人機協作,由 BaseCheckpointSaver 族做執行緒級持久化,@entrypoint/@task 提供函式式等價 API。

分層

每層一句話

啟動與設定:RunnableConfig 攜帶 thread_id/store/checkpointer,StateSnapshot 是 get_state 回傳的不可變快照。
Graph 建構:StateGraph 是使用者入口,add_node/add_edge/add_conditional_edges 定義拓撲,compile 產出 CompiledStateGraph(即 Pregel 實例)。
Pregel 引擎:Pregel 是編譯產物,stream/invoke/astream 是入口;PregelLoop.tick 執行單步,PregelRunner 並行跑任務,_algo 負責任務準備/寫回/中斷判定。
Channel:BaseChannel 抽象 update/consume/checkpoint 語意,LastValue 是預設覆蓋,Topic 是發布訂閱,Binop 是二元算子聚合。
Checkpoint:BaseCheckpointSaver 介面 put/get/list,InMemory/Sqlite/Postgres 三種實作,支援同步非同步。
串流:StreamMux 多模式 mux/demux,各 transformer(values/updates/messages/debug/lifecycle/subgraph/checkpoints/tasks)產出不同視圖。
功能 API:@entrypoint 把函式變成 Pregel 可執行體,@task 宣告可並行子任務。
中斷與子圖:interrupt() 觸發人機中斷,Command(resume/goto/update)驅動恢復與跳轉,Send 實現 fan-out。

分層動機

LangGraph 把「圖怎麼定義」(graph 建構)、「怎麼執行」(Pregel)、「狀態怎麼更新」(channel)、「怎麼持久」(checkpoint)、「怎麼看」(stream)、「函式式怎麼等價」(func)、「怎麼和人對拍」(interrupt)、「怎麼編排」(subgraph)完全解耦。這樣換 checkpoint 後端不影響執行邏輯,換 stream 模式不影響圖定義,加中斷不改 channel。Pregel 是唯一的中樞,所有執行路徑最終都走 PregelLoop.tick。

常見誤讀

「LangGraph 就是 LangChain 的圖封裝」——不是。它有獨立的 Pregel 執行引擎,不依賴 LangChain 的 chain/agent 抽象,可以單獨用。
「channel 就是 state」——channel 是狀態的更新語意層,不同 channel 類型(LastValue/Topic/Binop)決定狀態怎麼合併,這是它比普通狀態機強的地方。
「@entrypoint 是 StateGraph 的語法糖」——功能等價但實作不同,func API 走 FunctionalAPI 路徑,最終也編譯成 Pregel,但並行和 join 語意更接近普通函式。

LangGraph 架構總覽 ​

一句話 ​

分層 ​

每層一句話 ​

分層動機 ​

常見誤讀 ​

推薦閱讀順序 ​

LangGraph 架構總覽

一句話

分層

每層一句話

分層動機

常見誤讀

推薦閱讀順序