Deep Agents CLI

Deep Agents CLI 是一个开源的终端编码代理，构建于 Deep Agents SDK 之上。它具备持久记忆、跨会话上下文维护、学习项目约定、使用可定制技能以及带审批控制执行代码的能力。

Deep Agents CLI 具有以下内置功能：

文件操作 - 使用工具读取、写入和编辑文件，使代理能够管理和修改代码与文档。
Shell 执行 - 执行命令以运行测试、构建项目、管理依赖项并与版本控制系统交互。
网络搜索 - 搜索网络以获取最新信息和文档（需要 Tavily API 密钥）。
HTTP 请求 - 向 API 和外部服务发起 HTTP 请求，用于数据获取和集成任务。
任务规划与跟踪 - 将复杂任务分解为离散步骤并跟踪进度。
记忆存储与检索 - 跨会话存储和检索信息，使代理能够记住项目约定和学习到的模式。
上下文压缩与卸载 - 总结较旧的对话消息，并将原始消息卸载到存储中，在长时间会话中释放上下文窗口空间。
Human in the Loop - 要求对敏感工具操作进行人工批准。
技能 - 使用自定义专业知识和指令扩展代理能力。
MCP 工具 - 从 Model Context Protocol 服务器加载外部工具。
追踪 - 在 LangSmith 中追踪代理操作，用于可观测性和调试。

内置工具完整列表

内置工具

代理附带以下内置工具，无需配置即可使用：

工具	描述	Human in the Loop
`ls`	列出文件和目录	-
`read_file`	读取文件内容；部分模型支持多模态内容	-
`write_file`	创建或覆盖文件	需要¹
`edit_file`	对现有文件进行定向编辑	需要¹
`glob`	查找匹配模式的文件	-
`grep`	在文件中搜索文本模式	-
`execute`	在本地或远程沙箱中执行 shell 命令	需要¹
`web_search`	使用 Tavily 搜索网络	需要¹
`fetch_url`	获取网页并转换为 markdown	需要¹
`task`	将工作委派给子代理以并行执行	需要¹
`ask_user`	向用户提出自由形式或多项选择题	-
`compact_conversation`	总结较旧的消息，将原始消息卸载到后端存储，并在上下文中用摘要替换它们	混合²
`write_todos`	为复杂工作创建和管理任务列表	-

¹：潜在的破坏性操作在执行前需要用户批准。要绕过人工批准，您可以切换自动批准（shift+tab）或使用以下选项启动：

deepagents -y
# 或
deepagents --auto-approve

当以非交互方式运行 CLI（通过 -n 或管道输入）时，即使使用 -y/--auto-approve，shell 执行默认也是禁用的。使用 -S/--shell-allow-list 来允许特定命令（例如 -S "pytest,git,make"），recommended 用于安全的默认值，或 all 以允许任何命令。也支持 DEEPAGENTS_CLI_SHELL_ALLOW_LIST 环境变量。有关更多详细信息，请参阅非交互模式和管道。

²：当令牌使用量超过模型感知阈值时，CLI 会在后台自动卸载对话。卸载通过 LLM 总结较旧的消息，并将原始消息弹出到存储（/conversation_history/{thread_id}.md），并在上下文中用摘要替换它们。如果需要，代理仍然可以从卸载的文件中检索完整历史记录。compact_conversation 工具允许代理（或您）按需触发卸载。作为工具调用时，默认需要用户批准。

观看演示视频以了解 Deep Agents CLI 的工作原理。

Deep Agents CLI 在 Windows 上未得到官方支持。Windows 用户可以尝试在 Windows Subsystem for Linux (WSL) 下运行它。

快速开始

设置模型凭据

将您的提供商 API 密钥导出为环境变量，或将其添加到 ~/.deepagents/.env：

OpenAI
Anthropic
Google
其他

export OPENAI_API_KEY="your-api-key"

export ANTHROPIC_API_KEY="your-api-key"

export GOOGLE_API_KEY="your-api-key"

为避免在每个终端会话中设置密钥，请将它们添加到 ~/.deepagents/.env。请参阅环境变量。

CLI 适用于任何支持工具调用的 LLM。OpenAI、Anthropic 和 Google 默认已安装。对于其他提供商（Ollama、Groq、xAI 等），请参阅提供商。

安装并运行

OpenAI、Anthropic 和 Google 默认已安装。其他提供商（Ollama、Groq、xAI 等）作为可选附加组件提供——有关详细信息，请参阅提供商。

