LangGraph 详解(初学者完整版)

LangGraph 是 LangChain 团队出品的底层智能体编排框架:用”图”(状态 + 节点 + 边)来构建有状态、可持久化、可恢复的长时运行 Agent 与工作流。
本文面向初学者,从”为什么需要它”讲到全部核心概念,力求一份文档讲透。基于 LangGraph v1(当前 1.2.x,2026-11),内容核对自官方文档(docs.langchain.com)。

配套阅读:《第一个LangGraph程序.md》——本文讲”是什么/为什么/全部关键点”,那篇带你 40 分钟亲手写一个完整程序。

官方文档:https://docs.langchain.com/oss/python/langgraph/overview



1. 初学者地图:一张图看懂 LangGraph

先把全部概念放在一张图里,后面章节逐一展开。初学者只需先记住五个词:State、Node、Edge、Checkpointer、interrupt。

┌───────────────────────────────────────────────────────────────────┐
│                        你写的部分(图定义)                          │
│                                                                   │
│   State ──带 reducer 的 TypedDict,全图共享的数据总线                │
│   Node  ──普通 Python 函数:(state) -> 增量更新                     │
│   Edge  ──决定"下一步去哪":固定边 / 条件边 / Command / Send         │
│                                                                   │
├───────────────────────────────────────────────────────────────────┤
│                    框架提供的部分(运行时能力)                       │
│                                                                   │
│   Checkpointer ──每个超步自动存档:恢复、重试、时间旅行、会话隔离       │
│   interrupt    ──图在任意位置暂停,等人审批后 Command(resume) 继续    │
│   Store        ──跨会话长期记忆(用户偏好、事实档案)                  │
│   stream       ──7 种流式模式:token 级 / 节点增量 / 自定义进度        │
│                                                                   │
├───────────────────────────────────────────────────────────────────┤
│                        生态(按需引入)                              │
│   LangSmith(追踪评测)· Agent Server(部署)· Studio(可视化调试)   │
└───────────────────────────────────────────────────────────────────┘

一句话定位:LangGraph 之于 Agent,就像工作流引擎之于业务流程——把”模型自己决定下一步”和”工程上必须可控”这对矛盾,用图编排统一起来。

灵感来源:执行模型借鉴 Google 的 Pregel(BSP 超步模型),公共接口借鉴 NetworkX。由 LangChain Inc. 构建,但可以完全脱离 LangChain 使用(不用 LangChain 的模型/工具抽象也行)。


2. 为什么需要 LangGraph

2.1 三个阶段,复杂度逐级上升

用 LLM 做应用一般会经历三个阶段:

阶段 形态 需要什么
1. 单轮问答 prompt in → completion out 不需要框架
2. 工具调用 Agent 模型循环调工具直到给出答案 一个 ReAct 循环
3. 可靠的生产级 Agent/工作流 长时运行、多步骤、要断点恢复、要人工审批、要记住历史 状态机 + 持久化 + 编排

第 3 阶段自己手写要解决一堆问题:中间状态存哪、进程挂了怎么恢复、哪一步需要人审批、多轮对话记忆怎么存、每一步怎么观测。LangGraph 把这些做成一等公民。

2.2 它的四大一等能力(贯穿全文的主线)

能力 一句话解释 详细章节
持久执行(Durable Execution) 每步之后把状态写入 Checkpointer,崩溃/重启后从断点恢复 §8
人机协作(HITL) 任何节点都能 interrupt() 暂停等人,审批后 Command(resume=...) 继续 §9
记忆 短期(线程内消息/状态)+ 长期(跨会话 Store) §10
可控性与可观测 图结构显式可画、每步可 stream、接 LangSmith 全链路追踪 §11

2.3 “图”比”链”和”自由循环”好在哪

初学者常见疑问:为什么不直接写个 while 循环调 LLM?对比一下:

方案 问题
while 循环手搓 Agent 状态散在局部变量里;进程挂了全丢;没有审批暂停点;没法回放调试
LangChain LCEL 链 适合固定的线性管道,但分支/循环/动态路由表达不了
LangGraph 图 状态集中、每步存档、可暂停、可画图、可单步重放——显式、可恢复、可控

社区实践反复证明:很多场景下”显式、刚性的少数节点”比”一个大 Agent 自由发挥”更可控、更省 token、更好调试。LangGraph 的图正是承载这种确定性的工具。


3. 5 分钟跑通最小程序

3.1 安装

pip install -U langgraph
# 配合 LangChain 的模型抽象时(可选):
pip install -U langchain langchain-openai    # 或 langchain-anthropic

langgraph 会自动带上 langgraph-checkpoint、langgraph-prebuilt 等依赖。

3.2 最小可运行程序

from langgraph.graph import StateGraph, MessagesState, START, END

def mock_llm(state: MessagesState):
    return {"messages": [{"role": "ai", "content": "hello world"}]}

graph = StateGraph(MessagesState)
graph.add_node(mock_llm)                    # 省略名字时用函数名 "mock_llm"
graph.add_edge(START, "mock_llm")
graph.add_edge("mock_llm", END)
graph = graph.compile()                     # 编译成 Runnable;之后图不可再改

graph.invoke({"messages": [{"role": "user", "content": "hi!"}]})

就这十几行,五要素全齐:State(MessagesState,官方预置的只有 messages 一个字段的状态)、Node(mock_llm)、Edge(两条固定边)、编译(compile())、运行(invoke)。下面开始逐个概念讲透。


4. State(状态)详解

4.1 状态是什么:全图共享的数据总线

State 是一个(通常带 Annotated reducer 的)TypedDict / dataclass / Pydantic 模型。图里的每个节点都从它读数据、往它写增量,它是唯一的数据传递方式——节点之间不直接调用,全靠状态通信。

