LangGraph 导读：有状态 Agent 的设计哲学

本章阅读时间：约1.5小时（共12篇）

1.1 LangGraph 是什么

官方定义（来自 LangGraph 官方文档）：

LangGraph is a low-level orchestration framework and runtime for building, managing, and deploying long-running, stateful agents.

LangGraph 是一个低层编排框架和运行时，用于构建、管理和部署长时间运行的有状态 Agent。

官方文档进一步说明：

LangGraph is very low-level, and focused entirely on agent orchestration.

LangGraph 非常底层，完全专注于 Agent 的编排（orchestration）。

如果这个定义还是有点抽象，可以这样理解：LangGraph 把 Agent 的执行过程显式建模为一个有向图——每个处理步骤是图上的一个节点（Node），步骤之间的转移逻辑是图上的边（Edge），整个图的执行状态是一个明确定义的数据结构（State）。开发者从被动的"等 LLM 决定下一步"，变成主动的"设计 Agent 的执行逻辑"。

注意：LangGraph 由 LangChain Inc. 开发，但可以独立于 LangChain 使用——官方文档明确说明："LangGraph is built by LangChain Inc, the creators of LangChain, but can be used without LangChain."

1.1.1 LangGraph 在产品栈中的定位

官方将 LangChain 生态的工具分为三个层级：

官方对何时使用 LangGraph 的建议（原文）：

Use LangGraph when:

• You need fine-grained, low-level control over agent orchestration.
• You need durable execution for long-running, stateful agents.
• You're building complex workflows that combine deterministic and agentic steps.
• You need production-ready infrastructure for agent deployment.

1.1.2 为什么要学 LangGraph？

LangGraph 是目前生产环境中构建复杂 Agent 的主流选择，已被 Klarna、Uber、J.P. Morgan 等公司采用。学会 LangGraph，意味着能够构建真正生产就绪的 Agent 系统，而不仅仅是原型。

1.2 为什么需要 LangGraph：线性链解决不了的三个问题

在理解 LangGraph 之前，先搞清楚它要解决的核心问题。

问题一：循环与条件分支

真实的 Agent 任务不是线性的。一个研究 Agent 可能需要：搜索 → 评估结果质量 → 如果质量不够，再次搜索 → 如果质量够了，生成报告。这是一个包含条件判断和循环的流程。

LangChain 的 LCEL 链（prompt | model | parser）是线性的：A 完成后传给 B，B 完成后传给 C，没有循环、没有条件。要实现"搜索不满意就再搜一次"，需要在 Python 层面手写 while 循环包裹整个链，这很难维护，也无法利用框架的调试工具。

问题二：并行执行

"同时分析 10 个竞争对手"这类任务，10 个分析任务相互独立，应该并行执行。线性链只能串行：分析对手 1，完成后分析对手 2……LangGraph 的图结构天然支持并行：把 10 个分析任务分发到 10 个并行的节点，同时执行，最后汇总结果。

问题三：状态持久化

Agent 执行一半，进程崩溃了——从头开始，还是从断点恢复？对于运行 30 分钟的研究 Agent，"从头开始"意味着浪费之前所有工作。线性链没有持久化机制，中间状态存在内存里，进程一崩，全没了。

这三个问题，正是 LangGraph 官方文档所说的核心能力：Durable execution（持久化执行）、Human-in-the-loop（人机协作）、Comprehensive memory（完整记忆）。

1.3 LangGraph 的五个核心能力

官方文档列出 LangGraph 的五大核心能力（原文）：

1. Durable execution（持久化执行）

Build agents that persist through failures and can run for extended periods, resuming from where they left off.

Agent 在故障后能持续运行，可以从中断处恢复，而不是从头开始。

2. Human-in-the-loop（人机协作）

Incorporate human oversight by inspecting and modifying agent state at any point.

在任意节点暂停 Agent，让人类审查或修改状态后再继续执行。

3. Comprehensive memory（完整记忆）

Create stateful agents with both short-term working memory for ongoing reasoning and long-term memory across sessions.

同时支持单次会话内的短期工作记忆，以及跨会话的长期记忆。

4. Debugging with LangSmith（可观测性）

Gain deep visibility into complex agent behavior with visualization tools that trace execution paths, capture state transitions, and provide detailed runtime metrics.