curl -LsSf https://langch.in/gh-da-cli | bash

# OpenAI、Anthropic 和 Gemini 默认包含
DEEPAGENTS_EXTRAS="ollama,groq" curl -LsSf https://langch.in/gh-da-cli | bash

uv tool install 'deepagents-cli[ollama,groq]'

deepagents

给代理一个任务

创建一个打印 "Hello, World!" 的 Python 脚本

代理会提出带有差异的更改供您批准，然后再修改文件。

启用追踪（可选）

要在 LangSmith 中查看代理操作、工具调用和决策，请将以下内容添加到 ~/.deepagents/.env 或在 shell 中导出变量：

~/.deepagents/.env

LANGSMITH_TRACING=true
LANGSMITH_API_KEY=lsv2_...
LANGSMITH_PROJECT=optional-project-name  # 指定项目名称或默认为 "deepagents-cli"

有关设置详细信息和用法，请参阅使用 LangSmith 追踪。

提供商

OpenAI、Anthropic 和 Google 开箱即用。其他提供商单独安装，因此您只需引入所需内容。

# 向现有安装添加额外提供商
uv tool install deepagents-cli --with langchain-xai

有关支持的提供商完整列表，请参阅模型提供商。

交互模式

像在聊天界面中一样自然地输入。代理将使用其内置工具、技能和记忆来帮助您完成任务。

斜杠命令

在 CLI 会话中使用这些命令：

/model - 切换模型或打开交互式模型选择器。有关详细信息，请参阅切换模型
/agents - 在预配置的代理之间热交换，无需重新启动。有关详细信息，请参阅切换代理
/remember [context] - 审查对话并更新记忆和技能。可选地传递额外上下文
/skill:<name> [args] - 按名称直接调用技能。技能的 SKILL.md 指令会与您提供的任何参数一起注入到提示中
/skill-creator [args] - 创建有效代理技能的指南
/offload（别名 /compact）- 通过将消息卸载到存储并带有摘要占位符来释放上下文窗口空间。如果需要，代理可以从卸载的文件中检索完整历史记录
/tokens - 显示当前上下文窗口令牌使用情况细分
/clear - 清除对话历史并开始新线程
/threads - 浏览并恢复之前的对话线程
/mcp - 显示活动的 MCP 服务器和工具
/reload - 重新读取 .env 文件，刷新配置，并重新发现技能，无需重启。对话状态得以保留。有关覆盖行为，请参阅 DEEPAGENTS_CLI_ 前缀
/theme - 打开交互式主题选择器以切换颜色主题。内置主题可用，以及任何用户定义主题
/update - 检查并内联安装 CLI 更新。检测您的安装方法（uv、Homebrew、pip）并运行相应的升级命令
/auto-update - 切换自动更新开或关
/trace - 在 LangSmith 中打开当前线程（需要 LANGSMITH_API_KEY）
/editor - 在外部编辑器（$VISUAL / $EDITOR）中打开当前提示。请参阅外部编辑器
/changelog - 在浏览器中打开 CLI 变更日志
/docs - 在浏览器中打开文档
/feedback - 打开 GitHub issues 页面以提交错误报告或功能请求
/version - 显示已安装的 deepagents-cli 和 SDK 版本
/help - 显示帮助和可用命令
/quit - 退出 CLI

Shell 命令

输入 ! 进入 shell 模式，然后输入您的命令。

git status
npm test
ls -la

键盘快捷键

常规

快捷键	操作
`Enter`	提交提示
`Shift+Enter`、`Ctrl+J`、`Alt+Enter` 或 `Ctrl+Enter`	插入换行符
`Ctrl+A`	选择输入中的所有文本
`@filename`	自动完成文件并注入内容
`Shift+Tab` 或 `Ctrl+T`	切换自动批准
`Ctrl+U`	删除到行首
`Ctrl+X`	在外部编辑器中打开提示
`Ctrl+O`	展开/折叠最近的工具输出
`Escape`	中断当前操作
`Ctrl+C`	中断或退出
`Ctrl+D`	退出

非交互模式和管道

使用 -n 运行单个任务而不启动交互式 UI：

deepagents -n "编写一个打印 hello world 的 Python 脚本"

您也可以通过 stdin 管道输入。当输入被管道传输时，CLI 自动以非交互方式运行：