from typing import Annotated
from typing_extensions import TypedDict
from langgraph.graph.message import add_messages

class State(TypedDict):
    messages: Annotated[list, add_messages]   # reducer:追加而不是覆盖
    query: str                                # 无 reducer:直接覆盖

三种定义方式对比(官方推荐前两种):

方式 特点 何时用
TypedDict 最简单、性能好 默认选择
dataclass 支持默认值 需要字段默认值时
Pydantic BaseModel 带运行时校验 输入不可信、需要类型约束时(注意:create_agent 只支持 TypedDict)

4.2 Reducer:理解 LangGraph 的钥匙

State 存储在 channels(状态 schema 里的每个 key 就是一个 channel)。每个 channel 持有一个值,并定义”更新如何合并”——这个合并函数就是 reducer:

new_value = reducer(left=当前值, right=节点返回的更新)
  • 没有 reducer 的字段:默认行为是 last-write-wins——谁最后写谁生效(直接覆盖)。
  • 有 reducer 的字段:节点返回值会和当前值合并,而不是替换。
import operator
from typing import Annotated
from typing_extensions import TypedDict

class State(TypedDict):
    foo: int                                   # 无 reducer:覆盖
    bar: Annotated[list[str], operator.add]    # reducer:列表拼接
    tags: Annotated[list[str], my_merge]       # reducer:任意自定义函数

def my_merge(left: list[str], right: list[str]) -> list[str]:
    """reducer 就是普通二元函数:左=当前值,右=本次更新"""
    return list(set(left + right))             # 例如去重合并

更新示例:状态是 {"foo": 1, "bar": ["hi"]},某节点返回 {"bar": ["bye"]} → 新状态 {"foo": 1, "bar": ["hi", "bye"]}。foo 没被写就保持原样——节点返回的是增量(partial update),不是全量替换。

4.3 add_messages:你最常用的 reducer

add_messages 做两件事:新消息追加进列表;同 id 的消息原地替换。这是”对话历史自动累积”和”编辑历史消息”的全部秘密。

class State(TypedDict):
    messages: Annotated[list[AnyMessage], add_messages]

注意与 operator.add 的区别:operator.add 只能追加,没法在人工编辑场景原地更新某条历史消息;add_messages 按消息 id 判断,id 相同就替换。

它还支持”wire format”:节点可以直接返回 {"messages": [{"role": "user", "content": "..."}]} 这种字典形式,框架自动反序列化成消息对象,之后就能用 state["messages"][-1].content 点号访问。

4.4 MessagesState:预置的简写

官方预置了只有一个 messages 字段(已内置 add_messages reducer)的 MessagesState,最小程序可以直接用它;需要更多字段时子类化:

from langgraph.graph import MessagesState

class State(MessagesState):     # 继承了 messages + add_messages
    documents: list[str]        # 自己再加字段

4.5 Overwrite 与”重置 reducer 字段”

两个进阶细节(初学者先知道存在即可):

  • **Overwrite**:绕过合并型 reducer、直接替换值(包括”清空”)。合并型 reducer 下返回空值/空列表通常不会清掉旧数据(因为 reducer 把空值当作”无更新”合并),想强制清空就用它;
  • 重置场景:错误缓冲、重试计数器这类字段在新一轮要清零时,同样需要 Overwrite 或专门的清空写法,否则旧数据一直留着。

4.6 输入/输出 schema 与私有状态

默认图的输入/输出 schema 就是完整 state。进阶做法:

  • 收窄输入输出:定义单独的输入/输出 schema(state 的子集),只约束 invoke 接受什么、返回什么,对内仍然全量;
  • 私有 channel:某些字段(如中间草稿)只供内部节点使用,不放进输入/输出 schema——外部调用者根本看不到。

初学者阶段可以先不管这两条,等图变大、字段变多时再回来用。


5. Node(节点)详解

5.1 节点是普通 Python 函数

签名是 (state) -> dict,返回值是对状态的增量更新:

def node_a(state: State) -> dict:
    return {"query": state["query"].strip()}   # 只写改动的字段

节点里可以做任何事:调 LLM、查数据库、调工具、甚至 interrupt() 暂停等人。

5.2 三种可用签名

节点函数除了 state,还可以按位置接收另外两个可选参数:

def plain_node(state: State): ...
def node_with_config(state: State, config: RunnableConfig): ...
def node_with_runtime(state: State, runtime: Runtime[Context]): ...
参数 里面有什么 何时用
state 当前图状态 永远可用
config RunnableConfig:thread_id、tags、回调等运行配置 需要读 thread_id / 透传 tracing 配置
runtime Runtime 对象:runtime context、store、stream_writer、execution_info 需要长期记忆 Store、自定义流式、依赖注入

5.3 注册节点与默认命名

builder.add_node("a", node_a)    # 显式命名
builder.add_node(node_a)         # 省略名字 → 自动用函数名 "node_a"

内部会被包装成 RunnableLambda,自动获得批量调用、异步支持和 LangSmith tracing。

5.4 重试与缓存

  • 重试:builder.add_node("name", fn, retry=RetryPolicy(max_attempts=3))——节点是 retry 边界,失败自动重试;
  • 缓存:编译时传 cache=...,节点上挂 CachePolicy,相同输入直接复用结果。

5.5 幂等性:最重要的节点纪律

节点是 checkpoint 与 retry 的边界:interrupt 恢复、重试时,节点会从函数开头整个重跑。所以:

  • 节点里的副作用(写数据库、发请求)必须幂等(用 upsert、幂等键、读后写检查);
  • 昂贵且不该重复的子操作,可以用 Task 原语(已完成 task 会返回缓存结果,见 5.6);
  • 涉及 interrupt() 的节点尤其注意:interrupt 之前的代码每次 resume 都会再执行一遍(§9 详述)。