深度可见性：追踪执行路径、捕获状态转换、提供详细的运行时指标。

5. Production-ready deployment（生产就绪部署）

Deploy sophisticated agent systems confidently with scalable infrastructure designed to handle the unique challenges of stateful, long-running workflows.

专为有状态、长时间运行的工作流设计的可扩展基础设施。

1.4 LangGraph 的三个核心概念：State、Node、Edge

官方文档对 LangGraph 核心架构的描述（原文）：

At its core, LangGraph models agent workflows as graphs. You define the behavior of your agents using three key components: State, Nodes, Edges.

In short: nodes do the work, edges tell what to do next.

State（状态）

The State consists of the schema of the graph as well as reducer functions which specify how to apply updates to the state.

State 是贯穿整个图执行过程的共享数据结构，通常定义为 TypedDict 或 Pydantic BaseModel。每个节点接收 State 作为输入，返回 State 的更新作为输出。

from typing import TypedDict, Annotated
import operator

class State(TypedDict):
    messages: Annotated[list, operator.add]  # reducer：追加而非覆盖
    step: int

Node（节点）

Nodes are Python functions (either synchronous or asynchronous) that encode the logic of your agents. They receive the current state as input, perform some computation or side-effect, and return an updated state.

节点就是普通的 Python 函数，接收 State，返回 State 的更新。节点可以是 LLM 调用、工具执行、人工审核、数据处理——任何有明确输入输出的操作都可以是节点。

Edge（边）

Edges define how the logic is routed and how the graph decides to stop.

边有四种类型：

• 普通边：始终从节点 A 到节点 B
• 条件边：根据路由函数动态决定下一个节点
• 入口点：指定图的起始节点（START）
• 终止节点：指定图的终止（END）

官方还说明：

If a node has multiple outgoing edges, all of those destination nodes will be executed in parallel as a part of the next superstep.

多个出边 = 并行执行，这是 LangGraph 原生支持并行的机制。

1.5 LangGraph 核心概念地图

1.6 LangGraph vs 手写 Agent 的对比

在第 12 章，我们手写了一个 ReAct Agent（约 100 行 Python）。LangGraph 和手写版相比：

手写 Agent 的价值是理解底层原理，LangGraph 的价值是生产就绪。知道了手写 Agent 是如何工作的，才能理解 LangGraph 在哪些环节做了封装，出了问题才知道从哪里入手。

手写 Agent（线性流程，状态难以追踪）vs LangGraph（图结构，节点清晰可测试可扩展）

1.7 本章 12 篇文章的学习路径

本章从基础概念到复杂模式，按照认知难度递进编排。

概念入门（第 01-02 篇）

01 讲为什么 Agent 需要状态机——通过对比 AgentExecutor 的局限，建立对 LangGraph 设计动机的直觉理解。这是本章最重要的一篇，不理解动机就很难理解后续设计决策的合理性。02 讲条件边（Conditional Edge）和循环控制——这是超越线性流程的关键，掌握了条件边才能表达任意复杂的执行逻辑。

建议：读完第 01 篇后，提前阅读第 11 篇（高级状态设计/Reducer），再回来按顺序学习第 02-10 篇。State 的 Reducer 机制贯穿整个 LangGraph 的条件分支、并行执行和持久化，提前理解能避免后续很多困惑。

核心机制（第 03-06 篇）

03 讲 Human-in-the-Loop 人机协作设计：如何在特定节点暂停 Agent 等待人工输入，如何设计中断点，如何处理人工修改后的状态继续执行。04 讲 Subgraph 子图与模块化设计：把复杂 Agent 拆分成可复用的子图，是大规模 Agent 系统的架构基础。05 讲持久化（Persistence）与断点续跑：Checkpointer 的使用方式、线程（Thread）的概念、从中间状态恢复执行的实现。06 讲 Stream 流式输出与实时反馈：在 LangGraph 中实现逐 Token 输出和节点级事件流。

高级架构（第 07-10 篇）

