该 deepagents CLI，可从 deepagents-cli 包安装，提供用于 托管深度代理的部署工具。使用它来搭建本地代理项目、将其部署到 LangSmith、管理托管深度代理资源以及注册 MCP 服务器。

如需最快的端到端路径，请参阅 快速入门。如需工作流指南，请参阅 连接工具, 部署代理，以及 运行代理.

要求

安装 deepagents-cli 使用 uv （首选）或 pip:

uv tool install "deepagents-cli>=0.2.2"

pip install -U "deepagents-cli>=0.2.2"

升级现有 uv 安装，请运行 uv tool upgrade deepagents-cli.

CLI 读取 LANGSMITH_API_KEY。要创建密钥，请参阅 创建 API 密钥。要覆盖默认端点，请设置 LANGSMITH_ENDPOINT.

项目 .env 文件可以设置 API 密钥。项目 .env 文件无法为托管 API 请求设置端点、代理或 TLS 环境变量。请在您的 shell 或 ~/.deepagents/.env.

命令概览

裸 deepagents 调用不会启动交互式 REPL。请安装并运行 Deep Agents Code 以进行交互式编码会话。

初始化项目

使用 deepagents init 创建项目目录：

deepagents init my-agent

如果省略项目名称，CLI 会提示输入：

deepagents init

该 init 命令在项目目录中创建以下文件：

部署项目

运行 deepagents deploy 从项目目录：

deepagents deploy

首次部署创建 Managed Deep Agent。后续部署更新同一 Agent。部署状态为用户本地状态，存储在项目外部，因此提交到仓库的文件不会更改部署目标 Agent。

默认情况下，部署会上传项目、轮询 Agent 健康状态端点，并打印 Agent 名称、ID、短修订版本、Agent URL 和部署后 MCP 健康检查。使用 --detach 跳过轮询并在创建或更新后立即退出。

deepagents deploy --dry-run 打印 JSON，包含：

面向现有 Agent

对于共享仓库或有意更新现有 Managed Deep Agent，请在 agent.json:

{
  "name": "my-agent",
  "agent_id": "agent-uuid",
  "model": "openai:gpt-5.5",
  "backend": {
    "type": "state"
  }
}

首次使用时，CLI 会在更新远程代理前要求您确认。使用 --yes 跳过提示。

部署前验证项目

当项目格式不正确时，部署会在发送请求前失败。常见验证规则包括：

• - agent.json 和 AGENTS.md 是必需的。
• - agent.json 必须包含一个非空 name.
• - backend.sandbox_config 需要 backend.type to be sandbox.
• - backend.sandbox_config.scope 必须是 thread or agent.
• - backend.sandbox_config.policy_ids 必须是字符串数组。
• - backend.sandbox_config.idle_ttl_seconds 和 backend.sandbox_config.delete_after_stop_seconds 必须是整数。
• - 部署项目输入中不允许使用符号链接。
• - tools.json 必须包含一个 tools array.
• - 中的每个工具必须包含 tools.json 必须包含 name 和 mcp_server_url.
• - 技能文件需要带有以下内容的 YAML frontmatter name 和 description.
• - 子代理目录需要 agent.json 和 AGENTS.md.
• - 旧版 deepagents.toml 和 mcp.json 文件会产生迁移提示而不是被部署。

在部署前，CLI 还会验证引用的 MCP 服务器 URL。如果服务器 URL 未注册，部署将失败并给出添加它的命令提示。如果 OAuth 服务器已注册但调用者无法调用它，部署将失败并提示运行 deepagents mcp-servers connect <id|name|url>.

管理代理

列出代理：

deepagents agents list

该命令打印由代理 ID、代理名称和更新时间组成的制表符分隔行：

e2de7a35-9dda-462b-b982-9e57051993bc\tmy-agent\t2026-06-01T12:00:00Z

检查代理：

deepagents agents get <agent_id>

在响应中包含托管文件：

deepagents agents get <agent_id> --include-files

删除代理：

deepagents agents delete <agent_id>

删除命令会要求确认。使用以下命令跳过提示 --yes:

deepagents agents delete <agent_id> --yes

管理 MCP 服务器

有关实际设置指南，请参阅 连接工具.

接受 <server> 的命令接受 MCP 服务器 ID、精确名称或 URL。非 ID 值将根据以下内容进行解析 deepagents mcp-servers list; URL 匹配忽略大小写和尾部斜杠。如果名称或 URL 匹配多个服务器，请使用服务器 ID 重新运行命令。

添加 MCP 服务器

注册静态头部服务器：

