langsmith-deployment

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

LangSmith Deployment

Use this skill to deploy, revise, monitor, and troubleshoot LangGraph-based agents in LangSmith Deployment.

使用本技能在LangSmith Deployment中部署、修订、监控和排查基于LangGraph的Agent。

Use This Skill When

适用场景

You need to deploy a new agent to LangSmith Cloud.
You need to create a new deployment revision from Git changes or env changes.
You need rollback guidance for a failing revision.
You need to choose deployment model: Cloud, Hybrid/Self-hosted with control plane, or Standalone server.
You need CI/CD automation using LangSmith Deployment control-plane APIs.
You need monitoring and alert setup aligned with current LangSmith alert model.
You need
```
langgraph.json
```
validation and deployment compatibility checks.

你需要将新Agent部署到LangSmith Cloud。
你需要基于Git变更或环境变更创建新的部署修订版本。
你需要针对失败的修订版本获取回滚指导。
你需要选择部署模式：云部署、带控制平面的混合/自托管部署，或独立服务器部署。
你需要使用LangSmith Deployment控制平面API实现CI/CD自动化。
你需要按照当前LangSmith告警模型设置监控和告警。
你需要验证
```
langgraph.json
```
并检查部署兼容性。

Deployment Model Selection

部署模式选择

Model	Use when	Build/Source	Operates infra
Cloud	Fastest managed production path	GitHub repo via control plane	LangSmith
Hybrid/Self-hosted with control plane	You need private data plane + centralized deployment UI/API	Container image + control plane	You
Standalone server	You want direct Agent Server hosting without control plane	Containerized server	You

部署模式	适用场景	构建/来源	基础设施运维方
Cloud	最快的托管式生产部署路径	通过控制平面连接GitHub仓库	LangSmith
Hybrid/Self-hosted with control plane	需要私有数据平面 + 集中式部署UI/API	容器镜像 + 控制平面	您方
Standalone server	希望直接托管Agent Server而不使用控制平面	容器化服务器	您方

Core Workflow

核心工作流

Validate local deployment config.
Choose deployment model and endpoint strategy.
Create deployment or revision.
Configure environment variables and secrets correctly.
Configure monitoring and alerts.
Verify runtime behavior and keep rollback path ready.

验证本地部署配置。
选择部署模式和端点策略。
创建部署或修订版本。
正确配置环境变量和密钥。
配置监控和告警。
验证运行时行为并准备好回滚路径。

Script-First Commands

脚本优先命令

1) Validate

langgraph.json

1) 验证

langgraph.json

bash

uv run python skills/langsmith-deployment/scripts/validate_deployment.py --config langgraph.json --target cloud

bash

uv run python skills/langsmith-deployment/scripts/validate_deployment.py --config langgraph.json --target cloud

2) Create a Cloud deployment (US default)

2) 创建Cloud部署（默认美国区域）

bash

uv run python skills/langsmith-deployment/scripts/deploy_to_langsmith.py \
  --name "my-agent-prod" \
  --owner my-org \
  --repo my-agent-repo \
  --branch main \
  --config langgraph.json

bash

uv run python skills/langsmith-deployment/scripts/deploy_to_langsmith.py \
  --name "my-agent-prod" \
  --owner my-org \
  --repo my-agent-repo \
  --branch main \
  --config langgraph.json

3) Create a Cloud deployment (EU)

3) 创建Cloud部署（欧盟区域）

bash

uv run python skills/langsmith-deployment/scripts/deploy_to_langsmith.py \
  --name "my-agent-prod" \
  --owner my-org \
  --repo my-agent-repo \
  --region eu

bash

uv run python skills/langsmith-deployment/scripts/deploy_to_langsmith.py \
  --name "my-agent-prod" \
  --owner my-org \
  --repo my-agent-repo \
  --region eu

4) Use a self-hosted control plane

4) 使用自托管控制平面

bash

uv run python skills/langsmith-deployment/scripts/deploy_to_langsmith.py \
  --name "my-agent-prod" \
  --owner my-org \
  --repo my-agent-repo \
  --control-plane-url https://<your-langsmith-host>/api-host

bash

uv run python skills/langsmith-deployment/scripts/deploy_to_langsmith.py \
  --name "my-agent-prod" \
  --owner my-org \
  --repo my-agent-repo \
  --control-plane-url https://<your-langsmith-host>/api-host

5) Create a revision for an existing deployment

5) 为现有部署创建修订版本

bash

uv run python skills/langsmith-deployment/scripts/deploy_to_langsmith.py \
  --name "my-agent-prod" \
  --owner my-org \
  --repo my-agent-repo \
  --deployment-id <deployment-id> \
  --branch main

bash

