使用 CLI 部署 - Docs by LangChain

deepagents deploy 获取你的智能体配置和文件，并将它们作为 LangSmith 部署一起部署。 LangSmith 部署是具有 30 多个端点的水平可扩展服务器，包括 MCP、A2A、Agent Protocol、人机协作和记忆 API。基于开放标准构建：

开源引擎：MIT 许可证，适用于 Python 和 TypeScript
AGENTS.md：智能体指令的开放标准
Agent Skills：智能体知识和操作的开放标准
任何模型，任何沙箱：无供应商锁定
开放协议：MCP、A2A、Agent Protocol
可自托管：LangSmith 部署可以自托管，因此记忆保留在你的基础设施中

深度智能体部署目前处于测试阶段，需要 deepagents-cli>=0.0.36。API、配置格式和行为可能在不同版本之间发生变化。请参阅发布页面了解详细更新日志。

与 Claude Managed Agents 对比

	深度智能体部署	Claude Managed Agents
模型支持	OpenAI、Anthropic、Google、Bedrock、Azure、Fireworks、Baseten、OpenRouter、更多	仅 Anthropic
引擎	开源（MIT）	专有，闭源
沙箱	LangSmith、Daytona、Modal、Runloop 或自定义	内置
MCP 支持	✅	✅
技能支持	✅	✅
AGENTS.md 支持	✅	❌
智能体端点	MCP、A2A、Agent Protocol	专有
自托管	✅	❌

安装

安装 CLI 或直接使用 uvx 运行：

uv tool install deepagents-cli

用法

deepagents init [name] [--force]                                             # 创建新项目脚手架
deepagents dev  [--config deepagents.toml] [--port 2024] [--allow-blocking]  # 打包并本地运行
deepagents deploy [--config deepagents.toml] [--dry-run]                     # 打包并部署

默认情况下，deepagents deploy 在当前目录查找 deepagents.toml。传递 --config 使用不同路径：

deepagents deploy --config path/to/deepagents.toml

deepagents deploy 每次调用都会完全重建并创建新的修订版本。使用 deepagents dev 进行本地迭代。

`deepagents init`

创建新智能体项目脚手架：

deepagents init my-agent

这会创建以下文件：

文件	用途
`deepagents.toml`	智能体配置——名称、模型、可选沙箱
`AGENTS.md`	会话启动时加载的系统提示词
`.env`	API 密钥模板（`GOOGLE_API_KEY`、`LANGSMITH_API_KEY` 等）
`mcp.json`	MCP 服务器配置（默认为空）
`skills/`	Agent Skills 目录，包含一个示例 `review` 技能

初始化后，编辑你的项目文件并运行 deepagents deploy。

设置

部署命令使用以下项目布局。将以下文件放在 deepagents.toml 旁边，它们会被自动发现并部署：

my-agent/
├── deepagents.toml
├── AGENTS.md
├── .env
├── mcp.json
├── skills/
│   ├── code-review/
│   │   └── SKILL.md
│   └── data-analysis/
│       └── SKILL.md
├── subagents/
│   └── researcher/
│       ├── deepagents.toml
│       └── AGENTS.md
└── user/
    └── AGENTS.md

