LangGraph 深度指南

LangGraph 深度指南

LangGraph 把 Agent 从"一次提示词调用"变成可持久化、可中断、可回放的状态机 。学会它不难,难的是四件事:并发写同一个字段、中断恢复时的副作用、checkpoint 的体积、以及状态在父子图之间的流动。本文前半部分讲清模型与 API,后半部分用「12 个高频坑 + 8 个高难问题」直接给出现象、根因与修法。

数据截止 2026-11-17基于 langgraph 1.2.x含 9 段代码 · 13 张表 · 20 个问题解法

1.先建立模型:它不是框架,是一台状态机

大部分人学 LangGraph 卡住,是因为把它当成"更花哨的 chain"。它真正的模型是:状态(State)在节点之间流动,节点只返回增量,边决定下一步去哪,每个 superstep 结束后存一次快照。这四句话解释了后面 90% 的坑。

State

一个带 reducer 的字典,是所有节点共享的唯一事实源

Superstep

一轮并行执行;同轮内就绪节点同时跑,结束后统一合并状态

Checkpoint

每个 superstep 存一次快照,是中断、恢复、回放的物理基础

Thread

会话的隔离边界;thread_id 是恢复的唯一主键

与普通函数编排相比,这套模型换来三件事:可恢复 (进程崩了能从最后一个 checkpoint 继续)、可介入 (在任意节点前暂停等人审批)、可回放(拿到历史快照重跑或分叉)。代价是:状态必须可序列化、副作用必须幂等、并发写必须显式声明合并方式。

什么时候它不值得用

如果你的流程是"调一次模型 → 解析结果 → 返回",用普通的函数调用或 create_agent 就够,引入图只会增加抽象层。真正需要 LangGraph 的信号有三个:流程有分支或循环、需要中途暂停等人、需要跨请求续跑。

2.版本与生态:先对齐你在哪个时代

截至 2026-11-17,langgraph 最新稳定版为 1.2.x (1.2.0 于 2026-05 发布,新增 DeltaChannel、节点超时与错误处理、事件流 v3)12。LangGraph 与 LangChain 的 1.0 都在 2025-10-20 发布,这标志着两者关系发生了实质变化:LangChain 的 Agent 抽象现在构建在 LangGraph 之上。