uv run python skills/langsmith-deployment/scripts/deploy_to_langsmith.py \
  --name "my-agent-prod" \
  --owner my-org \
  --repo my-agent-repo \
  --deployment-id <deployment-id> \
  --branch main

6) Roll back deployment revision

6) 回滚部署修订版本

bash

uv run python skills/langsmith-deployment/scripts/rollback_deployment.py \
  --deployment-id <deployment-id> \
  --list-revisions

uv run python skills/langsmith-deployment/scripts/rollback_deployment.py \
  --deployment-id <deployment-id>

bash

uv run python skills/langsmith-deployment/scripts/rollback_deployment.py \
  --deployment-id <deployment-id> \
  --list-revisions

uv run python skills/langsmith-deployment/scripts/rollback_deployment.py \
  --deployment-id <deployment-id>

7) Generate monitoring + alert setup plan

7) 生成监控+告警设置方案

bash

uv run python skills/langsmith-deployment/scripts/setup_monitoring.py \
  --project my-agent-prod \
  --output-json /tmp/monitoring-plan.json

Note:

setup_monitoring.py

generates a docs-aligned setup plan/templates. Alerts are configured in LangSmith UI per project.

bash

uv run python skills/langsmith-deployment/scripts/setup_monitoring.py \
  --project my-agent-prod \
  --output-json /tmp/monitoring-plan.json

注意：

setup_monitoring.py

会生成与文档一致的设置方案/模板。告警需在LangSmith UI中按项目配置。

Configuration Rules To Enforce

需遵循的配置规则

```
graphs
```
is required in
```
langgraph.json
```
.
For Python projects,
```
dependencies
```
is required.
For JS projects (
```
node_version
```
present), dependencies may be handled via
```
package.json
```
.
```
env
```
may be either a string path to an env file or an inline object map.
```
python_version
```
should be one of
```
3.11
```
,
```
3.12
```
,
```
3.13
```
when set.
```
pip_installer
```
should be one of
```
auto
```
,
```
pip
```
,
```
uv
```
when set.
```
node_version
```
currently documented for LangGraph.js as
```
20
```
.

```
langgraph.json
```
中必须包含
```
graphs
```
字段。
对于Python项目，必须包含
```
dependencies
```
字段。
对于JS项目（存在
```
node_version
```
），依赖可通过
```
package.json
```
管理。
```
env
```
可以是环境文件的字符串路径，也可以是内联对象映射。
当设置
```
python_version
```
时，必须为
```
3.11
```
、
```
3.12
```
、
```
3.13
```
之一。
当设置
```
pip_installer
```
时，必须为
```
auto
```
、
```
pip
```
、
```
uv
```
之一。
LangGraph.js文档中当前指定的
```
node_version
```
为
```
20
```
。

API/Endpoint Notes

API/端点说明

LangSmith Deployment control-plane API defaults are:
US:
```
https://api.host.langchain.com
```
.
EU:
```
https://eu.api.host.langchain.com
```
.
Self-hosted control-plane base URL is typically
```
https://<host>/api-host
```
.
For org-scoped API keys, include workspace/tenant id (
```
X-Tenant-Id
```
), exposed by scripts as
```
--tenant-id
```
.

LangSmith Deployment控制平面API默认地址：
美国区域：
```
https://api.host.langchain.com
```
。
欧盟区域：
```
https://eu.api.host.langchain.com
```
。
自托管控制平面的基础URL通常为
```
https://<host>/api-host
```
。
对于组织范围的API密钥，需包含工作区/租户ID（
```
X-Tenant-Id
```
），脚本中可通过
```
--tenant-id
```
参数指定。

Secrets And Environment Guidance

密钥与环境配置指南

Never hardcode secrets in
```
langgraph.json
```
or source code.
Prefer environment injection from deployment UI, Kubernetes Secrets, or cloud secret managers.
Avoid passing secrets in shell arguments when possible; prefer
```
LANGSMITH_API_KEY
```
env var.
In control-plane deployment flows, tracing auth env handling differs from standalone; rely on deployment model docs before overriding tracing/auth vars.
For standalone server, ensure required runtime vars are present (
```
DATABASE_URI
```
,
```
REDIS_URI
```
, license key, and any app provider keys).

切勿在
```
langgraph.json
```
或源代码中硬编码密钥。
优先通过部署UI、Kubernetes Secrets或云密钥管理器注入环境变量。
尽可能避免在shell参数中传递密钥；优先使用
```
LANGSMITH_API_KEY
```
环境变量。
在控制平面部署流程中，追踪认证的环境变量处理逻辑与独立部署不同；在覆盖追踪/认证变量前，请参考部署模式文档。
对于独立服务器，确保存在必要的运行时变量（
```
DATABASE_URI
```
、
```
REDIS_URI
```
、许可证密钥以及所有应用提供商密钥）。