文件	描述
`deepagents.toml`	必需。配置智能体的身份、身份验证、沙箱环境以及预构建前端 React 聊天 UI 的部署。
`AGENTS.md`	必需。智能体的记忆。提供在启动时始终加载的持久上下文（项目约定、指令、偏好）。运行时只读。
`skills/`	可选。提供专业工作流和领域知识的技能定义目录。每个子目录应包含一个 `SKILL.md` 文件。运行时只读。上传时跳过点文件。
`user/`	可选。每用户可写记忆。如果 `user` 文件夹中存在 `AGENTS.md` 模板，智能体会为每个用户播种该模板（如果文件夹为空，智能体会创建一个空的 `AGENTS.md`）。智能体可以读取和写入此文件。通过记忆中间件预加载到智能体的上下文中。
`mcp.json`	可选。MCP 工具（HTTP/SSE）。如果 `mcp.json` 存在，它将包含在部署中，并且 `langchain-mcp-adapters` 将作为依赖项添加。参见 MCP (LangChain) 了解更多信息。 `mcp.json` 必须只包含使用 `http` 或 `sse` 传输的服务器。使用 `stdio` 传输的服务器在部署环境中不受支持，因为没有本地进程可以启动。部署前请将 stdio 服务器转换为 HTTP 或 SSE。
`subagents/`	可选。主智能体可以委派任务的专门子智能体。每个子目录必须包含 `deepagents.toml`、`AGENTS.md`，以及可选的 `skills` 文件夹。在打包时自动发现。
`.env`	可选。环境变量（API 密钥、密钥）。放在项目根目录的 `deepagents.toml` 旁边。参见环境变量。

配置文件

deepagents.toml 配置智能体的身份和沙箱环境。只有 [agent] 部分是必需的。[sandbox] 部分是可选的，默认无沙箱。

字段	类型	描述
`[agent]`	Object	必需。核心智能体身份（名称和模型）。
`[sandbox]`	Object	可选。配置智能体运行代码的隔离执行环境。默认无沙箱。
`[auth]`	Object	可选。配置已部署智能体的身份验证。当 `[frontend].enabled = true` 时必需。
`[frontend]`	Object	可选。启用和配置内置的聊天 UI 前端。

`[agent]`

配置核心智能体身份：

deepagents.toml

[agent]
name = "research-assistant"
description = "Researches market trends, competitors, and target audiences"
model = "google_genai:gemini-3.1-pro-preview"

字段	类型	描述
`name`	`string`	必需。已部署智能体的名称。在 LangSmith 中用作助手标识符。
`description`	`string`	可选。智能体功能的人类可读描述。
`model`	`string`	可选。`provider:model` 格式的模型标识符。参见支持的模型。`model` 字段中的 `provider:` 前缀决定所需的 `langchain-*` 包（例如 `google_genai` -> `langchain-google-genai`），该包会自动包含在部署中。这也包括子智能体配置中指定的模型。如果省略，默认使用基于凭据的模型（依次尝试 `openai:gpt-5.2`、`anthropic:claude-sonnet-4-6`、`google_genai:gemini-3.1-pro-preview`、`google_vertexai:gemini-3.1-pro-preview`、`nvidia:nvidia/nemotron-3-super-120b-a12b`）。

`[sandbox]`

配置智能体运行代码的隔离执行环境。沙箱提供带有文件系统和 shell 访问的容器，因此不受信任的代码不会影响主机。有关支持的提供商和高级沙箱配置，请参阅沙箱。

deepagents.toml

[sandbox]
provider = "langsmith"
template = "coding-agent"
image = "python:3.12"

字段	类型	描述
`provider`	`string`	可选。沙箱提供商。支持的值：`"none"`、`"daytona"`、`"modal"`、`"runloop"`、`"langsmith"`（私有测试版）。相关合作伙伴包会自动包含在部署中。参见沙箱集成了解提供商详情。默认为 `"none"`。省略或设置为 `provider = "none"` 时，沙箱被禁用。
`template`	`string`	可选。沙箱环境的提供商特定模板名称。默认为 `"deepagents-deploy"`。
`image`	`string`	可选。沙箱容器的基础 Docker 镜像。默认为 `"python:3"`。
`scope`	`string`	可选。沙箱生命周期范围。默认为 `"thread"`。`"thread"` 为每个对话创建一个沙箱。`"assistant"` 为同一助手的所有对话共享一个沙箱。

范围行为：

