> ## Documentation Index > Fetch the complete documentation index at: https://cndoc-langchain.site/llms.txt > Use this file to discover all available pages before exploring further. # 使用 CLI 部署 > 使用 Deep Agents CLI 将模型无关的开源智能体部署到生产环境 Deep Agents Deploy 将您的智能体配置部署为 [LangSmith 部署](/langsmith/deployment)：一个可水平扩展的服务器，包含 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 部署可以自托管，因此记忆数据保留在您的基础设施中 Deep Agents Deploy 目前处于测试阶段，需要 `deepagents-cli>=0.0.36`。API、配置格式和行为可能在版本之间发生变化。有关详细的变更日志，请参阅[发布页面](https://github.com/langchain-ai/deepagents/releases)。 ## 与 Claude 托管智能体的比较 | | Deep Agents Deploy | Claude 托管智能体 | | ------------ | -------------------------------------------------------------------------------------------------------------------- | ------------ | | 模型支持 | OpenAI、Anthropic、Google、Bedrock、Azure、Fireworks、Baseten、OpenRouter、[更多](/oss/python/integrations/providers/overview) | 仅限 Anthropic | | 运行时 | 开源 (MIT) | 专有、闭源 | | 沙箱 | LangSmith、Daytona、Modal、Runloop 或[自定义](/oss/python/contributing/implement-langchain#sandboxes) | 内置 | | MCP 支持 | ✅ | ✅ | | 技能支持 | ✅ | ✅ | | AGENTS.md 支持 | ✅ | ❌ | | 智能体端点 | MCP、A2A、Agent Protocol | 专有 | | 自托管 | ✅ | ❌ | ## 您正在部署的内容 `deepagents deploy` 将您的智能体配置打包并部署为 [LangSmith 部署](/langsmith/deployment)。您可以通过几个参数配置您的智能体： | 参数 | 描述 | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | **`model`** | 要使用的 LLM。任何提供商均可——参见[支持的模型](/oss/python/deepagents/models#supported-models)。 | | **`AGENTS.md`** | 系统提示，在每个会话开始时加载。 | | **`skills`** | 用于专业知识和操作的 [Agent Skills](https://agentskills.io/)。技能会同步到沙箱中，以便智能体在运行时执行它们。参见[技能文档](/oss/python/deepagents/skills)。 | | **`user/`** | 每个用户可写的记忆。如果 `user` 文件夹中存在 `AGENTS.md` 模板，智能体会为每个用户初始化该模板（如果文件夹为空，智能体会创建一个空的 `AGENTS.md`）。运行时可写。通过记忆中间件预加载到智能体的上下文中。 | | **`mcp.json`** | MCP 工具 (HTTP/SSE)。参见 [MCP 文档](/oss/python/langchain/mcp)。 | | **`subagents/`** | 主智能体可以委派任务的专用[子智能体](/oss/python/deepagents/subagents)。每个子目录包含自己的 `deepagents.toml`、`AGENTS.md`，以及可选的 `skills` 文件夹。参见[子智能体](#subagents)。 | | **`sandbox`** | 可选的执行环境。线程作用域的沙箱按线程配置，如果服务器重启将重新创建。如果您需要跨线程持久化的沙箱状态，请使用 `scope = "assistant"`。参见[沙箱提供商](#sandbox-providers)。 | | **`frontend`** | 可选的预构建 React 聊天 UI，与智能体一起部署在同一个部署中。可配置为每个用户认证或匿名模式，具有实时待办事项、文件和子智能体活动面板。参见 [`[frontend]`](#frontend)。 | ## 安装 安装 CLI 或直接使用 `uvx` 运行： ```bash uv theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} uv tool install deepagents-cli ``` ```bash uvx (no install) theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} uvx deepagents-cli deploy ``` ## 用法 ```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` 技能 | 初始化后，编辑 `AGENTS.md` 添加您的智能体指令，然后运行 `deepagents deploy`。可选地添加一个 `user/` 目录，其中包含每个用户的记忆模板——参见[用户记忆](#user-memory)。 ## 项目布局 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 ``` | 文件/目录 | 用途 | 是否必需 | | ------------ | -------------------------------------------------------------------------------------------------------------------- | ---- | | `AGENTS.md` | 智能体的[记忆](/oss/python/deepagents/memory)。提供持久化上下文（项目约定、指令、偏好），在启动时始终加载。运行时只读。 | 是 | | `skills/` | [技能](/oss/python/deepagents/skills)定义目录。每个子目录应包含一个 `SKILL.md` 文件。运行时只读。 | 否 | | `user/` | 每个用户可写的记忆。如果 `user` 文件夹中存在 `AGENTS.md` 模板，智能体会为每个用户初始化该模板（如果文件夹为空，智能体会创建一个空的 `AGENTS.md`）。运行时可写。通过记忆中间件预加载到智能体的上下文中。 | 否 | | `subagents/` | 主智能体可以委派任务的[子智能体](#subagents)。每个子目录必须包含 `deepagents.toml`、`AGENTS.md`，以及可选的 `skills` 文件夹。在打包时自动发现。 | 否 | | `mcp.json` | [MCP](https://modelcontextprotocol.io/) 服务器配置。在部署环境中仅支持 `http` 和 `sse` 传输。 | 否 | | `.env` | 环境变量（API 密钥、密钥）。放置在项目根目录的 `deepagents.toml` 旁边。 | 否 | `mcp.json` 必须仅包含使用 `http` 或 `sse` 传输的服务器。使用 `stdio` 传输的服务器在部署环境中不受支持，因为没有本地进程可以生成。 在部署前将 stdio 服务器转换为 HTTP 或 SSE。 ## 配置文件 `deepagents.toml` 配置智能体的身份和沙箱环境。只有 `[agent]` 部分是必需的。`[sandbox]` 部分是可选的，默认为无沙箱。 ### `[agent]` （必需） 核心智能体身份。有关模型选择和提供商配置的更多信息，请参阅[支持的模型](/oss/python/deepagents/models#supported-models)。 部署的智能体的名称。用作 LangSmith 中的助手标识符。 `provider:model` 格式的模型标识符。参见[支持的模型](/oss/python/deepagents/models#supported-models)。 ```toml deepagents.toml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} [agent] name = "research-assistant" model = "google_genai:gemini-3.1-pro-preview" ``` `name` 字段是整个配置文件中唯一必需的值。其他所有内容都有默认值。 技能、用户记忆、子智能体、MCP 服务器和模型依赖项从项目布局中自动检测： * **技能**：打包器递归扫描 `skills/`，跳过隐藏的点文件，并打包其余内容。 * **用户记忆**：如果 `user/` 存在，单个 `AGENTS.md` 将作为每个用户的记忆被打包（如果存在 `user/AGENTS.md`，则使用其内容，否则为空）。在运行时，每个用户获得自己的副本（在首次访问时初始化，永远不会被覆盖）。智能体可以读取和写入此文件。 * **子智能体**：如果 `subagents/` 存在，打包器会扫描有效的子目录（每个必须包含 `deepagents.toml` 和 `AGENTS.md`）。主智能体接收一个 `task` 工具，可以按名称将工作委派给每个子智能体。参见[子智能体](#subagents)。 * **MCP 服务器**：如果 `mcp.json` 存在，它将包含在部署中，并且 [`langchain-mcp-adapters`](https://pypi.org/project/langchain-mcp-adapters/) 将作为依赖项添加。仅支持 HTTP/SSE 传输（stdio 在打包时会被拒绝）。 * **模型依赖项**：`model` 字段中的 `provider:` 前缀决定了所需的 `langchain-*` 包（例如，`google_genai` -> `langchain-google-genai`）。这包括在子智能体配置中指定的模型。 * **沙箱依赖项**：`[sandbox].provider` 值映射到其伴侣包（例如，`daytona` -> `langchain-daytona`）。 ### `[sandbox]` 配置智能体运行代码的隔离执行环境。沙箱提供一个具有文件系统和 shell 访问权限的容器，因此不受信任的代码不会影响主机。有关支持的提供商和高级沙箱配置，请参阅[沙箱](/oss/python/deepagents/sandboxes)。 当省略或设置为 `provider = "none"` 时，沙箱被禁用。如果您需要代码执行或技能脚本执行，则使用沙箱。 沙箱提供商。决定容器在哪里运行。支持的值：`"none"`、`"daytona"`、`"modal"`、`"runloop"`、`"langsmith"`（私有测试版）。有关提供商详情，请参阅[沙箱集成](/oss/python/integrations/sandboxes)。 沙箱环境的提供商特定模板名称。 沙箱容器的基础 Docker 镜像。 沙箱生命周期作用域。`"thread"` 为每个对话创建一个沙箱。`"assistant"` 在同一助手的所有对话之间共享单个沙箱。 **作用域行为：** * `"thread"`（默认）：每个对话获得自己的沙箱。不同的线程获得不同的沙箱，但相同的线程在不同轮次中重用其沙箱。当每个对话应从干净环境开始时使用此选项。 * `"assistant"`：所有对话共享一个沙箱。文件、安装的包和其他状态在对话之间持久化。当智能体维护一个长期工作空间（如克隆的仓库）时使用此选项。 ### `[auth]` 添加 `[auth]` 部分以控制部署的智能体上的身份验证。存在时，打包器会生成一个 `auth.py` 文件并自动连接到部署中。当 `[frontend].enabled = true` 时，`[auth]` 是**必需的**；否则它是可选的（没有它，LangSmith 部署的默认 `x-api-key` 要求适用）。 身份验证提供商。支持的值：`"supabase"`、`"clerk"`、`"anonymous"`。 ```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 ``` 所需的环境变量取决于提供商： | 提供商 | 所需环境变量 | | ----------- | ------------------------------------------------- | | `supabase` | `SUPABASE_URL`、`SUPABASE_PUBLISHABLE_DEFAULT_KEY` | | `clerk` | `CLERK_SECRET_KEY` | | `anonymous` | 无 | 将这些添加到您的 `.env` 文件中，与其他凭据放在一起。打包器在部署时验证所有必需的变量是否存在，如果缺少任何变量，将快速失败并给出清晰的错误信息。 **运行时行为：** * 未认证的请求返回 `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 或匿名（参见下面的 [`[auth]`](#auth)）。 如果为 `true`，则将默认聊天 UI 打包到部署中。 在 UI 标题和浏览器标签页中显示的名称。 在标题中应用名称下方和空状态主图上显示的副标题。用于描述智能体的功能。 当没有消息时在空状态上显示的建议芯片。默认为通用的研究主题集；覆盖以根据您的智能体定制芯片。 ```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", ] ``` **身份验证提供商：** 当 `[frontend].enabled = true` 时，`[auth]` 是必需的。选择以下三种提供商之一： * **Clerk** (`[auth] provider = "clerk"`) —— 每个用户的真实身份验证。每个用户登录；线程和记忆按用户作用域划分。 * **Supabase** (`[auth] provider = "supabase"`) —— 每个用户的真实身份验证。与 Clerk 相同的按用户作用域划分。 * **匿名** (`[auth] provider = "anonymous"`) —— 打包器提供一个宽松的身份验证处理程序，覆盖 LangSmith 部署的默认 `x-api-key` 要求，以便前端可以访问 `/threads`，这意味着任何拥有部署 URL 的人都可以调用 API。前端为每个浏览器分配一个 UUID cookie，并根据它过滤线程选择器（仅 UX 作用域，非安全）。CLI 在推送前需要交互式 `y/N` 确认。 **您将获得：** * 与智能体的流式聊天 * 线程选择器，具有从第一条用户消息自动生成的标题 * 实时待办事项、文件和子智能体活动面板，反映您的深度智能体的实时图状态 * 浅色/深色主题切换，首次加载时遵循操作系统偏好设置，之后保持 * （仅 Clerk / Supabase）登录/注册/登出流程——Clerk 提供其完整小部件（社交登录、密码重置）；Supabase 提供电子邮件/密码以及内置的密码重置流程 **环境变量：** 前端重用 `[auth]` 已经要求的大部分内容。只有 Clerk 需要一个额外的浏览器端密钥。 | 提供商 | 附加变量 | | ---------- | --------------------------------------------------------------------- | | `supabase` | 无——重用 `[auth]` 中的 `SUPABASE_URL` 和 `SUPABASE_PUBLISHABLE_DEFAULT_KEY` | | `clerk` | `CLERK_PUBLISHABLE_KEY`（浏览器端可发布密钥；与 `CLERK_SECRET_KEY` 不同） | **部署后设置：** 部署后，将您的部署 URL 添加到身份验证提供商的仪表板中，以便身份验证重定向返回到应用程序。每个部署 URL 只需执行一次此步骤。 * **Clerk：** 仪表板 → 您的应用程序 → **域** → 添加您的部署主机（例如 `clerk-abc.us.langgraph.app`）。Clerk 开发实例自动将 localhost 加入白名单；生产部署 URL 需要显式加入白名单。 * **Supabase：** 仪表板 → **身份验证** → **URL 配置** → 将 `https:///app/**` 添加到 **重定向 URL**。没有此设置，密码重置和电子邮件确认链接将无法路由回您的应用程序。 ### `.env` 在 `deepagents.toml` 旁边放置一个 `.env` 文件，其中包含您的 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` 头中传递用户的身份验证提供商令牌。 * **`[auth] provider = "anonymous"`** —— 打包器提供一个宽松的身份验证处理程序。API 对任何拥有部署 URL 的人开放。无需头信息。（当部署 `[frontend]` 而没有真实的按用户身份验证时必需。） * **没有 `[auth]` 部分** —— 部署回退到 LangSmith 部署的默认 `x-api-key` 要求。在 `x-api-key` 头中传递您的 LangSmith API 密钥。仅在 `[frontend].enabled` 为 `false` 或未设置时有效。 当 `[auth]` 配置为 `supabase` 或 `clerk` 时，在 `Authorization` 头中传递来自身份验证提供商的令牌： ```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": {}}' ``` ```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() ``` | 提供商 | 获取令牌的位置 | | -------- | ------------------------------------------------------------- | | Supabase | 从 `supabase.auth.getSession()` 获取的 Supabase 会话 `access_token` | | Clerk | 从 `getToken()` 获取的 Clerk 会话令牌 | 每个用户的线程和记忆自动隔离——用户 B 无法看到用户 A 的线程。 ## 沙箱提供商 在 `deepagents.toml` 中设置 `[sandbox].provider`，并将所需的环境变量添加到 `.env`。有关可用提供商，请参阅[沙箱集成](/oss/python/integrations/sandboxes)。有关生命周期模式和 SDK 用法，请参阅[沙箱](/oss/python/deepagents/sandboxes)。 ## 部署端点 部署的服务器公开： * [**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/python/deepagents/human-in-the-loop)：敏感操作的审批门 * [**记忆**](/oss/python/deepagents/memory)：短期和长期记忆访问 ## 示例 一个具有每个用户偏好的内容写作智能体，智能体可以更新这些偏好： ```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 ``` ## 用户记忆 用户记忆为每个用户提供自己的可写 `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` | 否 | 共享（助手作用域） | | `/memories/skills/**` | 否 | 共享（助手作用域） | | `/memories/user/**` | 是 | 每个用户（`user_id` 作用域） | | `/memories/subagents//**` | 仅限子智能体 | 每个子智能体（隔离） | ### 用户身份 `user_id` 通过 `runtime.user.identity` 从自定义身份验证中解析。平台自动注入已认证用户的身份——无需通过 `configurable` 传递。如果没有已认证用户，该调用将优雅地跳过用户记忆功能。 ## 子智能体 子智能体允许主智能体将专门任务委派给隔离的子智能体。每个子智能体有自己的系统提示、可选技能和可选 MCP 工具。主智能体接收一个 `task` 工具，可以按名称将工作分派给子智能体。 有关子智能体为何有用以及它们在 SDK 级别如何工作的背景信息，请参阅[子智能体](/oss/python/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 会被拒绝） | ### 子智能体配置 子智能体的唯一标识符。必须在所有子智能体中唯一。 此子智能体的功能。主智能体使用此信息来决定何时委派。必须非空。 `provider:model` 格式的模型覆盖。省略以继承主智能体的模型。 ```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" ``` ### 继承 子智能体默认从主智能体继承一些属性： | 属性 | 继承 | 备注 | | -- | -- | --------------------------------------- | | 模型 | 是 | 在子智能体的 `deepagents.toml` 中使用 `model` 覆盖 | | 工具 | 是 | 通过在子智能体目录中添加 `mcp.json` 覆盖 | | 技能 | 否 | 在子智能体自己的 `skills/` 目录中显式声明 | ### 记忆隔离 每个子智能体在 `/memories/subagents//` 获得一个专用的、隔离的记忆命名空间。子智能体的 `AGENTS.md` 和技能在部署时初始化到此命名空间中。 | 路径 | 主智能体 | 子智能体 | | ------------------------------- | ----- | ----- | | `/memories/AGENTS.md` | 读 | 无访问权限 | | `/memories/skills/**` | 读 | 无访问权限 | | `/memories/user/**` | 读 + 写 | 无访问权限 | | `/memories/subagents//**` | 读 | 读 + 写 | ### 示例 一个将研究委派给专门子智能体的上市策略智能体： ```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 服务器公开自定义工具逻辑。 ***
[将这些文档](/use-these-docs)通过 MCP 连接到 Claude、VSCode 等，以获取实时答案。 [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/oss/deepagents/deploy.mdx) 或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。