echo "解释这段代码" | deepagents
cat error.log | deepagents -n "是什么导致了这个错误？"
git diff | deepagents -n "审查这些更改"
git diff | deepagents --skill code-review -n '总结更改'

当您将管道输入与 -n 或 -m 结合使用时，管道内容首先出现，然后是您传递给标志的文本。

最大管道输入大小为 10 MiB。

在非交互模式下，shell 执行默认是禁用的。使用 -S/--shell-allow-list 启用特定命令（例如 -S "pytest,git,make"），recommended 用于安全的默认值，或 all 以允许任何命令。

使用 `--max-turns` 限制轮次

CI/CD 管道中长时间运行或行为异常的代理可能会无限循环。--max-turns N 为操作员提供了一个硬性上限，而无需触及 SDK 内部：

deepagents -n "修复失败的测试" --max-turns 10

N 必须是正整数，并覆盖内部安全默认值，否则该默认值会限制失控循环。当超出预算时，以代码 124 退出（与 GNU timeout 匹配），因此 CI 可以区分预算命中和一般故障。需要 -n 或管道 stdin；否则以代码 2 退出。

干净输出和缓冲

使用 -q 获得适合管道传输到其他命令的干净输出，使用 --no-stream 在写入 stdout 之前缓冲完整响应（而不是流式传输）：

deepagents -n "为 Python 生成 .gitignore" -q > .gitignore
deepagents -n "列出依赖项" -q --no-stream | sort

在非交互模式下，代理被指示做出合理的假设并自主进行，而不是提出澄清问题。它还倾向于使用非交互式命令变体（例如 npm init -y、apt-get install -y）。

Shell 执行示例

# 允许特定命令（根据列表进行验证）
deepagents -n "运行测试并修复失败" -S "pytest,git,make"

# 使用精选的安全命令列表
deepagents -n "构建项目" -S recommended

# 允许任何 shell 命令
deepagents -n "修复构建" -S all

谨慎使用。-S all（或 --shell-allow-list all）允许代理执行任意 shell 命令，无需人工确认。

在启动时运行命令

使用 --startup-cmd 在会话接受第一个提示之前运行一次 shell 命令。输出显示在会话顶部，这对于在输入第一个提示之前检查 git status、列出文件或验证环境设置非常方便。

# 交互式：在第一个提示之前显示 git 状态
deepagents --startup-cmd "git status"

# 与初始提示结合使用——命令先运行，然后提交提示
deepagents --startup-cmd "ls -la" -m "总结此目录中的内容"

# 非交互式：在任务运行之前查看环境状态
deepagents --startup-cmd "git diff --stat" -n "审查这些更改"

该命令在任何 -m 提示或 --skill 调用分派之前运行，并尊重您的 shell 环境。非零退出和超时会发出警告，但不会中止会话。在非交互模式下，命令有 60 秒超时。

输出不会注入到代理的消息历史中——LLM 看不到它。要将命令输出交给代理，请通过 stdin 管道传输（例如 git diff | deepagents -n "审查这些更改"）。

切换模型

您可以在会话期间使用 /model 命令切换模型，或在启动时使用 --model 标志，无需重新启动 CLI：

> /model anthropic:claude-opus-4-6
> /model openai:gpt-5.5

deepagents --model openai:gpt-5.5

运行 /model 打开交互式模型选择器，该选择器按提供商分组显示可用模型。有关切换模型、设置默认值和添加自定义模型提供商的完整详细信息，请参阅模型提供商。

模型参数

通过在启动时向 --model-params 传递 JSON 或在会话中向 /model --model-params 传递 JSON 来覆盖模型调用参数（例如推理努力、思考预算、最大输出令牌等）：

deepagents --model openai:gpt-5.5 --model-params '{"reasoning": {"effort": "high"}}'

deepagents --model anthropic:claude-opus-4-7 --model-params '{"thinking": {"type": "enabled", "budget_tokens": 10000}}'

# 会话中——一步切换模型和参数
/model --model-params '{"temperature": 0.7}' anthropic:claude-opus-4-7

# 或打开选择器并将参数应用于您选择的任何模型
/model --model-params '{"num_ctx": 16384}'

CLI 标志仅限会话。--model-params 不能与 --default 结合使用。有关持久的提供商级别默认值、每个模型的覆盖以及提供商特定示例，请参阅提供商页面上的模型参数。

切换代理