"thread"（默认）：每个对话获得自己的沙箱。不同线程获得不同的沙箱，但同一线程在不同轮次间复用其沙箱。当每个对话应以全新环境开始时使用此选项。
"assistant"：所有对话共享一个沙箱。文件、已安装的包和其他状态在对话之间持久化。当智能体维护长期工作空间（如克隆的仓库）时使用此选项。

`[auth]`

添加 [auth] 部分以配置已部署智能体的身份验证。当 [frontend].enabled = true 时 [auth] 是必需的；否则是可选的（没有它，LangSmith 部署默认的 x-api-key 要求适用）。

deepagents.toml

[agent]
name = "my-agent"
model = "google-genai:gemini-3.1-pro-preview"

[auth]
provider = "supabase"   # supabase | clerk | anonymous

字段	类型	描述
`provider`	`string`	必需。身份验证提供商。支持的值：`"supabase"`、`"clerk"`、`"anonymous"`。

选择三个提供商之一：

Clerk（[auth] provider = "clerk"）——每用户真实身份验证。每个用户登录；线程和记忆按用户隔离。
Supabase（[auth] provider = "supabase"）——每用户真实身份验证。与 Clerk 相同的每用户隔离。
Anonymous（[auth] provider = "anonymous"）——打包器附带一个宽松的身份验证处理程序，覆盖 LangSmith 部署默认的 x-api-key 要求，以便前端可以访问 /threads，这意味着任何拥有部署 URL 的人都可以调用 API。前端为每个浏览器分配 UUID cookie 并按此过滤线程选择器（仅 UX 隔离，非安全性）。CLI 在推送前需要交互式 y/N 确认。

根据你的提供商，将以下凭据添加到 .env 中，与其他凭据一起：

提供商	必需的环境变量
`supabase`	`SUPABASE_URL`、`SUPABASE_PUBLISHABLE_DEFAULT_KEY`
`clerk`	`CLERK_SECRET_KEY`
`anonymous`	无

运行时行为：

未认证的请求返回 401。
成功后，已认证用户的身份被注入到 config.configurable.langgraph_auth_user_id 中。
所有资源（线程、运行、存储）通过 metadata.owner 自动按用户隔离。
LangSmith Studio 在本地开发时跳过身份验证。

有关如何进行身份验证的信息，请参阅身份验证。

`[frontend]`

前端部署需要 deepagents-cli>=0.0.43。

可选启用 [frontend] 以在同一部署中随智能体一起发布预构建的 React 聊天 UI。前端挂载在部署 URL 的 /app 上；你的 LangGraph API 保持在根路径（/threads、/runs、/assistants）。前端提供：

与智能体的流式输出聊天
带有从第一条用户消息自动生成标题的线程选择器
反映深度智能体实时图状态的实时待办事项、文件和子智能体活动面板
首次加载时跟随操作系统偏好的亮/暗主题切换，之后持久化
（仅 Clerk / Supabase）登录/注册/退出流程——Clerk 附带完整组件（社交登录、密码重置）；Supabase 附带电子邮件/密码和内置密码重置流程

每个前端使用三种身份验证提供商之一——Clerk、Supabase 或匿名（参见 [auth]）。

deepagents.toml

[agent]
name = "my-agent"
model = "anthropic:claude-sonnet-4-6"

[auth]
provider = "supabase"   # 或 "clerk"

[frontend]
enabled = true
app_name = "My Agent"
subtitle = "Your AI research assistant"
prompts = [
  "Summarize this paper",
  "Find related work",
  "Draft an outline",
]

字段	类型	描述
`enabled`	`boolean`	可选。如果为 `true`，将默认聊天 UI 打包到部署中。默认为 `false`。
`app_name`	`string`	可选。在 UI 头部和浏览器标签中显示的名称。默认为 `[agent].name`。
`subtitle`	`string`	可选。在头部应用名称下方和空状态主页显示的副标题。用来描述智能体的功能。默认为 `"Your deep agent, deployed."`。
`prompts`	`string[]`	可选。在没有消息时的空状态中显示的建议标签。默认为通用研究主题集；覆盖以定制适合你的智能体的标签。

