Cloud 与多框架部署流水线

Cloud 的两条发布路径

Cloud 创建前必须先通过 langgraph dev，但这只是必要条件。UI 路径首次需要 GitHub Organization owner/admin 授权 hosted-langserve App；后续开发者仍要有 Deployment 权限。新 Revision 与 Deployment 是不同对象，更新应创建 Revision、观察构建/服务日志和指标，再决定切流或中断。

推荐 CI/CD 门禁

PR
 ├─ 静态检查 + 单元测试
 ├─ Graph/Tool 集成测试
 ├─ 离线 Dataset 评估（AgentEvals/OpenEvals/LangSmith）
 └─ Preview Revision + 端到端验证
       └─ 质量阈值通过 → Production Revision
             └─ 在线 Trace/规则/评估/告警

• CI 要明确区分 LangSmith 数据 API 与 Deployment Control Plane API；混用 endpoint 是官方列出的常见错误。
• 预览和生产用独立 Secrets、模型配额与数据范围；不要让 PR 环境读取生产长期记忆。
• 发布门禁使用相对基线和关键失败样本，不只比较平均分。
• Revision 失败应中断/回滚，不删除整个 Deployment；保留构建日志、评估结果和版本关联供审计。

自托管控制平面发布

启用完整 Self-hosted Deployment 后，集群新增 Control Plane、Listener 与 Operator。典型流程是：本地验证 → langgraph build → 推到集群可访问的私有 Registry → 在自托管 Control Plane UI 填镜像 URL → Listener/Operator 部署。

这条路径不会替你管理 Registry、镜像签名、漏洞扫描或回滚。私有 Registry 凭据应由 Kubernetes Secret/工作负载身份提供；禁止把凭据写进镜像 URL 或 langgraph.json。

Standalone Agent Server

Standalone 不需要 Control Plane，可用 Kubernetes、Docker 或 Compose 直接运行 API/Queue + PostgreSQL + Redis，并可选把 Trace 发到 Cloud 或自托管 LangSmith。它是生产可用拓扑，但所有发布、扩缩容、健康检查和数据库生命周期由客户负责。

官方明确不建议把 Standalone Server 跑在会 scale-to-zero 的 Serverless 环境：后台任务可能丢失，冷启动扩容也不可靠。需要 Serverless Web 前端时，将持久 Agent Server 放在 Deployment/常驻容器，前端只做协议代理。

任意 Agent 框架接入

LangSmith Deployment 的服务契约是 Agent Server/Graph，而不是限定业务框架：

• Google ADK：deployments-wrap-sdk 把 ADK Runner、Session 与 token event 桥接成 Graph；包名是 deployments-wrap-sdk，import path 是 saf_sdk。
• Claude Agent SDK、Strands、CrewAI、AutoGen 等：用 LangGraph Functional API 的 @task + @entrypoint 包装入口，并用 entrypoint.final(value, save) 分离本轮输出与下轮持久状态。
• 未列出的框架也可按同样模式包装 callable，但 Tool/interrupt/streaming 能力取决于原框架和包装层，不能假设与原生 LangGraph 完全一致。

接入验收要覆盖：session/checkpoint 恢复、partial token、Tool error、cancel/interrupt、Trace 父子关系、并发与幂等。

Full-stack Web 的共同协议

Next.js、Nuxt、SvelteKit、Cloudflare Workers、Deno 和 Vite 示例共享 Agent Streaming Protocol：

• POST /api/threads/:threadId/commands 接收 run.start 等命令；
• POST /api/threads/:threadId/stream 返回 SSE；
• GET/POST /api/threads/:threadId/state 读写/初始化状态；
• Sidebar 还需要 Thread 列表、历史与删除路由。

示例的内存 Map、单实例对象或本地文件只适合演示。生产必须选择适配宿主的持久层：Cloudflare 可用 Durable Objects，Vercel/Node 可用外部 Redis/DB，并验证多实例、冷启动和 SSE replay。

框架差异

• Next.js：Route Handler 必须使用 Node runtime，SSE route 需动态执行；Vercel 部署时注意函数超时。
• Nuxt：Nitro 可部署到 Vercel、Netlify 或常驻 Node；不同 preset 的 streaming 行为要实测。
• SvelteKit/Cloudflare：Durable Object class 必须由 Worker module 导出，构建脚本会补充该导出。
• Cloudflare Worker：需 nodejs_compat，Free plan 的 DO 使用 SQLite class migration；访问外部模型受 Worker 限额约束。
• Deno：本地 source upload 不会自动跑云端 build command，CLI 部署前必须先构建 SPA。
• Vite + LangSmith：Agent 在 LangSmith Deployment，静态前端只通过 SDK 访问部署 URL；跨域、终端用户 Auth 和环境变量要单独配置。

生产化检查

1. 明确 Agent 是“嵌入 Web Host”还是“独立 Agent Server”，避免两个后端都维护 Thread。
2. 对 SSE 建立 heartbeat、断线续传、代理 buffering 和最长连接测试。
3. Thread ID 由服务端授权并采用 UUID；客户端给定 ID 不代表拥有该 Thread。
4. 所有协议命令做 schema 校验、幂等和并发策略选择。
5. 演示持久化替换为外部持久层，并验证多实例与恢复。
6. 发布使用 Revision、质量门禁与可观察回滚，不以“构建成功”代替在线验证。