
- 文件操作 - 读取、写入和编辑文件,使用使智能体能够管理和修改代码及文档的工具。
- Shell 执行 - 执行命令以运行测试、构建项目、管理依赖并与版本控制交互。
- Web 搜索 - 搜索 Web 以获取最新信息和文档(需要 Tavily API 密钥)。
- HTTP 请求 - 向 API 和外部服务发出 HTTP 请求以进行数据获取和集成任务。
- 任务规划和跟踪 - 将复杂任务分解为离散步骤并跟踪进度。
- 记忆存储和检索 - 跨会话存储和检索信息,使智能体能够记住项目约定和学习到的模式。
- 上下文压缩和卸载 - 总结较早的对话消息并将原始内容卸载到存储中,在长会话期间释放上下文窗口空间。
- 人机协同 (Human-in-the-loop) - 要求人工批准敏感工具操作。
- 技能 - 通过自定义专业知识和指令扩展智能体能力。
- MCP 工具 - 从 Model Context Protocol 服务器加载外部工具。
- 追踪 - 在 LangSmith 中追踪智能体操作以实现可观测性和调试。
内置工具完整列表
内置工具完整列表
内置工具
智能体附带以下内置工具,无需配置即可使用:| 工具 | 描述 | 人机协同 |
|---|---|---|
ls | 列出文件和目录 | - |
read_file | 读取文件内容;针对特定模型支持多模态内容 | - |
write_file | 创建或覆盖文件 | 需要1 |
edit_file | 对现有文件进行 targeted 编辑 | 需要1 |
glob | 查找匹配模式的文件 | - |
grep | 跨文件搜索文本模式 | - |
execute | 在本地或远程沙盒中执行 Shell 命令 | 需要1 |
web_search | 使用 Tavily 搜索 Web | 需要1 |
fetch_url | 获取并将 Web 页面转换为 Markdown | 需要1 |
task | 将工作委托给子智能体以并行执行 | 需要1 |
ask_user | 向用户提出自由形式或多项选择题 | - |
compact_conversation | 总结较早的消息,将原始内容卸载到后端存储,并在上下文中用摘要替换它们 | 混合2 |
write_todos | 为复杂工作创建和管理任务列表 | - |
当非交互地运行 CLI(通过
-n 或管道 stdin)时,即使使用 -y/--auto-approve,Shell 执行默认也是禁用的。使用 -S/--shell-allow-list 来白名单特定命令(例如 -S "pytest,git,make"),recommended 用于安全默认值,或 all 以允许任何命令。还支持 DEEPAGENTS_CLI_SHELL_ALLOW_LIST 环境变量。有关更多详情,请参阅 非交互模式和管道。/conversation_history/{thread_id}.md),在上下文中用摘要替换它们。如果需要,智能体仍然可以从卸载文件中检索完整历史。compact_conversation 工具允许智能体(或你)按需触发卸载。当作为工具调用时,默认需要用户批准。Deep Agents CLI 未在 Windows 上获得官方支持。Windows 用户可以尝试在 Windows
Subsystem for Linux
(WSL) 下运行它。
快速开始
设置模型凭据
将提供商的 API 密钥导出为环境变量或将其添加到 CLI 适用于任何支持工具调用的 LLM。OpenAI、Anthropic 和 Google 默认已安装。对于其他提供商(Ollama、Groq、xAI 等),请参阅 提供商。
~/.deepagents/.env:- OpenAI
- Anthropic
- Google
- 其他
安装并运行
启用追踪(可选)
要在 LangSmith 中查看智能体操作、工具调用和决策,请将以下内容添加到 有关设置详情和用法,请参阅 使用 LangSmith 追踪。
~/.deepagents/.env 或在 Shell 中导出变量:~/.deepagents/.env
提供商
OpenAI、Anthropic 和 Google 开箱即用。其他提供商单独安装,因此你只需拉取所需的内容。交互模式
像在聊天界面中一样自然输入。 智能体将使用其内置工具、技能和记忆来帮助你完成任务。斜杠命令
斜杠命令
在 CLI 会话中使用这些命令:
/model- 切换模型或打开交互模型选择器。有关详情,请参阅 切换模型/remember [context]- 审查对话并更新记忆和技能。可选地传递额外上下文/skill:<name> [args]- 按名称直接调用技能。技能的SKILL.md指令连同你提供的任何参数一起注入到 Prompt 中/skill-creator [args]- 创建有效代理技能的指南/offload(别名/compact) - 通过将消息卸载到存储并带有摘要占位符来释放上下文窗口空间。如果需要,智能体可以从卸载文件中检索完整历史/tokens- 显示当前上下文窗口 Token 使用量细分/clear- 清除对话历史并开始新线程/threads- 浏览和恢复之前的对话线程/mcp- 显示活动 MCP 服务器和工具/reload- 重新读取.env文件,刷新配置,并重新发现技能而无需重启。对话状态得以保留。有关覆盖行为,请参阅DEEPAGENTS_CLI_前缀/theme- 打开交互主题选择器以切换颜色主题。内置主题可用,加上任何 用户定义的主题/update- 检查并内联安装 CLI 更新。检测你的安装方法(uv、Homebrew、pip)并运行适当的升级命令/auto-update- 切换自动更新的开启或关闭/trace- 在 LangSmith 中打开当前线程(需要LANGSMITH_API_KEY)/editor- 在你的外部编辑器中打开当前 Prompt($VISUAL/$EDITOR)。请参阅 外部编辑器/changelog- 在浏览器中打开 CLI 变更日志/docs- 在浏览器中打开文档/feedback- 打开 GitHub 问题页面以提交错误报告或功能请求/version- 显示已安装的deepagents-cli和 SDK 版本/help- 显示帮助和可用命令/quit- 退出 CLI
Shell 命令
Shell 命令
输入
! 进入 Shell 模式,然后输入你的命令。键盘快捷键
键盘快捷键
常规
| 快捷键 | 操作 |
|---|---|
Enter | 提交 Prompt |
Shift+Enter、Ctrl+J、Alt+Enter 或 Ctrl+Enter | 插入换行 |
Ctrl+A | 选择输入中的所有文本 |
@filename | 自动补全文件并注入内容 |
Shift+Tab 或 Ctrl+T | 切换自动批准 |
Ctrl+U | 删除到行首 |
Ctrl+X | 在外部编辑器中打开 Prompt |
Ctrl+O | 展开/折叠最近的工具输出 |
Escape | 中断当前操作 |
Ctrl+C | 中断或退出 |
Ctrl+D | 退出 |
非交互模式和管道
使用-n 运行单个任务而无需启动交互 UI:
-n 或 -m 结合使用时,管道内容首先出现,随后是你传递给标志的文本。
最大管道输入大小为 10 MiB。
-S/--shell-allow-list 启用特定命令(例如 -S "pytest,git,make"),recommended 用于安全默认值,或 all 以允许任何命令。
干净输出和缓冲
干净输出和缓冲
使用 在非交互模式下,指示智能体做出合理假设并自主继续,而不是询问澄清问题。它还倾向于非交互命令变体(例如
-q 获得适合管道传输到其他命令的干净输出,并使用 --no-stream 缓冲完整响应(而不是流式传输)后再写入 stdout:npm init -y、apt-get install -y)。Shell 执行示例
Shell 执行示例
切换模型
你可以使用/model 命令在会话期间切换模型而无需重启 CLI,或在启动时使用 --model 标志:
/model 打开一个交互模型选择器,显示按提供商分组的可用模型。
有关切换模型、设置默认值以及添加自定义模型提供商的完整详情,请参阅 模型提供商。
交互模型选择器
交互模型选择器
选择器为高亮模型显示详细页脚,包括上下文窗口大小、输入模态(文本、图像、音频、PDF、视频)和能力(推理、工具调用、结构化输出)。被
--profile-override 或 config.toml 覆盖的值标有黄色 * 前缀。模型参数
模型参数
在会话中途切换时使用 这些是仅会话的覆盖,并具有最高优先级,覆盖配置文件
--model-params 传递额外模型构造函数参数:params 中的值。--model-params 不能与 --default 结合使用。配置
CLI 将所有配置存储在~/.deepagents/ 下。在该目录内,每个智能体都有自己的子目录(默认:agent):
| 路径 | 用途 |
|---|---|
~/.deepagents/config.toml | 模型默认值、提供商设置、构造函数参数、profile 覆盖、主题、更新设置、MCP 信任存储 |
~/.deepagents/.env | 全局 API 密钥和秘密。请参阅 配置 |
~/.deepagents/hooks.json | 生命周期事件钩子(会话开始/结束、任务完成等) |
~/.deepagents/<agent_name>/ | 每智能体记忆、技能和对话线程 |
.deepagents/ (项目根目录) | 项目特定记忆和技能,在 git 仓库内运行时加载 |
config.toml 架构、提供商参数、profile 覆盖和钩子配置 — 请参阅 配置。
记忆
自定义任何智能体主要有两种方式:-
记忆:
AGENTS.md文件和跨会话持久化的自动保存记忆。使用记忆来获取通用编码风格、偏好和学习到的约定。 - 技能:全局和项目特定的上下文、约定、指南或指令。使用技能来获取仅在执行特定任务时需要的上下文。
/remember 明确提示智能体从当前对话更新其记忆和技能。
自动记忆
当你使用智能体时,它会自动将信息存储在~/.deepagents/<agent_name>/memories/ 中作为 Markdown 文件,使用记忆优先协议:
- 研究:在开始任务之前搜索记忆以获取相关上下文
- 响应:在执行期间不确定时检查记忆
- 学习:自动保存新信息以供未来会话使用
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
全局
AGENTS.md (~/.deepagents/agent/AGENTS.md)- 你的个性、风格和通用编码偏好
- 通用语气和沟通风格
- 通用编码偏好(格式化、类型提示等)
- 适用于各处的工具使用模式
- 不随项目变化的工作流和方法论
AGENTS.md (项目根目录中的 .deepagents/AGENTS.md)- 项目特定上下文和约定
- 项目架构和设计模式
- 特定于此代码库的编码约定
- 测试策略和部署流程
- 团队指南和项目结构
使用技能
技能是可重用的智能体能力,提供专业化工作流和领域知识。 你可以使用 技能 为你的 Deep 智能体提供新能力和专业知识。 Deep 智能体技能遵循 Agent Skills 标准。 一旦你添加了技能,你的 Deep 智能体将自动使用它们,并在你使用智能体并提供额外信息时更新它们。 使用/remember 明确提示智能体从当前对话更新技能和记忆。
添加技能
添加技能
-
创建技能:
这将生成:
-
打开生成的
SKILL.md并编辑文件以包含你的指令。 -
可选地向
test-skill文件夹添加额外脚本或其他资源。有关更多信息,请参阅 示例。
安装社区技能
安装社区技能
你可以使用 Vercel 的 Skills CLI 等工具在你的环境中安装社区 Agent Skills 并使它们对你的 Deep 智能体可用:全局安装 (
-g) 将技能符号链接到 ~/.deepagents/agent/skills/ — 默认智能体的用户级技能目录。项目级安装(省略 -g)将技能放置在相对于当前目录的 .deepagents/skills/ 中,使它们对该项目中运行的任何智能体可用,无论智能体名称如何。全局安装仅针对默认
agent 目录。如果你使用自定义命名的智能体,请使用项目级安装或手动将技能符号链接到 ~/.deepagents/{your-agent}/skills/。技能发现
技能发现
在启动时,CLI 从 Deep Agents 和共享别名目录发现技能:当存在重复技能名称时,后优先级目录覆盖前优先级目录(请参阅 应用数据)。对于项目特定技能,项目的根文件夹必须有一个
.git 文件夹。
当你从项目文件夹内的任何地方启动 CLI 时,CLI 将通过检查包含的 .git 文件夹来找到项目的根文件夹。对于每个技能,CLI 从 SKILL.md 文件的 frontmatter 读取名称和描述。
当你使用 CLI 时,如果任务匹配技能的描述,智能体将读取技能文件并遵循其指令。你也可以直接使用 /skill:<name> [args] 调用技能。技能发现在启动时运行,并在 /reload 时再次运行。从命令行调用技能
从命令行调用技能
使用
--skill 在启动时调用技能而无需交互地输入斜杠命令:--skill 也适用于非交互模式:带有
--quiet 或 --no-stream 的 --skill 需要 -n(非交互模式)。列出技能
列出技能
子智能体
将自定义 子智能体 定义为 Markdown 文件,以便 CLI 智能体可以将专业化任务委托给它们。每个子智能体位于其自己的文件夹中,带有AGENTS.md 文件:
name 和 description(与 SubAgent 字典规范 相同)。Markdown 正文成为子智能体的 system_prompt。除了基础规范外,AGENTS.md 文件还支持可选的 model frontmatter 字段,该字段为此子智能体覆盖主智能体的模型。使用 provider:model-name 格式(例如 anthropic:claude-opus-4-6、openai:gpt-5.4)。省略以继承主智能体的模型。
其他
SubAgent
字段(tools、middleware、interrupt_on、skills)当前无法通过
AGENTS.md frontmatter 配置 —
以此方式定义的自定义子智能体继承主智能体的工具。直接使用 SDK 以获得完全控制。文件格式
文件格式
子智能体
AGENTS.md 文件使用 YAML frontmatter 后跟 Markdown 正文:示例:成本效益子智能体
示例:成本效益子智能体
使用 MCP 工具
使用来自外部 MCP (Model Context Protocol) 服务器的工具扩展 CLI。将.mcp.json 放置在项目根目录,CLI 会自动发现它。有关配置格式、自动发现和故障排除,请参阅 MCP 工具指南。
使用远程沙盒
CLI 使用 沙盒作为工具 模式:CLI 进程(LLM 循环、记忆、工具分发)在你的机器上运行,但智能体工具调用(read_file、write_file、execute 等)目标是远程沙盒,而不是你的本地文件系统。要将文件放入沙盒,请使用 设置脚本 或提供商的文件传输 API(请参阅 处理文件)。
有关沙盒架构、集成模式和安全最佳实践的更深入探讨,请参阅 沙盒。
LangSmith 沙盒支持默认包含在 CLI 中。AgentCore、Modal、Daytona 和 Runloop
需要安装扩展。
沙盒标志和示例
沙盒标志和示例
| 标志 | 描述 |
|---|---|
--sandbox TYPE | 要使用的沙盒提供商:langsmith、agentcore、modal、daytona 或 runloop(默认:none) |
--sandbox-id ID | 通过 ID 复用现有沙盒而不是创建新沙盒。跳过创建和清理。有关更多信息,请参阅你的沙盒文档 |
--sandbox-setup PATH | 在沙盒创建后在其中运行的设置脚本路径 |
设置脚本
设置脚本
使用 CLI 使用你的本地环境变量扩展设置脚本中的
--sandbox-setup 在创建后在沙盒内运行 Shell 脚本。这对于克隆仓库、安装依赖和配置环境变量很有用。setup.sh
${VAR} 引用。将秘密存储在本地 .env 文件中以供设置脚本访问。使用 LangSmith 追踪
启用 LangSmith 追踪以在 LangSmith 项目中查看智能体操作、工具调用和决策。 将你的追踪密钥添加到~/.deepagents/.env,以便在每个会话中启用追踪而无需每 Shell 导出:
~/.deepagents/.env
.env。有关完整加载顺序,请参阅 环境变量。
如果你愿意,也可以将这些设置为 Shell 环境变量。Shell 导出始终优先于 .env 值,因此这是临时覆盖或测试的好选项:
将智能体追踪与应用追踪分离
将智能体追踪与应用追踪分离
当从 LangChain 应用程序编程地调用 CLI 时(例如,作为 非交互模式 中的子进程),你的应用程序和 CLI 都会产生 LangSmith 追踪。默认情况下,这些都落入同一个项目。要将 CLI 追踪发送到专用项目,请设置 然后为你的父应用程序的追踪配置 这使你的应用级可观测性保持干净,同时仍在单独项目中捕获智能体的内部执行。你也可以使用
DEEPAGENTS_CLI_LANGSMITH_PROJECT:~/.deepagents/.env
LANGSMITH_PROJECT:~/.deepagents/.env
DEEPAGENTS_CLI_ 前缀 将 LangSmith 凭据范围限定到 CLI(例如 DEEPAGENTS_CLI_LANGSMITH_API_KEY)。/trace 打印 URL 并在浏览器中打开它。
命令参考
命令行选项
命令行选项
| 选项 | 描述 |
|---|---|
-a, --agent NAME | 使用具有分离记忆的命名智能体(默认:agent) |
-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 | 会话启动时自动提交的初始 Prompt(交互模式) |
--skill NAME | 在启动时调用技能 |
-n, --non-interactive TEXT | 非交互地运行单个任务并退出。除非设置 --shell-allow-list,否则 Shell 被禁用 |
-q, `—quiet |