环境变量： 前端复用 [auth] 已经需要的大部分内容。只有 Clerk 需要一个额外的面向浏览器的密钥。

提供商	额外变量
`supabase`	无——复用 `[auth]` 中的 `SUPABASE_URL` 和 `SUPABASE_PUBLISHABLE_DEFAULT_KEY`
`clerk`	`CLERK_PUBLISHABLE_KEY`（面向浏览器的可公开密钥；与 `CLERK_SECRET_KEY` 不同）

部署后设置： 部署后，将你的部署 URL 添加到身份验证提供商的仪表板中，以便身份验证重定向回到应用。这是每个部署 URL 的一次性步骤。

Clerk： 仪表板 → 你的应用 → Domains → 添加你的部署主机（例如 clerk-abc.us.langgraph.app）。Clerk 开发实例自动白名单 localhost；生产部署 URL 需要显式白名单。
Supabase： 仪表板 → Authentication → URL Configuration → 将 https://<your-deployment>/app/** 添加到 Redirect URLs。没有这个，密码重置和电子邮件确认链接不会路由回你的应用。

环境变量

将 .env 文件放在 deepagents.toml 旁边，包含你的 API 密钥：

# 必需——模型提供商密钥
ANTHROPIC_API_KEY=sk-...
OPENAI_API_KEY=sk-...
# ...等

# 部署和 LangSmith 沙箱必需
LANGSMITH_API_KEY=lsv2_...

# 可选——沙箱提供商密钥
DAYTONA_API_KEY=...
MODAL_TOKEN_ID=...
MODAL_TOKEN_SECRET=...
RUNLOOP_API_KEY=...

# [auth] provider = "supabase" 时必需
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_PUBLISHABLE_DEFAULT_KEY=eyJhbGc...

# [auth] provider = "clerk" 时必需
CLERK_SECRET_KEY=sk_test_...

# [frontend].enabled = true 且 [auth] provider = "clerk" 时必需
CLERK_PUBLISHABLE_KEY=pk_test_...

身份验证

运行时的身份验证姿态取决于 [auth]：

[auth] provider = "supabase" 或 "clerk" —— 每用户真实身份验证。在 Authorization 请求头中传递用户的身份验证提供商 Token。
[auth] provider = "anonymous" —— 打包器附带宽松的身份验证处理程序。API 对任何拥有部署 URL 的人开放。无需请求头。（在没有真实每用户身份验证的情况下发布 [frontend] 时必需。）
没有 [auth] 部分 —— 部署回退到 LangSmith 部署默认的 x-api-key 要求。在 x-api-key 请求头中传递你的 LangSmith API 密钥。仅在 [frontend].enabled 为 false 或未设置时有效。

当 [auth] 配置为 supabase 或 clerk 时，在 Authorization 请求头中传递来自你的身份验证提供商的 Token：

curl
Python (langgraph-sdk)

curl -X POST https://your-deployment-url/threads \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {}}'

from langgraph_sdk import get_client

client = get_client(
    url="https://your-deployment-url",
    headers={"Authorization": "Bearer YOUR_ACCESS_TOKEN"},
)

thread = await client.threads.create()

提供商	获取 Token 的位置
Supabase	来自 `supabase.auth.getSession()` 的 Supabase 会话 `access_token`
Clerk	来自 `getToken()` 的 Clerk 会话 Token

每个用户的线程和记忆自动隔离——用户 B 无法看到用户 A 的线程。

部署端点

已部署的服务器暴露：

MCP：将你的智能体作为工具从其他智能体调用
A2A：通过 A2A 协议进行多智能体编排
Agent Protocol：用于构建 UI 的标准 API
人机协作：敏感操作的审批门控
记忆：短期和长期记忆访问

用户记忆

用户记忆为每个用户提供自己的可写 AGENTS.md，在对话之间持久化。要启用它，在项目根目录创建 user/ 目录：

