深度智能体 CLI - Docs by LangChain

深度智能体 CLI 是一个基于深度智能体 SDK 构建的开源编程智能体。 CLI 可与任何支持工具调用的大语言模型（LLM）配合使用，并允许你在输入之间切换 LLM。它保留对话中学习内容的持久记忆，维护跨会话的上下文，使用可自定义的技能，并通过审批控制执行代码。

快速开始

安装和启动

OpenAI、Anthropic 和 Google 默认已安装。其他提供商（Ollama、Groq、xAI 等）作为可选附加项提供——详见提供商。

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

deepagents

添加提供商凭据

CLI 可与任何支持工具调用的 LLM 配合使用。使用 /auth 命令为所选提供商设置 API 密钥——有关完整流程和存储详情，请参阅提供商凭据。有关其他提供商和无头运行，请参阅提供商。

网络搜索使用 Tavily，不通过 /auth 配置。如果启动时看到”Web search disabled — TAVILY_API_KEY is not set”，请将 TAVILY_API_KEY=tvly-... 添加到 ~/.deepagents/.env 并运行 /reload（或重启）。参见使用 Tavily 启用网络搜索。

给智能体一个任务

Create a Python script that prints "Hello, World!"

智能体解释查询并在修改文件前提出带差异的更改供你批准。如果需要，它可以运行 shell 命令来测试代码、检查文档或搜索网络获取最新信息。

启用追踪（可选）

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

~/.deepagents/.env

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

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

深度智能体 CLI 不正式支持 Windows。Windows 用户可以尝试在 Windows Subsystem for Linux (WSL) 下运行。

功能

深度智能体 CLI 具有以下内置功能：

文件操作 - 读取、写入和编辑文件的工具，使智能体能够管理和修改代码及文档。
Shell 执行 - 执行命令以运行测试、构建项目、管理依赖项并与版本控制交互。
远程沙箱 - 在 LangSmith、Daytona、Modal、Runloop 或 AgentCore 中运行智能体工具，而非在本地机器上。链接页面涵盖提供商安装、凭据、沙箱标志（--sandbox、--sandbox-id、--sandbox-setup）和设置脚本。
网络搜索 - 搜索网络获取最新信息和文档。需要在 TAVILY_API_KEY 中设置 Tavily API 密钥。
HTTP 请求 - 向 API 和外部服务发出 HTTP 请求以进行数据获取和集成任务。
任务规划和跟踪 - 将复杂任务分解为离散步骤并跟踪进度。
子智能体 - 使用 task 工具委派工作。在 CLI 中，将自定义子智能体定义为 AGENTS.md 文件；链接页面涵盖路径、frontmatter 和示例。
记忆存储和检索 - 跨会话存储和检索信息，使智能体能够记住项目约定和学习到的模式。
上下文压缩和卸载 - 总结较旧的对话消息并将原始内容卸载到存储，在长会话期间释放上下文窗口空间。
人机协作 - 对敏感的工具操作要求人工审批。
技能 - 使用自定义专业知识和说明扩展智能体能力。
MCP 工具 - 从模型上下文协议服务器加载外部工具。
追踪 - 在 LangSmith 中追踪智能体操作以进行可观测性和调试。

完整内置工具列表

内置工具

智能体附带以下内置工具，无需配置即可使用：

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

¹：可能具有破坏性的操作在执行前需要用户批准。要跳过人工审批，你可以切换自动批准（shift+tab）或使用该选项启动：

deepagents -y
# 或
deepagents --auto-approve

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

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

观看演示视频了解深度智能体 CLI 的工作方式。

命令参考

# 使用特定的智能体配置
deepagents --agent mybot

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

# 自动批准工具使用（跳过人机协作提示）
deepagents -y

# 列出目录内容，然后将目录摘要作为第一个提示——命令先运行，然后提交提示
# 提示无法访问命令输出
deepagents --startup-cmd "ls -la" -m "Summarize what's in this directory"

# 非交互模式带启动命令：在任务运行前显示 git 状态
# 任务无法访问命令输出
deepagents --startup-cmd "git diff --stat" -n "Review these changes"

命令行选项

选项	描述
`-a`, `--agent NAME`	使用带有独立记忆的命名智能体。覆盖 `config.toml` 中的 `[agents].recent`。默认：`agent`（或如果设置了 `[agents].recent` 则为最近使用的智能体）
`-M`, `--model MODEL`	使用特定模型（`provider:model`）
`--model-params JSON`	以 JSON 字符串传递给模型的额外关键字参数（例如 `'{"temperature": 0.7}'`）
`--default-model [MODEL]`	设置默认模型
`--clear-default-model`	清除默认模型
`-r`, `--resume [ID]`	恢复会话：`-r` 恢复最近的，`-r <ID>` 恢复特定线程
`-m`, `--message TEXT`	会话启动时自动提交的初始提示（交互模式）
`--skill NAME`	启动时调用技能
`--startup-cmd CMD`	启动时运行的 shell 命令，在第一个提示之前。输出在记录中渲染供你参考，但不会添加到智能体的消息历史中。要将命令输出交给智能体，请通过 stdin 管道传入（例如 `git diff \| deepagents -n "Review these changes"`）。非零退出和超时会发出警告但不会中止；非交互模式应用 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`	自动批准所有工具调用而不提示（禁用人机协作）。在交互式会话中使用 `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 字段。

配置

有关完整参考——包括 config.toml 模式、提供商参数、配置文件覆盖和钩子配置——请参阅配置。 CLI 将所有配置存储在 ~/.deepagents/ 下。在该目录中，每个智能体有自己的子目录（默认：agent）：

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

# 列出所有配置的智能体
deepagents agents list

交互模式

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

斜杠命令

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

/model - 切换模型或打开交互式模型选择器。
/agents - 在预配置的智能体之间热切换而不重新启动。参见命令参考了解详情
/auth - 管理模型提供商的存储 API 密钥。参见提供商凭据了解详情
/remember [context] - 回顾对话并更新记忆和技能。可选择传递额外上下文
/skill:<name> [args] - 按名称直接调用技能。技能的 SKILL.md 说明连同你提供的任何参数一起注入到提示中
/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 - 在外部编辑器中打开当前提示（$VISUAL / $EDITOR）。参见外部编辑器
/changelog - 在浏览器中打开 CLI 更新日志
/docs - 在浏览器中打开文档
/feedback - 打开 GitHub issues 页面以提交 bug 报告或功能请求
/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 "Write a Python script that prints hello world"

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

echo "Explain this code" | deepagents
cat error.log | deepagents -n "What's causing this error?"
git diff | deepagents -n "Review these changes"
git diff | deepagents --skill code-review -n 'summarize changes'

当你将管道输入与 -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 "fix the failing tests" --max-turns 10

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

干净输出和缓冲

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

deepagents -n "Generate a .gitignore for Python" -q > .gitignore
deepagents -n "List dependencies" -q --no-stream | sort

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

Shell 执行示例

# 允许特定命令（针对列表验证）
deepagents -n "Run the tests and fix failures" -S "pytest,git,make"

# 使用精选的安全命令列表
deepagents -n "Build the project" -S recommended

# 允许任何 shell 命令
deepagents -n "Fix the build" -S all

请谨慎使用。-S all（或 --shell-allow-list all）允许智能体执行任意 shell 命令而无需人工确认。

使用 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 tracing: 'my-project'

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

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

Documentation Index

​快速开始

​功能

​内置工具

​命令参考

​配置

​交互模式

​非交互模式和管道

​使用 LangSmith 追踪

快速开始

功能

内置工具

命令参考

配置

交互模式

非交互模式和管道

使用 LangSmith 追踪