Verification After Deploy

部署后验证

Check deployment/revision status in LangSmith Deployments UI.
Verify server API and health endpoints from deployment runtime (
```
/docs
```
etc.).
Run a smoke invocation against your assistant/graph.
Confirm traces, latency, and error metrics in Monitoring dashboards.

在LangSmith Deployments UI中检查部署/修订版本状态。
从部署运行时验证服务器API和健康端点（如
```
/docs
```
等）。
对助手/图执行一次冒烟调用。
在监控仪表盘中确认追踪数据、延迟和错误指标。

References To Load By Task

任务参考文档

```
references/deployment-guide.md
```
: Deployment model choice and end-to-end execution.
```
references/cicd-integration.md
```
: CI/CD stages, control-plane automation patterns, preview/prod strategy.
```
references/environment-management.md
```
: Env var sources, secrets patterns, standalone required vars.
```
references/monitoring-alerts.md
```
: Dashboards, alert model, webhook payload guidance.
```
references/scaling-configuration.md
```
: Scaling responsibilities by model and tuning knobs.

references/troubleshooting-deployment.md

: Failure triage and rollback strategy.

```
references/deployment-guide.md
```
：部署模式选择与端到端执行指南。
```
references/cicd-integration.md
```
：CI/CD阶段、控制平面自动化模式、预发布/生产策略。
```
references/environment-management.md
```
：环境变量来源、密钥管理模式、独立部署所需变量。
```
references/monitoring-alerts.md
```
：仪表盘、告警模型、Webhook负载指南。
```
references/scaling-configuration.md
```
：各部署模式的扩缩容职责与调优选项。

references/troubleshooting-deployment.md

：故障排查与回滚策略。

Script Map

脚本清单

scripts/validate_deployment.py

: Validate

langgraph.json

and deployment readiness.

```
scripts/deploy_to_langsmith.py
```
: Create deployment or revision via control-plane API.
```
scripts/deploy_to_langsmith.ts
```
: TypeScript equivalent deploy/revision script.
```
scripts/rollback_deployment.py
```
: List and rollback revisions.
```
scripts/setup_monitoring.py
```
: Generate alert/dashboard/webhook setup plan.

scripts/validate_deployment.py

：验证

langgraph.json

和部署就绪状态。

```
scripts/deploy_to_langsmith.py
```
：通过控制平面API创建部署或修订版本。
```
scripts/deploy_to_langsmith.ts
```
：TypeScript版本的部署/修订脚本。
```
scripts/rollback_deployment.py
```
：列出并回滚修订版本。
```
scripts/setup_monitoring.py
```
：生成告警/仪表盘/Webhook设置方案。

Assets

资源文件

```
assets/templates/langgraph-cloud.json
```
: Cloud-oriented starter config.
```
assets/templates/github-actions-deploy.yml
```
: CI/CD template for deployment automation.
```
assets/templates/kubernetes-deployment.yaml
```
: Kubernetes template for self-managed environments.
```
assets/templates/.env.example
```
: Env var template for safe sharing.

```
assets/templates/langgraph-cloud.json
```
：面向云部署的初始配置模板。

assets/templates/github-actions-deploy.yml

：用于部署自动化的CI/CD模板。

```
assets/templates/kubernetes-deployment.yaml
```
：用于自托管环境的Kubernetes模板。
```
assets/templates/.env.example
```
：用于安全共享的环境变量模板。

langsmith-deployment

Original

Translation

LangSmith Deployment

LangSmith Deployment

Use This Skill When

适用场景

Deployment Model Selection

部署模式选择

Core Workflow

核心工作流

Script-First Commands

脚本优先命令

1) Validate langgraph.json

1) 验证langgraph.json

2) Create a Cloud deployment (US default)

2) 创建Cloud部署（默认美国区域）

3) Create a Cloud deployment (EU)

3) 创建Cloud部署（欧盟区域）

4) Use a self-hosted control plane

4) 使用自托管控制平面

5) Create a revision for an existing deployment

5) 为现有部署创建修订版本

6) Roll back deployment revision

6) 回滚部署修订版本

7) Generate monitoring + alert setup plan

7) 生成监控+告警设置方案

Configuration Rules To Enforce

需遵循的配置规则

API/Endpoint Notes

API/端点说明

Secrets And Environment Guidance

密钥与环境配置指南

Verification After Deploy

部署后验证

References To Load By Task

任务参考文档

Script Map

脚本清单

Assets

资源文件

1) Validate
`langgraph.json`

1) 验证
`langgraph.json`