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 通过抛特殊异常实现暂停,恢复时整个节点从头重跑,因此:
- **不要用 try/except 包裹
interrupt()**——会吞掉中断异常。要么把 interrupt 和易错代码分开,要么 except 里写具体异常类型; - 不要在节点内用非确定性逻辑重排/条件跳过 interrupt 调用——resume 值按严格索引匹配,每次执行的调用顺序必须一致。不要
while True循环里调 interrupt,多轮输入用条件边循环回节点; - payload 不要传复杂值——只传 JSON 可序列化内容,不传函数、类实例;
- 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"; - 排除输出:给不想流出的调用(如内部结构化输出)打
nostreamtag,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. 常见坑与最佳实践
初学者按出现频率排序:
- MemorySaver 上生产 → 重启丢光所有会话。本地用 SqliteSaver,云上用 PostgresSaver(记得
setup()建表;thread_id < 255 字符); - 忘了 thread_id → 每次调用都像失忆。所有 invoke/stream 都带
config={"configurable": {"thread_id": ...}},且多轮之间必须同一个 config; - 状态里塞大对象 → 每个 checkpoint 都序列化整个状态。大文档/大数据集放外部存储(文件、数据库),状态里只存引用/ID;
- 节点返回全量而不是增量 → 无 reducer 字段会被整字段覆盖。只返回改动的字段;需要累积的字段挂 reducer;
- 并行分支写无 reducer 的共享 key → 并行写直接冲突。fan-out 前确认共享字段有 reducer(或各写各的私有字段);
- 条件边和 Command 混用 → 同一个节点的出边只用一种机制(推荐节点内
Command(goto=...)); - try/except 包住
interrupt()→ 吞掉中断异常。interrupt 和易错代码分开写; - interrupt 前有非幂等副作用 → 每次 resume 重跑产生重复记录。副作用放 interrupt 之后或拆独立节点;
- 工具死循环 → docstring 模糊或没写”何时调用”;
GraphRecursionError时检查路由是否成环; - 子图 token 不出现在 messages 流 → 忘了
subgraphs=True; - Checkpoint 无限增长 → 长会话定期清理旧 checkpoint 或设保留策略;
- 照抄 v0.x 老教程 → import 报错。认准
from langgraph.graph import StateGraph, START, END(不是Graph,也不是add_node("agent", ..., agent=...)那套); - 不画图就调试 → 先
draw_mermaid()确认结构,再stream_mode="updates"看每步增量,最后才上 LangSmith。
19. 学习路径与资源
三阶段路线:
- 入门(1 天):官方 Quickstart → 《第一个LangGraph程序.md》亲手写完整图(状态/条件边/工具循环/记忆/HITL/流式全部跑一遍);
- 进阶(1 周):官方 Graph API Concepts(reducer、superstep、Pregel)→ 按需查 How-to Guides(streaming、subgraph、multi-agent、persistence)→ 给自己的图加 Store 长期记忆;
- 高级(按需):多智能体架构与 handoffs → 时间旅行调试 → 部署(Agent Server 或自建 FastAPI)→ LangSmith 评测。
官方资源索引:
版本速记(搜资料时用得上):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 观测。