生产化、测试、部署、迁移与案例

生产应用的最小结构

一个可由 Agent Server 加载的 LangGraph 应用通常包含：

一个或多个已编译 graph，或返回 graph 的工厂函数；
langgraph.json；
requirements.txt、pyproject.toml 等依赖清单；
可选 .env，仅用于本地开发；
业务包、测试和必要系统依赖。

langgraph.json 至少描述：

dependencies：本地包与第三方依赖；
graphs：唯一 graph name 到 Python 对象路径的映射；
env：本地环境变量文件；
可选 dockerfile_lines 等系统依赖配置。

生产环境变量应由部署平台注入，不依赖仓库里的 .env。API key、数据库口令与加密密钥不得提交版本库。

Graph export

graphs 中每个 name 必须唯一，目标可以是：

已 compile 的 graph；
构造并返回 graph 的函数。

create_agent 本身返回已编译 LangGraph graph，可以直接导出。复杂项目应让 graph 定义、工具、State schema、外部 adapter 与配置分层，避免一个文件同时承担全部职责。

本地 Agent Server

官方本地路径：

安装带 inmem 能力的 LangGraph CLI；
创建或准备 LangGraph 项目；
以 editable mode 安装本地依赖；
从 .env.example 创建本地 .env；
运行 langgraph dev；
在 Studio 或 SDK 中测试。

默认本地 server 地址为 127.0.0.1:2024。langgraph dev 使用内存模式，只适合开发与测试；重启会丢失内存状态，不能由此推断生产持久化已验证。

Safari 连接本地 Studio 有 localhost 限制时可使用 tunnel，但 tunnel 会扩大暴露面，应只在受控开发环境启用并检查 allowed origins。

本地 API 验证

至少覆盖：

threadless run：确认 graph 能加载与执行；
带 thread_id 的 run：确认多轮 State；
streaming：确认 token、状态和 interrupt；
错误路径：确认 retry、handler 与 trace；
restart：确认使用真实持久化后能恢复。

仅在 in-memory dev server 成功，不等于数据库 migration、并发或重启恢复通过。

Studio

LangSmith Studio 是连接本地 Agent Server 的可视化开发界面，可查看：

graph 步骤和中间 State；
发给模型的 prompt；
tool call 参数与结果；
异常上下文；
token、延迟和 trace；
thread、assistant 与历史步骤；
从历史步骤重新运行。

开发 server 支持 hot reload。Studio 适合快速诊断，但仍要把关键断言固化为自动化测试。

如果不希望本地数据发送为 LangSmith trace，显式设置 LANGSMITH_TRACING=false。Studio 连接本地 server 与 trace 上传是不同概念，不应混淆。

Agent Chat UI

Agent Chat UI 是开源 Next.js 客户端，可连接本地或已部署 Agent Server，支持：

实时聊天；
tool call 与结果展示；
interrupt thread 检测；
time travel 与 State fork；
可选 generative UI。

连接时需要：

graph ID，即 langgraph.json 中的 graph name；
deployment URL 或本地 server URL；
远端服务需要的认证信息。

官方 hosted UI 适合快速验证；生产产品通常需要自建前端、服务端认证与租户隔离，不能把 LangSmith API key 暴露在公共浏览器。

部署模型

LangSmith Deployment 提供：

Cloud；
hybrid；
standalone server；
self-hosted control plane。

Cloud quickstart 以 GitHub repository 为输入，部署后可在 Studio 测试并取得 API URL。选择部署方式时要单独评估：

数据驻留与合规；
持久化后端；
Redis / Postgres 容量；
网络出口；
并发、队列与长任务；
secrets 与认证；
日志、trace、metrics；
灰度、回滚与数据库 migration。

生产化不是把本地 graph 上传即可。至少要验证 background execution、HITL 长暂停、进程重启、扩缩容与历史 checkpoint 兼容。

RemoteGraph

RemoteGraph 是客户端侧接口，把已部署 graph 以近似 CompiledGraph 的方式使用，支持 invoke、stream、get_state、update_state 及异步版本。

适用场景