运行 /agents 打开代理选择器，并在 ~/.deepagents/ 中的代理之间热交换，无需重新启动。切换会重置对话线程并刷新技能发现。选择会被持久化，因此下一次裸 deepagents 启动将恢复相同的代理。-a/--agent 始终覆盖；-r/--resume 恢复线程的原始代理。

配置

CLI 将所有配置存储在 ~/.deepagents/ 下。在该目录中，每个代理都有自己的子目录（默认：agent）：

路径	用途
`~/.deepagents/config.toml`	模型默认值、提供商设置、构造函数参数、配置文件覆盖、主题、更新设置、MCP 信任存储
`~/.deepagents/.env`	全局 API 密钥和密钥。请参阅配置
`~/.deepagents/hooks.json`	生命周期事件钩子（会话开始/结束、任务完成等）
`~/.deepagents/<agent_name>/`	每个代理的记忆、技能和对话线程
`.deepagents/`（项目根目录）	项目特定的记忆和技能，在 git 仓库内运行时加载

# 列出所有配置的代理
deepagents agents list

有关完整参考——包括 config.toml 模式、提供商参数、配置文件覆盖和钩子配置——请参阅配置。

记忆

自定义任何代理有两种主要方式：

记忆：AGENTS.md 文件和跨会话持久化的自动保存记忆。将记忆用于通用编码风格、偏好和学习到的约定。
技能：全局和项目特定的上下文、约定、指南或指令。将技能用于仅在执行特定任务时需要的上下文。

使用 /remember 明确提示代理从当前对话更新其记忆和技能。

使用 SDK 构建自定义代理？有关编程记忆后端，请参阅记忆。

自动记忆

当您使用代理时，它会使用记忆优先协议自动将信息存储在 ~/.deepagents/<agent_name>/memories/ 中的 markdown 文件中：

研究：在开始任务之前搜索记忆以获取相关上下文
响应：在执行过程中不确定时检查记忆
学习：自动保存新信息以供未来会话使用

代理按主题组织其记忆，并使用描述性文件名：

~/.deepagents/backend-dev/memories/
├── api-conventions.md
├── database-schema.md
└── deployment-process.md

当您教代理约定时：

deepagents --agent backend-dev
> 我们的 API 使用 snake_case 并包含 created_at/updated_at 时间戳

它会为未来的会话记住：

> 创建一个 /users 端点
# 应用约定而无需提示

AGENTS.md 文件

AGENTS.md 文件提供持久上下文，在会话开始时始终加载：

全局：~/.deepagents/<agent_name>/AGENTS.md — 每次会话加载。
项目：任何 git 项目根目录中的 .deepagents/AGENTS.md — 当 CLI 从该项目内运行时加载。

这两个文件在启动时都会附加到系统提示中。

记忆如何工作

代理在回答项目特定问题或您引用过去的工作或模式时，也可能读取其记忆文件。当您提供有关其应如何行为的信息、对其工作的反馈或记住某事的指令时，代理将更新 AGENTS.md。如果它从您的交互中识别出模式或偏好，它也会更新其记忆。要在其他记忆文件中添加更多结构化的项目知识，请将它们添加到 .deepagents/ 中并在 AGENTS.md 文件中引用它们。您必须在 AGENTS.md 文件中引用其他文件，代理才能意识到它们。其他文件不会在启动时读取，但代理可以在需要时引用和更新它们。

何时使用全局与项目 AGENTS.md

全局 AGENTS.md（~/.deepagents/agent/AGENTS.md）

您的个性、风格和通用编码偏好
一般语气和沟通风格
通用编码偏好（格式化、类型提示等）
适用于所有地方的工具使用模式
不随项目变化的工作流程和方法

项目 AGENTS.md（项目根目录中的 .deepagents/AGENTS.md）

项目特定的上下文和约定
项目架构和设计模式
特定于此代码库的编码约定
测试策略和部署流程
团队指南和项目结构

使用技能

技能是可重用的代理能力，提供专门的工作流程和领域知识。您可以使用技能为您的深度代理提供新的能力和专业知识。深度代理技能遵循 Agent Skills 标准。一旦您添加了技能，您的深度代理将自动使用它们，并在您使用代理并提供额外信息时更新它们。使用 /remember 明确提示代理从当前对话更新技能和记忆。

添加技能

创建技能：

# 用户技能（存储在 ~/.deepagents/<agent_name>/skills/ 中）
deepagents skills create test-skill

# 项目技能（存储在 .deepagents/skills/ 中）
deepagents skills create test-skill --project

这将生成：

