01 先用一句话讲透 LangGraph

LangGraph 不是把组件用竖线连起来。它把一个复杂 Agent 变成一张图。

图里有三个核心角色：State、Node、Edge。State 保存当前任务的全部关键状态。Node 执行业务逻辑。Edge 决定下一个节点。

如果 LangChain 的 Chain 像流水线，LangGraph 就像流程引擎。流水线只能往前走；图可以分支、循环、并行、暂停、恢复。

02 为什么必须先懂 State / Node / Edge？

因为后面的 create_agent、Memory、ToolNode、Human-in-the-loop，本质都在这三个概念上叠能力。

你看不懂 State，就会把上下文塞乱。你看不懂 Node，就会把所有逻辑写成一个大函数。你看不懂 Edge，就会让 Agent 到处乱跑。

03 State：不是普通变量，是整张图的共享快照

State 是图运行时的“当前快照”。用户问题、对话消息、检索结果、工具结果、路由决策、最终答案，都可以放在 State 里。

但 State 不是垃圾桶。它只保存多个节点都要读写的关键数据。临时变量放节点内部。长期用户画像放 Store。

官方 Graph API 文档把 State 定义为图的共享数据结构，通常用 TypedDict、dataclass 或 Pydantic model 描述；节点返回的是 State 的局部更新，不需要返回完整 State。

04 Reducer：决定 State 是覆盖，还是合并

State 最大的坑，是列表字段。

如果没有 reducer，节点返回一个新的列表，就会覆盖旧列表。比如 messages、docs、tool_results，这类字段通常不能简单覆盖。

所以 LangGraph 允许你给某个字段声明 reducer。它告诉图引擎：这个字段的新旧值，应该怎么合并。

这就是为什么 messages 常常要用 add_messages。它不是装饰代码，而是状态合并规则。

05 Node：不是类，是执行任务的函数

Node 是图里的工人。它拿到当前 State，执行一段逻辑，然后返回 State 的局部更新。

这个逻辑可以很简单，也可以很重：调用模型、查向量库、调业务接口、做规则判断、写审计日志，都可以放在 Node 里。

但 Node 最好保持单一职责。一个节点只干一件事。这样出错时，Trace 才能看懂。

06 Edge：不是数据管道，是路由规则

Edge 只回答一个问题：下一个节点是谁？

固定 Edge 适合确定流程。条件 Edge 适合根据 State 动态分流。START 决定入口。END 决定结束。多个目标会进入下一轮 super-step 并行执行。

最容易犯的错：同一个节点既加固定边，又用条件边或 Command 动态跳转。这样两个路径都可能执行，流程会变得难以推理。

07 START 和 END：两个虚拟节点

START 不是你写的业务函数。它代表图的入口。用户输入从这里进入图。

END 也不是业务函数。它代表图执行结束。状态走到 END，最终结果就返回给调用方。

08 compile()：从“图纸”变成“可执行图”

StateGraph 只是 builder。你往里面加 State、Node、Edge，只是在画图纸。

compile() 才是关键。它会检查图结构，装配运行时，把节点、边、状态通道、reducer、checkpointer 组合成一个可执行的 CompiledStateGraph。

没有 compile，图不能 invoke，也不能 stream。

09 invoke/stream：图是怎么真正跑起来的？

图的执行不是普通函数调用栈。它更像一轮一轮传递消息。

输入 State 进入 START。入口节点被激活。节点执行后返回更新。Reducer 合并更新。Edge 决定下一批节点。直到所有节点都不再活跃，且没有消息在路上，图结束。

官方文档把这种运行过程称为 super-step。并行节点属于同一个 super-step，顺序节点属于不同 super-step。

10 源码视角：StateGraph 的核心对象关系

源码里，StateGraph 不是直接运行器。它更像“图构建器”。它持有 nodes、edges、branches、channels、schemas。

nodes 保存节点定义。edges 保存固定边。branches 保存条件边。channels 保存 State 字段对应的状态通道。compile() 把这些东西装配成可执行图。

11 常见图形：线性、分支、循环、并行

学 LangGraph，不要只盯一个 ReAct Agent。先学会四种图形。

线性流程适合固定任务。条件分支适合意图识别。循环适合自检和重试。并行适合多数据源检索、多个工具同时执行。

12 企业项目里，State 应该怎么设计？

State 设计得好，整个 Agent 就稳。State 设计得乱，后面全是补丁。

建议把 State 按职责分层：输入层、对话层、检索层、工具层、控制层、输出层。这样每个节点都知道自己读什么、写什么。

13 最容易踩的 8 个坑

第一，把所有逻辑写进一个节点。结果 Trace 看不懂，异常也不好定位。

第二，把 State 当全局变量乱改。节点应该返回更新，不要依赖隐式副作用。

第三，列表字段不写 reducer。messages、docs、tool_results 很容易被覆盖。

第四，同一个节点混用固定边和动态路由。两个路径都可能执行。

第五，条件路由函数返回值不稳定。返回值最好有限、明确、可映射。

第六，State 字段太多。字段越多，节点依赖越乱。

第七，不设置 END。图可能循环到递归限制。

第八，不用 trace。复杂图不上观测，等于黑盒。

14 总结

LangGraph 的基础，不是 API，而是思维方式。

State 是系统当前快照。Node 是独立执行单元。Edge 是控制流。Reducer 是状态合并规则。compile 是从图纸到程序。invoke/stream 是按 super-step 运行。