本地开发使用 CompiledGraph，生产改用远端部署而保持近似 API；
通过 thread_id 获取远端持久 State；
把不同部署的 graph 组合为跨服务 subgraph；
把复杂远端流程复用为 node 或 tool。

初始化必须提供 graph name 或 assistant ID，并提供：

deployment URL；或
async LangGraphClient；或
SyncLangGraphClient。

如果 client 与 URL 同时传入，client 优先。

thread persistence

RemoteGraph 默认调用可以是无状态的。需要多轮、HITL 或远端 State 时：

通过 SDK 创建或取得 thread；
在 config 中传 thread_id；
用 RemoteGraph 调用；
用 get_state 验证持久状态。

RemoteGraph 作为 subgraph 且父图有 checkpointer 时，thread ID 使用 UUID。

关键风险

不要让 RemoteGraph 调用同一 deployment RemoteGraph 面向其他 deployment。让一个部署通过 RemoteGraph 调用自己，或同部署内另一个 graph，可能造成死锁和资源耗尽。同一 deployment 内应使用本地图组合或 subgraph。

跨部署调用还要考虑：

网络 timeout 与 retry；
调用链幂等；
认证 header 与租户传播；
distributed tracing；
下游部署容量与级联故障；
每个远端 run 的独立计费和配额。

测试策略

每个测试重新构图

大量 LangGraph 测试依赖 State。推荐每个测试：

创建 fresh builder；
使用 fresh InMemorySaver；
compile；
使用唯一 thread_id。

避免测试间共享 checkpoint 产生顺序依赖。

单节点与边测试

compiled graph 通过 graph.nodes 暴露节点引用，可以单独 invoke 节点并断言更新。此方式绕过 compile 时传入的 checkpointer，因此：

适合纯节点逻辑；
不能替代 persistence、interrupt、retry 的集成测试；
conditional routing function 应单独以不同 State 覆盖所有分支。

Partial execution

大图可通过 checkpoint 构造中间状态：

使用 InMemorySaver compile；
update_state 并以 as_node 指定起点之前的节点；
同一 thread_id invoke；
用 interrupt_after 在目标节点停止；
断言部分路径 State。

如果一段流程具有稳定边界并需要大量独立测试，把它重构为 subgraph 往往更清晰。

必测场景

正常顺序与所有条件分支；
parallel fan-out / fan-in 与 reducer；
一条并行分支失败后只重跑失败分支；
retryable 与 non-retryable 异常；
run timeout、idle timeout 与 heartbeat；
error handler 补偿；
interrupt、拒绝、编辑、无效输入重问；
同一 thread 恢复与错误 thread 拒绝；
replay、fork 与副作用幂等；
subgraph 三种 persistence 模式；
per-thread subgraph 并行冲突保护；
process restart 后 checkpoint 恢复；
旧 checkpoint 在新 graph 版本上恢复；
streaming v2 和 event streaming v3 的前端契约；
trace 中敏感数据脱敏。

单元测试通过不等于生产恢复。数据库 checkpointer、Store、真实模型、网络断开和并发需要独立集成或演练。

Observability

LangSmith 把一次调用建模为 trace，内部步骤是 runs。可用于：

本地 debug；
评估输出；
线上 dashboard 与监控；
查看节点、工具和模型调用链。

tracing 控制

全局环境变量开启；
tracing_context 对局部调用开启或关闭；
project name 区分环境与服务；
tags、metadata 记录 tenant 的非敏感标识、版本和实验组。

不要把 token、完整用户隐私或认证材料放入 metadata。

anonymizer

可以用 anonymizer 在 trace 上传前屏蔽敏感格式。它是纵深防御，不替代：

源头数据最小化；
输入输出字段 allowlist；
日志级别控制；
stream 脱敏；
checkpoint 加密；
访问控制与 retention。

生产告警至少关注：

节点错误率与 retry 次数；
timeout 与 GraphDrained；
interrupt 长时间未恢复；
thread / checkpoint 增长；
Store 查询延迟；
token 与模型费用；
graph recursion limit；
远端 deployment 级联失败。

向后兼容：最新代码会作用于旧 thread

