应用打包、CLI/SDK 与本地开发

两套 CLI 不要混淆

工具	用途	典型命令
LangGraph CLI	构建、运行、打包、部署 Agent Server	`dev`、`up`、`build`、`deploy`、`dockerfile`
LangSmith CLI	查询/管理 Project、Trace、Run、Dataset、Evaluator、Thread、Sandbox 与通用 API	`auth login`、`profile`、`traces`、`runs`、`sandbox`

前者围绕运行时镜像和 langgraph.json，后者围绕 LangSmith 数据与管理面。CI 中应固定版本并用 JSON 输出，不要靠 human-readable 文本解析。

可部署应用契约

最小应用包含：

langgraph.json：dependencies、graphs、env、可选 http/auth/store/checkpointer；
可导入的 Graph 路径；
Python 的 requirements.txt/pyproject.toml/package，或 JS 的 package.json；
运行时环境变量与 Secrets。

Python 与 JavaScript 都允许节点内运行任意框架代码；部署要求的是导出兼容 Graph/包装器，不要求业务逻辑全用 LangGraph API。Monorepo 中 langgraph.json 放在 Agent 目录，父级共享包要显式成为构建上下文/Workspace 依赖，避免本地路径在远端镜像缺失。

dockerfile_lines 只适合追加少量系统包。复杂基础镜像、证书、非 root 用户和供应链要求应先用 langgraph dockerfile 生成，再纳入正常镜像评审与扫描。

本地验证阶梯

阶段	`langgraph dev`	`langgraph up`
目标	快速迭代	生产相似验证
Docker	不需要	需要
状态	内存并持久到 `.langgraph_api`	PostgreSQL + Redis
能证明	Graph 可加载、基础 API/Studio 可用	镜像、依赖、网络、持久化更接近生产

建议顺序：单元/Graph 测试 → dev → up → 构建镜像 → 部署预览 Revision → 端到端/评估。dev 成功不证明 Docker 系统依赖、外部数据库、TLS、并发或回滚可用。

studio-deploy 当前会重定向到 /langsmith/studio：Studio 是 Agent IDE，支持 Graph/Chat mode、Thread/Assistant 管理、time travel、实验与一键 Cloud 部署。它是调试入口，不是生产健康检查。

SDK 边界

Python/TypeScript LangGraph SDK 提供 Assistants、Threads、Runs、Crons、Store 与 Auth client；RemoteGraph 让远端 Graph 表现为本地 Graph。Deployment SDK 的同步/异步 Client 是相同 Server API 的封装，生产封装层应保留 request ID、timeout、retry、idempotency 与流式断线恢复。

SmithDB 新查询方法是一次真实迁移，不只是重命名：Run/Trace/Thread 查询的方法、筛选参数、字段选择、分页与异常类型均改变。官方时间线：Cloud 旧端点 2026 年 7 月底 deprecated、2027-01-31 移除；Self-hosted 在 v0.16 deprecated、v0.18 移除。迁移应先盘点旧方法、双跑结果对比，再切换调用与告警。

凭据与 Profile

PAT 继承创建者权限，适合个人脚本；生产服务优先 Workspace/Organization scoped service key。
Profile JSON 可保存 endpoint、workspace、API key 或 OAuth refresh token，必须视为 Secret：不提交、不烘焙镜像、不打印日志，仅从 Secret volume 挂载。
LangSmith CLI OAuth 登录的最低版本为 v0.2.30；self-host OAuth 登录还要求 CLI v0.2.46+、LangSmith v0.16+ 并配置签名 JWKS。
Jupyter/长进程会缓存环境变量；Trace 落错项目时先核对变量，再清 SDK cache 并重新加载，而不是盲目重启生产服务。

Cloud 环境变量页面 env-var 与 env-var-cloud 当前正文完全相同，但两个公开 URL 都是有效入口。配置时仍要区分 Cloud 与 env-var-self-hosted 的额外数据库、挂载和 Redis 参数。

模型与 Playground

自定义模型通过 LangServe 风格的 model server 接入 Playground，并可声明 configurable fields。该方式给 UI 调试用，不等同于生产模型网关：仍需认证、限流、超时、审计和协议兼容测试。

Self-hosted Playground 的 provider 环境变量只注入 playground 服务，commonEnv 不会自动进入它。GKE/EKS 优先 Workload Identity/IRSA，而不是长期云密钥。

Serverless 追踪

JS Serverless 进程可能在后台 Trace flush 前终止。可设置 LANGSMITH_TRACING_BACKGROUND=false，或在返回前 awaitPendingTraceBatches()。高并发时用 manual flush 降低请求数，但必须衡量尾延迟、平台超时和丢 Trace 风险。

发布门禁

固定 CLI、SDK、Agent Server API 版本，并记录兼容矩阵。
在干净容器内验证依赖解析，禁止依赖开发机隐式包或父目录。
dev 与 up 都跑健康、Thread 持久化、stream reconnect、auth 负向测试。
Preview Revision 运行离线评估、迁移兼容与最小真实依赖 smoke test。
Profile/API key 只从 Secret 注入，日志与构建产物执行 Secret scan。
SmithDB 迁移在截止日期前完成调用盘点、字段差异、分页与异常回归。