5.6 工作单元的选择(进阶认知)

原语 自有 checkpoint 恢复/重试行为 适用场景
节点内普通函数 否 随节点重跑 无路由分叉、重复执行可接受
Task 否(结果存于父 checkpoint) 已完成的 task 返回缓存结果 有副作用或昂贵、不应重复
Subgraph 有(父线程命名空间下) 在被中断节点处恢复 独立路由/schema,或被多个父图复用
Graph node 是 从该节点恢复,之前的节点不重跑 需要路由分叉/interrupt/时间旅行

初学者记住结论即可:把图切成足够小的节点,天然就获得了”从断点恢复、失败的节点不重跑”的好处——这也是”别把一百行业务塞一个节点”的根本原因。


6. Edge(边)与路由:条件边、Command、Send

边决定”节点跑完之后下一步去哪”。LangGraph 有四种路由机制,每个节点的出边只用其中一种(混用是路由 bug 的头号来源)。

6.1 普通边(固定流转)

from langgraph.graph import StateGraph, START, END

builder = StateGraph(State)
builder.add_node("a", node_a)
builder.add_edge(START, "a")     # 入口
builder.add_edge("a", END)       # 出口
  • START / END 是虚拟的入口/终点节点;
  • 入口也可以是条件的:add_conditional_edges(START, router_fn)——按输入决定第一跳。

6.2 条件边(函数决定下一跳)

def router(state: State) -> str:
    if state["query"].startswith("/help"):
        return "help_node"
    return "answer_node"

builder.add_conditional_edges("a", router, {"help_node": "help_node", "answer_node": "answer_node"})
  • 路由函数接收当前 state,返回:目标节点名、END、名称列表(fan-out,多路并行)、或 Send 对象列表(见 6.4);
  • 显式映射表(第三个参数)可选,但建议写上——它同时是给 draw_mermaid() 可视化用的边声明。

6.3 Command:状态更新 + 路由一步完成(v1 推荐)

v1 推荐在节点内直接返回 Command,把”改状态”和”决定去哪”写在一起,更内聚:

from langgraph.types import Command

def route(state: State) -> Command[Literal["help_node", "answer_node"]]:
    if state["query"].startswith("/help"):
        return Command(update={"query": ""}, goto="help_node")
    return Command(goto="answer_node")

Command 的四个参数:

参数 用途
update 状态更新(同普通节点返回值)
goto 下一节点(同条件边的返回)
graph 从子图跳父图时用 Command.PARENT
resume interrupt 恢复专用(§9)

两个要点:

  • 返回类型注解成 Command[Literal["节点名"]],图可视化才能画出这条动态边;
  • Command(resume=...) 是唯一能作为 invoke()/stream() 输入的 Command 形式。不要拿 Command(update=...) 当多轮对话的输入用——任何 Command 输入都从最新 checkpoint 恢复而不是从头跑,新回合应该传普通 dict。

两种写法怎么选:路由逻辑和状态更新在一起、还要顺手改状态 → Command;路由是纯函数、想复用、不碰状态 → add_conditional_edges。

6.4 Send API:map-reduce(动态并行分发)

当数量只在运行时才知道、且每个子项要独立跑一遍同一节点时(比如”对列表里每个主题各生成一个笑话”),用条件边返回 Send 列表:

from langgraph.types import Send

def continue_to_jokes(state: State):
    return [Send("generate_joke", {"subject": s}) for s in state["subjects"]]

builder.add_conditional_edges("node_a", continue_to_jokes)
  • 每个 Send(目标节点, 自定义输入) 是一个独立并行任务,输入不必是完整 State;
  • 各分支写共享 key 时由该 key 的 reducer 合并(又见 4.2——没有 reducer 的共享字段在并行写时会冲突报错)。

这是构建 orchestrator-worker(指挥官-工人)模式的基础。

6.5 并行 fan-out / fan-in

更简单的并行:一个节点多条出边,目标在同一个超步内并行执行,全部结束后汇合到下游节点(fan-in)。同样依赖共享 key 的 reducer 来合并各分支的写入。


7. 执行模型:Pregel 超步

LangGraph 按 Pregel 超步(superstep)执行,理解它就理解了”图是怎么转起来的”:

一轮超步 = 「所有当前该跑的节点并行执行」
         → 「各自返回增量」
         → 「reducer 合并进状态」
         → 「存档 checkpoint」
         → 「按边决定下一轮跑谁」

直到:所有节点失活 且 没有消息在途 → 运行结束
  • 并行节点共享一个超步;顺序节点各占一个超步;
  • 节点在”收到入边消息”时被激活——这就是为什么没有入边的节点永远不会跑。

递归上限(recursion_limit)

  • 新版本默认上限很高(1.1.4+ 为 10,007 个超步;更早的版本是 25——这也是老教程里常见 GraphRecursionError 的原因);
  • 超限抛 GraphRecursionError,工具死循环、路由成环时最先看到它;
  • 覆盖方式(注意 recursion_limit 在顶层,不放 configurable 下):
graph.invoke(input, config={"recursion_limit": 50, "configurable": {"thread_id": "t1"}})

图会变吗:已存档线程的兼容性

已完成线程可以自由增删改名节点/边;中断中的线程可以改边、加节点,但不能改名/删除即将进入的节点;state key 增删兼容,改名会丢旧值。改图结构时注意正在等待恢复的会话。


8. Checkpointer 与持久化(含时间旅行)

8.1 两套持久化系统的分工