user/
└── AGENTS.md          # 可选——如果未提供则播种为空

如果 user/ 目录存在（即使为空），每个用户都会在 /memories/user/AGENTS.md 获得自己的 AGENTS.md。如果你提供了 user/AGENTS.md，其内容将用作初始模板；否则播种一个空文件。在运行时，用户记忆通过自定义身份验证（runtime.server_info.user.identity）按用户隔离。用户第一次与智能体交互时，其命名空间用模板播种。后续交互复用现有文件——智能体的编辑会持久化，重新部署不会覆盖用户数据。

工作原理

打包时 —— 打包器读取 user/AGENTS.md（或使用空字符串）并将其包含在播种负载中。
运行时（首次访问） —— 当智能体首次看到一个 user_id 时，它将 AGENTS.md 模板写入该用户命名空间下的存储。现有条目永远不会被覆盖。
预加载 —— 用户 AGENTS.md 传递给记忆中间件，因此智能体在每次对话开始时都能在上下文中看到其内容。
可写 —— 智能体可以使用 edit_file 工具更新它。共享的 AGENTS.md 文件和技能文件夹是只读的。

权限

路径	可写	作用域
`/memories/AGENTS.md`	否	共享（assistant 范围）
`/memories/skills/**`	否	共享（assistant 范围）
`/memories/user/**`	是	每用户（`user_id` 范围）
`/memories/subagents/<name>/**`	仅子智能体	每子智能体（隔离）

用户身份

user_id 通过自定义身份验证从 runtime.user.identity 解析。平台自动注入已认证用户的身份——无需通过 configurable 传递。如果没有已认证用户，该次调用的用户记忆功能会被优雅地跳过。

子智能体

子智能体让主智能体将专门任务委派给隔离的子智能体。每个子智能体有自己的系统提示词、可选技能和可选 MCP 工具。主智能体收到一个 task 工具，按名称将工作分派给子智能体。有关子智能体为何有用以及它们在 SDK 级别如何工作的背景，请参阅子智能体。

目录结构

在项目根目录创建 subagents/ 目录。每个子目录是一个子智能体：

my-agent/
├── deepagents.toml
├── AGENTS.md
└── subagents/
    ├── researcher/
    │   ├── deepagents.toml       # 名称、描述、可选的模型覆盖
    │   ├── AGENTS.md             # 子智能体系统提示词
    │   ├── skills/               # 可选——子智能体特定技能
    │   │   └── analyze-market/
    │   │       └── SKILL.md
    │   └── mcp.json              # 可选——HTTP/SSE MCP 工具
    └── writer/
        ├── deepagents.toml
        └── AGENTS.md

每个子智能体子目录必须包含：

文件	用途
`deepagents.toml`	包含 `[agent].name` 和 `[agent].description` 的子智能体配置
`AGENTS.md`	子智能体的系统提示词

每个子智能体子目录可以包含：

文件	用途
`skills/`	子智能体特定技能（包含 `SKILL.md` 文件）
`mcp.json`	MCP 服务器配置（仅 HTTP/SSE；stdio 会被拒绝）

子智能体配置

subagents/researcher/deepagents.toml

[agent]
name = "researcher"
description = "Researches market trends, competitors, and target audiences"
model = "google_genai:gemini-3.1-pro-preview"

字段	类型	描述
`name`	`string`	必需。子智能体的唯一标识符。必须在所有子智能体中唯一。
`description`	`string`	必需。此子智能体的功能描述。主智能体使用此描述来决定何时委派任务。必须非空。
`model`	`string`	可选。`provider:model` 格式的模型覆盖。省略以继承主智能体的模型。

继承

子智能体默认从主智能体继承某些属性：

属性	是否继承	备注
模型	是	在子智能体的 `deepagents.toml` 中使用 `model` 覆盖
工具	是	通过在子智能体目录中添加 `mcp.json` 来覆盖
技能	否	在子智能体自己的 `skills/` 目录中显式声明