skills/
└── test-skill
    └── SKILL.md

打开生成的 SKILL.md 并编辑文件以包含您的指令。
可选地向 test-skill 文件夹添加额外的脚本或其他资源。有关更多信息，请参阅示例。

您也可以将现有技能直接复制到代理的文件夹：

mkdir -p ~/.deepagents/<agent_name>/skills
cp -r examples/skills/web-research ~/.deepagents/<agent_name>/skills/

安装社区技能

您可以使用 Vercel 的 Skills CLI 等工具在您的环境中安装社区 Agent Skills，并使其可供您的深度代理使用：

# 全局安装技能
npx skills add vercel-labs/agent-skills --skill web-design-guidelines -a deepagents -g -y

# 列出已安装的技能
npx skills ls -a deepagents -g

全局安装（-g）将技能符号链接到 ~/.deepagents/agent/skills/ — 默认代理的用户级技能目录。项目级安装（省略 -g）将技能放置在相对于当前目录的 .deepagents/skills/ 中，使其可供在该项目中运行的任何代理使用，无论代理名称如何。

全局安装仅针对默认 agent 目录。如果您使用自定义命名的代理，请使用项目级安装或将技能手动符号链接到 ~/.deepagents/{your-agent}/skills/。

技能发现

在启动时，CLI 从 Deep Agents 和共享别名目录中发现技能：

~/.deepagents/<agent_name>/skills/
~/.agents/skills/
.deepagents/skills/
.agents/skills/
~/.claude/skills/          （实验性）
.claude/skills/            （实验性）

当存在重复的技能名称时，后优先级目录覆盖前一个（请参阅应用数据）。对于项目特定的技能，项目的根文件夹必须有一个 .git 文件夹。当您从项目文件夹内的任何位置启动 CLI 时，CLI 将通过检查包含的 .git 文件夹来找到项目的根文件夹。对于每个技能，CLI 从 SKILL.md 文件的 frontmatter 中读取名称和描述。当您使用 CLI 时，如果任务与技能的描述匹配，代理将读取技能文件并遵循其指令。您也可以使用 /skill:<name> [args] 直接调用技能。技能发现在启动时运行，并在 /reload 时再次运行。

从命令行调用技能

使用 --skill 在启动时调用技能，而无需交互式输入斜杠命令：

# 打开 TUI 并立即运行技能
deepagents --skill code-review

# 使用 -m 向技能传递请求
deepagents --skill code-review -m '审查认证模块'

# 将内容管道传输到技能
cat diff.txt | deepagents --skill code-review

# 管道传输内容并添加请求
cat diff.txt | deepagents --skill code-review -m '关注安全性'

--skill 在非交互模式下也有效：

# 无头运行技能
deepagents --skill code-review -n '审查此补丁'

# 安静模式（仅代理输出到 stdout）
deepagents --skill code-review -n '审查此补丁' -q

--skill 与 --quiet 或 --no-stream 需要 -n（非交互模式）。

列出技能

# 列出所有用户技能
deepagents skills list

# 列出项目技能
deepagents skills list --project

# 获取有关特定技能的详细信息
deepagents skills info test-skill
deepagents skills info test-skill --project

子代理

将自定义子代理定义为 markdown 文件，以便 CLI 代理可以将专门任务委派给它们。每个子代理位于自己的文件夹中，包含一个 AGENTS.md 文件：

.deepagents/agents/{subagent-name}/AGENTS.md   # 项目级
~/.deepagents/{agent}/agents/{subagent-name}/AGENTS.md  # 用户级

项目子代理覆盖同名的用户子代理（请参阅优先级规则）。 frontmatter 需要 name 和 description（与 SubAgent 字典规范相同）。markdown 正文成为子代理的 system_prompt。除了基本规范外，AGENTS.md 文件还支持可选的 model frontmatter 字段，该字段为此子代理覆盖主代理的模型。使用 provider:model-name 格式（例如 anthropic:claude-opus-4-6、openai:gpt-5.5）。省略以继承主代理的模型。

其他 SubAgent 字段（tools、middleware、interrupt_on、skills）目前无法通过 AGENTS.md frontmatter 配置——以此方式定义的自定义子代理继承主代理的工具。要完全控制，请直接使用 SDK。

文件格式

子代理 AGENTS.md 文件使用 YAML frontmatter，后跟 markdown 正文：

---
name: researcher
description: 在撰写内容之前研究网络主题
model: anthropic:claude-haiku-4-5-20251001
---