LangGraph 不把一个 run 永久钉死在其启动时的代码版本。旧 thread 恢复时执行当前部署的最新 graph。因此每次发布都相当于修改“graph 代码 ↔ 已持久 State”的 API。

兼容问题分三类：

技术兼容：旧 checkpoint 能否加载，旧节点名能否找到；
业务兼容：旧 thread 是否应继续旧业务路径；
确定性兼容：Functional API replay 是否仍能匹配 task 与 interrupt。

技术兼容矩阵

变更	已完成 thread	interrupted / in-flight thread
新增或改 edge	通常安全	节点仍存在时安全
新增 node	安全	通常安全
删除或重命名 node	完成后无恢复路径，通常可接受	高风险，可能正准备进入旧节点
新增可选 State key	安全	安全
删除 State key	通常可加载，但旧逻辑可能读取	先 deprecate
重命名 State key	旧值丢失	高风险
收紧类型或新增必填字段	可能无法加载旧 State	高风险

发现 in-flight thread

Agent Server 搜索 busy、interrupted、error 等状态；
tracing 监控旧节点是否仍被进入；
已知 thread_id 时用 get_state 与 get_state_history；
无法证明 drain 完成时，保留兼容节点和字段。

业务版本

即使技术上能加载，新流程也不一定应追溯作用于旧 thread。推荐在 thread 起点把 flow_version 写入 State：

老 thread 没字段时默认旧版本；
新 thread 在起点写入新版本；
conditional edge 按版本分流；
全部旧 thread drain 后移除兼容分支。

版本必须在第一次需要分支之前写入；中途才写无法区分已有 thread。

Functional replay 兼容

entrypoint 恢复会从函数开头 replay，并按位置复用 task 结果与 interrupt 输入。in-flight run 前不能随意：

新增、删除或重排 task；
新增、删除或重排 interrupt；
把 random、time、网络调用直接放在 entrypoint；
用不稳定条件改变 task 调用顺序。

大改时选择：

先让 in-flight run drain；
新逻辑放进新 task；
在 langgraph.json 注册新 graph name，只让新 thread 使用。

LangGraph v1 迁移

LangGraph v1 整体保持较高向后兼容，主要变化：

Python 最低版本为 3.10，放弃 Python 3.9；
langgraph.prebuilt.create_react_agent deprecated；
推荐 langchain.agents.create_agent；
AgentState 等旧预置类型迁到 langchain.agents；
MessageGraph 迁为带 messages key 的 StateGraph；
旧 HumanInterrupt 类型迁到 LangChain HITL middleware；
ValidationNode 由 create_agent 的工具输入校验替代。

如果只是标准 ReAct agent，迁到 create_agent；仍需混合确定性步骤、自定义 State 或特殊路由时，保留自定义 StateGraph。

从 langgraph-supervisor 迁移

langgraph-supervisor 已不再积极维护。推荐用 create_agent + tool-wrapped subagents：

旧做法	推荐替代
create_supervisor + worker graph nodes	主 create_agent 把每个 subagent 包装成 tool
output_mode	在 tool wrapper 中格式化返回
create_handoff_tool	自定义 tool 调用 subagent.invoke
supervisor 嵌套 supervisor	扁平 leaf tools，或把中层 agent 再包装成 tool

interrupt 可从内层 subagent tool 一直冒泡到顶层 graph，前提：

只给最外层 graph 配 checkpointer；
subagent 保持默认 per-invocation，继承父 checkpointer；
顶层调用传 thread_id。

需要固定路由、验证、共享 State、静态 subgraph 发现或每层独立 checkpoint namespace 时，使用自定义 StateGraph，而不是强行全部 tool 化。

多层 supervisor 可：

扁平为一个 supervisor + 多个 leaf agent tools；
或按需嵌套 tool-wrapped agent。

旧 output_mode 的 full_history / last_message 行为应在 wrapper 中明确转换，避免把全部子 agent 历史无界塞回父消息。

版本演进摘要

官方 LangGraph changelog 入口当前重定向到共享 Python releases changelog。与本专题直接相关的里程碑：

v1.0.0 — 2025-10-20