Checkpointer(检查点器) Store(存储)
持久化什么 图状态快照 应用自定义的键值数据
范围 单个 thread(会话)内 跨 thread
记忆类型 短期记忆 长期记忆
用于 会话延续、HITL、时间旅行、容错 用户偏好、事实档案、共享知识
访问方式 config 里传 thread_id 节点/应用代码里 store.get/put/search

大多数应用两个都用:checkpointer 管当前会话,store 管跨会话的持久信息。本节讲 checkpointer,Store 见 §10。

8.2 基本用法:compile 时挂载

from langgraph.checkpoint.memory import MemorySaver       # 测试用(新版也叫 InMemorySaver)
# from langgraph.checkpoint.sqlite import SqliteSaver     # 本地生产:pip install langgraph-checkpoint-sqlite
# from langgraph.checkpoint.postgres import PostgresSaver # 云上生产

graph = builder.compile(checkpointer=MemorySaver())

config = {"configurable": {"thread_id": "user-42"}}
graph.invoke({"messages": [...]}, config)

工作机制:

  • 每个超步结束都存档一次完整状态快照;
  • 节点失败可重试、进程崩溃/重启后从断点恢复;
  • thread_id 隔离会话:同一个编译后的图,不同 thread_id 就是不同的对话,彼此完全隔离。每次 invoke 都带同一个 config 才有记忆——这是初学者第一大坑。

8.3 Checkpointer 实现选型

实现 场景 备注
MemorySaver / InMemorySaver 本地开发、单元测试 只存内存,重启全丢,永远别上生产(官方反复强调的头号坑)
SqliteSaver 本地/单机小规模生产 需单独安装 langgraph-checkpoint-sqlite
PostgresSaver / AsyncPostgresSaver 云上生产 首次要 checkpointer.setup() 建表;thread_id 列长有限制(<255 字符,超长会报数据库错误)
Agent Server 托管 部署在官方 Server 自动处理持久化,不用手动配置(§16)

两个运维提醒:长对话的 checkpoint 会无限累积(增加延迟和存储成本),要定期清理或设保留策略;子图默认有自己的 checkpoint 命名空间,跨图共享数据建议用 Store(§12)。

8.4 读取与修改状态:get_state / update_state

# 读当前状态(含 next:下一步要跑的节点;tasks:在途任务)
snapshot = graph.get_state(config)
print(snapshot.values, snapshot.next)

# 人工修改状态(例如管理员改参数、修正错误字段)
graph.update_state(config, {"query": "修正后的输入"})

8.5 时间旅行(Time Travel):get_state_history

checkpointer 保存了每一步的快照,所以可以回到任意历史时刻:

# 列出全部历史快照(从新到旧)
for s in graph.get_state_history(config):
    print(s.config, s.values.get("messages", [])[-1:])

# 取某个历史快照的 config,从那里重新 invoke——
# 相当于"改写历史":从那一步重来,后续节点重新执行
past = list(graph.get_state_history(config))[-3]
graph.invoke(None, past.config)     # None = 从该 checkpoint 恢复执行

用途:调试(看每一步状态长什么样)、修状态重放、对比不同分支。这是手搓 Agent 完全没有的能力。

8.6 Static breakpoints:调试用断点

与 interrupt(动态,§9)相对的是静态 breakpoints——在固定位置暂停:

graph = builder.compile(interrupt_before=["tools"])   # 编译时声明
# 或每次运行时指定:
graph.invoke(inputs, config, interrupt_before=["tools"])
动态 interrupt() 静态 breakpoints
位置 代码任意处、可条件触发 节点前后固定位置
恢复 Command(resume=value) graph.invoke(None, config)
适用 HITL 工作流(官方推荐) 调试/测试,逐节点单步执行

9. Human-in-the-loop:interrupt 全解

这是 LangGraph 相对手搓 Agent 最实用的能力:把”人审批”变成图里的一个暂停点,暂停状态持久化在 Checkpointer 里——人可以一小时后甚至第二天再批,进程重启都不影响。

9.1 基本机制

from langgraph.types import interrupt, Command

def approve_node(state: State):
    decision = interrupt({"question": "是否发送这封邮件?",   # payload:给协调者看的暂停信息
                          "details": state["action_details"]})  # 图在此暂停
    if decision != "yes":            # decision = 恢复时 Command(resume=...) 的值
        return Command(goto="cancel")
    return {"status": "sent"}

# —— 客户端侧 ——
result = graph.invoke(input, config)
print(result["__interrupt__"])                          # invoke 返回结果里带中断信息

# ……人看完后,随时恢复(可以换进程、隔一天):
result = graph.invoke(Command(resume="yes"), config)

前提三件套:**checkpointer + config 里的 thread_id + 在暂停点调用 interrupt()**。

payload 可以是任意 JSON 可序列化值;恢复值同样任意,由你定义审批协议(布尔、结构体都行)。

9.2 四条 interrupt 铁律(官方 Rules of interrupts)

interrupt 通过抛特殊异常实现暂停,恢复时整个节点从头重跑,因此:

  1. **不要用 try/except 包裹 interrupt()**——会吞掉中断异常。要么把 interrupt 和易错代码分开,要么 except 里写具体异常类型;
  2. 不要在节点内用非确定性逻辑重排/条件跳过 interrupt 调用——resume 值按严格索引匹配,每次执行的调用顺序必须一致。不要 while True 循环里调 interrupt,多轮输入用条件边循环回节点;
  3. payload 不要传复杂值——只传 JSON 可序列化内容,不传函数、类实例;
  4. interrupt 之前的副作用必须幂等——每次 resume 都会重跑,db.create_audit_log() 这种”创建新记录”的调用放 interrupt 之前会产生重复记录;要么用 upsert,要么把副作用拆到独立节点。

