本文是「LangGraph 教程系列」第 12 篇。写作时基于 langgraph 1.2.10、langchain 1.3.14、langchain-openai 1.4.1、Python 3.12+。配套代码仓库 https://github.com/wxj006007/deep-research-assistant ，本篇对应 tag v5。

v4 的 Supervisor 已经能把研究员、审稿人和写作员组织起来。可 python -m 退出后，外部客户端没有稳定的运行入口，人工审批也没有可以回到的服务端会话，更谈不上查一条慢请求究竟卡在搜索、模型还是调度。

最后一版不再给助手增加一个业务角色。它把同一张图交给 LangGraph Platform：平台提供 Thread、Run、流式 API 和运行时持久化，LangSmith 则把每次运行变成可追踪的执行记录。

一、代码和平台各管什么

部署不等于在图外再包一层 FastAPI。这个案例的业务边界已经在 StateGraph 中，Platform 可以直接把编译图变成服务。

图仍负责 Supervisor 路由、人工审批、资料和记忆写入条件。Platform 负责线程和运行的生命周期，不能把用户身份、输入校验或业务授权替你做掉。LangSmith 负责观察，不是业务数据库。

二、部署入口只导出图

v4 的本地演示传入 MemorySaver 与 InMemoryStore，方便单进程运行。v5 不能把这两个对象硬编码进去，否则云端运行时就无法接管持久化资源。

# src/v5_service.py
from src.v4_multi_agent import build_graph

graph = build_graph()

部署清单把一个稳定名称映射到这个入口。

{
  "dependencies": ["."],
  "graphs": {
    "deep_research_assistant": "./src/v5_service.py:graph"
  },
  "env": ".env"
}

langgraph.json 不是另一套工作流定义。它只告诉 Platform 应加载哪个 Python 图、安装哪些项目依赖、从哪里读取本地开发环境变量。生产密钥由 Platform 的部署环境配置，不应提交进仓库。

三、Thread 是服务端会话边界

调用方先创建或复用一个 Thread，再在该 Thread 上启动 Run。对于这个助手，Thread 对应一次可暂停、可恢复的研究会话；ResearchContext 中的 user_id 和 research_id 仍分别用来隔离长期记忆和保证摘要写入幂等。

创建或复用 Thread
  -> 提交问题和 ResearchContext，启动 Run
  -> 流式消费回答、状态更新和业务进度
  -> 收到 interrupt 后展示审批
  -> 用同一 Thread 恢复 Run

不要让浏览器任意传入另一个用户的 user_id。业务后端应从已认证身份生成它，并为每次研究生成或验证 research_id。Thread ID 可以由客户端保存用于恢复，但访问它前仍要做归属校验。

四、本地先验证服务形状

安装依赖、配置模型环境变量后，在仓库根目录启动开发服务。

langgraph dev

这个命令读取 langgraph.json，加载 deep_research_assistant 图，并提供与托管环境一致的开发 API。先在这里验证四件事：新 Thread 能启动运行；流式调用能看到回答和更新；审批中断能以同一 Thread 恢复；取消路径不会新增长期记忆。

通过后，将同一仓库和配置发布到 LangGraph Platform Cloud。Cloud 负责服务运行与持久化基础设施；本项目不再另建 FastAPI、Docker 编排或一套自管 PostgreSQL 教程，以免把重点从 agent 服务化转成运维搭建。

五、可观测不是只看一条最终答案

启用 LangSmith 追踪。

LANGSMITH_TRACING=true
LANGSMITH_API_KEY=lsv2_pt_your-key-here
LANGSMITH_PROJECT=deep-research-assistant

一次 v5 Run 的 trace 应能展开父图、Supervisor、研究员子图、审稿人、写作员和模型调用。排查问题时，先看运行总时长和错误，再定位具体节点：Supervisor 是否反复分派、研究员是否因审批停住、搜索是否无结果、审稿人是否不断要求返工、写作员消耗了多少时间和 token。

trace 的价值在于把“回答质量不好”还原成可检查的执行路径，而不是只记录输入和输出。可以按项目观察失败率、延迟和模型成本趋势，再为异常增长设置告警。

但观测不等于无边界记录。不要把 API Key 写进 metadata；不要把完整长期记忆、审批原文或内部 state 默认暴露给前端；日志保留期和用户删除请求也必须由应用的隐私策略约束。

六、上线前的最小检查表

• 模型、搜索、LangSmith 密钥仅存在于部署环境，不在仓库或 trace metadata 中出现。
• API 层从认证身份生成 user_id，校验 Thread 的归属，拒绝跨用户访问。
• 同一个 research_id 重试不会重复写入摘要；取消和预算耗尽不会伪装成成功研究。
• 用真实的流式 Run 验证 interrupt/resume，而不只验证一次同步调用。
• 在 LangSmith 中确认能从一次异常 Run 定位到具体节点和模型调用。

从 v0 的直接回答到 v5 的服务化研究团队，变化并不是“把提示词写得更长”。图给了流程分叉、循环、暂停、记忆、组合和调度的明确位置；服务和观测则让这些位置在真实用户到来后仍然可运行、可恢复、可解释。

赞或收藏 关注 我们下次再见