您是一个可以访问网络搜索的研究助理。

## 您的流程
1. 搜索相关信息
2. 清晰地总结发现

示例：经济高效的子代理

对于简单的委派任务使用更便宜、更快的模型，同时将主代理保留在更强大的模型上：

---
name: general-purpose
description: 用于研究和多步骤任务的通用代理
model: anthropic:claude-haiku-4-5-20251001
---

您是一个通用助理。高效完成任务并返回简洁的摘要。

这将覆盖内置的通用子代理，将所有委派任务路由到更便宜的模型。有关更多信息，请参阅覆盖通用子代理。

使用 MCP 工具

使用来自外部 MCP (Model Context Protocol) 服务器的工具扩展 CLI。在项目根目录放置一个 .mcp.json，CLI 会自动发现它。需要 OAuth 的服务器（Slack、GitHub、Linear、Notion 等）可以使用 deepagents mcp login <server> 进行一次身份验证；令牌会持久化到 ~/.deepagents/mcp-tokens/ 并自动刷新。有关配置格式、OAuth 登录、自动发现和故障排除，请参阅 MCP 工具指南。

使用远程沙箱

CLI 使用沙箱作为工具模式：CLI 进程（LLM 循环、记忆、工具分派）在您的机器上运行，但代理工具调用（read_file、write_file、execute 等）针对远程沙箱，而不是您的本地文件系统。要将文件放入沙箱，请使用设置脚本或提供商的文件传输 API（请参阅处理文件）。有关沙箱架构、集成模式和安全最佳实践的更深入了解，请参阅沙箱。

LangSmith 沙箱支持默认包含在 CLI 中。AgentCore、Modal、Daytona 和 Runloop 需要安装附加组件。

安装提供商依赖项

LangSmith
Daytona
Modal
Runloop
AgentCore

安装 deepagents-cli 时默认包含。无需额外安装。

uv tool install deepagents-cli --with langchain-daytona

uv tool install deepagents-cli --with langchain-runloop

uv tool install deepagents-cli --with langchain-agentcore-codeinterpreter

设置提供商凭据

LangSmith
Daytona
Modal
Runloop
AgentCore

export LANGSMITH_API_KEY="your-key"

export DAYTONA_API_KEY="your-key"

export RUNLOOP_API_KEY="your-key"

export AWS_ACCESS_KEY_ID="your-key"
export AWS_SECRET_ACCESS_KEY="your-secret"
export AWS_SESSION_TOKEN="session-token"
export AWS_REGION="us-west-2"

使用沙箱运行 CLI

LangSmith
Daytona
Modal
Runloop
AgentCore

deepagents --sandbox langsmith

deepagents --sandbox daytona

deepagents --sandbox runloop

deepagents --sandbox agentcore

标志	描述
`--sandbox TYPE`	要使用的沙箱提供商：`langsmith`、`agentcore`、`modal`、`daytona` 或 `runloop`（默认：`none`）
`--sandbox-id ID`	通过 ID 重用现有沙箱，而不是创建新的。跳过创建和清理。有关更多信息，请参阅您的沙箱文档
`--sandbox-setup PATH`	在创建时在沙箱内运行的设置脚本路径

示例：

# 创建新的 Daytona 沙箱
deepagents --sandbox daytona

# 重用现有沙箱（跳过创建和清理）
deepagents --sandbox runloop --sandbox-id dbx_abc123

# 在沙箱创建后运行设置脚本
deepagents --sandbox modal --sandbox-setup ./setup.sh

设置脚本

使用 --sandbox-setup 在创建后在沙箱内运行 shell 脚本。这对于克隆仓库、安装依赖项和配置环境变量非常有用。

setup.sh

#!/bin/bash
set -e

# 使用 GitHub 令牌克隆仓库
git clone https://x-access-token:${GITHUB_TOKEN}@github.com/username/repo.git $HOME/workspace
cd $HOME/workspace

# 使环境变量持久化
cat >> ~/.bashrc <<'EOF'
export GITHUB_TOKEN="${GITHUB_TOKEN}"
export OPENAI_API_KEY="${OPENAI_API_KEY}"
cd $HOME/workspace
EOF
source ~/.bashrc

CLI 使用您的本地环境变量扩展设置脚本中的 ${VAR} 引用。将密钥存储在本地 .env 文件中以供设置脚本访问。