9.3 四种常用模式

a) 审批(最常用):见 9.1,批准/拒绝走不同分支。

b) 审查并编辑状态:人直接改内容,resume 值就是修改后的结果:

def review_node(state: State):
    edited = interrupt({"instruction": "请审阅并修改这段内容",
                        "content": state["generated_text"]})
    return {"generated_text": edited}      # resume 值直接写回状态

c) 工具内中断:在 @tool 函数内部调 interrupt()——LLM 自然调用工具时自动暂停,恢复值还可以覆盖工具参数(如 response.get("to", to)),审批逻辑可复用:

@tool
def send_email(to: str, body: str) -> str:
    """发送邮件。"""
    confirm = interrupt({"action": "send_email", "to": to, "body": body})
    if confirm is not True:
        return "用户取消了发送"
    return f"已发送邮件给 {to}"

d) 验证人类输入(多轮表单):interrupt() 每个节点 invocation 只调一次,无效输入的错误提示存进 state,用条件边循环回本节点重新 interrupt,直到输入合法。

9.4 进阶能力

  • 响应 schema(≥1.2.12):interrupt(payload, response_schema=PydanticModel)——恢复值经校验后返回类型化对象,无效输入抛 pydantic.ValidationError;Studio 会自动渲染成表单;
  • 多个并行中断:fan-out 多分支同时中断时,用 interrupt ID → resume 值的映射恢复:Command(resume={i.id: value for i in stream.interrupts});
  • 严格恢复模式(1.2.20+,可选 __pregel_strict_resume):resume 指向已不存在的 interrupt 时显式报错而非静默重跑,多 interrupt 场景建议开。

9.5 子图中的中断行为

以函数方式调用含 interrupt 的子图时,恢复从父图调用子图的那个节点的开头执行,子图也从触发 interrupt 的节点开头恢复——两侧 interrupt 之前的代码都会重跑。又一个”幂等性”的重要理由。

9.6 双提交(Double Texting)

用户在上一次运行还没结束时又发新消息(聊天应用常见)。LangGraph 支持配置处理策略:拒绝新请求、中断旧运行、排队、回滚旧运行再开新的。部署层(Agent Server)一般已内置处理,自建服务时需要考虑。


10. 记忆系统:短期记忆与长期 Store

10.1 总览:两层记忆

层 载体 作用域 典型内容
短期记忆 Checkpointer + thread_id 单个会话(thread) messages、中间状态、上传文件、检索文档
长期记忆 BaseStore(InMemoryStore / Postgres Store) 跨会话、按 namespace 用户偏好、事实档案、few-shot 示例、agent 指令

关键认知:记忆不在模型里,在状态里。checkpointer 把每个超步后的完整状态存档,下次同 thread_id 的调用从存档恢复;消息列表靠 add_messages reducer 自动带着全部历史。

10.2 短期记忆的管理:裁剪与摘要

长对话是短期记忆的头号问题:历史塞不进上下文窗口会直接报错;就算塞得进,模型也会”分心”、变慢、变贵。两种主流手段:

  • 裁剪(trim):只保留最近 N 条消息进模型调用(注意:是从状态里”取最近 N 条”喂模型,不是删历史——历史还在 checkpoint 里);
  • 摘要(summarization):用模型把旧消息压缩成一段摘要,作为一条特殊消息留在历史里;官方在 create_agent 层提供了 Summarization middleware,手写图可自行实现 summarize 节点。

10.3 长期记忆:Store 的 namespace / key / value

长期记忆以 JSON 文档形式存在 Store 里,组织结构类似文件系统:namespace 相当于文件夹(可多层),key 相当于文件名:

from langgraph.store.memory import InMemoryStore

store = InMemoryStore()          # 生产换 Postgres-backed Store
namespace = ("user-42", "preferences")

store.put(namespace, "style", {"rules": ["用户喜欢简短直接的回答"]})
item = store.get(namespace, "style")
print(item.value["rules"])

# 搜索:可按内容过滤 + 语义向量相似度排序(需配置 index/embed)
items = store.search(namespace, query="说话风格偏好")

节点里通过签名注入使用(见 5.2 的 runtime,或旧式签名直接收 store: BaseStore 参数):

def call_model(state: State, store: BaseStore):
    prefs = store.get(("user-42", "preferences"), "style")
    ...

10.4 记忆的三种类型(CoALA 框架)

官方用人类记忆类比 agent 记忆,这个框架在选型时很有用:

类型 存什么 人类例子 Agent 例子
Semantic(语义) 事实 学校学到的知识 用户档案、事实(”用户喜欢简洁回答”)
Episodic(情景) 经历 做过的事 过往成功的 agent 操作 → few-shot 示例
Procedural(程序性) 规则 骑车的肌肉记忆 agent 自己的 system prompt(通过反思自我改进)
  • Semantic 两种管理方式:单份持续更新的 profile(整份 JSON 每次重生成)或 collection(多条记忆文档按需检索);
  • Episodic 实践上常做成 few-shot 示例库:把成功案例存进 Store,检索最相关的注入 prompt;
  • Procedural 的典型用法是”反思”:把当前指令 + 近期对话喂给模型生成改进版指令,store.put 写回——agent 自己进化自己的 prompt。

10.5 写入时机:热路径 vs 后台

方式 优点 缺点
热路径(agent 运行中顺手写,如 ChatGPT 的 save_memories 工具) 实时可用、对用户透明 增加延迟;agent 分心,记忆质量可能下降
后台(单独异步任务/cron 定期总结) 不拖慢主流程、逻辑解耦 更新不及时;要设计触发时机

初学者建议:先用热路径(把”记笔记”做成一个工具),规模大了再转后台。


11. 流式输出全解

