10.15 部署与可观测性：让 Agent 上线并看得见

前面十五节，图都在终端里跑。要变成给用户用的产品，还差两件事：部署（让图变成稳定的 API 服务）和可观测性（跑歪了你能看见它卡在哪一步、花了多少钱、答得对不对）。

1. 部署：把图变成服务

本地脚本再完整，用户也调不到。部署就是把同一张图挂到一个有鉴权、有队列、有接口文档的服务上。LangGraph 官方工具链由轻到重分三层：

方案	是什么	适合
本地 Server	`langgraph dev` / `langgraph up`，一条命令把图变成带 REST API 的本地服务，自带 Studio 调试界面	开发自测、前后端联调
Agent Chat UI	官方开源的聊天前端模板，接上 Server 就有对话框 + 中断审批 UI	快速做演示站点
LangGraph Platform	官方托管：自动扩缩容、持久化任务队列、定时任务（Cron）、流式推送	生产上线、不想自己运维

本地跑服务的关键是一份 langgraph.json——声明图在哪、依赖是什么：

json

{
  "dependencies": ["."],
  "graphs": {
    "travel_agent": "./main.py:build_graph"
  },
  "env": ".env"
}

然后 langgraph dev。图就从“终端程序”升级成带 API、自带 Studio 的服务。16 节旅行助手的动态 interrupt() 会向客户端返回结构化审批包，前端据此展示工具名与参数，再用 Command(resume=...) 提交批准或驳回。

把图变成 HTTP 服务只是起点。上线前还要补：身份认证、租户隔离、请求限流、超时、取消任务、版本管理。长时间运行时，客户端断开是否取消任务，也要有明确约定。

发布新图版本时，正在跑的旧线程是否继续使用旧结构，需要提前验证。状态字段和节点名称变了，还要考虑检查点迁移，避免升级后旧会话无法恢复。官方对“已结束线程”比较宽松（拓扑可改），对“中断中的线程”很严：不要重命名或删除它即将进入的那个节点。

Agent 生产化的真正难点常常不是“跑不起来”，而是“跑歪了你不知道”：某天回答质量下滑，是 Prompt 问题、模型抽风，还是检索工具返回了垃圾？全链路追踪就是为这种问题准备的。

一次执行像快递运单：下单（用户提问）→ 分拣（模型思考）→ 上路（工具调用）→ 签收（最终回答）。LangSmith 这类平台就是运单的物流详情页——每一环几点几分、耗时多少、包裹内容（Prompt 与响应）都能点开。

市面上主流观测框架有 LangChain 官方的 LangSmith 和开源的 Langfuse。它们能把每次执行的完整链路记成可检索的追踪页，并支持指标与评测回归。本章以及本知识库的项目暂不接入它们，统一用 05 节的三个方法（可视化 + 流式 + 打日志）。理由有三：

零依赖可运行。 接入观测平台通常要注册账号、申请 Key、连云端（Langfuse 私有化也至少多运维一个服务），而本库示例应做到“装好 langgraph 就能跑”；
数据不出域。 追踪会把完整 Prompt、响应、工具返回值送出去，教学演示没必要引入隐私与合规负担；
不是知识缺口。 观测框架是装上就能用的工具，不是需要单独开一章训练的能力。先把日志与流式调试练扎实，团队需要时再接入不迟。

本章各节示例都用 stream_mode="updates" 逐节点打印状态，并在节点函数里留 print。等将来接入观测平台，这些位置恰好就是埋点处。

可观测记录至少能串起：一次用户请求、图运行、模型调用、工具调用。除了耗时与错误，还应区分模型拒答、工具空结果和流程异常。日志中的提示词与工具返回可能含敏感数据，要设脱敏、访问权限和保留期限。

🔧 动手建议： 下一节的综合实战项目自带 graph 对象。学完本节后，可以给它配一份 langgraph.json，用 langgraph dev 跑起来，在终端流式输出里观察多智能体的接力过程。

下一节： 招式学完，回到代码——打开旅行助手调度台，把全章零件装进一台能在浏览器里值班的整机，并看清它距离正式上线还缺哪些护栏。