07 讲 Multi-Agent 多智能体协作架构：Supervisor 模式（一个协调者分发任务给多个 Worker）和 Swarm 模式（Agent 之间对等协作）的设计与实现。08 讲错误处理与容错机制：官方文档将错误分为四类——瞬时错误（RetryPolicy 自动重试）、LLM 可恢复错误（写入 State 循环回 LLM）、用户可修复错误（interrupt 暂停等待）、未知错误（让异常冒泡）。09 是完整实战——构建一个研究报告生成 Agent，综合应用前几篇的所有概念。10 讲 Send API 并行任务与 MapReduce 模式：同时分发多个子任务、汇总结果，是高效 Multi-Agent 架构的关键。

深度机制（第 11-12 篇）

11 讲高级状态设计：Reducer 函数（如何合并并发节点的状态更新）、状态分层（区分私有状态和公共状态）。（注：虽然编号靠后，但建议在第 01 篇之后提前阅读，State 的 Reducer 是贯穿全章的基础机制）12 讲 Command：LangGraph 的现代路由方式，官方描述为"a versatile primitive for controlling graph execution"，比条件边更灵活，可以同时做状态更新和路由跳转。

1.8 LangGraph 与 LangChain 的关系

这是最容易产生误解的地方。官方文档明确说明两者的关系：

While LangChain is built on top of LangGraph, you don't need to know LangGraph to use LangChain.

We will commonly use LangChain components throughout the documentation to integrate models and tools, but you don't need to use LangChain to use LangGraph.

两者不是替代关系，而是分层关系：LangGraph 是底层运行时，LangChain 的 Agent 模块构建在 LangGraph 之上。在实际项目中，LangGraph 负责图结构和状态管理，LangChain 的组件（ChatModel、Tools、Retriever）作为图中节点的具体实现。

何时只用 LangChain，何时引入 LangGraph（参考官方建议）：

• 简单对话机器人、单次文档处理、固定流程的 Workflow → LangChain 足够
• 需要中间状态持久化、Human-in-the-Loop、复杂分支逻辑、Multi-Agent 协作 → 引入 LangGraph

1.9 与其他章节的关联

与 Agent 基础（第 12 章）的关系

LangGraph 是 Agent 基础章节中 Plan-and-Solve（先规划再执行）、Reflection（自我反思迭代）、Human-in-the-Loop 等概念的工程化实现。理解了 Agent 基础，LangGraph 的每个设计决策都能找到对应的理论来源：Checkpointer 解决了 Agent 状态持久化的问题，Conditional Edge 实现了 Plan-and-Solve 的分支决策，interrupt 实现了 Human-in-the-Loop 的暂停机制。

与 LangChain（第 14 章）的关系

LangGraph 可独立于 LangChain 使用，但官方文档中的大量示例使用了 LangChain 的 ChatModel、ToolNode 等组件作为图中的节点。第 14 章是本章的重要参考，理解了 LangChain 的组件体系，能更好地在 LangGraph 的节点里使用这些组件。

与生产化部署（第 18 章）的关系

LangGraph 的 Checkpointer 机制、Stream 输出、Human-in-the-Loop 设计，在生产化部署中有直接应用。第 18 章的流式输出 SSE 实现和异步任务队列，与 LangGraph 的 Stream 和 Persistence 机制高度关联。

与前沿方向（第 20 章）的关系

Multi-Agent 架构（第 07 篇）与前沿方向章节的 Multi-Agent 协作主题高度重叠，两章从不同角度（工程实现 vs 架构模式）覆盖同一主题。

1.10 学完本章能做什么

• 图结构设计：能把任意复杂的 Agent 执行逻辑用图结构表达——哪些步骤、哪些条件分支、哪些循环、哪些并行
• 状态管理：能定义清晰的 State 数据结构，为每个节点设计合理的状态读写边界，理解 Reducer 的作用
• 持久化实现：能为长时间运行的 Agent 任务添加 Checkpointer，实现断点续跑
• Human-in-the-Loop：能用 interrupt() 在关键节点设计人工介入机制，让 Agent 在需要时暂停等待确认
• Multi-Agent 架构：能用 Supervisor 模式实现多 Agent 分工协作，处理超出单 Agent 能力边界的任务
• 生产调试：能利用 LangGraph 的结构化状态和节点独立测试能力，配合 LangSmith 快速定位生产问题

LangGraph 的核心转变：把 Agent 从"让 LLM 自由发挥"的黑盒，变成"可设计、可调试、可持久化"的工程系统。从原型到生产之间的差距，很大程度上就在这里。