---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: private
status: active
tags:
  - study
  - langchain
  - langgraph
  - production
  - testing
  - migration
topic: LangGraph Python 的应用结构、测试、部署、RemoteGraph、迁移与案例
sources:
  - https://docs.langchain.com/oss/python/langgraph/application-structure
  - https://docs.langchain.com/oss/python/langgraph/local-server
  - https://docs.langchain.com/oss/python/langgraph/test
  - https://docs.langchain.com/oss/python/langgraph/backward-compatibility
  - https://docs.langchain.com/oss/python/langgraph/studio
  - https://docs.langchain.com/oss/python/langgraph/ui
  - https://docs.langchain.com/oss/python/langgraph/deploy
  - https://docs.langchain.com/oss/python/langgraph/observability
  - https://docs.langchain.com/oss/python/langgraph/case-studies
  - https://docs.langchain.com/oss/python/langgraph/changelog-py
  - https://docs.langchain.com/oss/python/langgraph/agentic-rag
  - https://docs.langchain.com/oss/python/langgraph/sql-agent
  - https://docs.langchain.com/langsmith/use-remote-graph
  - https://docs.langchain.com/oss/python/releases/changelog
  - https://docs.langchain.com/oss/python/migrate/langgraph-v1
  - https://docs.langchain.com/oss/python/migrate/langgraph-supervisor
last_verified: 2026-08-11
---
# 生产化、测试、部署、迁移与案例

## 生产应用的最小结构

一个可由 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 必须唯一，目标可以是：

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

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

## 本地 Agent Server

官方本地路径：

1. 安装带 inmem 能力的 LangGraph CLI；
2. 创建或准备 LangGraph 项目；
3. 以 editable mode 安装本地依赖；
4. 从 .env.example 创建本地 .env；
5. 运行 langgraph dev；
6. 在 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 时：

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

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

### 关键风险

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

跨部署调用还要考虑：

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

## 测试策略

### 每个测试重新构图

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

1. 创建 fresh builder；
2. 使用 fresh InMemorySaver；
3. compile；
4. 使用唯一 thread_id。

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

### 单节点与边测试

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

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

### Partial execution

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

1. 使用 InMemorySaver compile；
2. update_state 并以 as_node 指定起点之前的节点；
3. 同一 thread_id invoke；
4. 用 interrupt_after 在目标节点停止；
5. 断言部分路径 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。

兼容问题分三类：

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

### 技术兼容矩阵

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

推荐：

- 新字段先 NotRequired 或 Optional；
- 删除按 deprecation window 处理；
- rename 采用 add → dual write / dual route → drain → remove；
- 节点容忍未知旧字段；
- staging 用旧 checkpoint 做 replay / resume；
- thread 搜索和 trace 都显示无旧节点活动后再删除。

### 发现 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，前提：

1. 只给最外层 graph 配 checkpointer；
2. subagent 保持默认 per-invocation，继承父 checkpointer；
3. 顶层调用传 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 图的控制流：

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

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

生产增强项：

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

## 实战案例二：SQL Agent

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

1. 列出数据库表；
2. 获取 schema；
3. 生成查询；
4. 检查查询；
5. 执行查询；
6. 返回答案。

相比只在 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 与级联隔离；
- 定期故障演练和数据删除演练。

## 关联笔记

- [[01-LangGraph基础与API选择]]
- [[02-Graph-API状态与控制流]]
- [[03-持久化记忆与容错]]
- [[04-流式HITL与子图]]

## 来源

### LangGraph 主目录 12 页

- [Application structure](https://docs.langchain.com/oss/python/langgraph/application-structure)
- [Run a local server](https://docs.langchain.com/oss/python/langgraph/local-server)
- [Test](https://docs.langchain.com/oss/python/langgraph/test)
- [Backward compatibility](https://docs.langchain.com/oss/python/langgraph/backward-compatibility)
- [LangSmith Studio](https://docs.langchain.com/oss/python/langgraph/studio)
- [Agent Chat UI](https://docs.langchain.com/oss/python/langgraph/ui)
- [Deployment](https://docs.langchain.com/oss/python/langgraph/deploy)
- [LangSmith Observability](https://docs.langchain.com/oss/python/langgraph/observability)
- [Case studies](https://docs.langchain.com/oss/python/langgraph/case-studies)
- [LangGraph changelog entry](https://docs.langchain.com/oss/python/langgraph/changelog-py)
- [Build a custom RAG agent](https://docs.langchain.com/oss/python/langgraph/agentic-rag)
- [Build a custom SQL agent](https://docs.langchain.com/oss/python/langgraph/sql-agent)

### 补充生产与迁移页

- [RemoteGraph](https://docs.langchain.com/langsmith/use-remote-graph)
- [Python releases changelog](https://docs.langchain.com/oss/python/releases/changelog)
- [LangGraph v1 migration](https://docs.langchain.com/oss/python/migrate/langgraph-v1)
- [Migrate from langgraph-supervisor](https://docs.langchain.com/oss/python/migrate/langgraph-supervisor)