LangGraph v1；
create_react_agent 迁向 create_agent；
Python 3.10+；
旧 0.x 文档转为 archive。

v1.1.0 — 2026-03-10

stream / astream version=v2，统一 StreamPart；
invoke / ainvoke version=v2，GraphOutput.value 与 interrupts；
Pydantic、dataclass values 自动 coercion；
修复 time travel 与 interrupt / subgraph 恢复；
v2 为 opt-in，旧字典访问仅过渡兼容。

v1.2.0 — 2026-05-12

DeltaChannel beta；
async per-node timeout；
node-level error handler；
RunControl graceful shutdown；
event streaming version=v3 beta，类型化 channel projections；
timeout 与 error handler 当前为 Python 特性。

升级前不能只看包版本号，应同时检查：

graph State 与 checkpoint 兼容；
stream / invoke 返回结构；
自定义 checkpointer 是否支持 DeltaChannel；
前端 SDK 是否对应新协议；
in-flight thread 是否 drain；
rollback 是否能读取新 checkpoint 格式。

实战案例一：Agentic RAG

官方自定义 RAG 图的控制流：

预处理文档、切分、embedding、写入 vector store；
用 retriever tool 封装语义检索；
generate_query_or_respond 由模型决定直接回答还是检索；
ToolNode 执行 retriever；
grade_documents 用结构化输出判断相关性；
不相关时 rewrite_question，再回到决策节点；
相关时 generate_answer，只基于检索上下文作答。

它区别于固定 RAG 的核心是：检索由模型按需触发，并有“相关性判断 → 查询改写 → 再检索”的反馈环。

生产增强项：

rewrite 循环上限；
文档权限过滤先于向量检索；
source ID 与引用保留；
grader 失败时安全降级；
embedding / index 版本；
prompt injection 防护；
retrieval、grade、answer 分段评估。

实战案例二：SQL Agent

官方自定义 SQL agent 用专用节点强制执行：

列出数据库表；
获取 schema；
生成查询；
检查查询；
执行查询；
返回答案。

相比只在 system prompt 中要求“先看表、先检查 SQL”，显式节点与边能真正约束顺序。

安全底线

数据库账号最小权限，优先只读；
限定 schema、table 与 row 范围；
禁止任意 DDL / DML；
查询 parser 或 allowlist；
statement timeout、row limit、成本上限；
参数化可参数化部分；
高风险 SQL 在执行前 interrupt；
审批人可以批准、编辑或拒绝；
trace 和返回结果脱敏；
tutorial 的薄工具 wrapper 不能直接用于生产。

加入 HITL 后必须 compile checkpointer；interrupt 可无限期暂停，恢复时仍要使用原 thread_id。

Case studies 说明

官方案例索引覆盖：

金融与支付；
医疗与生命科学；
软件研发和代码生成；
电商与客服；
物流、政府、媒体、旅行；
企业搜索、研究与数据提取。

案例包括 Klarna、Uber、J.P. Morgan、LinkedIn、GitLab、Replit、Vodafone、Elastic 等。这个索引证明 LangGraph 被用于多种生产场景，但不能直接证明某个具体架构、吞吐或可靠性指标适合当前项目；选型仍需以自己的 SLO、数据边界和演练结果为准。

上线 Gate

构建

graph name、State schema 与 reducer 有文档；
deterministic 与 agentic 边界明确；
所有外部副作用幂等；
loop、fan-out 和 RemoteGraph 有预算；
secrets 不进 State、日志或仓库。

测试

节点、edge、partial path、完整 E2E；
persistence 数据库 migration；
crash / restart / retry / timeout / drain；
interrupt 多轮恢复；
旧 checkpoint 升级；
stream 与前端 contract；
负载和并发。

发布

in-flight thread 审计；
flow_version 或兼容窗口；
checkpoint / Store backup 与 retention；
新版本写入格式的回滚策略；
逐步放量；
监控与告警就绪。

运维

Studio 与 trace 可定位每个节点；
PII anonymizer 与访问控制；
checkpoint 体积、历史数量、恢复失败指标；
RemoteGraph 分布式 trace 与级联隔离；
定期故障演练和数据删除演练。