沙箱隔离代码执行，但代理仍然容易受到不可信输入的提示注入攻击。仅使用Human in the Loop批准、短期密钥和受信任的设置脚本。有关详细信息，请参阅安全注意事项。

使用 LangSmith 追踪

启用 LangSmith 追踪以在 LangSmith 项目中查看代理操作、工具调用和决策。将您的追踪密钥添加到 ~/.deepagents/.env，以便在每个会话中启用追踪，而无需每次 shell 导出：

~/.deepagents/.env

LANGSMITH_TRACING=true
LANGSMITH_API_KEY=lsv2_...
LANGSMITH_PROJECT=optional-project-name  # 指定项目名称或默认为 "deepagents-cli"

要为特定项目覆盖，请将相同的密钥添加到项目目录中的 .env。有关完整的加载顺序，请参阅环境变量。如果您愿意，也可以将这些设置为 shell 环境变量。Shell 导出始终优先于 .env 值，因此这是临时覆盖或测试的好选择：

export LANGSMITH_TRACING=false

将代理追踪与应用追踪分开

当从 LangChain 应用程序以编程方式调用 CLI 时（例如，在非交互模式中作为子进程），您的应用程序和 CLI 都会产生 LangSmith 追踪。默认情况下，这些都落在同一个项目中。要将 CLI 追踪发送到专用项目，请设置 DEEPAGENTS_CLI_LANGSMITH_PROJECT：

~/.deepagents/.env

DEEPAGENTS_CLI_LANGSMITH_PROJECT=my-deep-agent-execution

然后为父应用程序的追踪配置 LANGSMITH_PROJECT：

~/.deepagents/.env

LANGSMITH_PROJECT=my-app-traces

这使您的应用程序级可观测性保持干净，同时仍在单独的项目中捕获代理的内部执行。您也可以使用 DEEPAGENTS_CLI_ 前缀（例如 DEEPAGENTS_CLI_LANGSMITH_API_KEY）将 LangSmith 凭据限定到 CLI。

配置后，CLI 会显示一个状态行，其中包含指向 LangSmith 项目的链接。在支持的终端中，单击链接可直接打开它。您也可以使用 /trace 打印 URL 并在浏览器中打开它。

✓ LangSmith 追踪：'my-project'

命令参考

# 使用特定代理配置
deepagents --agent mybot

# 使用特定模型（provider:model 格式或自动检测）
deepagents --model anthropic:claude-opus-4-7
deepagents --model gpt-5.5

# 自动批准工具使用（跳过Human in the Loop提示）
deepagents -y

命令行选项

选项	描述
`-a`, `--agent NAME`	使用具有独立记忆的命名代理。覆盖 `config.toml` 中的 `[agents].recent`。默认：`agent`（或如果设置了 `[agents].recent`，则为最近使用的代理）
`-M`, `--model MODEL`	使用特定模型（`provider:model`）
`--model-params JSON`	作为 JSON 字符串传递给模型的额外 kwargs（例如 `'{"temperature": 0.7}'`）
`--default-model [MODEL]`	设置默认模型
`--clear-default-model`	清除默认模型
`-r`, `--resume [ID]`	恢复会话：`-r` 用于最近的，`-r <ID>` 用于特定线程
`-m`, `--message TEXT`	会话启动时自动提交的初始提示（交互模式）
`--skill NAME`	在启动时调用技能
`--startup-cmd CMD`	在第一个提示之前在启动时运行的 shell 命令。输出呈现在记录中供您参考，但不会添加到代理的消息历史中。非零退出和超时会警告但不会中止；非交互模式应用 60 秒超时。请参阅在启动时运行命令
`-n`, `--non-interactive TEXT`	以非交互方式运行单个任务并退出。除非设置了 `--shell-allow-list`，否则 shell 被禁用
`--max-turns N`	在非交互模式下限制代理轮次。超出时以代码 124 退出。需要 `-n` 或管道 stdin。请参阅使用 `--max-turns` 限制轮次
`-q`, `--quiet`	用于管道传输的干净输出——只有代理的响应进入 stdout。需要 `-n` 或管道 stdin
`--no-stream`	缓冲完整响应并一次性写入 stdout，而不是流式传输。需要 `-n` 或管道 stdin
`--stdin`	显式从 stdin 读取输入，而不是自动检测。当 stdin 不可用或为 TTY 时会清晰地报错
`-y`, `--auto-approve`	自动批准所有工具调用，无需提示（禁用Human in the Loop）。在交互会话期间使用 `Shift+Tab` 切换
`-S`, `--shell-allow-list LIST`	以逗号分隔的要自动批准的 shell 命令，`'recommended'` 用于安全的默认值，或 `'all'` 以允许任何命令。适用于 `-n` 和交互模式
`--json`	从管理子命令（`agents`、`threads`、`skills`、`update`）发出机器可读的 JSON。输出信封：`{"schema_version": 1, "command": "...", "data": ...}`
`--sandbox TYPE`	用于代码执行的远程沙箱：`none`（默认）、`langsmith`、`agentcore`、`modal`、`daytona`、`runloop`。LangSmith 已包含；AgentCore/Modal/Daytona/Runloop 需要附加组件
`--sandbox-id ID`	重用现有沙箱（跳过创建和清理）
`--sandbox-setup PATH`	在创建后在沙箱中运行的设置脚本路径
`--mcp-config PATH`	添加显式 MCP 配置作为最高优先级源（与自动发现的配置合并）
`--no-mcp`	禁用所有 MCP 工具加载
`--trust-project-mcp`	信任具有 stdio 服务器的项目级 MCP 配置（跳过批准提示）
`--profile-override JSON`	作为 JSON 字符串覆盖模型配置文件字段（例如 `'{"max_input_tokens": 4096}'`）。在配置文件配置文件覆盖之上合并
`--acp`	作为 ACP 服务器通过 stdio 运行，而不是启动交互式 UI
`-v`, `--version`	显示版本
`-h`, `--help`	显示帮助

