---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags: [langchain, langsmith, cli, sdk, packaging, local-development]
topic: Agent 应用打包、CLI/SDK、本地验证与迁移
sources:
  - "https://docs.langchain.com/langsmith/cli"
  - "https://docs.langchain.com/langsmith/create-account-api-key"
  - "https://docs.langchain.com/langsmith/custom-docker"
  - "https://docs.langchain.com/langsmith/custom-endpoint"
  - "https://docs.langchain.com/langsmith/env-var"
  - "https://docs.langchain.com/langsmith/env-var-cloud"
  - "https://docs.langchain.com/langsmith/langgraph-js-ts-sdk"
  - "https://docs.langchain.com/langsmith/langgraph-python-sdk"
  - "https://docs.langchain.com/langsmith/langsmith-cli"
  - "https://docs.langchain.com/langsmith/local-dev-testing"
  - "https://docs.langchain.com/langsmith/monorepo-support"
  - "https://docs.langchain.com/langsmith/profile-configuration"
  - "https://docs.langchain.com/langsmith/self-host-playground-environment-settings"
  - "https://docs.langchain.com/langsmith/serverless-environments"
  - "https://docs.langchain.com/langsmith/setup-app-requirements-txt"
  - "https://docs.langchain.com/langsmith/setup-javascript"
  - "https://docs.langchain.com/langsmith/setup-pyproject"
  - "https://docs.langchain.com/langsmith/smith-deployments-sdk"
  - "https://docs.langchain.com/langsmith/smithdb-sdk-migration"
  - "https://docs.langchain.com/langsmith/studio-deploy"
  - "https://docs.langchain.com/langsmith/troubleshooting-variable-caching"
last_verified: 2026-08-11
---

# 应用打包、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 文本解析。

## 可部署应用契约

最小应用包含：

1. `langgraph.json`：dependencies、graphs、env、可选 http/auth/store/checkpointer；
2. 可导入的 Graph 路径；
3. Python 的 `requirements.txt`/`pyproject.toml`/package，或 JS 的 `package.json`；
4. 运行时环境变量与 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 风险。

## 发布门禁

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