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 语义更接近普通函数。

推荐阅读顺序

先看 启动与配置,再看 StateGraph 和 Pregel 引擎,然后按 PregelLoop tick → Channel → Checkpoint → 流式 → 功能 API → 中断与恢复 → 子图编排 的顺序往下。

对照官方资料:LangGraph 文档 · GitHub。