LangSmith 04：部署与上线治理

#1、本篇任务：发布一个可恢复、可回滚的 Agent 服务

LangSmith 的观测和评测可以独立使用；Deployment/Agent Server 用于运行和管理长期、有状态 Agent。是否采用 Cloud、Hybrid、Self-hosted 或 Standalone，取决于数据边界、规模和运维能力，而不是功能越多越好。

#2、先判断是否需要 Agent Server

简单 CLI 或 webhook 可以直接调用应用 worker。需要 thread/run 管理、断线恢复、长任务队列、HITL、定时运行和集中部署时，Agent Server 才明显有价值。

它不替代业务认证、租户 ACL、领域数据库、工具授权或幂等。平台管理图运行，应用仍管理业务事实。

#3、部署制品

复制repo/
  graph/          # 编排代码与导出的 compiled graph
  domain/         # 业务服务接口
  tests/          # unit/integration/evals
  deployment/     # 镜像、健康检查、资源、迁移
environment/
  secrets         # 模型、DB、LangSmith key，由密钥管理注入
  versions        # release、prompt、index、state schema

锁定依赖和基础镜像；密钥不进入仓库或镜像；启动时验证配置和依赖；liveness/readiness 分离；状态 schema 迁移先演练再发布。

#4、Run 生命周期

复制queued → running → waiting_for_input → running → succeeded
                  ↘ failed / cancelled / expired

每次迁移记录 request、thread、run、actor 和版本。取消不是关闭浏览器连接：停止派发新节点，终止可中断工作，等待不可中断工具完成并记录结果。恢复必须从授权 thread/checkpoint 继续，不能从 START 重放副作用。

#5、容量与隔离

API 限制请求大小和用户/租户速率；run worker 限制并发、deadline、递归和队列公平性；模型限制 token、工具次数和费用；工具限制超时、可重试错误和熔断；checkpoint/artifact 设置 TTL、加密和访问审计。

压测混合短问答、长任务、待审批、慢工具和取消请求。只测 QPS 看不到长任务占满 worker、某租户影响其他租户等问题。

#6、发布与回滚

复制构建固定制品 → staging 数据迁移与 eval → 小流量/影子运行
→ 观察质量、延迟、成本、安全 → 扩大流量

回滚清单同时包含代码、prompt、模型、索引和 state schema。旧 thread 可绑定 graph version，由兼容 worker完成；不要让旧 checkpoint 突然交给不兼容新图。

#7、必须演练的故障

流式断开后恢复；审批过期拒绝；模型 provider 故障时降级；向量库故障时拒答；worker 在副作用后崩溃仍不重复执行；trace 服务不可用不影响请求；候选版本安全 evaluator 回归时停止扩量并回滚。

每项演练留下 trace、指标、恢复步骤、负责人和自动化案例。

#8、课程阶段验收

现在你应具备一条完整开发闭环：LangChain 构建 Agent，LangGraph控制状态和恢复，Deep Agents处理长任务，LangSmith解释运行、评测变更并治理部署。

最后四篇把这些能力迁移到简易 OpenCode 和单渠道 OpenClaw。重点不是重新背框架，而是把同一原则用于代码与消息系统。

官方阅读：Deployment、Self-hosted LangSmith。