| 名称 | 是什么 | 什么时候用 |
| langgraph | 图运行时:State、节点、边、checkpoint、interrupt | 需要自定义控制流、持久化、人工介入 |
| langchain.agents.create_agent | 基于 LangGraph 的通用 Agent 构造器,取代旧的 create_react_agent 用法 | 标准「模型 + 工具循环」,不需要自己画图[3](#表 1:容易混淆的四个东西 名称 是什么 什么时候用 langgraph 图运行时:State、节点、边、checkpoint、interrupt 需要自定义控制流、持久化、人工介入 langchain.agents.create_agent 基于 LangGraph 的通用 Agent 构造器,取代旧的 create_react_agent 用法 标准「模型 + 工具循环」,不需要自己画图[3] LangSmith Deployment(原 LangGraph Platform) 托管/自托管的 Agent Server 与运维面 要托管运行、队列、任务调度、可视化[16] LangSmith 可观测与评测平台 要看 trace、对比版本、做回归[15]) |
| LangSmith Deployment(原 LangGraph Platform) | 托管/自托管的 Agent Server 与运维面 | 要托管运行、队列、任务调度、可视化[16](#表 1:容易混淆的四个东西 名称 是什么 什么时候用 langgraph 图运行时:State、节点、边、checkpoint、interrupt 需要自定义控制流、持久化、人工介入 langchain.agents.create_agent 基于 LangGraph 的通用 Agent 构造器,取代旧的 create_react_agent 用法 标准「模型 + 工具循环」,不需要自己画图[3] LangSmith Deployment(原 LangGraph Platform) 托管/自托管的 Agent Server 与运维面 要托管运行、队列、任务调度、可视化[16] LangSmith 可观测与评测平台 要看 trace、对比版本、做回归[15]) |

LangSmith 可观测与评测平台 要看 trace、对比版本、做回归[15](#表 1:容易混淆的四个东西 名称 是什么 什么时候用 langgraph 图运行时:State、节点、边、checkpoint、interrupt 需要自定义控制流、持久化、人工介入 langchain.agents.create_agent 基于 LangGraph 的通用 Agent 构造器,取代旧的 create_react_agent 用法 标准「模型 + 工具循环」,不需要自己画图[3] LangSmith Deployment(原 LangGraph Platform) 托管/自托管的 Agent Server 与运维面 要托管运行、队列、任务调度、可视化[16] LangSmith 可观测与评测平台 要看 trace、对比版本、做回归[15])
[表 1:容易混淆的四个东西]

许可与成本也要提前知道:LangGraph 库本身是 MIT ;托管服务按席位与用量计费(文档列出的 Developer 为 0、Plus 为 39/席位/月,企业版另议),自托管 Server 属企业能力,需要 license key 1716。这意味着"只想本地跑通"完全免费,"想自己部署一套带队列的服务"则要评估商务成本。

迁移提醒

如果你在网上看到 langgraph.prebuilt.create_react_agent 的教程,那是 1.0 之前的写法。1.0 之后同一个能力在 langchain.agents.create_agent3;旧符号是否仍保留取决于版本,按新文档写能少踩一层兼容坑。

3.十分钟跑通:最小可运行的图

下面这段代码包含了一个图需要的最小要素:声明状态 → 加节点 → 连边 → 编译 → 调用 。START 与 END 是两个特殊常量,代表入口与出口4。

hello_graph.py · 最小骨架

复制代码
from typing import Annotated, TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages

class State(TypedDict):
    messages: Annotated[list, add_messages]   # 追加,而不是覆盖
    step: int

def draft(state: State) -> dict:
    # 只返回增量,不要返回整份 state
    return {"messages": [{"role": "assistant", "content": "初稿"}], "step": 1}

def review(state: State) -> dict:
    return {"step": 2}

builder = StateGraph(State)
builder.add_node("draft", draft)
builder.add_node("review", review)
builder.add_edge(START, "draft")
builder.add_edge("draft", "review")
builder.add_edge("review", END)

graph = builder.compile()
out = graph.invoke({"messages": [{"role": "user", "content": "写一段介绍"}], "step": 0})
print(out["step"])   # 2

三个细节值得现在记住:compile() 之前不能调用;节点函数的返回值是增量 而非完整状态;add_messages 是 reducer,它把新消息追加到列表末尾并做去重与 ID 处理。把这三条搞错,后面会连续踩坑。

4.State 与 reducer:整个框架最关键的一处设计

默认情况下,每个字段的更新方式是覆盖 (LastValue):节点 B 返回 {"x": 2},B 就把 x 覆盖成 2。这在串行流程里没问题,一旦出现并行分支或循环累积,就会出现"只剩最后一个值"或直接报错。

state.py · 三种字段语义

复制代码
import operator
from typing import Annotated, TypedDict
from langgraph.graph.message import add_messages

class State(TypedDict):
    # ① 覆盖:最后写入者胜(默认行为)
    current_step: str

    # ② 追加:并行分支各自 append,不会互相覆盖
    findings: Annotated[list[str], operator.add]

    # ③ 消息专用:带 ID 去重、支持删除指令
    messages: Annotated[list, add_messages]

    # ④ 累积计数:并行分支各自 +1 也能正确累加
    attempts: Annotated[int, operator.add]

| 字段声明 | 单节点写 | 同 superstep 多节点写 | 典型用途 |
| x: str | 覆盖 | 报错 INVALID_CONCURRENT_GRAPH_UPDATE | 只由单一节点维护的标记位 |
| Annotated[list, operator.add] | 追加 | 各自追加,顺序不确定但内容都在 | 并行检索结果、日志、候选列表 |
| Annotated[list, add_messages] | 按 ID 合并 | 可并发,自动去重 | 对话历史 |

Annotated[int, operator.add] 累加 可并发,累加正确 重试次数、token 计数
[表 2:reducer 决定"并发写"的合法性]

最容易犯的一个错

节点里写 state["findings"].append(x); return state。这既原地改了共享状态(违反"只返回增量"),又返回了整份 state(会覆盖别人的写入)。正确写法只有一句:return {"findings": [x]}------让 reducer 去合并。

5.控制流四件套:条件边、Send、Command、子图

简单分支用条件边;需要"一对多并行再汇总"用 Send;节点执行完想直接决定下一步用 Command;整套流程要复用就封装成子图。四者的选择标准是决策发生在哪一层。

flow.py · 四种控制流的写法

复制代码
from typing import Literal, TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.types import Command, Send

class State(TypedDict):
    question: str
    route: str
    results: list[str]

# ① 条件边:路由函数只负责"去哪"
def router(state: State) -> Literal["search", "calc", END]:
    if "计算" in state["question"]:
        return "calc"
    if state["question"]:
        return "search"
    return END

# ② Send:一对多扇出,每个分支拿到自己的输入
def fan_out(state: State):
    return [Send("worker", {"q": q}) for q in ["a", "b", "c"]]

# ③ Command:节点内部既更新状态又决定下一步
def escalate(state: State) -> Command:
    return Command(update={"route": "human"}, goto="human_review")

graph = StateGraph(State)
graph.add_node("worker", worker_fn)
graph.add_node("escalate", escalate)
graph.add_node("human_review", review_fn)
graph.add_edge(START, "escalate")
graph.add_conditional_edges("worker", router)
graph.add_edge("human_review", END)

# ④ 子图:编译后再当节点挂上去
sub = sub_builder.compile()            # 子图也可以有自己的 state
graph.add_node("research", sub)         # 直接传编译后的图

| 机制 | 决策发生在 | 适合 | 注意 |
| 条件边 | 节点之外的路由函数 | 固定分支、循环判断 | 返回值必须是合法节点名或 END,漏掉分支就会走错 |
| Send | 路由函数返回多个 Send | map-reduce、批量子任务 | 汇总字段必须有 reducer,否则并发写冲突 |
| Command | 节点内部 | 需要"边改状态边跳转"的动态流程 | goto 可接节点名、列表或 Send |

子图 预先封装 可复用子流程、团队分工 状态只在同名字段间传递,默认继承父 checkpointer
[表 3:四件套的适用边界 [5](#表 3:四件套的适用边界 [5] [6] 机制 决策发生在 适合 注意 条件边 节点之外的路由函数 固定分支、循环判断 返回值必须是合法节点名或 END,漏掉分支就会走错 Send 路由函数返回多个 Send map-reduce、批量子任务 汇总字段必须有 reducer,否则并发写冲突 Command 节点内部 需要"边改状态边跳转"的动态流程 goto 可接节点名、列表或 Send 子图 预先封装 可复用子流程、团队分工 状态只在同名字段间传递,默认继承父 checkpointer) [6](#表 3:四件套的适用边界 [5] [6] 机制 决策发生在 适合 注意 条件边 节点之外的路由函数 固定分支、循环判断 返回值必须是合法节点名或 END,漏掉分支就会走错 Send 路由函数返回多个 Send map-reduce、批量子任务 汇总字段必须有 reducer,否则并发写冲突 Command 节点内部 需要"边改状态边跳转"的动态流程 goto 可接节点名、列表或 Send 子图 预先封装 可复用子流程、团队分工 状态只在同名字段间传递,默认继承父 checkpointer)]

Send 与 reducer 必须成对出现

Send("worker", {"q": q}) 会为每个条目启动一次独立执行,它们在同一个 superstep 里并行跑。如果每个 worker 都往 results 里写,而 results 没有 reducer,就会直接抛并发更新错误------这不是 bug,是框架在提醒你"合并规则没定义"。

6.持久化:checkpointer 是中断与恢复的地基

只要挂了 checkpointer 并传入 thread_id,每个 superstep 结束后都会写一份快照。这让三件事成为可能:崩溃后从最后一个成功步骤继续 、人工审批后恢复 、回放与分叉。

persist.py · 三种 checkpointer 与状态读取

复制代码
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.checkpoint.postgres import PostgresSaver

# 开发期:进程内存,重启即丢
graph = builder.compile(checkpointer=InMemorySaver())

# 生产:Postgres(需先装 langgraph-checkpoint-postgres 并执行 setup)
with PostgresSaver.from_conn_string(DB_URL) as saver:
    saver.setup()                       # 建表与索引,可重复执行
    graph = builder.compile(checkpointer=saver)

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

# 读取:最新快照 / 下一个待执行节点
snap = graph.get_state(config)
print(snap.values, snap.next)

# 历史:倒序排列,可用于回放与分叉
for s in graph.get_state_history(config):
    print(s.config["configurable"]["checkpoint_id"], s.next)

# 人工修正状态:生成一个 source=update 的新检查点
graph.update_state(config, {"step": 10})

| 实现 | 安装 | 适用 | 限制 |
| InMemorySaver | 内置 | 本地调试、单测、Demo | 进程退出即丢;无淘汰,长跑会涨内存[8](#表 4:三种 checkpointer 的选择 实现 安装 适用 限制 InMemorySaver 内置 本地调试、单测、Demo 进程退出即丢;无淘汰,长跑会涨内存[8] SqliteSaver langgraph-checkpoint-sqlite 桌面应用、单机服务 并发写受限,不适合多实例[8] PostgresSaver / AsyncPostgresSaver langgraph-checkpoint-postgres 生产、多实例、需要 TTL 需 setup() 建表;连接管理要自己做好[8]) |
| SqliteSaver | langgraph-checkpoint-sqlite | 桌面应用、单机服务 | 并发写受限,不适合多实例[8](#表 4:三种 checkpointer 的选择 实现 安装 适用 限制 InMemorySaver 内置 本地调试、单测、Demo 进程退出即丢;无淘汰,长跑会涨内存[8] SqliteSaver langgraph-checkpoint-sqlite 桌面应用、单机服务 并发写受限,不适合多实例[8] PostgresSaver / AsyncPostgresSaver langgraph-checkpoint-postgres 生产、多实例、需要 TTL 需 setup() 建表;连接管理要自己做好[8]) |

PostgresSaver / AsyncPostgresSaver langgraph-checkpoint-postgres 生产、多实例、需要 TTL 需 setup() 建表;连接管理要自己做好[8](#表 4:三种 checkpointer 的选择 实现 安装 适用 限制 InMemorySaver 内置 本地调试、单测、Demo 进程退出即丢;无淘汰,长跑会涨内存[8] SqliteSaver langgraph-checkpoint-sqlite 桌面应用、单机服务 并发写受限,不适合多实例[8] PostgresSaver / AsyncPostgresSaver langgraph-checkpoint-postgres 生产、多实例、需要 TTL 需 setup() 建表;连接管理要自己做好[8])
[表 4:三种 checkpointer 的选择]

thread_id 是恢复的主键,checkpoint_id 是快照的主键。这两个概念分开理解很重要:同一个 thread 下有多份 checkpoint ,指定到具体 checkpoint 就能"回到过去",这是时间旅行与分叉的实现方式21。

7.durability:拿性能换"能丢多少"

持久化不是非黑即白。运行时可传 durability 选择落盘时机,三个取值由弱到强:exit、async、sync9。这是纯工程取舍------写得越勤,恢复越准,但每步的延迟越高。

| 取值 | 落盘时机 | 崩溃会丢什么 | 适合 |
| exit | 仅在成功结束、出错或中断退出时 | 中间所有步骤的进度 | 短流程、可整体重跑 |
| async | 执行下一步的同时异步写 | 最近若干步(进程崩溃时可能丢) | 多数在线业务的折中 |

sync 进入下一步之前同步写完 几乎不丢 长流程、每步都昂贵(如外部扣款)
[表 5:三种 durability 的语义与代价 [9](#表 5:三种 durability 的语义与代价 [9] 取值 落盘时机 崩溃会丢什么 适合 exit 仅在成功结束、出错或中断退出时 中间所有步骤的进度 短流程、可整体重跑 async 执行下一步的同时异步写 最近若干步(进程崩溃时可能丢) 多数在线业务的折中 sync 进入下一步之前同步写完 几乎不丢 长流程、每步都昂贵(如外部扣款))]

一个必须接受的语义:at-least-once

持久化 + 重试的组合语义是**"至少执行一次"** ,不是"恰好一次"。进程在写完外部调用、还没写 checkpoint 时崩溃,恢复后那个节点会整段重跑。所以节点里的副作用必须具备幂等性(幂等键、upsert、先查后写),否则就会出现"重复发邮件""重复扣款"。这一点在下一节还会展开13。

8.中断与恢复:只能"重跑节点",不能"从中间接着跑"

interrupt() 是 LangGraph 最有用的能力,也是最容易用错的能力。它需要 checkpointer 与 thread_id;恢复时传 Command(resume=...),而被中断的那个节点会从头重新执行 ,不是从 interrupt() 那一行之后继续7。

hitl.py · 审批后继续

复制代码
from langgraph.types import interrupt, Command

def approve(state: State) -> dict:
    # 想让人看的内容直接传给 interrupt
    decision = interrupt({"question": "是否批准这笔退款?", "amount": state["amount"]})

    # 恢复后代码从这里继续,但整个节点是重跑过的
    if decision == "approve":
        return {"status": "approved"}
    return {"status": "rejected"}

config = {"configurable": {"thread_id": "refund-9"}}

# 第一次:跑到 interrupt 就停下,返回值里带 __interrupt__
graph.invoke({"amount": 300, "status": "pending"}, config)

# 第二次:带着人的决定恢复
graph.invoke(Command(resume="approve"), config)

这条语义决定了架构:副作用必须放在 interrupt 之后

如果 approve 节点在 interrupt() 之前 就调了退款接口,那么每次恢复都会再调一次。正确做法是把外部副作用放在 interrupt() 之后,或者用幂等键让重复调用无副作用。用函数式 API 时可以把副作用包进 @task,命中缓存后不会重复执行7。

9.流式输出:先搞清你消费的是哪一层

stream_mode 决定你拿到的是"整份状态"还是"某个节点的增量"还是"模型 token"。选错模式,前端就会收到意料之外的结构------这是接入前端时最常见的返工点10。

| 模式 | 每次产出 | 典型用途 |
| values | 每一步之后的完整状态 | 调试、渲染整体状态面板 |
| updates | 本次各节点的增量 | 进度提示"某节点完成" |
| messages | (chunk, metadata) | 逐 token 打字机效果 |
| custom | 节点通过 writer 主动写出的内容 | 自定义进度、阶段性结果 |
| checkpoints / tasks | 检查点事件 / 任务生命周期 | 需要 checkpointer;做运维视图 |
| debug | checkpoints + tasks 的合并 | 本地排障 |

多模式组合 stream_mode=["updates","messages"] 同时要进度与 token
[表 6:七种 stream_mode [6](#表 6:七种 stream_mode [6] [10] 模式 每次产出 典型用途 values 每一步之后的完整状态 调试、渲染整体状态面板 updates 本次各节点的增量 进度提示"某节点完成" messages (chunk, metadata) 逐 token 打字机效果 custom 节点通过 writer 主动写出的内容 自定义进度、阶段性结果 checkpoints / tasks 检查点事件 / 任务生命周期 需要 checkpointer;做运维视图 debug checkpoints + tasks 的合并 本地排障 多模式组合 stream_mode=["updates","messages"] 同时要进度与 token) [10](#表 6:七种 stream_mode [6] [10] 模式 每次产出 典型用途 values 每一步之后的完整状态 调试、渲染整体状态面板 updates 本次各节点的增量 进度提示"某节点完成" messages (chunk, metadata) 逐 token 打字机效果 custom 节点通过 writer 主动写出的内容 自定义进度、阶段性结果 checkpoints / tasks 检查点事件 / 任务生命周期 需要 checkpointer;做运维视图 debug checkpoints + tasks 的合并 本地排障 多模式组合 stream_mode=["updates","messages"] 同时要进度与 token)]

stream.py · 自定义进度与多模式

复制代码
from langgraph.config import get_stream_writer

def research(state: State) -> dict:
    writer = get_stream_writer()
    for i, q in enumerate(state["queries"]):
        writer({"progress": f"{i}/{len(state['queries'])}", "query": q})
    return {"done": True}

# 同时订阅进度与 token
for mode, chunk in graph.stream(inputs, config,
                              stream_mode=["updates", "messages"]):
    print(mode, chunk)

# 新版本可用统一事件结构:每个事件带 type / ns / data
# for ev in graph.stream_events(inputs, config, version="v3"): ...

结构差异要提前知道:旧版单模式下直接返回裸数据,多模式下返回 (mode, data),子图还会多一层 namespace;1.1 起可以传 version="v2" 拿到统一的 {type, ns, data} 结构,1.2 更推荐用 stream_events(version="v3")10。前端按 type 分流,比按"猜结构"稳得多。

10.短期记忆与长期记忆:两套机制,别混用

checkpointer 存的是"某个 thread 内的图状态 ",随会话增长;Store 存的是"跨 thread 的业务事实 ",按 namespace + key 组织,可以带向量检索。前者是过程,后者是知识1218。

| 维度 | checkpointer(短期) | Store(长期) |
| 作用域 | 单个 thread | 跨 thread,按 namespace 划分 |
| 存什么 | 完整图状态、每个 superstep 的快照 | 业务 KV,如用户偏好、已确认事实 |
| 增长方式 | 随步数与消息数增长 | 随业务实体增长 |
| 典型用途 | 多轮对话、中断恢复、回放 | 用户画像、长期偏好、跨会话检索 |

清理方式 TTL、删 thread、裁剪消息 按 namespace 定期清理
[表 7:两套持久化机制的边界]

一个常见的设计错误

把"用户叫张三、偏好中文"这类稳定事实写进 messages,于是每轮都要重发一遍,token 成本线性上涨。正确做法是抽成 summary 或写进 Store,只在需要时检索注入------短期记忆用来维持对话连贯,长期记忆用来避免重复询问。

11.容错:重试、超时、递归上限三件套

三个机制解决三种失败:瞬时失败用重试 (网络抖动、5xx)、卡死用超时 (模型不返回)、逻辑死循环用递归上限(路由永不结束)。它们的配置位置不同,别混着调。

resilience.py · 三个旋钮

复制代码
from langgraph.types import RetryPolicy
from langgraph.graph import StateGraph

policy = RetryPolicy(
    max_attempts=3,
    initial_interval=0.5,      # 秒
    backoff_factor=2.0,
    max_interval=128,
    jitter=True,
    # retry_on 默认不重试 ValueError/TypeError 等编程错误
)

builder.add_node("call_model", call_model, retry_policy=policy)

# 超时:1.2 起支持,且只对 async 节点生效
builder.add_node("slow_tool", slow_tool, timeout=30)

graph = builder.compile(checkpointer=saver)

# 递归上限放在 config 顶层,不是 configurable 里
graph.invoke(inputs, {"configurable": {"thread_id": "t1"},
                     "recursion_limit": 50})

| 旋钮 | 配在哪 | 失败时发生什么 | 注意 |
| RetryPolicy | 节点声明处 | 整节点重跑,退避后重试 | 默认不重试编程错误(ValueError 等),只重试可恢复错误 |
| timeout | add_node(...) | 抛 NodeTimeoutError,本次写入被清空 | 1.2+ 且必须 async 节点;sync 节点配超时会在编译期报错 |

recursion_limit config 顶层 抛 GraphRecursionError 计的是 superstep 数,不是"循环了几次"
[表 8:三个旋钮的语义 [13](#表 8:三个旋钮的语义 [13] [11] 旋钮 配在哪 失败时发生什么 注意 RetryPolicy 节点声明处 整节点重跑,退避后重试 默认不重试编程错误(ValueError 等),只重试可恢复错误 timeout add_node(...) 抛 NodeTimeoutError,本次写入被清空 1.2+ 且必须 async 节点;sync 节点配超时会在编译期报错 recursion_limit config 顶层 抛 GraphRecursionError 计的是 superstep 数,不是"循环了几次") [11](#表 8:三个旋钮的语义 [13] [11] 旋钮 配在哪 失败时发生什么 注意 RetryPolicy 节点声明处 整节点重跑,退避后重试 默认不重试编程错误(ValueError 等),只重试可恢复错误 timeout add_node(...) 抛 NodeTimeoutError,本次写入被清空 1.2+ 且必须 async 节点;sync 节点配超时会在编译期报错 recursion_limit config 顶层 抛 GraphRecursionError 计的是 superstep 数,不是"循环了几次")]

重叠的重试会放大故障

如果节点内部还包了一层 SDK 自带重试,两层的次数会相乘:外层 3 次 × 内层 3 次 = 9 次,超时也会叠加。只在一处做重试 ------要么交给 LangGraph 的 RetryPolicy,要么在客户端里做,不要两边都开。

12.部署与可观测:从脚本到服务

本地跑通只需要一个 Python 文件;要变成"别人能调用的服务",需要 langgraph.json 声明入口,再由 CLI 或托管平台托管。可观测则统一走 LangSmith:设好环境变量,每次运行的节点、模型调用、token 与延迟都会成为 trace15。

langgraph.json · 最小声明

复制代码
{
  "dependencies": ["."],
  "graphs": {
    "agent": "./app/graph.py:graph"
  },
  "env": {"OPENAI_API_KEY": "..."}
}

# 本地开发(无需 Docker)
# langgraph dev
# 构建镜像 / 本地起完整服务 / 部署到托管
# langgraph build / langgraph up / langgraph deploy

| 方式 | 适合 | 代价 / 门槛 |
| langgraph dev | 本地联调、前端对接 | 轻量、无需容器,不具备生产能力 |
| 托管 Agent Server | 要托管运维、队列、任务调度 | 按席位与用量计费[17](#表 9:部署路径的选择 [14] [16] 方式 适合 代价 / 门槛 langgraph dev 本地联调、前端对接 轻量、无需容器,不具备生产能力 托管 Agent Server 要托管运维、队列、任务调度 按席位与用量计费[17] 自托管 Server 数据不出域、要接内部网络 属企业能力,需 license key[16] 自己包 FastAPI 已有服务框架、只需图运行时 持久化、队列、重试、鉴权都要自己实现) |
| 自托管 Server | 数据不出域、要接内部网络 | 属企业能力,需 license key[16](#表 9:部署路径的选择 [14] [16] 方式 适合 代价 / 门槛 langgraph dev 本地联调、前端对接 轻量、无需容器,不具备生产能力 托管 Agent Server 要托管运维、队列、任务调度 按席位与用量计费[17] 自托管 Server 数据不出域、要接内部网络 属企业能力,需 license key[16] 自己包 FastAPI 已有服务框架、只需图运行时 持久化、队列、重试、鉴权都要自己实现) |

自己包 FastAPI 已有服务框架、只需图运行时 持久化、队列、重试、鉴权都要自己实现
[表 9:部署路径的选择 [14](#表 9:部署路径的选择 [14] [16] 方式 适合 代价 / 门槛 langgraph dev 本地联调、前端对接 轻量、无需容器,不具备生产能力 托管 Agent Server 要托管运维、队列、任务调度 按席位与用量计费[17] 自托管 Server 数据不出域、要接内部网络 属企业能力,需 license key[16] 自己包 FastAPI 已有服务框架、只需图运行时 持久化、队列、重试、鉴权都要自己实现) [16](#表 9:部署路径的选择 [14] [16] 方式 适合 代价 / 门槛 langgraph dev 本地联调、前端对接 轻量、无需容器,不具备生产能力 托管 Agent Server 要托管运维、队列、任务调度 按席位与用量计费[17] 自托管 Server 数据不出域、要接内部网络 属企业能力,需 license key[16] 自己包 FastAPI 已有服务框架、只需图运行时 持久化、队列、重试、鉴权都要自己实现)]

可观测的最小配置就三个环境变量:LANGSMITH_TRACING=true、LANGSMITH_API_KEY、LANGSMITH_PROJECT。trace 里能看到图与节点的层级、每次模型调用的 prompt 与 completion、token 与延迟、工具调用与异常------排查"到底哪一步变慢/变贵"时,这比打日志有效15。

13.十二个高频坑:现象、根因、修法

下面这些都是"第一次做项目几乎必然遇到"的问题,按出现频率排序。每一条都可以用一句话概括根因,但不知道根因时会浪费一整天。

| 现象 | 根因 | 修法 |
| 并行分支只保留最后一个值 / 报 INVALID_CONCURRENT_GRAPH_UPDATE | 字段是默认 LastValue 通道,同一 superstep 多节点写同一 key 无法合并[20](#表 10:高频问题清单(含官方文档对应条目) 现象 根因 修法 并行分支只保留最后一个值 / 报 INVALID_CONCURRENT_GRAPH_UPDATE 字段是默认 LastValue 通道,同一 superstep 多节点写同一 key 无法合并[20] 给会被并发写的字段加 reducer;节点只返回增量 审批通过后重复发邮件、重复扣款 恢复时被中断节点从头重跑,interrupt 之前的副作用又执行一次[7] 副作用移到 interrupt 之后;用幂等键或 @task 缓存 长会话后写入变慢、数据库暴涨 每个 superstep 存一次快照,且消息全量累积无保留策略[8] 配 TTL、删旧 thread、裁剪消息、考虑增量通道 "Recursion limit of 25 reached" recursion_limit 计 superstep 数;路由永不返回 END 或终止条件依赖的字段没被更新[11] 路由显式覆盖 END;加迭代计数器;确需长流程才调高上限 异步服务里请求卡死、健康检查超时 在事件循环里跑同步节点或同步模型调用,阻塞了整个循环 统一用 ainvoke/astream + AsyncPostgresSaver;阻塞调用放线程池 子图改了字段,父图看不到 子图有独立 schema,只有同名字段才会自动传递[19] 父子 schema 都声明该字段;跨边界数据走 Store map-reduce 汇总报并发冲突 每个 Send 分支都在同一 step 写汇总 key,而该 key 没有 reducer[22] 汇总字段加 reducer;分支只返回自己的局部结果 Postgres 报 relation does not exist checkpointer 的建表脚本没执行,setup() 不会自动跑[8] 部署或升级时执行 setup() / asetup() 前端按 SSE 解析却收到奇怪结构 单模式返回裸数据、多模式返回元组、子图多一层 namespace[10] 用 version="v2" 统一结构,前端按 type 分流 结构化输出校验失败,整图崩掉 模型输出不满足 schema,且默认没有纠错重试[23] 带错误回传的重试 + 节点级 RetryPolicy + 收紧 schema token 成本随轮次线性上涨 messages 全量留在 state 并每轮重发[18] 按 token 预算裁剪;旧消息摘要后删除原文 不同用户看到彼此的历史 thread_id 硬编码或前端未按会话生成,导致串号 用用户/会话 UUID 生成,长度控制在 255 字符内[26]) | 给会被并发写的字段加 reducer;节点只返回增量 |
| 审批通过后重复发邮件、重复扣款 | 恢复时被中断节点从头重跑,interrupt 之前的副作用又执行一次[7](#表 10:高频问题清单(含官方文档对应条目) 现象 根因 修法 并行分支只保留最后一个值 / 报 INVALID_CONCURRENT_GRAPH_UPDATE 字段是默认 LastValue 通道,同一 superstep 多节点写同一 key 无法合并[20] 给会被并发写的字段加 reducer;节点只返回增量 审批通过后重复发邮件、重复扣款 恢复时被中断节点从头重跑,interrupt 之前的副作用又执行一次[7] 副作用移到 interrupt 之后;用幂等键或 @task 缓存 长会话后写入变慢、数据库暴涨 每个 superstep 存一次快照,且消息全量累积无保留策略[8] 配 TTL、删旧 thread、裁剪消息、考虑增量通道 "Recursion limit of 25 reached" recursion_limit 计 superstep 数;路由永不返回 END 或终止条件依赖的字段没被更新[11] 路由显式覆盖 END;加迭代计数器;确需长流程才调高上限 异步服务里请求卡死、健康检查超时 在事件循环里跑同步节点或同步模型调用,阻塞了整个循环 统一用 ainvoke/astream + AsyncPostgresSaver;阻塞调用放线程池 子图改了字段,父图看不到 子图有独立 schema,只有同名字段才会自动传递[19] 父子 schema 都声明该字段;跨边界数据走 Store map-reduce 汇总报并发冲突 每个 Send 分支都在同一 step 写汇总 key,而该 key 没有 reducer[22] 汇总字段加 reducer;分支只返回自己的局部结果 Postgres 报 relation does not exist checkpointer 的建表脚本没执行,setup() 不会自动跑[8] 部署或升级时执行 setup() / asetup() 前端按 SSE 解析却收到奇怪结构 单模式返回裸数据、多模式返回元组、子图多一层 namespace[10] 用 version="v2" 统一结构,前端按 type 分流 结构化输出校验失败,整图崩掉 模型输出不满足 schema,且默认没有纠错重试[23] 带错误回传的重试 + 节点级 RetryPolicy + 收紧 schema token 成本随轮次线性上涨 messages 全量留在 state 并每轮重发[18] 按 token 预算裁剪;旧消息摘要后删除原文 不同用户看到彼此的历史 thread_id 硬编码或前端未按会话生成,导致串号 用用户/会话 UUID 生成,长度控制在 255 字符内[26]) | 副作用移到 interrupt 之后;用幂等键或 @task 缓存 |
| 长会话后写入变慢、数据库暴涨 | 每个 superstep 存一次快照,且消息全量累积无保留策略[8](#表 10:高频问题清单(含官方文档对应条目) 现象 根因 修法 并行分支只保留最后一个值 / 报 INVALID_CONCURRENT_GRAPH_UPDATE 字段是默认 LastValue 通道,同一 superstep 多节点写同一 key 无法合并[20] 给会被并发写的字段加 reducer;节点只返回增量 审批通过后重复发邮件、重复扣款 恢复时被中断节点从头重跑,interrupt 之前的副作用又执行一次[7] 副作用移到 interrupt 之后;用幂等键或 @task 缓存 长会话后写入变慢、数据库暴涨 每个 superstep 存一次快照,且消息全量累积无保留策略[8] 配 TTL、删旧 thread、裁剪消息、考虑增量通道 "Recursion limit of 25 reached" recursion_limit 计 superstep 数;路由永不返回 END 或终止条件依赖的字段没被更新[11] 路由显式覆盖 END;加迭代计数器;确需长流程才调高上限 异步服务里请求卡死、健康检查超时 在事件循环里跑同步节点或同步模型调用,阻塞了整个循环 统一用 ainvoke/astream + AsyncPostgresSaver;阻塞调用放线程池 子图改了字段,父图看不到 子图有独立 schema,只有同名字段才会自动传递[19] 父子 schema 都声明该字段;跨边界数据走 Store map-reduce 汇总报并发冲突 每个 Send 分支都在同一 step 写汇总 key,而该 key 没有 reducer[22] 汇总字段加 reducer;分支只返回自己的局部结果 Postgres 报 relation does not exist checkpointer 的建表脚本没执行,setup() 不会自动跑[8] 部署或升级时执行 setup() / asetup() 前端按 SSE 解析却收到奇怪结构 单模式返回裸数据、多模式返回元组、子图多一层 namespace[10] 用 version="v2" 统一结构,前端按 type 分流 结构化输出校验失败,整图崩掉 模型输出不满足 schema,且默认没有纠错重试[23] 带错误回传的重试 + 节点级 RetryPolicy + 收紧 schema token 成本随轮次线性上涨 messages 全量留在 state 并每轮重发[18] 按 token 预算裁剪;旧消息摘要后删除原文 不同用户看到彼此的历史 thread_id 硬编码或前端未按会话生成,导致串号 用用户/会话 UUID 生成,长度控制在 255 字符内[26]) | 配 TTL、删旧 thread、裁剪消息、考虑增量通道 |
| "Recursion limit of 25 reached" | recursion_limit 计 superstep 数;路由永不返回 END 或终止条件依赖的字段没被更新[11](#表 10:高频问题清单(含官方文档对应条目) 现象 根因 修法 并行分支只保留最后一个值 / 报 INVALID_CONCURRENT_GRAPH_UPDATE 字段是默认 LastValue 通道,同一 superstep 多节点写同一 key 无法合并[20] 给会被并发写的字段加 reducer;节点只返回增量 审批通过后重复发邮件、重复扣款 恢复时被中断节点从头重跑,interrupt 之前的副作用又执行一次[7] 副作用移到 interrupt 之后;用幂等键或 @task 缓存 长会话后写入变慢、数据库暴涨 每个 superstep 存一次快照,且消息全量累积无保留策略[8] 配 TTL、删旧 thread、裁剪消息、考虑增量通道 "Recursion limit of 25 reached" recursion_limit 计 superstep 数;路由永不返回 END 或终止条件依赖的字段没被更新[11] 路由显式覆盖 END;加迭代计数器;确需长流程才调高上限 异步服务里请求卡死、健康检查超时 在事件循环里跑同步节点或同步模型调用,阻塞了整个循环 统一用 ainvoke/astream + AsyncPostgresSaver;阻塞调用放线程池 子图改了字段,父图看不到 子图有独立 schema,只有同名字段才会自动传递[19] 父子 schema 都声明该字段;跨边界数据走 Store map-reduce 汇总报并发冲突 每个 Send 分支都在同一 step 写汇总 key,而该 key 没有 reducer[22] 汇总字段加 reducer;分支只返回自己的局部结果 Postgres 报 relation does not exist checkpointer 的建表脚本没执行,setup() 不会自动跑[8] 部署或升级时执行 setup() / asetup() 前端按 SSE 解析却收到奇怪结构 单模式返回裸数据、多模式返回元组、子图多一层 namespace[10] 用 version="v2" 统一结构,前端按 type 分流 结构化输出校验失败,整图崩掉 模型输出不满足 schema,且默认没有纠错重试[23] 带错误回传的重试 + 节点级 RetryPolicy + 收紧 schema token 成本随轮次线性上涨 messages 全量留在 state 并每轮重发[18] 按 token 预算裁剪;旧消息摘要后删除原文 不同用户看到彼此的历史 thread_id 硬编码或前端未按会话生成,导致串号 用用户/会话 UUID 生成,长度控制在 255 字符内[26]) | 路由显式覆盖 END;加迭代计数器;确需长流程才调高上限 |
| 异步服务里请求卡死、健康检查超时 | 在事件循环里跑同步节点或同步模型调用,阻塞了整个循环 | 统一用 ainvoke/astream + AsyncPostgresSaver;阻塞调用放线程池 |
| 子图改了字段,父图看不到 | 子图有独立 schema,只有同名字段 才会自动传递[19](#表 10:高频问题清单(含官方文档对应条目) 现象 根因 修法 并行分支只保留最后一个值 / 报 INVALID_CONCURRENT_GRAPH_UPDATE 字段是默认 LastValue 通道,同一 superstep 多节点写同一 key 无法合并[20] 给会被并发写的字段加 reducer;节点只返回增量 审批通过后重复发邮件、重复扣款 恢复时被中断节点从头重跑,interrupt 之前的副作用又执行一次[7] 副作用移到 interrupt 之后;用幂等键或 @task 缓存 长会话后写入变慢、数据库暴涨 每个 superstep 存一次快照,且消息全量累积无保留策略[8] 配 TTL、删旧 thread、裁剪消息、考虑增量通道 "Recursion limit of 25 reached" recursion_limit 计 superstep 数;路由永不返回 END 或终止条件依赖的字段没被更新[11] 路由显式覆盖 END;加迭代计数器;确需长流程才调高上限 异步服务里请求卡死、健康检查超时 在事件循环里跑同步节点或同步模型调用,阻塞了整个循环 统一用 ainvoke/astream + AsyncPostgresSaver;阻塞调用放线程池 子图改了字段,父图看不到 子图有独立 schema,只有同名字段才会自动传递[19] 父子 schema 都声明该字段;跨边界数据走 Store map-reduce 汇总报并发冲突 每个 Send 分支都在同一 step 写汇总 key,而该 key 没有 reducer[22] 汇总字段加 reducer;分支只返回自己的局部结果 Postgres 报 relation does not exist checkpointer 的建表脚本没执行,setup() 不会自动跑[8] 部署或升级时执行 setup() / asetup() 前端按 SSE 解析却收到奇怪结构 单模式返回裸数据、多模式返回元组、子图多一层 namespace[10] 用 version="v2" 统一结构,前端按 type 分流 结构化输出校验失败,整图崩掉 模型输出不满足 schema,且默认没有纠错重试[23] 带错误回传的重试 + 节点级 RetryPolicy + 收紧 schema token 成本随轮次线性上涨 messages 全量留在 state 并每轮重发[18] 按 token 预算裁剪;旧消息摘要后删除原文 不同用户看到彼此的历史 thread_id 硬编码或前端未按会话生成,导致串号 用用户/会话 UUID 生成,长度控制在 255 字符内[26]) | 父子 schema 都声明该字段;跨边界数据走 Store |
| map-reduce 汇总报并发冲突 | 每个 Send 分支都在同一 step 写汇总 key,而该 key 没有 reducer[22](#表 10:高频问题清单(含官方文档对应条目) 现象 根因 修法 并行分支只保留最后一个值 / 报 INVALID_CONCURRENT_GRAPH_UPDATE 字段是默认 LastValue 通道,同一 superstep 多节点写同一 key 无法合并[20] 给会被并发写的字段加 reducer;节点只返回增量 审批通过后重复发邮件、重复扣款 恢复时被中断节点从头重跑,interrupt 之前的副作用又执行一次[7] 副作用移到 interrupt 之后;用幂等键或 @task 缓存 长会话后写入变慢、数据库暴涨 每个 superstep 存一次快照,且消息全量累积无保留策略[8] 配 TTL、删旧 thread、裁剪消息、考虑增量通道 "Recursion limit of 25 reached" recursion_limit 计 superstep 数;路由永不返回 END 或终止条件依赖的字段没被更新[11] 路由显式覆盖 END;加迭代计数器;确需长流程才调高上限 异步服务里请求卡死、健康检查超时 在事件循环里跑同步节点或同步模型调用,阻塞了整个循环 统一用 ainvoke/astream + AsyncPostgresSaver;阻塞调用放线程池 子图改了字段,父图看不到 子图有独立 schema,只有同名字段才会自动传递[19] 父子 schema 都声明该字段;跨边界数据走 Store map-reduce 汇总报并发冲突 每个 Send 分支都在同一 step 写汇总 key,而该 key 没有 reducer[22] 汇总字段加 reducer;分支只返回自己的局部结果 Postgres 报 relation does not exist checkpointer 的建表脚本没执行,setup() 不会自动跑[8] 部署或升级时执行 setup() / asetup() 前端按 SSE 解析却收到奇怪结构 单模式返回裸数据、多模式返回元组、子图多一层 namespace[10] 用 version="v2" 统一结构,前端按 type 分流 结构化输出校验失败,整图崩掉 模型输出不满足 schema,且默认没有纠错重试[23] 带错误回传的重试 + 节点级 RetryPolicy + 收紧 schema token 成本随轮次线性上涨 messages 全量留在 state 并每轮重发[18] 按 token 预算裁剪;旧消息摘要后删除原文 不同用户看到彼此的历史 thread_id 硬编码或前端未按会话生成,导致串号 用用户/会话 UUID 生成,长度控制在 255 字符内[26]) | 汇总字段加 reducer;分支只返回自己的局部结果 |
| Postgres 报 relation does not exist | checkpointer 的建表脚本没执行,setup() 不会自动跑[8](#表 10:高频问题清单(含官方文档对应条目) 现象 根因 修法 并行分支只保留最后一个值 / 报 INVALID_CONCURRENT_GRAPH_UPDATE 字段是默认 LastValue 通道,同一 superstep 多节点写同一 key 无法合并[20] 给会被并发写的字段加 reducer;节点只返回增量 审批通过后重复发邮件、重复扣款 恢复时被中断节点从头重跑,interrupt 之前的副作用又执行一次[7] 副作用移到 interrupt 之后;用幂等键或 @task 缓存 长会话后写入变慢、数据库暴涨 每个 superstep 存一次快照,且消息全量累积无保留策略[8] 配 TTL、删旧 thread、裁剪消息、考虑增量通道 "Recursion limit of 25 reached" recursion_limit 计 superstep 数;路由永不返回 END 或终止条件依赖的字段没被更新[11] 路由显式覆盖 END;加迭代计数器;确需长流程才调高上限 异步服务里请求卡死、健康检查超时 在事件循环里跑同步节点或同步模型调用,阻塞了整个循环 统一用 ainvoke/astream + AsyncPostgresSaver;阻塞调用放线程池 子图改了字段,父图看不到 子图有独立 schema,只有同名字段才会自动传递[19] 父子 schema 都声明该字段;跨边界数据走 Store map-reduce 汇总报并发冲突 每个 Send 分支都在同一 step 写汇总 key,而该 key 没有 reducer[22] 汇总字段加 reducer;分支只返回自己的局部结果 Postgres 报 relation does not exist checkpointer 的建表脚本没执行,setup() 不会自动跑[8] 部署或升级时执行 setup() / asetup() 前端按 SSE 解析却收到奇怪结构 单模式返回裸数据、多模式返回元组、子图多一层 namespace[10] 用 version="v2" 统一结构,前端按 type 分流 结构化输出校验失败,整图崩掉 模型输出不满足 schema,且默认没有纠错重试[23] 带错误回传的重试 + 节点级 RetryPolicy + 收紧 schema token 成本随轮次线性上涨 messages 全量留在 state 并每轮重发[18] 按 token 预算裁剪;旧消息摘要后删除原文 不同用户看到彼此的历史 thread_id 硬编码或前端未按会话生成,导致串号 用用户/会话 UUID 生成,长度控制在 255 字符内[26]) | 部署或升级时执行 setup() / asetup() |
| 前端按 SSE 解析却收到奇怪结构 | 单模式返回裸数据、多模式返回元组、子图多一层 namespace[10](#表 10:高频问题清单(含官方文档对应条目) 现象 根因 修法 并行分支只保留最后一个值 / 报 INVALID_CONCURRENT_GRAPH_UPDATE 字段是默认 LastValue 通道,同一 superstep 多节点写同一 key 无法合并[20] 给会被并发写的字段加 reducer;节点只返回增量 审批通过后重复发邮件、重复扣款 恢复时被中断节点从头重跑,interrupt 之前的副作用又执行一次[7] 副作用移到 interrupt 之后;用幂等键或 @task 缓存 长会话后写入变慢、数据库暴涨 每个 superstep 存一次快照,且消息全量累积无保留策略[8] 配 TTL、删旧 thread、裁剪消息、考虑增量通道 "Recursion limit of 25 reached" recursion_limit 计 superstep 数;路由永不返回 END 或终止条件依赖的字段没被更新[11] 路由显式覆盖 END;加迭代计数器;确需长流程才调高上限 异步服务里请求卡死、健康检查超时 在事件循环里跑同步节点或同步模型调用,阻塞了整个循环 统一用 ainvoke/astream + AsyncPostgresSaver;阻塞调用放线程池 子图改了字段,父图看不到 子图有独立 schema,只有同名字段才会自动传递[19] 父子 schema 都声明该字段;跨边界数据走 Store map-reduce 汇总报并发冲突 每个 Send 分支都在同一 step 写汇总 key,而该 key 没有 reducer[22] 汇总字段加 reducer;分支只返回自己的局部结果 Postgres 报 relation does not exist checkpointer 的建表脚本没执行,setup() 不会自动跑[8] 部署或升级时执行 setup() / asetup() 前端按 SSE 解析却收到奇怪结构 单模式返回裸数据、多模式返回元组、子图多一层 namespace[10] 用 version="v2" 统一结构,前端按 type 分流 结构化输出校验失败,整图崩掉 模型输出不满足 schema,且默认没有纠错重试[23] 带错误回传的重试 + 节点级 RetryPolicy + 收紧 schema token 成本随轮次线性上涨 messages 全量留在 state 并每轮重发[18] 按 token 预算裁剪;旧消息摘要后删除原文 不同用户看到彼此的历史 thread_id 硬编码或前端未按会话生成,导致串号 用用户/会话 UUID 生成,长度控制在 255 字符内[26]) | 用 version="v2" 统一结构,前端按 type 分流 |
| 结构化输出校验失败,整图崩掉 | 模型输出不满足 schema,且默认没有纠错重试[23](#表 10:高频问题清单(含官方文档对应条目) 现象 根因 修法 并行分支只保留最后一个值 / 报 INVALID_CONCURRENT_GRAPH_UPDATE 字段是默认 LastValue 通道,同一 superstep 多节点写同一 key 无法合并[20] 给会被并发写的字段加 reducer;节点只返回增量 审批通过后重复发邮件、重复扣款 恢复时被中断节点从头重跑,interrupt 之前的副作用又执行一次[7] 副作用移到 interrupt 之后;用幂等键或 @task 缓存 长会话后写入变慢、数据库暴涨 每个 superstep 存一次快照,且消息全量累积无保留策略[8] 配 TTL、删旧 thread、裁剪消息、考虑增量通道 "Recursion limit of 25 reached" recursion_limit 计 superstep 数;路由永不返回 END 或终止条件依赖的字段没被更新[11] 路由显式覆盖 END;加迭代计数器;确需长流程才调高上限 异步服务里请求卡死、健康检查超时 在事件循环里跑同步节点或同步模型调用,阻塞了整个循环 统一用 ainvoke/astream + AsyncPostgresSaver;阻塞调用放线程池 子图改了字段,父图看不到 子图有独立 schema,只有同名字段才会自动传递[19] 父子 schema 都声明该字段;跨边界数据走 Store map-reduce 汇总报并发冲突 每个 Send 分支都在同一 step 写汇总 key,而该 key 没有 reducer[22] 汇总字段加 reducer;分支只返回自己的局部结果 Postgres 报 relation does not exist checkpointer 的建表脚本没执行,setup() 不会自动跑[8] 部署或升级时执行 setup() / asetup() 前端按 SSE 解析却收到奇怪结构 单模式返回裸数据、多模式返回元组、子图多一层 namespace[10] 用 version="v2" 统一结构,前端按 type 分流 结构化输出校验失败,整图崩掉 模型输出不满足 schema,且默认没有纠错重试[23] 带错误回传的重试 + 节点级 RetryPolicy + 收紧 schema token 成本随轮次线性上涨 messages 全量留在 state 并每轮重发[18] 按 token 预算裁剪;旧消息摘要后删除原文 不同用户看到彼此的历史 thread_id 硬编码或前端未按会话生成,导致串号 用用户/会话 UUID 生成,长度控制在 255 字符内[26]) | 带错误回传的重试 + 节点级 RetryPolicy + 收紧 schema |
| token 成本随轮次线性上涨 | messages 全量留在 state 并每轮重发[18](#表 10:高频问题清单(含官方文档对应条目) 现象 根因 修法 并行分支只保留最后一个值 / 报 INVALID_CONCURRENT_GRAPH_UPDATE 字段是默认 LastValue 通道,同一 superstep 多节点写同一 key 无法合并[20] 给会被并发写的字段加 reducer;节点只返回增量 审批通过后重复发邮件、重复扣款 恢复时被中断节点从头重跑,interrupt 之前的副作用又执行一次[7] 副作用移到 interrupt 之后;用幂等键或 @task 缓存 长会话后写入变慢、数据库暴涨 每个 superstep 存一次快照,且消息全量累积无保留策略[8] 配 TTL、删旧 thread、裁剪消息、考虑增量通道 "Recursion limit of 25 reached" recursion_limit 计 superstep 数;路由永不返回 END 或终止条件依赖的字段没被更新[11] 路由显式覆盖 END;加迭代计数器;确需长流程才调高上限 异步服务里请求卡死、健康检查超时 在事件循环里跑同步节点或同步模型调用,阻塞了整个循环 统一用 ainvoke/astream + AsyncPostgresSaver;阻塞调用放线程池 子图改了字段,父图看不到 子图有独立 schema,只有同名字段才会自动传递[19] 父子 schema 都声明该字段;跨边界数据走 Store map-reduce 汇总报并发冲突 每个 Send 分支都在同一 step 写汇总 key,而该 key 没有 reducer[22] 汇总字段加 reducer;分支只返回自己的局部结果 Postgres 报 relation does not exist checkpointer 的建表脚本没执行,setup() 不会自动跑[8] 部署或升级时执行 setup() / asetup() 前端按 SSE 解析却收到奇怪结构 单模式返回裸数据、多模式返回元组、子图多一层 namespace[10] 用 version="v2" 统一结构,前端按 type 分流 结构化输出校验失败,整图崩掉 模型输出不满足 schema,且默认没有纠错重试[23] 带错误回传的重试 + 节点级 RetryPolicy + 收紧 schema token 成本随轮次线性上涨 messages 全量留在 state 并每轮重发[18] 按 token 预算裁剪;旧消息摘要后删除原文 不同用户看到彼此的历史 thread_id 硬编码或前端未按会话生成,导致串号 用用户/会话 UUID 生成,长度控制在 255 字符内[26]) | 按 token 预算裁剪;旧消息摘要后删除原文 |

不同用户看到彼此的历史 thread_id 硬编码或前端未按会话生成,导致串号 用用户/会话 UUID 生成,长度控制在 255 字符内[26](#表 10:高频问题清单(含官方文档对应条目) 现象 根因 修法 并行分支只保留最后一个值 / 报 INVALID_CONCURRENT_GRAPH_UPDATE 字段是默认 LastValue 通道,同一 superstep 多节点写同一 key 无法合并[20] 给会被并发写的字段加 reducer;节点只返回增量 审批通过后重复发邮件、重复扣款 恢复时被中断节点从头重跑,interrupt 之前的副作用又执行一次[7] 副作用移到 interrupt 之后;用幂等键或 @task 缓存 长会话后写入变慢、数据库暴涨 每个 superstep 存一次快照,且消息全量累积无保留策略[8] 配 TTL、删旧 thread、裁剪消息、考虑增量通道 "Recursion limit of 25 reached" recursion_limit 计 superstep 数;路由永不返回 END 或终止条件依赖的字段没被更新[11] 路由显式覆盖 END;加迭代计数器;确需长流程才调高上限 异步服务里请求卡死、健康检查超时 在事件循环里跑同步节点或同步模型调用,阻塞了整个循环 统一用 ainvoke/astream + AsyncPostgresSaver;阻塞调用放线程池 子图改了字段,父图看不到 子图有独立 schema,只有同名字段才会自动传递[19] 父子 schema 都声明该字段;跨边界数据走 Store map-reduce 汇总报并发冲突 每个 Send 分支都在同一 step 写汇总 key,而该 key 没有 reducer[22] 汇总字段加 reducer;分支只返回自己的局部结果 Postgres 报 relation does not exist checkpointer 的建表脚本没执行,setup() 不会自动跑[8] 部署或升级时执行 setup() / asetup() 前端按 SSE 解析却收到奇怪结构 单模式返回裸数据、多模式返回元组、子图多一层 namespace[10] 用 version="v2" 统一结构,前端按 type 分流 结构化输出校验失败,整图崩掉 模型输出不满足 schema,且默认没有纠错重试[23] 带错误回传的重试 + 节点级 RetryPolicy + 收紧 schema token 成本随轮次线性上涨 messages 全量留在 state 并每轮重发[18] 按 token 预算裁剪;旧消息摘要后删除原文 不同用户看到彼此的历史 thread_id 硬编码或前端未按会话生成,导致串号 用用户/会话 UUID 生成,长度控制在 255 字符内[26])
[表 10:高频问题清单(含官方文档对应条目)]

八个高难问题:需要设计决策,不是改一行代码

下面这八件事不会让程序报错,但会让系统在规模上来之后变得不可维护。它们共同的特征是:修法涉及架构,而不是 API 用法。

① 并发写入的"顺序不确定性"

加了 operator.add 之后不再报错,但并行分支的追加顺序由调度决定,不保证稳定。如果下游依赖顺序(比如"先检索再总结"),就会得到时好时坏的结果。两个解法:让 reducer 自己按 key 归并成字典,而不是拼列表;或者在不依赖顺序的地方使用、在需要顺序的地方显式排序。下面是一个按 id 归并的自定义 reducer:

reducer.py · 确定性合并

复制代码
from typing import Annotated, TypedDict

def merge_by_id(left: dict, right: dict) -> dict:
    # 后写覆盖同 id,但不改变其他条目;结果与顺序无关
    merged = dict(left or {})
    merged.update(right or {})
    return merged

class State(TypedDict):
    docs: Annotated[dict[str, dict], merge_by_id]   # key 是 doc_id

# 分支返回 {"docs": {doc_id: {...}}},天然幂等、天然可并发

② interrupt 的幂等设计

正确的心智模型是:节点 = 一段可重放的事务边界 。它可能被执行两次,所以里面不能有"只能发生一次"的动作。三种落地方式:把副作用放到 interrupt() 之后;用业务幂等键(订单号 + 动作类型)做 upsert;或用 @task 包住副作用以命中外层缓存。选哪种取决于副作用能不能被幂等化------不能的话,就必须靠"放到 interrupt 之后"来规避。

③ checkpoint 容量治理

容量近似等于状态大小 × superstep 数 × 分支宽度 。长会话之所以爆,主要不是步数多,而是 messages 每一步都全量复制一份。治理顺序是:先裁剪上下文(只留最近 N 轮 + 摘要),再设线程 TTL,最后才考虑存储层优化。托管服务可以按"保留最近 N 条"或"到期删除"配置 TTL,自建则要自己写清理任务25。1.2 引入的 DeltaChannel 针对的正是"全量重复"这个问题,但属于新能力,采用前先在测试环境量一下收益2。

④ 子图状态与 namespace

子图默认会随父图一起生成检查点,并拥有自己的 namespace。这带来两个后果:同名字段才会传递 ,以及子图内部的中间状态不会自动暴露给父图 。如果希望子图跨多次调用累积状态,需要给它单独开 checkpointer;如果只是想在父子之间传数据,最省心的做法是把共享字段写进两边 schema,其余走 Store19。

⑤ Postgres 连接与 PgBouncer

直接用裸连接会有一个隐蔽问题:一个长任务会独占一条连接 ,并发一上来就把连接数打满。生产做法是进程级复用一个连接池,并开启健康检查。如果中间隔着 PgBouncer 且使用事务模式,还要注意预处理语句的限制------LangGraph 的 Postgres 实现会用到预处理语句,需要相应配置才能正常工作24。

⑥ 流式协议的版本漂移

这是最容易造成"后端改一行、前端全崩"的地方。旧结构里单模式与多模式返回的形态不同,子图还会多套一层。工程解法是把结构统一在服务端 :后端固定用 v2/v3 结构输出,再自己转成前端要的 SSE 事件格式,前端只依赖你们定义的协议,不依赖库的默认形态10。

⑦ 成本与上下文治理

成本控制不是"换个便宜模型"这么简单。真正有效的是三件事:进模型前裁剪 (按 token 预算选最近消息)、把稳定事实移出对话 (写进 Store 或摘要字段)、删除而不是隐藏 (用消息删除指令移除原文,而不是靠提示词让模型"忽略")。三者叠加,长会话的边际成本才会趋于平稳18。

⑧ 多租户与会话隔离

thread_id 是数据隔离的唯一屏障,一旦可被客户端任意指定,就等于把别人的会话交出去。设计上要满足三点:由服务端生成或校验(不能让前端直接传别人的 ID)、把租户维度编进 ID 或映射表、在读取状态前做一次归属校验。Store 的 namespace 同理,应按租户 + 实体分层,而不是只用一个全局前缀。

这八个问题的共同解法

它们最终都归结为三个设计决定:状态里放什么、副作用放在哪、隔离边界画在哪。把这三件事在动手写第一个节点之前定下来,比事后调参有效得多。

调试手册:按症状查,不按代码猜

LangGraph 的调试有一个天然优势:每个 superstep 都有快照,所以"猜"的空间很小。遇到问题时,先确定问题发生在哪一步,再往里看。

| 症状 | 先看什么 | 再往哪查 |
| 结果不对但没报错 | get_state_history 逐步对比状态 | 哪个节点的增量与预期不一致;是否被后续节点覆盖 |
| 某节点偶尔失败 | trace 里该节点的耗时与错误类型 | 是否可重试错误;重试策略是否覆盖该类型 |
| 恢复后行为异常 | 恢复前的最后一个 checkpoint 的 next | 被中断节点是否重跑;副作用是否重复 |
| 越跑越慢 | superstep 数量与状态大小 | 是否有循环没收敛;messages 是否无限增长 |

前端收到错乱的数据 实际 stream_mode 与版本参数 多模式是否返回元组;子图是否多一层 namespace
[表 11:五种症状的定位路径]
  • 打开 LangSmith tracing,先看 trace 再改代码------90% 的问题看一眼就清楚。
  • 每个节点入口打印一次"我是谁 + 收到什么 key",能瞬间发现状态没传过来。
  • 用 graph.get_state(config).next 确认"下一个要跑谁",比读代码快。
  • 本地复现时把 checkpointer 换成 InMemorySaver,排除数据库因素。
  • 怀疑并发问题时,把并行分支临时改成串行,看结果是否稳定。
  • 怀疑上下文问题时,打印 token 估算与消息条数,而不是凭感觉。

学习路线与迁移注意

建议按"能跑 → 能停 → 能恢复 → 能扩展 → 能上线"的顺序练,每一步都有可验证的产出,而不是读完文档就以为会了。

第一周:能跑(图、状态、边)

写一个三分支的问答图,含一个循环与一个 END 出口。验收:能解释为什么加了 reducer 之后并发写不再报错。

第二周:能停(interrupt)

做一个人工审批流程,故意在节点前半段插入一个"发邮件"动作。验收:能复现重复发送,并用三种方式各修一次。

第三周:能恢复(checkpointer)

接 Postgres,进程中途 kill 再续跑;用 get_state_history 回到某个快照分叉。验收:能说清 durability 三种取值的差异。

第四周:能扩展(Send / 子图)

把串行的多文档处理改成 map-reduce;把其中一段封装成子图复用。验收:能说清子图哪些字段会传到父图。

第五周起:能上线(容错 / 观测 / 成本)

加 RetryPolicy 与超时、接 LangSmith、做上下文裁剪与线程 TTL。验收:能拿出"故障注入后自动恢复"的证据。

| 旧写法 | 现在 | 影响 |
| langgraph.prebuilt.create_react_agent | from langchain.agents import create_agent | 标准 Agent 不再需要自己画图[3](#表 12:从旧写法迁移到 1.x 的对照 旧写法 现在 影响 langgraph.prebuilt.create_react_agent from langchain.agents import create_agent 标准 Agent 不再需要自己画图[3] 直接解析 stream 的裸返回值 version="v2" 或 stream_events(version="v3") 结构统一,前端不用猜[10] 依赖"节点内中断后从中间继续" 接受"整节点重跑"的语义 副作用必须放在 interrupt 之后[7] "LangGraph Platform" 概念 Agent Server / LangSmith Deployment 自托管需 license key[16]) |
| 直接解析 stream 的裸返回值 | version="v2" 或 stream_events(version="v3") | 结构统一,前端不用猜[10](#表 12:从旧写法迁移到 1.x 的对照 旧写法 现在 影响 langgraph.prebuilt.create_react_agent from langchain.agents import create_agent 标准 Agent 不再需要自己画图[3] 直接解析 stream 的裸返回值 version="v2" 或 stream_events(version="v3") 结构统一,前端不用猜[10] 依赖"节点内中断后从中间继续" 接受"整节点重跑"的语义 副作用必须放在 interrupt 之后[7] "LangGraph Platform" 概念 Agent Server / LangSmith Deployment 自托管需 license key[16]) |
| 依赖"节点内中断后从中间继续" | 接受"整节点重跑"的语义 | 副作用必须放在 interrupt 之后[7](#表 12:从旧写法迁移到 1.x 的对照 旧写法 现在 影响 langgraph.prebuilt.create_react_agent from langchain.agents import create_agent 标准 Agent 不再需要自己画图[3] 直接解析 stream 的裸返回值 version="v2" 或 stream_events(version="v3") 结构统一,前端不用猜[10] 依赖"节点内中断后从中间继续" 接受"整节点重跑"的语义 副作用必须放在 interrupt 之后[7] "LangGraph Platform" 概念 Agent Server / LangSmith Deployment 自托管需 license key[16]) |

"LangGraph Platform" 概念 Agent Server / LangSmith Deployment 自托管需 license key[16](#表 12:从旧写法迁移到 1.x 的对照 旧写法 现在 影响 langgraph.prebuilt.create_react_agent from langchain.agents import create_agent 标准 Agent 不再需要自己画图[3] 直接解析 stream 的裸返回值 version="v2" 或 stream_events(version="v3") 结构统一,前端不用猜[10] 依赖"节点内中断后从中间继续" 接受"整节点重跑"的语义 副作用必须放在 interrupt 之后[7] "LangGraph Platform" 概念 Agent Server / LangSmith Deployment 自托管需 license key[16])
[表 12:从旧写法迁移到 1.x 的对照]

| 要做什么 | 写法 |
| 定义状态 | class State(TypedDict) + Annotated[T, reducer] |
| 建图 | StateGraph(State, context_schema=...) |
| 加节点 | add_node(name, fn, retry_policy=..., timeout=...) |
| 加静态边 | add_edge(START, "a") / add_edge("a", END) |
| 加条件边 | add_conditional_edges("a", router),router 返回节点名 / END / 列表 / Send |
| 编译 | compile(checkpointer=..., store=...) |
| 调用 | invoke(inputs, config) / ainvoke(...) |
| 流式 | stream(inputs, config, stream_mode=[...]) |
| 读状态 | get_state(config) / get_state_history(config) |
| 改状态 | update_state(config, values) |
| 暂停 / 恢复 | 节点内 interrupt(payload);恢复 invoke(Command(resume=...)) |

读取运行时上下文 def n(state, runtime: Runtime[Ctx]),取 runtime.context
[表 13:API 速查(按使用顺序)]

三句话收尾

状态只放增量能表达的东西 ,别把整份数据在节点间搬来搬去;节点当作可重放的事务 ,副作用要么幂等要么放在 interrupt 之后;隔离靠 thread_id 与 namespace,不要靠提示词约束。做到这三点,剩下都是配置问题。

说明

API 名称、参数与语义取自 LangGraph / LangChain 官方文档(访问于 2026-11-17,对应 langgraph 1.2.x)。文中"未确认"项指官方页面未明确写明、不同来源存在差异的部分;具体取舍请以锁定版本的文档与源码为准。文中代码为示意,运行前请按你的模型与工具配置补全依赖。

相关推荐
Cosolar1 小时前
2026 年 Java AI Agent 生态全景盘点:50+ Java 开源项目的分类、实测与选型判断
人工智能·架构·agent
张一凡932 小时前
你的 AGENTS.md,真的管到模型写代码了吗?
前端·后端·agent
qinglongcn2 小时前
怎么让 200 轮的长任务不崩——三层保全策略
agent·ai编程
数字工作台3 小时前
给 LangGraph 加一道可审计记忆:替换默认 Checkpointer,实现防篡改 + 崩溃不丢数据
python·agent
阿里云大数据AI技术3 小时前
如何用 STAROps Elasticsearch 智能助手看穿“搜索变慢”
人工智能·agent
小七-七牛开发者4 小时前
Anthropic:Agent 不必一直运行,也能持续工作
agent·claude·deepseek·anthropic·alwaysonagent
一起学安全技术4 小时前
拆大模型 10|结构化输出:让模型返回数据,而不是一段话
人工智能·语言模型·json
xyphf_和派孔明6 小时前
第十章: Agent Skill的调用机制解读
langchain·llm·agent
Csvn7 小时前
所有问题都喂最贵的模型?规则路由实测:30 个问题里 16 个能交给便宜模型(C03)
人工智能·aigc·agent