deepagents mcp-servers add \
  --url https://example.com/mcp \
  --name my-tools \
  --header Authorization="Bearer <token>"

注册 OAuth MCP 服务器：

deepagents mcp-servers add \
  --url https://example.com/mcp \
  --name github-tools \
  --auth-type oauth \
  --connect

OAuth add 支持与 connect: --scope, --force-new, --timeout相同的 OAuth 标志，以及 --no-browser.

列出 MCP 服务器工具

列出已注册服务器的工具：

deepagents mcp-servers tools <id|name|url>

该命令打印每个工具名称及其描述的第一行，然后打印一个可粘贴的 tools.json 代码片段。对于 OAuth 服务器，请先连接，以便 MCP 服务器记录包含调用者的 oauth_provider_id.

更新 MCP 服务器

更新服务器 URL 或头信息：

deepagents mcp-servers update <id|name|url> \
  --url https://new.example.com/mcp \
  --header Authorization="Bearer <token>"

该命令至少需要一个更改标志。

删除 MCP 服务器：

deepagents mcp-servers delete <id|name|url>

删除命令会要求确认。使用 --yes:

deepagents mcp-servers delete <id|name|url> --yes

连接 OAuth MCP 服务器

启动或重用 OAuth 授权：

deepagents mcp-servers connect <id|name|url>

如果授权待处理，CLI 会打印验证 URL。当 --timeout 0 设置后，CLI 启动授权并退出。之后重新运行 deepagents mcp-servers connect <id|name|url> 以完成或重用连接。

项目文件参考

Managed Deep Agents 项目使用此布局：

my-agent/
  agent.json
  AGENTS.md
  tools.json
  skills/<name>/SKILL.md
  skills/<name>/<file>
  subagents/<name>/agent.json
  subagents/<name>/AGENTS.md
  subagents/<name>/tools.json
  subagents/<name>/skills/<skill-name>/SKILL.md

agent.json

agent.json 配置 Managed Deep Agent 资源：

{
  "name": "my-agent",
  "description": "A managed deep agent.",
  "model": "openai:gpt-5.5",
  "backend": {
    "type": "state"
  }
}

配置后端

由 deepagents-cli>=0.2.2 生成的托管 Deep Agents 项目使用 state 后端。当代理需要代码执行、文件系统操作或长时间运行任务的隔离环境时，请使用 LangSmith 沙盒 后端。

沙盒后端可以包含可选的沙盒设置：

{
  "backend": {
    "type": "sandbox",
    "sandbox_config": {
      "scope": "thread",
      "policy_ids": ["policy-id"],
      "idle_ttl_seconds": 900,
      "delete_after_stop_seconds": 300
    }
  }
}

backend.sandbox_config 仅在 backend.type is sandbox时有效。对于快照、服务 URL、权限、CLI 命令和 SDK 使用等独立沙盒功能，请参阅 LangSmith 沙盒概述.

配置权限

可选的 permissions 字段位于 agent.json 中，用于设置标识、可见性和租户访问。支持的值为：

AGENTS.md

AGENTS.md 包含主要代理指令。CLI 将此内容作为代理系统提示发送，并将其存储在托管文件树中。

tools.json

tools.json 配置 MCP 支持的工具。 deepagents init 使用空 tools 数组创建此文件。在注册 MCP 服务器后添加工具条目：

{
  "tools": [
    {
      "name": "example_tool",
      "mcp_server_url": "https://example.com/mcp",
      "mcp_server_name": "my-tools",
      "display_name": "example_tool"
    }
  ],
  "interrupt_config": {
    "https://example.com/mcp::example_tool": true
  }
}

每个工具需要 name 和 mcp_server_url. mcp_server_name 和 display_name 是可选的。 interrupt_config 是可选的，存在时必须为对象。按 "{mcp_server_url}::{tool_name}"作为键来标记每个中断条目。额外的 ::{mcp_server_name} 组件被接受以保持兼容性。

技能

每个技能位于 skills/<name>/SKILL.md 下，需要 YAML 前置元数据：

---
name: summarize
description: Summarize text into a one-paragraph summary.
---

# Summarize

Given a text, produce a one-paragraph summary.

CLI 递归包含技能目录中的所有其他文件，不包括隐藏路径。

子代理

每个子代理位于 subagents/<name>/ 下，需要：

子代理示例 agent.json:

{
  "description": "Researches a topic.",
  "model": "openai:gpt-5.5"
}

旧的 model_id 键在本地子代理文件中仍被接受，但新项目应使用 model。REST API SubagentSpec 使用 model_id.

子代理名称来自目录名称。名称检查不区分大小写以避免重复。