LangGraph保姆级教程：从核心组件到多Agent实战

LangGraph 是 LangChain 生态中一套相对独立的组件体系——它的官网都用了独立域名。相比直接用 LangChain 写 Agent，LangGraph 用图的方式组织代理逻辑，在循环、分支、持久化和人机交互上提供了更底层的控制力。B站 UP 主这套教程从 Hello World 讲起，逐步展开到多 Agent 实战，下面把其中的核心脉络梳理清楚。

LangGraph 是什么，适合谁用

LangGraph 的定位是做 Agent 的高效开发框架，核心思路是用图的节点和边来构建代理流程。官方提供了完整的文档、示例代码、教程和 API Reference，做 RAG 场景时也有多种案例可以参考，包括 Agentic RAG、Self-RAG 等进阶模式。

它的主要能力集中在几个方向：循环与分支、持久化（检查点机制）、人机交互（断点执行）、流式调用处理，以及和 LangChain、LangSmith 的整合。

安装上有一个容易踩的坑：装了 LangChain 0.3 之后，LangGraph 需要单独升级到匹配版本，否则会报 Pydantic v1 的告警。告警本身不影响运行结果，但建议一并升级到最新版。

检查点机制（Checkpointing） 是 LangGraph 区别于普通链式调用的关键设计。它在图的每一次状态变更后自动落盘一份快照，记录当前节点、消息列表、变量值等全部图状态。快照可以存在内存（MemorySaver）、SQLite、Postgres 等后端。有了检查点，同一条工作流被中断后可以从上一个断点恢复，而不是从头重跑；也为「时间旅行」调试、回滚到某个历史状态、以及 human-in-the-loop 场景提供了基础——人工审核时暂停图，修改状态后再继续。

Pydantic v1 告警 也是常见困惑来源。LangChain 0.3 已迁移到 Pydantic v2，而早期 LangGraph 版本仍依赖 Pydantic v1 的兼容层。混用时会提示 Support for class-based config is deprecated 之类的告警。它不影响运行，但如果要彻底消除，需把 LangGraph 一并升到与 LangChain 0.3 对齐的版本，并统一依赖声明。

Hello World：一张图看懂 LangGraph 的开发模式

教程用一个「查询天气」的迷你案例来建立直观感受。整个流程是一张有向图：起始节点指向 Agent 节点，Agent 调用工具节点，工具节点返回结果给 Agent，Agent 判断无需继续调用工具后走到结束节点。

代码层面分几个关键步骤：

定义工具。 用装饰器把 search 函数变成 LangChain 工具，函数内部判断输入是否包含「上海」，包含就返回一段模拟天气数据。然后把工具放进列表，调用 bind_tools 绑定到大模型，让大模型自行匹配该调用哪个工具。

构建工具节点。 工具除了绑定给大模型，还需要变成一个工具节点，因为 LangGraph 里所有要执行的任务都必须是节点。普通节点本质就是函数，但工具节点需要用 LangGraph 提供的专用类来包装。

定义路由函数。 路由函数从共享内存（MessageState）中取出消息，判断大模型是否要求调用工具——要求就返回工具节点，不要求就返回结束节点。

组装图。 创建 StateGraph 并传入 MessageState，然后依次添加 agent 节点和 tools 节点，设置入口点为 agent，用条件边连接 agent 到路由函数，用普通边连接 tools 回 agent。

编译与运行。 加上 MemorySaver 作为检查点存储，调用 compile 生成可运行对象，之后用 stream 等方式调用即可。运行时传入和 LangChain 一致的 config（包含 session id / user id），同一 id 下上下文就能生效。

核心组件逐个拆解

节点就是函数

LangGraph 里的节点理解起来并不复杂——它就是一个干活的函数或方法。添加节点时第一个参数是节点名称，第二个参数是函数本身。工具节点稍有不同，需要用 ToolNode 包装，因为工具是列表形式、可能多个，LangGraph 调用工具时会做特殊处理，不能当普通函数直接用。

普通边与条件边

边分两类。普通边（add_edge）连接的两个节点之间走向确定，比如工具节点执行完固定返回 agent 节点。条件边（add_conditional_edges）则要挂一个路由函数，由函数返回值决定走哪条分支。路由函数最终能到达的节点，在添加条件边时就要声明清楚。

状态与共享内存

每个节点执行完都会对状态产生变更，就像打游戏过关后的存档。这个存档在不同节点之间共享，路由函数、调用大模型的函数都从里面取消息。换句话说，状态是贯穿整张图的数据主线。

MessageState 是 LangGraph 中最常用的状态类型，本质上是一个带 messages 字段的 TypedDict，字段值是一个消息列表（List[BaseMessage]）。它之所以特殊，是因为 LangGraph 为 messages 字段预设了「按追加方式合并」的 reducer——每次节点返回新消息时，图不会覆盖旧列表，而是把它们拼接进去。这样大模型在后续调用时就能看到完整的对话历史，工具调用与工具返回也能按顺序保留。如果自定义状态里包含普通字段（如计数器、标志位），默认行为是覆盖而不是累加，需要时可通过 Annotated 显式指定 reducer。

检查点与编译

MemorySaver 承担检查点（存档点）的角色，让跨会话的上下文得以保留。最后的 compile 步骤把图构建成可执行对象，对接 LangChain 的 Runnable 规范，之后就能用 stream 等标准接口调用。

compile 的作用不只是「生成可运行对象」。传入 checkpointer 后，编译产物会对每次执行自动持久化状态；不传则只得到一次性运行图。编译阶段还会做静态校验：入口点是否设置、条件边声明的目标节点是否存在、状态 schema 是否合法等，能在运行前暴露大部分结构错误。编译产物的调用接口沿用了 LangChain Runnable 规范，因此 invoke、stream、astream_events、batch 等方法都可直接使用，也方便嵌入到已有的 LangChain 应用中。

从单 Agent 走向多 Agent：什么时候该用代码而不是拖拽

市面上已有不少可视化拖拽工具（如 Dify 等开源方案），做增删改查、管理后台这类简单业务流程确实能简化开发。但流程一旦复杂，拖拽的通用性就不够了，需要用 LangGraph 通过代码做更精确的管控。

教程强调的是「Agent 工作流定制化」这一趋势。学完 LangGraph 后再回头看那些拖拽工具，会发现其底层思想正是参考了这套图式的工作流模型。单 Agent 能调用大模型，而真正的智能体不仅能调用多个大模型，还能在循环、分支、持久化上按需编排——这正是 LangGraph 在多 Agent 实战中的价值所在。

多 Agent 的常见编排模式 主要有几类。其一是 Supervisor（主管）模式：一个负责分发的路由 Agent 根据任务选择把控制权交给哪个子 Agent，子 Agent 完成后回报主管，再决定下一步。其二是 Network/Swarm 模式：Agent 之间可以直接互相移交（handoff），没有中心节点约束。其三是 Hierarchical 层级模式：主管之下再套一层主管，适合规模较大的系统。LangGraph 之所以适合这类场景，正是因为它用显式的节点和边把「谁把控制权交给谁」写进图里，配合检查点就能在任意 Agent 边界暂停、恢复或人工介入，这是纯提示词堆叠难以稳定实现的。