调试 Agent 行为的第一习惯——先 stream 再谈 invoke:能实时看到每个节点干了什么。

11.1 七种 stream_mode

for chunk in graph.stream(inputs, config, stream_mode="updates"):
    ...
模式 推送内容 典型用途
values 每步后的全量状态快照 检查累积效果
updates 每节点的状态增量 调试:看每步干了什么
messages LLM 的 (token, metadata) 二元组,逐 token 前端打字机效果
custom 节点内 get_stream_writer() 发的自定义数据 长任务进度条
checkpoints Checkpoint 事件(格式同 get_state()) 观察存档过程(需 checkpointer)
tasks 任务开始/结束事件(含结果与错误) 监控执行(需 checkpointer)
debug checkpoints + tasks + 额外元数据,最全 深度调试

多模式可叠加:stream_mode=["updates", "messages"]。

11.2 新版统一格式(v2,≥1.1)

传 version="v2" 后,无论单模式、多模式还是子图,每个 chunk 都是统一的 {type, ns, data} 字典,按 chunk["type"] 分流处理(类型可收窄);子图事件靠 chunk["ns"](namespace 元组)区分来源,根图为空元组。v2 的 invoke() 返回 GraphOutput(.value 与 .interrupts 属性)。

11.3 token 级流式的过滤技巧

messages 模式会把图里所有 LLM 调用的 token 都推出来,需要过滤:

  • 按调用过滤:给模型打 tag init_chat_model(..., tags=["joke"]),流里检查 metadata["tags"];
  • 按节点过滤:metadata["langgraph_node"] == "some_node";
  • 排除输出:给不想流出的调用(如内部结构化输出)打 nostream tag,token 不进 messages 流;
  • 非流式模型:初始化时 disable_streaming=True。

11.4 自定义流:get_stream_writer

节点里随时发自定义进度(也可用于转发非 LangChain 模型 SDK 的 chunk):

from langgraph.config import get_stream_writer

def my_node(state: State):
    writer = get_stream_writer()
    writer({"progress": "已处理 50%"})
    return {"answer": "done"}

# 调用端:stream_mode="custom"

注意(Python < 3.11 的异步限制):必须显式把 RunnableConfig 传进异步 LLM 调用;且不能用 get_stream_writer(),改为在节点签名里声明 writer: StreamWriter 参数由框架注入。

11.5 子图流式陷阱

create_agent 返回的编译图作为节点加入父图后就是子图。不加 subgraphs=True,父图的 stream_mode="messages" 不会输出内层 agent 的 LLM token——前端”看不到打字效果”多半是这个原因。

11.6 图可视化

print(graph.get_graph().draw_mermaid())    # 输出 Mermaid 文本,贴进 mermaid.live 即可看图

Command 节点记得加返回类型注解 Command[Literal["目标"]],动态边才会被画出来。改图之后先画一遍,确认拓扑和你想的一致,再谈行为。


12. 子图(Subgraph)

图可以当节点嵌进另一个图,是构建多智能体系统和复用模块的基础。

12.1 三种嵌套通信方式

方式 做法 适用
共享完整 schema 子图与父图用同一个 State 类 简单场景
共享部分 key 子图 state 是父图 state 的子集,同名 key 自动对接 大多数场景
显式映射 父图加包装节点,调用子图前把父状态”翻译”成子图输入,返回后再翻译回来 schema 完全不同时

12.2 关键细节

  • 子图有自己的 checkpoint,存在父线程的命名空间下(编译时可传 checkpointer=False 禁用);编译时也要把 checkpointer 传给子图;
  • 共享 key 的 reducer 定义在父图:子图与父图共用的 key,reducer 要在父图 state 里声明;
  • 跨图跳转:子图节点里 Command(goto="父图节点名", graph=Command.PARENT);
  • 父图直接看子图状态不实时(各管各的 checkpoint namespace)——需要跨图边界共享的数据建议走 Store;
  • 子图可被多个父图复用,作为独立恢复单元。

13. 多智能体架构

多智能体 = 多个子图(每个是一个 Agent)+ 父图路由。官方描述的常见模式:

13.1 三种经典拓扑

Supervisor(主管模式)           Network(网状)                Hierarchical(层级)
      ┌────────┐                A ⇄ B      C                  ┌────────┐
      │Supervisor│               ↖ ↓    ↙ ↓                  │ Supervisor│
      └─┬──┬──┬─┘                  ⇅    ⇅                    └─┬──┬──┘
        ↓  ↓  ↓                    ↘ ↓  ↙                     ↓     ↓
     Agent1 Agent2 Agent3        全互联,各自决定           子 Supervisor → 各自的工人
模式 怎么走 适用
Supervisor 主管节点(通常是 LLM)决定把任务交给哪个工人,工人干完回主管 最常用、最可控,入门首选
Network 每个 agent 都能决定把控制权交给谁(handoffs),去中心化 任务协作路径不可预知;调试难
Hierarchical supervisor 的 supervisor,树状分层 工人多、需要分组管理

13.2 Handoffs:控制权移交

“agent A 决定把对话交给 agent B”的机制:本质是一个特殊工具——调用后**更新状态(记录交接)并 Command(goto="agent_b")**。通常同时切换当前的活跃 agent 标记/系统提示,让 B 接管后续。

13.3 通信方式:共享状态 vs 消息传递

  • 共享状态:所有 agent 读写同一个大 State(简单,但字段多了容易互相踩);
  • 消息传递 / 独立状态:每个 agent 有自己的子图状态,只通过明确的消息交接——隔离好,适合规模大的系统。

