> ## 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. # Deep Agents CLI > 基于 Deep Agents SDK 构建的终端编码代理 Deep Agents CLI 是一个开源的终端编码代理，构建于 [Deep Agents SDK](/oss/javascript/deepagents/quickstart) 之上。 它具备持久记忆、跨会话上下文维护、学习项目约定、使用可定制技能以及带审批控制执行代码的能力。 Deep Agents CLI Deep Agents CLI 具有以下内置功能： * **文件操作** - 使用工具读取、写入和编辑文件，使代理能够管理和修改代码与文档。 * **Shell 执行** - 执行命令以运行测试、构建项目、管理依赖项并与版本控制系统交互。 * **网络搜索** - 搜索网络以获取最新信息和文档（需要 Tavily API 密钥）。 * **HTTP 请求** - 向 API 和外部服务发起 HTTP 请求，用于数据获取和集成任务。 * **任务规划与跟踪** - 将复杂任务分解为离散步骤并跟踪进度。 * **记忆存储与检索** - 跨会话存储和检索信息，使代理能够记住项目约定和学习到的模式。 * **上下文压缩与卸载** - 总结较旧的对话消息，并将原始消息卸载到存储中，在长时间会话中释放上下文窗口空间。 * **Human in the Loop** - 要求对敏感工具操作进行人工批准。 * **技能** - 使用自定义专业知识和指令扩展代理能力。 * **[MCP 工具](/oss/javascript/deepagents/cli/mcp-tools)** - 从 [Model Context Protocol](https://modelcontextprotocol.io/) 服务器加载外部工具。 * **[追踪](/oss/javascript/deepagents/cli/overview#tracing-with-langsmith)** - 在 LangSmith 中追踪代理操作，用于可观测性和调试。 ## 内置工具 代理附带以下内置工具，无需配置即可使用： | 工具 | 描述 | Human in the Loop | | ---------------------- | ---------------------------------- | ----------------- | | `ls` | 列出文件和目录 | - | | `read_file` | 读取文件内容；部分模型支持多模态内容 | - | | `write_file` | 创建或覆盖文件 | 需要1 | | `edit_file` | 对现有文件进行定向编辑 | 需要1 | | `glob` | 查找匹配模式的文件 | - | | `grep` | 在文件中搜索文本模式 | - | | `execute` | 在本地或远程沙箱中执行 shell 命令 | 需要1 | | `web_search` | 使用 Tavily 搜索网络 | 需要1 | | `fetch_url` | 获取网页并转换为 markdown | 需要1 | | `task` | 将工作委派给子代理以并行执行 | 需要1 | | `ask_user` | 向用户提出自由形式或多项选择题 | - | | `compact_conversation` | 总结较旧的消息，将原始消息卸载到后端存储，并在上下文中用摘要替换它们 | 混合2 | | `write_todos` | 为复杂工作创建和管理任务列表 | - | 1：潜在的破坏性操作在执行前需要用户批准。要绕过人工批准，您可以切换自动批准（shift+tab）或使用以下选项启动： ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} 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` 环境变量。有关更多详细信息，请参阅[非交互模式和管道](#non-interactive-mode-and-piping)。 2：当令牌使用量超过模型感知阈值时，CLI 会在后台自动卸载对话。卸载通过 LLM 总结较旧的消息，并将原始消息弹出到存储（`/conversation_history/{thread_id}.md`），并在上下文中用摘要替换它们。如果需要，代理仍然可以从卸载的文件中检索完整历史记录。`compact_conversation` 工具允许代理（或您）按需触发卸载。作为工具调用时，默认需要用户批准。 [观看演示视频](https://youtu.be/IrnacLa9PJc?si=3yUnPbxnm2yaqVQb) 以了解 Deep Agents CLI 的工作原理。 Deep Agents CLI 在 Windows 上未得到官方支持。Windows 用户可以尝试在 [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/install) 下运行它。 ## 快速开始 将您的提供商 API 密钥导出为环境变量，或将其添加到 `~/.deepagents/.env`： ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} export OPENAI_API_KEY="your-api-key" ``` ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} export ANTHROPIC_API_KEY="your-api-key" ``` ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} export GOOGLE_API_KEY="your-api-key" ``` 有关支持的提供商完整列表及其所需的环境变量，请参阅[提供商](#providers)。 为避免在每个终端会话中设置密钥，请将它们添加到 `~/.deepagents/.env`。请参阅[环境变量](/oss/javascript/deepagents/cli/configuration#environment-variables)。 CLI 适用于任何支持工具调用的 LLM。OpenAI、Anthropic 和 Google 默认已安装。对于其他提供商（Ollama、Groq、xAI 等），请参阅[提供商](#providers)。 OpenAI、Anthropic 和 Google 默认已安装。其他提供商（Ollama、Groq、xAI 等）作为可选附加组件提供——有关详细信息，请参阅[提供商](#providers)。 ```bash Script theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} curl -LsSf https://langch.in/gh-da-cli | bash ``` ```bash Optional extras theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} # OpenAI、Anthropic 和 Gemini 默认包含 DEEPAGENTS_EXTRAS="ollama,groq" curl -LsSf https://langch.in/gh-da-cli | bash ``` ```bash uv theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} uv tool install 'deepagents-cli[ollama,groq]' ``` ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} deepagents ``` ```txt theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} 创建一个打印 "Hello, World!" 的 Python 脚本 ``` 代理会提出带有差异的更改供您批准，然后再修改文件。 要在 LangSmith 中查看代理操作、工具调用和决策，请将以下内容添加到 `~/.deepagents/.env` 或在 shell 中导出变量： ```bash title="~/.deepagents/.env" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} LANGSMITH_TRACING=true LANGSMITH_API_KEY=lsv2_... LANGSMITH_PROJECT=optional-project-name # 指定项目名称或默认为 "deepagents-cli" ``` 有关设置详细信息和用法，请参阅[使用 LangSmith 追踪](#tracing-with-langsmith)。 ## 提供商 OpenAI、Anthropic 和 Google 开箱即用。其他提供商单独安装，因此您只需引入所需内容。 ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} # 向现有安装添加额外提供商 uv tool install deepagents-cli --with langchain-xai ``` 有关支持的提供商完整列表，请参阅[模型提供商](/oss/javascript/deepagents/cli/providers)。 ## 交互模式 像在聊天界面中一样自然地输入。 代理将使用其内置工具、技能和记忆来帮助您完成任务。 在 CLI 会话中使用这些命令： * `/model` - 切换模型或打开交互式模型选择器。有关详细信息，请参阅[切换模型](#switch-models) * `/agents` - 在预配置的代理之间热交换，无需重新启动。有关详细信息，请参阅[切换代理](#switch-agents) * `/remember [context]` - 审查对话并更新记忆和技能。可选地传递额外上下文 * `/skill: [args]` - 按名称直接调用技能。技能的 `SKILL.md` 指令会与您提供的任何参数一起注入到提示中 * `/skill-creator [args]` - 创建有效代理技能的指南 * `/offload`（别名 `/compact`）- 通过将消息卸载到存储并带有摘要占位符来释放上下文窗口空间。如果需要，代理可以从卸载的文件中检索完整历史记录 * `/tokens` - 显示当前上下文窗口令牌使用情况细分 * `/clear` - 清除对话历史并开始新线程 * `/threads` - 浏览并恢复之前的对话线程 * `/mcp` - 显示活动的 MCP 服务器和工具 * `/reload` - 重新读取 `.env` 文件，刷新配置，并重新发现技能，无需重启。对话状态得以保留。有关覆盖行为，请参阅 [`DEEPAGENTS_CLI_` 前缀](/oss/javascript/deepagents/cli/configuration#deepagents_cli_-prefix) * `/theme` - 打开交互式主题选择器以切换颜色主题。内置主题可用，以及任何[用户定义主题](/oss/javascript/deepagents/cli/configuration#themes) * `/update` - 检查并内联安装 CLI 更新。检测您的安装方法（uv、Homebrew、pip）并运行相应的升级命令 * `/auto-update` - 切换自动更新开或关 * `/trace` - 在 LangSmith 中打开当前线程（需要 `LANGSMITH_API_KEY`） * `/editor` - 在外部编辑器（`$VISUAL` / `$EDITOR`）中打开当前提示。请参阅[外部编辑器](/oss/javascript/deepagents/cli/configuration#external-editor) * `/changelog` - 在浏览器中打开 CLI 变更日志 * `/docs` - 在浏览器中打开文档 * `/feedback` - 打开 GitHub issues 页面以提交错误报告或功能请求 * `/version` - 显示已安装的 `deepagents-cli` 和 SDK 版本 * `/help` - 显示帮助和可用命令 * `/quit` - 退出 CLI 输入 `!` 进入 shell 模式，然后输入您的命令。 ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} 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： ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} deepagents -n "编写一个打印 hello world 的 Python 脚本" ``` 您也可以通过 stdin 管道输入。当输入被管道传输时，CLI 自动以非交互方式运行： ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} 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` 以允许任何命令。 CI/CD 管道中长时间运行或行为异常的代理可能会无限循环。`--max-turns N` 为操作员提供了一个硬性上限，而无需触及 SDK 内部： ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} deepagents -n "修复失败的测试" --max-turns 10 ``` `N` 必须是正整数，并覆盖内部安全默认值，否则该默认值会限制失控循环。当超出预算时，以代码 124 退出（与 GNU `timeout` 匹配），因此 CI 可以区分预算命中和一般故障。需要 `-n` 或管道 stdin；否则以代码 2 退出。 使用 `-q` 获得适合管道传输到其他命令的干净输出，使用 `--no-stream` 在写入 stdout 之前缓冲完整响应（而不是流式传输）： ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} deepagents -n "为 Python 生成 .gitignore" -q > .gitignore deepagents -n "列出依赖项" -q --no-stream | sort ``` 在非交互模式下，代理被指示做出合理的假设并自主进行，而不是提出澄清问题。它还倾向于使用非交互式命令变体（例如 `npm init -y`、`apt-get install -y`）。 ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} # 允许特定命令（根据列表进行验证） 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`、列出文件或验证环境设置非常方便。 ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} # 交互式：在第一个提示之前显示 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： ```txt theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} > /model anthropic:claude-opus-4-6 > /model openai:gpt-5.5 ``` ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} deepagents --model openai:gpt-5.5 ``` 运行 `/model` 打开交互式模型选择器，该选择器按提供商分组显示可用模型。 有关切换模型、设置默认值和添加自定义模型提供商的完整详细信息，请参阅[模型提供商](/oss/javascript/deepagents/cli/providers)。 ### 模型参数 通过在启动时向 `--model-params` 传递 JSON 或在会话中向 `/model --model-params` 传递 JSON 来覆盖模型调用参数（例如推理努力、思考预算、最大输出令牌等）： ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} deepagents --model openai:gpt-5.5 --model-params '{"reasoning": {"effort": "high"}}' ``` ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} deepagents --model anthropic:claude-opus-4-7 --model-params '{"thinking": {"type": "enabled", "budget_tokens": 10000}}' ``` ```txt theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} # 会话中——一步切换模型和参数 /model --model-params '{"temperature": 0.7}' anthropic:claude-opus-4-7 # 或打开选择器并将参数应用于您选择的任何模型 /model --model-params '{"num_ctx": 16384}' ``` CLI 标志仅限会话。`--model-params` 不能与 `--default` 结合使用。有关持久的提供商级别默认值、每个模型的覆盖以及提供商特定示例，请参阅提供商页面上的[模型参数](/oss/javascript/deepagents/cli/providers#model-parameters)。 ## 切换代理 运行 `/agents` 打开代理选择器，并在 `~/.deepagents/` 中的代理之间热交换，无需重新启动。切换会重置对话线程并刷新技能发现。选择会被持久化，因此下一次裸 `deepagents` 启动将恢复相同的代理。`-a`/`--agent` 始终覆盖；`-r`/`--resume` 恢复线程的原始代理。 ## 配置 CLI 将所有配置存储在 `~/.deepagents/` 下。在该目录中，每个代理都有自己的子目录（默认：`agent`）： | 路径 | 用途 | | ----------------------------- | ---------------------------------------------------------------------------------------- | | `~/.deepagents/config.toml` | 模型默认值、提供商设置、构造函数参数、配置文件覆盖、主题、更新设置、MCP 信任存储 | | `~/.deepagents/.env` | 全局 API 密钥和密钥。请参阅[配置](/oss/javascript/deepagents/cli/configuration#environment-variables) | | `~/.deepagents/hooks.json` | 生命周期事件钩子（会话开始/结束、任务完成等） | | `~/.deepagents//` | 每个代理的记忆、技能和对话线程 | | `.deepagents/`（项目根目录） | 项目特定的记忆和技能，在 git 仓库内运行时加载 | ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} # 列出所有配置的代理 deepagents agents list ``` 有关完整参考——包括 `config.toml` 模式、提供商参数、配置文件覆盖和钩子配置——请参阅[配置](/oss/javascript/deepagents/cli/configuration)。 ## 记忆 自定义任何代理有两种主要方式： * **记忆**：`AGENTS.md` 文件和跨会话持久化的自动保存记忆。将记忆用于通用编码风格、偏好和学习到的约定。 * **技能**：全局和项目特定的上下文、约定、指南或指令。将技能用于仅在执行特定任务时需要的上下文。 使用 `/remember` 明确提示代理从当前对话更新其记忆和技能。 使用 SDK 构建自定义代理？有关编程记忆后端，请参阅[记忆](/oss/javascript/deepagents/memory)。 ### 自动记忆 当您使用代理时，它会使用记忆优先协议自动将信息存储在 `~/.deepagents//memories/` 中的 markdown 文件中： 1. **研究**：在开始任务之前搜索记忆以获取相关上下文 2. **响应**：在执行过程中不确定时检查记忆 3. **学习**：自动保存新信息以供未来会话使用 代理按主题组织其记忆，并使用描述性文件名： ``` ~/.deepagents/backend-dev/memories/ ├── api-conventions.md ├── database-schema.md └── deployment-process.md ``` 当您教代理约定时： ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} deepagents --agent backend-dev > 我们的 API 使用 snake_case 并包含 created_at/updated_at 时间戳 ``` 它会为未来的会话记住： ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} > 创建一个 /users 端点 # 应用约定而无需提示 ``` ### AGENTS.md 文件 [`AGENTS.md` 文件](https://agents.md/)提供持久上下文，在会话开始时始终加载： * **全局**：`~/.deepagents//AGENTS.md` — 每次会话加载。 * **项目**：任何 git 项目根目录中的 `.deepagents/AGENTS.md` — 当 CLI 从该项目内运行时加载。 这两个文件在启动时都会附加到系统提示中。 代理在回答项目特定问题或您引用过去的工作或模式时，也可能读取其记忆文件。 当您提供有关其应如何行为的信息、对其工作的反馈或记住某事的指令时，代理将更新 `AGENTS.md`。 如果它从您的交互中识别出模式或偏好，它也会更新其记忆。 要在其他记忆文件中添加更多结构化的项目知识，请将它们添加到 `.deepagents/` 中并在 `AGENTS.md` 文件中引用它们。 您必须在 `AGENTS.md` 文件中引用其他文件，代理才能意识到它们。 其他文件不会在启动时读取，但代理可以在需要时引用和更新它们。 **全局 `AGENTS.md`**（`~/.deepagents/agent/AGENTS.md`） * 您的个性、风格和通用编码偏好 * 一般语气和沟通风格 * 通用编码偏好（格式化、类型提示等） * 适用于所有地方的工具使用模式 * 不随项目变化的工作流程和方法 **项目 `AGENTS.md`**（项目根目录中的 `.deepagents/AGENTS.md`） * 项目特定的上下文和约定 * 项目架构和设计模式 * 特定于此代码库的编码约定 * 测试策略和部署流程 * 团队指南和项目结构 ## 使用技能 技能是可重用的代理能力，提供专门的工作流程和领域知识。 您可以使用[技能](/oss/javascript/deepagents/skills)为您的深度代理提供新的能力和专业知识。 深度代理技能遵循 [Agent Skills 标准](https://agentskills.io/)。 一旦您添加了技能，您的深度代理将自动使用它们，并在您使用代理并提供额外信息时更新它们。 使用 `/remember` 明确提示代理从当前对话更新技能和记忆。 1. 创建技能： ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} # 用户技能（存储在 ~/.deepagents//skills/ 中） deepagents skills create test-skill # 项目技能（存储在 .deepagents/skills/ 中） deepagents skills create test-skill --project ``` 这将生成： ```plaintext theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} skills/ └── test-skill └── SKILL.md ``` 2. 打开生成的 `SKILL.md` 并编辑文件以包含您的指令。 3. 可选地向 `test-skill` 文件夹添加额外的脚本或其他资源。有关更多信息，请参阅[示例](/oss/javascript/deepagents/skills#example)。 您也可以将现有技能直接复制到代理的文件夹： ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} mkdir -p ~/.deepagents//skills cp -r examples/skills/web-research ~/.deepagents//skills/ ``` 您可以使用 Vercel 的 [Skills CLI](https://github.com/vercel-labs/skills) 等工具在您的环境中安装社区 [Agent Skills](https://agentskills.io/)，并使其可供您的深度代理使用： ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} # 全局安装技能 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 和共享别名目录中发现技能： ```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} ~/.deepagents//skills/ ~/.agents/skills/ .deepagents/skills/ .agents/skills/ ~/.claude/skills/ （实验性） .claude/skills/ （实验性） ``` 当存在重复的技能名称时，后优先级目录覆盖前一个（请参阅[应用数据](/oss/javascript/deepagents/data-locations#skills)）。 对于项目特定的技能，项目的根文件夹必须有一个 `.git` 文件夹。 当您从项目文件夹内的任何位置启动 CLI 时，CLI 将通过检查包含的 `.git` 文件夹来找到项目的根文件夹。 对于每个技能，CLI 从 `SKILL.md` 文件的 frontmatter 中读取名称和描述。 当您使用 CLI 时，如果任务与技能的描述匹配，代理将读取技能文件并遵循其指令。 您也可以使用 `/skill: [args]` 直接调用技能。技能发现在启动时运行，并在 `/reload` 时再次运行。 使用 `--skill` 在启动时调用技能，而无需交互式输入斜杠命令： ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} # 打开 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` 在非交互模式下也有效： ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} # 无头运行技能 deepagents --skill code-review -n '审查此补丁' # 安静模式（仅代理输出到 stdout） deepagents --skill code-review -n '审查此补丁' -q ``` `--skill` 与 `--quiet` 或 `--no-stream` 需要 `-n`（非交互模式）。 ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} # 列出所有用户技能 deepagents skills list # 列出项目技能 deepagents skills list --project # 获取有关特定技能的详细信息 deepagents skills info test-skill deepagents skills info test-skill --project ``` ## 子代理 将自定义[子代理](/oss/javascript/deepagents/subagents)定义为 markdown 文件，以便 CLI 代理可以将专门任务委派给它们。每个子代理位于自己的文件夹中，包含一个 `AGENTS.md` 文件： ```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} .deepagents/agents/{subagent-name}/AGENTS.md # 项目级 ~/.deepagents/{agent}/agents/{subagent-name}/AGENTS.md # 用户级 ``` 项目子代理覆盖同名的用户子代理（请参阅[优先级规则](/oss/javascript/deepagents/data-locations#subagents)）。 frontmatter 需要 `name` 和 `description`（与 [`SubAgent` 字典规范](/oss/javascript/deepagents/subagents#subagent-dictionary-based)相同）。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 正文： ```markdown theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} --- name: researcher description: 在撰写内容之前研究网络主题 model: anthropic:claude-haiku-4-5-20251001 --- 您是一个可以访问网络搜索的研究助理。 ## 您的流程 1. 搜索相关信息 2. 清晰地总结发现 ``` 对于简单的委派任务使用更便宜、更快的模型，同时将主代理保留在更强大的模型上： ```markdown theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} --- name: general-purpose description: 用于研究和多步骤任务的通用代理 model: anthropic:claude-haiku-4-5-20251001 --- 您是一个通用助理。高效完成任务并返回简洁的摘要。 ``` 这将覆盖内置的通用子代理，将所有委派任务路由到更便宜的模型。有关更多信息，请参阅[覆盖通用子代理](/oss/javascript/deepagents/subagents#override-the-general-purpose-subagent)。 ## 使用 MCP 工具 使用来自外部 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 服务器的工具扩展 CLI。在项目根目录放置一个 `.mcp.json`，CLI 会自动发现它。需要 OAuth 的服务器（Slack、GitHub、Linear、Notion 等）可以使用 `deepagents mcp login ` 进行一次身份验证；令牌会持久化到 `~/.deepagents/mcp-tokens/` 并自动刷新。有关配置格式、OAuth 登录、自动发现和故障排除，请参阅 [MCP 工具指南](/oss/javascript/deepagents/cli/mcp-tools)。 ## 使用远程沙箱 CLI 使用[沙箱作为工具](/oss/javascript/deepagents/sandboxes#sandbox-as-tool-pattern)模式：CLI 进程（LLM 循环、记忆、工具分派）在您的机器上运行，但代理工具调用（`read_file`、`write_file`、`execute` 等）针对远程沙箱，而不是您的本地文件系统。要将文件放入沙箱，请使用[设置脚本](#setup-scripts)或提供商的文件传输 API（请参阅[处理文件](/oss/javascript/deepagents/sandboxes#working-with-files)）。 有关沙箱架构、集成模式和安全最佳实践的更深入了解，请参阅[沙箱](/oss/javascript/deepagents/sandboxes)。 LangSmith 沙箱支持默认包含在 CLI 中。AgentCore、Modal、Daytona 和 Runloop 需要安装附加组件。 安装 `deepagents-cli` 时默认包含。无需额外安装。 ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} uv tool install deepagents-cli --with langchain-daytona ``` ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} uv tool install deepagents-cli --with langchain-modal ``` ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} uv tool install deepagents-cli --with langchain-runloop ``` ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} uv tool install deepagents-cli --with langchain-agentcore-codeinterpreter ``` ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} export LANGSMITH_API_KEY="your-key" ``` ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} export DAYTONA_API_KEY="your-key" ``` ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} modal setup ``` ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} export RUNLOOP_API_KEY="your-key" ``` ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} 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" ``` ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} deepagents --sandbox langsmith ``` ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} deepagents --sandbox daytona ``` ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} deepagents --sandbox modal ``` ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} deepagents --sandbox runloop ``` ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} deepagents --sandbox agentcore ``` | 标志 | 描述 | | ---------------------- | -------------------------------------------------------------------------- | | `--sandbox TYPE` | 要使用的沙箱提供商：`langsmith`、`agentcore`、`modal`、`daytona` 或 `runloop`（默认：`none`） | | `--sandbox-id ID` | 通过 ID 重用现有沙箱，而不是创建新的。跳过创建和清理。有关更多信息，请参阅您的沙箱文档 | | `--sandbox-setup PATH` | 在创建时在沙箱内运行的设置脚本路径 | 示例： ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} # 创建新的 Daytona 沙箱 deepagents --sandbox daytona # 重用现有沙箱（跳过创建和清理） deepagents --sandbox runloop --sandbox-id dbx_abc123 # 在沙箱创建后运行设置脚本 deepagents --sandbox modal --sandbox-setup ./setup.sh ``` 使用 `--sandbox-setup` 在创建后在沙箱内运行 shell 脚本。这对于克隆仓库、安装依赖项和配置环境变量非常有用。 ```bash title="setup.sh" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} #!/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批准、短期密钥和受信任的设置脚本。有关详细信息，请参阅[安全注意事项](/oss/javascript/deepagents/sandboxes#security-considerations)。 ## 使用 LangSmith 追踪 启用 [LangSmith](https://smith.langchain.com/) 追踪以在 LangSmith 项目中查看代理操作、工具调用和决策。 将您的追踪密钥添加到 `~/.deepagents/.env`，以便在每个会话中启用追踪，而无需每次 shell 导出： ```bash title="~/.deepagents/.env" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} LANGSMITH_TRACING=true LANGSMITH_API_KEY=lsv2_... LANGSMITH_PROJECT=optional-project-name # 指定项目名称或默认为 "deepagents-cli" ``` 要为特定项目覆盖，请将相同的密钥添加到项目目录中的 `.env`。有关完整的加载顺序，请参阅[环境变量](/oss/javascript/deepagents/cli/configuration#environment-variables)。 如果您愿意，也可以将这些设置为 shell 环境变量。Shell 导出始终优先于 `.env` 值，因此这是临时覆盖或测试的好选择： ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} export LANGSMITH_TRACING=false ``` 当从 LangChain 应用程序以编程方式调用 CLI 时（例如，在[非交互模式](#non-interactive-mode-and-piping)中作为子进程），您的应用程序和 CLI 都会产生 LangSmith 追踪。默认情况下，这些都落在同一个项目中。 要将 CLI 追踪发送到专用项目，请设置 `DEEPAGENTS_CLI_LANGSMITH_PROJECT`： ```bash title="~/.deepagents/.env" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} DEEPAGENTS_CLI_LANGSMITH_PROJECT=my-deep-agent-execution ``` 然后为父应用程序的追踪配置 `LANGSMITH_PROJECT`： ```bash title="~/.deepagents/.env" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} LANGSMITH_PROJECT=my-app-traces ``` 这使您的应用程序级可观测性保持干净，同时仍在单独的项目中捕获代理的内部执行。 您也可以使用 [`DEEPAGENTS_CLI_` 前缀](/oss/javascript/deepagents/cli/configuration#deepagents_cli_-prefix)（例如 `DEEPAGENTS_CLI_LANGSMITH_API_KEY`）将 LangSmith 凭据限定到 CLI。 配置后，CLI 会显示一个状态行，其中包含指向 LangSmith 项目的链接。在支持的终端中，单击链接可直接打开它。您也可以使用 `/trace` 打印 URL 并在浏览器中打开它。 ```sh theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} ✓ LangSmith 追踪：'my-project' ``` ## 命令参考 ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} # 使用特定代理配置 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 ` 用于特定线程 | | `-m`, `--message TEXT` | 会话启动时自动提交的初始提示（交互模式） | | `--skill NAME` | 在启动时调用技能 | | `--startup-cmd CMD` | 在第一个提示之前在启动时运行的 shell 命令。输出呈现在记录中供您参考，但**不会**添加到代理的消息历史中。非零退出和超时会警告但不会中止；非交互模式应用 60 秒超时。请参阅[在启动时运行命令](#run-a-command-at-startup) | | `-n`, `--non-interactive TEXT` | 以非交互方式运行单个任务并退出。除非设置了 `--shell-allow-list`，否则 shell 被禁用 | | `--max-turns N` | 在非交互模式下限制代理轮次。超出时以代码 124 退出。需要 `-n` 或管道 stdin。请参阅[使用 `--max-turns` 限制轮次](#non-interactive-mode-and-piping) | | `-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` | 显示帮助 | | 命令 | 描述 | | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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 工具](/oss/javascript/deepagents/cli/mcp-tools#oauth-login) | | `deepagents deploy` | 将您的代理部署到 LangSmith。请参阅[使用 CLI 部署](/oss/javascript/deepagents/deploy) | 所有管理子命令都支持 `--json` 以获得机器可读的输出。有关详细信息，请参阅[命令行选项](#command-line-options)。 破坏性命令（`agents reset`、`skills delete`、`threads delete`）支持 `--dry-run` 以预览将发生的情况而不进行更改。在 JSON 模式下，`--dry-run` 返回相同的信封，其中包含 `dry_run: true` 字段。 ***
[将这些文档连接](/use-these-docs)到 Claude、VSCode 等，通过 MCP 获得实时答案。 [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/oss/deepagents/cli/overview.mdx) 或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。