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。
源码心法：StateGraph 初始化时会接收 state_schema、input_schema、output_schema。随后通过内部 schema 解析，把字段变成可读写的 channels。每个 channel 都有自己的更新规则。 |
官方 Graph API 文档把 State 定义为图的共享数据结构，通常用 TypedDict、dataclass 或 Pydantic model 描述；节点返回的是 State 的局部更新，不需要返回完整 State。
04 Reducer：决定 State 是覆盖，还是合并
State 最大的坑，是列表字段。
如果没有 reducer，节点返回一个新的列表，就会覆盖旧列表。比如 messages、docs、tool_results，这类字段通常不能简单覆盖。
所以 LangGraph 允许你给某个字段声明 reducer。它告诉图引擎：这个字段的新旧值，应该怎么合并。
State 字段更新逻辑可以压缩成： |
这就是为什么 messages 常常要用 add_messages。它不是装饰代码，而是状态合并规则。
05 Node：不是类，是执行任务的函数
Node 是图里的工人。它拿到当前 State，执行一段逻辑，然后返回 State 的局部更新。
这个逻辑可以很简单，也可以很重：调用模型、查向量库、调业务接口、做规则判断、写审计日志，都可以放在 Node 里。
但 Node 最好保持单一职责。一个节点只干一件事。这样出错时，Trace 才能看懂。
源码心法：add_node() 的核心不是执行节点，而是注册节点：推断节点名、推断输入 schema、封装成 Runnable、保存到 builder.nodes。真正执行发生在 compile 之后的 invoke/stream 阶段。 |
06 Edge：不是数据管道，是路由规则
Edge 只回答一个问题：下一个节点是谁？
固定 Edge 适合确定流程。条件 Edge 适合根据 State 动态分流。START 决定入口。END 决定结束。多个目标会进入下一轮 super-step 并行执行。
最容易犯的错：同一个节点既加固定边，又用条件边或 Command 动态跳转。这样两个路径都可能执行，流程会变得难以推理。
07 START 和 END：两个虚拟节点
START 不是你写的业务函数。它代表图的入口。用户输入从这里进入图。
END 也不是业务函数。它代表图执行结束。状态走到 END，最终结果就返回给调用方。
START -> 第一个业务节点 |
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() 把这些东西装配成可执行图。
StateGraph 关键字段可以这样理解： |
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 运行。
一句话总结：会写 LangGraph，不是会背 add_node 和 add_edge，而是能把复杂 Agent 拆成清晰的状态、节点和路由。 |
内容来源：LangGraph 基础：Node、Edge、State 是什么？：功能变化与行业影响解析_热闻岛
