langgraph教程系列-12-把agent跑成服务-部署与可观测

本文是「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 本篇对应 tagv5。v4 的 Supervisor 已经能把研究员、审稿人和写作员组织起来。可python -m退出后外部客户端没有稳定的运行入口人工审批也没有可以回到的服务端会话更谈不上查一条慢请求究竟卡在搜索、模型还是调度。最后一版不再给助手增加一个业务角色。它把同一张图交给 LangGraph Platform平台提供 Thread、Run、流式 API 和运行时持久化LangSmith 则把每次运行变成可追踪的执行记录。一、代码和平台各管什么部署不等于在图外再包一层 FastAPI。这个案例的业务边界已经在StateGraph中Platform 可以直接把编译图变成服务。渲染错误:Mermaid 渲染失败: Parse error on line 3: ...rm API] api -- graph[v5 研究图] gr ----------------------^ Expecting AMP, COLON, PIPE, TESTSTR, DOWN, DEFAULT, NUM, COMMA, NODE_STRING, BRKT, MINUS, MULT, UNICODE_TEXT, got GRAPH图仍负责 Supervisor 路由、人工审批、资料和记忆写入条件。Platform 负责线程和运行的生命周期不能把用户身份、输入校验或业务授权替你做掉。LangSmith 负责观察不是业务数据库。二、部署入口只导出图v4 的本地演示传入MemorySaver与InMemoryStore方便单进程运行。v5 不能把这两个对象硬编码进去否则云端运行时就无法接管持久化资源。# src/v5_service.pyfromsrc.v4_multi_agentimportbuild_graph graphbuild_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_TRACINGtrue LANGSMITH_API_KEYlsv2_pt_your-key-here LANGSMITH_PROJECTdeep-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 的服务化研究团队变化并不是“把提示词写得更长”。图给了流程分叉、循环、暂停、记忆、组合和调度的明确位置服务和观测则让这些位置在真实用户到来后仍然可运行、可恢复、可解释。赞或收藏 关注 我们下次再见