13.4 官方辅助库

  • langgraph-supervisor:快速搭 supervisor 多智能体;
  • langgraph-swarm:快速搭 swarm(去中心化交接)模式;
  • 更重的”计划-子任务-文件系统”形态,官方现在推荐 Deep Agents(deepagents,构建在 LangGraph 上的 agent harness,见 §14)。

入门建议:先手写一个两个 agent 的 supervisor 图(一个路由节点 + 两个子图),理解了 handoff 本质,再用辅助库提速。


14. LangGraph 与 LangChain 生态的关系

2025-10 发布的 LangGraph v1.0 冻结了核心 API,官方对产品分工的表述(2026 年当前):

产品 定位
LangGraph 编排运行时:持久执行、流式、HITL、记忆——只管编排,不管 prompt 和 agent 架构
LangChain agent 框架:模型/工具抽象与 agent 循环(create_agent)
Deep Agents 构建在 LangGraph 上的 agent harness:规划、子 agent、文件系统工具、上下文管理
LangSmith 追踪、评估、prompt 管理、部署平台(跨框架)

API 分层(v1 重要变化)

API 状态 说明
StateGraph / 节点 / 边 / Command / interrupt 稳定核心 v1 承诺不变,放心写
langgraph.prebuilt.create_react_agent 已弃用 迁移到 LangChain 的 create_agent
langchain.agents.create_agent 推荐的高层入口 内部就构建在 LangGraph 上,带 Middleware 机制

官方给的分层哲学:

LangChain create_agent   ← 快速开始,标准 ReAct Agent,Middleware 定制
        ↓ 需要更细粒度控制时
LangGraph StateGraph     ← 自定义编排:工作流、多智能体、特殊路由

用 create_agent 起步没有被”锁定”——它本来就是 LangGraph 图,随时可以降级到裸 StateGraph。

模型无关:任何支持 tool-calling 的模型都行(OpenAI / Anthropic / Gemini / Ollama 本地模型),换模型不改图逻辑。


15. 核心 API 速查

# ---------- 构建 ----------
from langgraph.graph import StateGraph, MessagesState, START, END
from langgraph.types import Command, interrupt, Send
from langgraph.graph.message import add_messages

builder = StateGraph(State)
builder.add_node("a", fn)                      # 或 add_node(fn) 用函数名
builder.add_node("a", fn, retry=RetryPolicy(max_attempts=3))
builder.add_edge(START, "a")                   # 固定边
builder.add_conditional_edges("a", router_fn, {"x": "x", "y": "y"})   # 条件边
graph = builder.compile(checkpointer=..., store=..., interrupt_before=[...])

# ---------- 运行 ----------
graph.invoke(input, config={"configurable": {"thread_id": "t1"}})
graph.invoke(input, config={"recursion_limit": 50, "configurable": {...}})
graph.stream(input, config, stream_mode="updates")            # 或列表多模式
graph.ainvoke / astream                                       # 异步

# ---------- 状态与恢复 ----------
graph.get_state(config)                        # 当前状态(.values / .next / .tasks)
graph.get_state_history(config)                # 全部历史快照(时间旅行)
graph.update_state(config, values)             # 人工修改状态
graph.invoke(Command(resume=value), config)    # interrupt 后恢复
graph.invoke(None, past_snapshot.config)       # 从历史 checkpoint 重放

# ---------- 调试 ----------
print(graph.get_graph().draw_mermaid())        # 生成 Mermaid 图结构

预构建组件(langgraph.prebuilt):ToolNode(批量执行工具调用并包装 ToolMessage)、tools_condition(工具循环路由)、InjectedState(工具注入状态)均稳定可用;create_react_agent 已弃用。


16. 部署与生态

组件 干什么 何时需要
LangSmith 全链路追踪、评估、数据集回放;Engine 可从 trace 发现问题并提议修复 PR 调试复杂 Agent、上线前评测
Agent Server / LangGraph Platform 把图部署成 REST API 服务:自动持久化、cron、双提交处理、扩缩容 团队共享、生产部署(托管后 checkpointer/store 都不用手动配)
LangGraph Studio 可视化调试器:看图、单步、改状态重放、渲染 interrupt 表单 开发期
langgraph-sdk 客户端 SDK(stream 重连、优先级等) 调用部署好的图
Templates 官方模板(ReAct、RAG、记忆服务、multi-agent)直接克隆 起步加速

自建部署也完全可以:用 FastAPI 包一层 ainvoke + 自己挂 PostgresSaver,不依赖官方平台。


17. 什么时候用 / 不用 LangGraph

适合用:

  • 需要断点恢复、重试的长时运行任务(数据处理管线、深度研究 Agent);
  • 需要人工审批环节的流程(发邮件、下单、执行 SQL 前);
  • 多智能体协作(supervisor-worker、子图嵌套);
  • 步骤间共享复杂状态、且有确定性路由要求的工作流;
  • 需要长期记忆跨会话的助手。

不必用:

  • 单轮问答、简单 prompt 链——一个函数就够了;
  • 标准”工具调用循环”——直接 langchain.agents.create_agent 更省事;
  • 纯检索问答(RAG 单次链路)——LCEL 链更轻。

经验法则:先问”需不需要持久化 / 审批 / 复杂状态”。三个都不需要,就别上图。


18. 常见坑与最佳实践

