/AGENTS.md` — 每个会话都加载。
* **项目**：任何 git 项目根目录中的 `.deepagents/AGENTS.md` — 当 CLI 从该项目内运行时加载。
这两个文件都会在启动时附加到系统提示中。使用 `/remember` 明确提示代理从当前对话更新其记忆和技能。
当回答项目特定问题或当您引用过去的工作或模式时，代理也可能会读取其记忆文件。
当您提供关于代理应如何行为、对其工作的反馈或要记住某些内容的指令时，代理将更新 `AGENTS.md`。
如果它从您的交互中识别出模式或偏好，它也会更新其记忆。
要在额外的记忆文件中添加更多结构化的项目知识，请将它们添加到 `.deepagents/` 中，并在 `AGENTS.md` 文件中引用它们。
您必须在 `AGENTS.md` 文件中引用额外文件，以便代理知道它们的存在。
额外文件不会在启动时读取，但代理可以在需要时引用和更新它们。
**全局 `AGENTS.md`**（`~/.deepagents/agent/AGENTS.md`）
* 您的个性、风格和通用编码偏好
* 一般语气和沟通风格
* 通用编码偏好（格式化、类型提示等）
* 适用于所有地方的工具使用模式
* 每个项目都不会改变的工作流程和方法论
**项目 `AGENTS.md`**（项目根目录中的 `.deepagents/AGENTS.md`）
* 项目特定的上下文和约定
* 项目架构和设计模式
* 特定于此代码库的编码约定
* 测试策略和部署流程
* 团队指南和项目结构
## 使用技能
技能是可重用的代理能力，提供专门的工作流程和领域知识。
您可以使用[技能](/oss/javascript/deepagents/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) 等工具在您的环境中安装社区[代理技能](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/`。
```
当存在重复的技能名称时，优先级较低的目录会覆盖优先级较高的目录（请参阅[应用数据](/oss/javascript/deepagents/data-locations#skills)）。
对于项目特定的技能，项目的根文件夹必须包含一个 `.git` 文件夹。
当您从项目文件夹内的任何位置启动 CLI 时，CLI 将通过检查包含的 `.git` 文件夹来找到项目的根文件夹。
对于每个技能，CLI 会从 `SKILL.md` 文件的前置元数据中读取名称和描述。
当您使用 CLI 时，如果任务与技能描述匹配，代理将读取技能文件并遵循其指令。
```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)）。
前置元数据需要 `name` 和 `description`（与 [SubAgent 字典规范](/oss/javascript/deepagents/subagents#subagent-dictionary-based)相同）。markdown 正文成为子代理的 `system_prompt`。除了基本规范外，`AGENTS.md` 文件还支持可选的 `model` 前置元数据字段，该字段会为此子代理覆盖主代理的模型。使用 `provider:model-name` 格式（例如 `anthropic:claude-haiku-4-5-20251001`、`openai:gpt-4o`）。省略则继承主代理的模型。
其他 SubAgent 字段（`tools`、`middleware`、`interrupt_on`、`skills`）不能通过 `AGENTS.md` 前置元数据进行配置 — 以这种方式定义的自定义子代理会继承主代理的工具。如需完全控制，请直接使用 SDK。
子代理 `AGENTS.md` 文件使用 YAML 前置元数据，后跟 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（模型上下文协议）](https://modelcontextprotocol.io/)服务器的工具扩展 CLI。将 `.mcp.json` 放在项目根目录，CLI 会自动发现它。有关配置格式、自动发现和故障排除，请参阅 [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-agentcore-codeinterpreter
```
```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-runloop
```
```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"}}
export LANGSMITH_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"}}
export DAYTONA_API_KEY="your-key"
```
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
export RUNLOOP_API_KEY="your-key"
```
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
modal setup
```
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
deepagents --sandbox langsmith
```
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
deepagents --sandbox agentcore
```
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
deepagents --sandbox daytona
```
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
deepagents --sandbox runloop
```
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
deepagents --sandbox modal
```
| 标志 | 描述 |
| ---------------------- | -------------------------------------------------------------------------- |
| `--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` 文件中，以便设置脚本访问。
沙箱隔离代码执行，但代理仍然容易受到不受信任输入的提示注入攻击。请使用人机协同批准、短期秘密和仅受信任的设置脚本。有关详细信息，请参阅[安全考虑](/oss/javascript/deepagents/sandboxes#security-considerations)。
## 使用 LangSmith 追踪
启用 LangSmith 追踪以在 LangSmith 项目中查看代理操作：
1. 启用 LangSmith 追踪：
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
export LANGCHAIN_TRACING=true
export LANGCHAIN_API_KEY="your-api-key"
```
2. 为深度代理操作（如工具调用和代理决策）配置代理追踪：
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
export DEEPAGENTS_LANGSMITH_PROJECT="my-deep-agent-execution"
```
3. 如果您正在使用 Deep Agents 构建 LangChain 应用，并希望将代理追踪与应用追踪分开，也请配置 `LANGSMITH_PROJECT`：
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
export LANGSMITH_PROJECT="my-app-calls-to-langchain"
```
配置后，CLI 会显示：
````sh theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
✓ LangSmith tracing: 'my-project'
```##命令参考
```bash
# 使用特定的代理配置
deepagents --agent mybot
# 使用特定模型（格式：提供者:模型 或自动检测）
deepagents --model anthropic:claude-sonnet-4-5
deepagents --model gpt-4o
# 自动批准工具使用（跳过人工介入提示）
deepagents -y
````
| 选项 | 描述 |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `-a`, `--agent NAME` | 使用具有独立记忆的命名代理（默认值：`agent`） |
| `-M`, `--model MODEL` | 使用特定模型（`提供者:模型`） |
| `--model-params JSON` | 以 JSON 字符串形式传递给模型的额外 kwargs（例如 `'{"temperature": 0.7}'`） |
| `--default-model [MODEL]` | 设置默认模型 |
| `--clear-default-model` | 清除默认模型 |
| `-r`, `--resume [ID]` | 恢复会话：`-r` 恢复最近会话，`-r ` 恢复特定线程 |
| `-m`, `--message TEXT` | 会话启动时自动提交的初始提示（交互模式） |
| `-n`, `--non-interactive TEXT` | 以非交互方式运行单个任务后退出。除非设置 `--shell-allow-list`，否则禁用 Shell |
| `-q`, `--quiet` | 干净的管道输出——仅代理的响应输出到 stdout。需要 `-n` 或管道 stdin |
| `--no-stream` | 缓冲完整响应并一次性写入 stdout，而非流式输出。需要 `-n` 或管道 stdin |
| `-y`, `--auto-approve` | 自动批准所有工具调用而不提示（禁用人工介入）。在交互会话期间可使用 `Shift+Tab` 切换 |
| `-S`, `--shell-allow-list LIST` | 要自动批准的 Shell 命令列表（逗号分隔），`'recommended'` 表示安全默认值，或 `'all'` 允许任何命令。同时适用于 `-n` 和交互模式 |
| `--json` | 从管理子命令（`list`、`reset`、`threads`、`skills`）输出机器可读的 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` | 信任项目级 MCP 配置中的 stdio 服务器（跳过批准提示） |
| `-v`, `--version` | 显示版本 |
| `-h`, `--help` | 显示帮助 |
| 命令 | 描述 |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deepagents help` | 显示帮助 |
| `deepagents list` | 列出所有代理 |
| `deepagents reset --agent NAME` | 清除代理记忆并重置为默认值 |
| `deepagents reset --agent NAME --target SOURCE` | 从另一个代理复制记忆 |
| `deepagents skills list [--project]` | 列出所有技能（别名：`ls`） |
| `deepagents skills create NAME [--project]` | 使用模板 `SKILL.md` 创建新技能 |
| `deepagents skills info NAME [--project]` | 显示技能的详细信息 |
| `deepagents skills delete NAME [--project] [-f]` | 删除技能及其内容 |
| `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` | 删除会话 |
所有管理子命令均支持 `--json` 以输出机器可读格式。详见[命令行选项](#命令行选项)。
***
[Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/i18n\zh-CN\oss\deepagents\cli\overview.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
[Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
Deep Agents CLI 具有以下内置功能：
*