> ## Documentation Index
> Fetch the complete documentation index at: https://nvd-54.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 CLI 部署

> 使用深度智能体 CLI 将模型无关的开源智能体部署到生产环境

`deepagents deploy` 获取你的智能体配置和文件，并将它们作为 [LangSmith 部署](/langsmith/deployment)一起部署。

LangSmith 部署是具有 30 多个端点的水平可扩展服务器，包括 MCP、A2A、Agent Protocol、人机协作和记忆 API。基于开放标准构建：

* **开源引擎**：MIT 许可证，适用于 [Python](https://github.com/langchain-ai/deepagents) 和 [TypeScript](https://github.com/langchain-ai/deepagentsjs)
* **[AGENTS.md](https://agents.md/)**：智能体指令的开放标准
* **[Agent Skills](https://agentskills.io/)**：智能体知识和操作的开放标准
* **任何模型，任何沙箱**：无供应商锁定
* **开放协议**：[MCP](https://modelcontextprotocol.io/docs/getting-started/intro)、[A2A](https://a2a-protocol.org/latest/)、[Agent Protocol](https://github.com/langchain-ai/agent-protocol)
* **可自托管**：LangSmith 部署可以自托管，因此记忆保留在你的基础设施中

<Warning>
  深度智能体部署目前处于测试阶段，需要 `deepagents-cli>=0.0.36`。API、配置格式和行为可能在不同版本之间发生变化。请参阅[发布页面](https://github.com/langchain-ai/deepagents/releases)了解详细更新日志。
</Warning>

## 与 Claude Managed Agents 对比

|              | 深度智能体部署                                                                                                                  | Claude Managed Agents |
| ------------ | ------------------------------------------------------------------------------------------------------------------------ | --------------------- |
| 模型支持         | OpenAI、Anthropic、Google、Bedrock、Azure、Fireworks、Baseten、OpenRouter、[更多](/oss/javascript/integrations/providers/overview) | 仅 Anthropic           |
| 引擎           | 开源（MIT）                                                                                                                  | 专有，闭源                 |
| 沙箱           | LangSmith、Daytona、Modal、Runloop 或[自定义](/oss/javascript/contributing/implement-langchain#sandboxes)                       | 内置                    |
| MCP 支持       | ✅                                                                                                                        | ✅                     |
| 技能支持         | ✅                                                                                                                        | ✅                     |
| AGENTS.md 支持 | ✅                                                                                                                        | ❌                     |
| 智能体端点        | MCP、A2A、Agent Protocol                                                                                                   | 专有                    |
| 自托管          | ✅                                                                                                                        | ❌                     |

## 安装

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

<CodeGroup>
  ```bash uv theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  uv tool install deepagents-cli
  ```

  ```bash uvx（无需安装） theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  uvx deepagents-cli deploy
  ```
</CodeGroup>

## 用法

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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` 使用不同路径：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
deepagents deploy --config path/to/deepagents.toml
```

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

### `deepagents init`

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

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
deepagents init my-agent
```

这会创建以下文件：

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

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

## 设置

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

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

## 配置文件

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

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

### `[agent]`

配置核心智能体身份：

```toml deepagents.toml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
[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` 格式的模型标识符。参见[支持的模型](/oss/javascript/deepagents/models#supported-models)。`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 访问的容器，因此不受信任的代码不会影响主机。有关支持的提供商和高级沙箱配置，请参阅[沙箱](/oss/javascript/deepagents/sandboxes)。

```toml deepagents.toml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
[sandbox]
provider = "langsmith"
template = "coding-agent"
image = "python:3.12"
```

| 字段         | 类型       | 描述                                                                                                                                                                                                        |
| ---------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider` | `string` | *可选*。沙箱提供商。支持的值：`"none"`、`"daytona"`、`"modal"`、`"runloop"`、`"langsmith"`（私有测试版）。相关合作伙伴包会自动包含在部署中。参见[沙箱集成](/oss/javascript/integrations/sandboxes)了解提供商详情。默认为 `"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` 要求适用）。

```toml deepagents.toml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
[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 在本地开发时跳过身份验证。

有关如何进行身份验证的信息，请参阅[身份验证](#authentication)。

### `[frontend]`

<Note>
  前端部署需要 `deepagents-cli>=0.0.43`。
</Note>

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

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

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

```toml deepagents.toml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
[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 密钥：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# 必需——模型提供商密钥
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：

<Tabs>
  <Tab title="curl">
    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    curl -X POST https://your-deployment-url/threads \
      -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"metadata": {}}'
    ```
  </Tab>

  <Tab title="Python (langgraph-sdk)">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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()
    ```
  </Tab>
</Tabs>

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

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

## 部署端点

已部署的服务器暴露：

* [**MCP**](https://modelcontextprotocol.io/docs/getting-started/intro)：将你的智能体作为工具从其他智能体调用
* [**A2A**](https://a2a-protocol.org/latest/)：通过 A2A 协议进行多智能体编排
* [**Agent Protocol**](https://github.com/langchain-ai/agent-protocol)：用于构建 UI 的标准 API
* [**人机协作**](/oss/javascript/deepagents/human-in-the-loop)：敏感操作的审批门控
* [**记忆**](/oss/javascript/deepagents/memory)：短期和长期记忆访问

## 用户记忆

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

```txt theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
user/
└── AGENTS.md          # 可选——如果未提供则播种为空
```

如果 `user/` 目录存在（即使为空），每个用户都会在 `/memories/user/AGENTS.md` 获得自己的 `AGENTS.md`。如果你提供了 `user/AGENTS.md`，其内容将用作初始模板；否则播种一个空文件。

在运行时，用户记忆通过自定义身份验证（`runtime.server_info.user.identity`）按用户隔离。用户第一次与智能体交互时，其命名空间用模板播种。后续交互复用现有文件——智能体的编辑会持久化，重新部署不会覆盖用户数据。

### 工作原理

1. **打包时** —— 打包器读取 `user/AGENTS.md`（或使用空字符串）并将其包含在播种负载中。
2. **运行时（首次访问）** —— 当智能体首次看到一个 `user_id` 时，它将 `AGENTS.md` 模板写入该用户命名空间下的存储。现有条目永远不会被覆盖。
3. **预加载** —— 用户 `AGENTS.md` 传递给记忆中间件，因此智能体在每次对话开始时都能在上下文中看到其内容。
4. **可写** —— 智能体可以使用 `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 级别如何工作的背景，请参阅[子智能体](/oss/javascript/deepagents/subagents)。

### 目录结构

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

```txt theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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 会被拒绝） |

### 子智能体配置

```toml subagents/researcher/deepagents.toml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
[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 策略智能体：

```toml deepagents.toml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
[agent]
name = "gtm-strategist"
model = "google_genai:gemini-3.1-pro-preview"
```

```toml subagents/researcher/deepagents.toml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
[agent]
name = "researcher"
description = "Researches market trends, competitors, and target audiences to inform GTM strategy"
model = "google_genai:gemini-3.1-pro-preview"
```

```markdown subagents/researcher/AGENTS.md theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# 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 服务器暴露自定义工具逻辑。

## 示例

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

```toml deepagents.toml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
[agent]
name = "deepagents-deploy-content-writer"
model = "google_genai:gemini-3.1-pro-preview"
```

```txt theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
my-content-writer/
├── deepagents.toml
├── AGENTS.md
├── skills/
│   ├── blog-post/SKILL.md
│   └── social-media/SKILL.md
└── user/
    └── AGENTS.md          # 可写——智能体学习用户偏好
```

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

```toml deepagents.toml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
[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 策略智能体：

```txt theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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 的轻量级内部演示智能体（无需注册，无需基础设施）：

```toml deepagents.toml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
[agent]
name = "internal-demo"
model = "anthropic:claude-sonnet-4-6"

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

[frontend]
enabled = true
```

***

<div className="source-links">
  <Callout icon="terminal-2">
    [将这些文档连接](/use-these-docs)到 Claude、VSCode 等，通过 MCP 获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/oss/deepagents/deploy.mdx)或[提交 issue](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>