初学者按出现频率排序:

  1. MemorySaver 上生产 → 重启丢光所有会话。本地用 SqliteSaver,云上用 PostgresSaver(记得 setup() 建表;thread_id < 255 字符);
  2. 忘了 thread_id → 每次调用都像失忆。所有 invoke/stream 都带 config={"configurable": {"thread_id": ...}},且多轮之间必须同一个 config;
  3. 状态里塞大对象 → 每个 checkpoint 都序列化整个状态。大文档/大数据集放外部存储(文件、数据库),状态里只存引用/ID;
  4. 节点返回全量而不是增量 → 无 reducer 字段会被整字段覆盖。只返回改动的字段;需要累积的字段挂 reducer;
  5. 并行分支写无 reducer 的共享 key → 并行写直接冲突。fan-out 前确认共享字段有 reducer(或各写各的私有字段);
  6. 条件边和 Command 混用 → 同一个节点的出边只用一种机制(推荐节点内 Command(goto=...));
  7. try/except 包住 interrupt() → 吞掉中断异常。interrupt 和易错代码分开写;
  8. interrupt 前有非幂等副作用 → 每次 resume 重跑产生重复记录。副作用放 interrupt 之后或拆独立节点;
  9. 工具死循环 → docstring 模糊或没写”何时调用”;GraphRecursionError 时检查路由是否成环;
  10. 子图 token 不出现在 messages 流 → 忘了 subgraphs=True;
  11. Checkpoint 无限增长 → 长会话定期清理旧 checkpoint 或设保留策略;
  12. 照抄 v0.x 老教程 → import 报错。认准 from langgraph.graph import StateGraph, START, END(不是 Graph,也不是 add_node("agent", ..., agent=...) 那套);
  13. 不画图就调试 → 先 draw_mermaid() 确认结构,再 stream_mode="updates" 看每步增量,最后才上 LangSmith。

19. 学习路径与资源

三阶段路线:

  1. 入门(1 天):官方 Quickstart → 《第一个LangGraph程序.md》亲手写完整图(状态/条件边/工具循环/记忆/HITL/流式全部跑一遍);
  2. 进阶(1 周):官方 Graph API Concepts(reducer、superstep、Pregel)→ 按需查 How-to Guides(streaming、subgraph、multi-agent、persistence)→ 给自己的图加 Store 长期记忆;
  3. 高级(按需):多智能体架构与 handoffs → 时间旅行调试 → 部署(Agent Server 或自建 FastAPI)→ LangSmith 评测。

官方资源索引:

资源 地址
LangGraph 概览 https://docs.langchain.com/oss/python/langgraph/overview
Graph API 文档 https://docs.langchain.com/oss/python/langgraph/graph-api
持久化 https://docs.langchain.com/oss/python/langgraph/persistence
中断(HITL) https://docs.langchain.com/oss/python/langgraph/interrupts
记忆 https://docs.langchain.com/oss/python/concepts/memory
流式 https://docs.langchain.com/oss/python/langgraph/streaming
v1 发布说明 https://docs.langchain.com/oss/python/releases/langgraph-v1
LangChain Agents(create_agent) https://docs.langchain.com/oss/python/langchain/agents
Deep Agents https://docs.langchain.com/oss/python/deepagents/overview
GitHub 仓库 https://github.com/langchain-ai/langgraph
LangChain Academy https://academy.langchain.com

版本速记(搜资料时用得上):v0.2(2024)→ v0.3 → v1.0(2025-10,核心 API 冻结) → 1.1.x(2026 上半年,stream v2 格式)→ 1.2.x(2026 下半年,当前 1.2.20,interrupt response_schema 等)。v1 之后核心 API 保持稳定,版本更新主要是修复与平台能力。


20. 附录:术语表与一页纸总结

术语表

术语 含义
State 图的全局数据总线,通常为带 reducer 的 TypedDict
Channel state 的每个 key 背后的存储槽位,持有值并定义合并规则
Reducer 二元合并函数 (当前值, 更新) -> 新值;无 reducer 则覆盖
Node 普通函数 (state) -> 增量更新;是 checkpoint/retry/interrupt 的边界
Edge 节点间的流转关系:固定边 / 条件边 / Command / Send
Superstep Pregel 式执行的一轮:并行跑激活节点 → 合并 → 存档 → 下一轮
CompiledGraph builder.compile() 的产物,标准 Runnable,图此后冻结
thread / thread_id 一次会话;同一图的多个 thread 状态互相隔离
Checkpointer 每超步存档状态快照的组件(Memory/Sqlite/Postgres)
Checkpoint 某超步结束时的完整状态快照,可回放(时间旅行)
interrupt / Command(resume) 图暂停等人 / 带值恢复执行
Store 跨 thread 的长期记忆键值库,按 namespace 组织
Send map-reduce 动态并行分发原语
Subgraph 作为节点嵌入父图的图;多智能体的基本形态
Handoff agent 间控制权移交(一种特殊工具 + goto)
stream_mode 流式输出内容的模式(values/updates/messages/custom/…)
recursion_limit 单次运行的最大超步数,超限抛 GraphRecursionError

一页纸总结

  • LangGraph = 状态 + 节点 + 边 的图编排,专为有状态、长时运行、可控的 Agent/工作流;
  • 四大能力:持久执行、HITL、记忆、流式,全部是官方一等公民;
  • reducer 决定状态怎么合并(add_messages 追加消息、operator.add 拼列表、无 reducer 覆盖);节点返回增量、只写改动字段;
  • 路由四机制:固定边、条件边、Command(goto=...)(推荐)、Send(动态并行);同一节点出边只用一种;
  • checkpointer + thread_id 实现会话隔离、断点恢复、时间旅行;interrupt() + Command(resume=...) 实现人类审批;Store 按 namespace 实现跨会话长期记忆;
  • 流式七模式,调试三步走:draw_mermaid() 看结构 → stream_mode="updates" 看增量 → LangSmith 看全链路;
  • 高层用 langchain.agents.create_agent(或 Deep Agents),底层用 StateGraph,两者同一运行时;
  • 生产三件套:SqliteSaver/PostgresSaver(不是 MemorySaver)、幂等节点副作用、LangSmith 观测。