CLI 命令

命令	描述
`deepagents help`	显示帮助
`deepagents agents list`	列出所有代理（别名：`ls`）
`deepagents agents reset --agent NAME`	清除代理记忆并重置为默认值。支持 `--dry-run`
`deepagents agents reset --agent NAME --target SOURCE`	从另一个代理复制记忆
`deepagents update`	检查并安装 CLI 更新
`deepagents skills list [--project]`	列出所有技能（别名：`ls`）
`deepagents skills create NAME [--project]`	使用模板 `SKILL.md` 创建新技能。幂等——重新创建现有技能会打印信息性消息而不是错误
`deepagents skills info NAME [--project]`	显示有关技能的详细信息
`deepagents skills delete NAME [--project] [-f]`	删除技能及其内容。支持 `--dry-run`
`deepagents threads list [--agent NAME] [--limit N]`	列出会话（别名：`ls`）。默认限制：20。`-n` 是 `--limit` 的短标志。其他标志：`--sort {created,updated}`、`--branch TEXT`（按 git 分支过滤）、`-v`/`--verbose`（显示所有列，包括分支、创建时间和初始提示）、`-r`/`--relative`（相对时间戳）
`deepagents threads delete ID`	删除会话。支持 `--dry-run`
`deepagents mcp login NAME [--config PATH]`	运行标记为 `auth: "oauth"` 的 MCP 服务器的 OAuth 登录流程。请参阅 MCP 工具
`deepagents deploy`	将您的代理部署到 LangSmith。请参阅使用 CLI 部署

所有管理子命令都支持 --json 以获得机器可读的输出。有关详细信息，请参阅命令行选项。破坏性命令（agents reset、skills delete、threads delete）支持 --dry-run 以预览将发生的情况而不进行更改。在 JSON 模式下，--dry-run 返回相同的信封，其中包含 dry_run: true 字段。

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

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

Get started

Deployment

Core capabilities

Frontend

Protocols

Command line interface

内置工具

快速开始

提供商

交互模式

非交互模式和管道

在启动时运行命令

切换模型

模型参数

切换代理

配置

记忆

自动记忆

AGENTS.md 文件

使用技能

子代理

使用 MCP 工具

使用远程沙箱

使用 LangSmith 追踪

命令参考

​内置工具

​快速开始

​提供商

​交互模式

​非交互模式和管道

​在启动时运行命令

​切换模型

​模型参数

​切换代理

​配置

​记忆

​自动记忆

​AGENTS.md 文件

​使用技能

​子代理

​使用 MCP 工具

​使用远程沙箱

​使用 LangSmith 追踪

​命令参考

内置工具

快速开始

提供商

交互模式

非交互模式和管道

在启动时运行命令

切换模型

模型参数

切换代理

配置

记忆

自动记忆

AGENTS.md 文件

使用技能

子代理

使用 MCP 工具

使用远程沙箱

使用 LangSmith 追踪

命令参考