记忆隔离

每个子智能体在 /memories/subagents/<name>/ 获得专用的隔离记忆命名空间。子智能体的 AGENTS.md 和技能在部署时播种到此命名空间中。

路径	主智能体	子智能体
`/memories/AGENTS.md`	读取	无访问权
`/memories/skills/**`	读取	无访问权
`/memories/user/**`	读取 + 写入	无访问权
`/memories/subagents/<name>/**`	读取	读取 + 写入

示例

一个将研究委派给专门子智能体的 GTM 策略智能体：

deepagents.toml

[agent]
name = "gtm-strategist"
model = "google_genai:gemini-3.1-pro-preview"

subagents/researcher/deepagents.toml

[agent]
name = "researcher"
description = "Researches market trends, competitors, and target audiences to inform GTM strategy"
model = "google_genai:gemini-3.1-pro-preview"

subagents/researcher/AGENTS.md

# Market Researcher

You are a market research specialist. Your job is to gather and synthesize
market data to support go-to-market decisions.

## Focus Areas
- Market sizing: TAM, SAM, SOM estimates
- Competitor analysis: product positioning, pricing, market share
- Audience segmentation: demographics, psychographics, buying behavior

限制

MCP：仅 HTTP/SSE。 stdio 传输在打包时被拒绝。
无自定义 Python 工具。 使用 MCP 服务器暴露自定义工具逻辑。

示例

带有每用户偏好的内容写作智能体，智能体可以更新这些偏好：

deepagents.toml

[agent]
name = "deepagents-deploy-content-writer"
model = "google_genai:gemini-3.1-pro-preview"

my-content-writer/
├── deepagents.toml
├── AGENTS.md
├── skills/
│   ├── blog-post/SKILL.md
│   └── social-media/SKILL.md
└── user/
    └── AGENTS.md          # 可写——智能体学习用户偏好

带有 LangSmith 沙箱用于运行代码的编码智能体：

deepagents.toml

[agent]
name = "deepagents-deploy-coding-agent"
model = "google_genai:gemini-3.1-pro-preview"

[sandbox]
provider = "langsmith"
template = "coding-agent"
image = "python:3.12"

将研究委派给子智能体的 GTM 策略智能体：

my-gtm-agent/
├── deepagents.toml
├── AGENTS.md
├── skills/
│   └── competitor-analysis/
│       └── SKILL.md
└── subagents/
    └── market-researcher/
        ├── deepagents.toml
        ├── AGENTS.md
        └── skills/
            └── analyze-market/
                └── SKILL.md

匿名模式下带有内置 UI 的轻量级内部演示智能体（无需注册，无需基础设施）：

deepagents.toml

[agent]
name = "internal-demo"
model = "anthropic:claude-sonnet-4-6"

[auth]
provider = "anonymous"   # API 对任何拥有 URL 的人开放——部署时确认

[frontend]
enabled = true

将这些文档连接到 Claude、VSCode 等，通过 MCP 获取实时答案。

在 GitHub 上编辑此页面或提交 issue。

Documentation Index

​与 Claude Managed Agents 对比

​安装

​用法

​deepagents init

​设置

​配置文件

​[agent]

​[sandbox]

​[auth]

​[frontend]

​环境变量

​身份验证

​部署端点

​用户记忆

​工作原理

​权限

​用户身份

​子智能体

​目录结构

​子智能体配置

​继承

​记忆隔离

​示例

​限制

​示例

与 Claude Managed Agents 对比

安装

用法

`deepagents init`

设置

配置文件

`[agent]`

`[sandbox]`

`[auth]`

`[frontend]`

环境变量

身份验证

部署端点

用户记忆

工作原理

权限

用户身份

子智能体

目录结构

子智能体配置

继承

记忆隔离

示例

限制

示例