01 先用一句话讲透 LangGraphLangGraph 不是把组件用竖线连起来。它把一个复杂 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 字段更新逻辑可以压缩成old_state node_update - reducer - new_state没有 reducernew_value 直接覆盖 old_value有 reducer按你指定的规则合并比如追加消息、追加文档、去重结果这就是为什么 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 - 第一个业务节点业务节点 - 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() 把这些东西装配成可执行图。StateGraph 关键字段可以这样理解nodes - 节点注册表edges - 固定路由表branches - 条件路由表channels - State 字段通道schemas - State / Input / Output schemacompiled - 是否已经编译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 是什么功能变化与行业影响解析_热闻岛