Deep Agents 框架-CLI

引言

本文主要介绍一下Deep Agents CLI，不是核心知识。Deep Agents CLI 是一个基于 Deep Agents SDK 构建的开源终端编程助手。它具备持久化记忆 ，能在不同会话间保持上下文连贯，能学习项目的代码规范，支持自定义技能，并且在执行代码时还设有审批控制机制。

这就相当于给刚才提到的"终端助手"做了一次全身"体检"，列出了它具体能干哪些活儿。从写代码到上网查资料，甚至还能自己学着变聪明，功能确实挺全的。

来看看它的内置超能力清单：

🛠️ 核心能力概览

📂 文件操作

读取、写入和编辑文件，让助手能帮你管理和修改代码及文档。

💻 终端执行

执行各种命令，比如运行测试、构建项目、管理依赖包，或者跟版本控制系统（比如 Git）打交道。

🌐 网络搜索

上网搜索最新的信息和文档（这个功能需要配置 Tavily API 密钥）。

📡 HTTP 请求

发送 HTTP 请求去连接外部 API 或服务，方便抓取数据或做集成任务。

📝 任务规划与追踪

把复杂的大任务拆解成一个个具体的步骤，并实时追踪进度。

🧠 记忆存取

在不同会话之间存取信息，让助手能记住项目的规范和它之前学到的套路。

🗜️ 上下文压缩与卸载

把旧的对话消息总结压缩，把原始内容存起来，这样在长对话中就能腾出空间，防止"大脑"过载。

🤝 人机协作

遇到敏感操作时，必须经过你的批准才能执行。

🎓 技能扩展

通过自定义的专长和指令，给助手"补课"，扩展它的能力边界。

🔌 MCP 工具支持

能够从 Model Context Protocol 服务器加载外部工具。

🔍 链路追踪

在 LangSmith 上追踪助手的操作，方便你观察运行状态和排查 Bug。

🛠️ 内置工具概览

🔒 安全机制（人机协作）

无需批准：像查看文件、搜索文本这类只读操作，Agent 可以自己做主。
必须批准：涉及修改文件、执行命令、联网或创建子任务等"危险"操作，Agent 必须先问你："我可以这样做吗？"

📋 工具分类

文件管理 ：ls（列目录）、read_file（读文件）、write_file（写文件）、edit_file（改文件）、glob（找文件）、grep（搜文本）。
系统与网络 ：execute（跑命令）、web_search（上网搜）、fetch_url（抓网页）。
任务与交互 ：task（分派给子代理）、ask_user（问用户）、write_todos（写待办清单）。
上下文优化 ：compact_conversation（压缩对话历史，省内存）。

1 那些具有潜在破坏性的操作（比如写文件、执行命令），在执行前通常需要你手动批准。

如果你想跳过这个确认步骤，可以按快捷键 Shift+Tab 开启自动批准模式，或者在启动时直接加上相应的命令行选项。

复制代码

deepagents -y
# or
deepagents --auto-approve

当你通过 -n 或管道输入（piped stdin）以非交互式模式 运行 CLI 时，即使你加了 -y 或 --auto-approve（自动批准）参数，Shell 命令执行功能默认也是被禁用的 。你需要使用 -S 或 --shell-allow-list 参数来指定允许执行的命令白名单（比如 -S "pytest,git,make"），这是推荐的安全做法；当然，你也可以设置为 all 来允许执行任何命令此外，也可以通过设置环境变量 DEEPAGENTS_CLI_SHELL_ALLOW_LIST 来实现同样的效果。

2 当对话的 Token 用量超过模型感知的阈值时，CLI 会在后台自动进行**"记忆卸载"**。

具体流程是：利用 LLM 把旧的对话消息总结成摘要，然后把原始内容"踢"出去存到硬盘上（路径为 /conversation_history/{thread_id}.md），并在当前的上下文窗口中用摘要替换掉旧消息，从而腾出空间。虽然旧消息被移出了当前上下文，但如果 Agent 需要，它仍然可以去那个存档文件里读取完整的历史记录。此外，有一个叫 compact_conversation 的工具，可以让 Agent（或者你）随时手动触发这个压缩过程。注意：当作为工具被调用时，默认情况下需要你手动批准。

1 使用命令行

1.1 起步

设置模型凭证

将你的服务商 API 密钥导出为环境变量，或者将其添加到 ~/.deepagents/.env 文件中。

安装与运行

该命令行工具支持任何具备"工具调用"能力的 LLM。OpenAI、Anthropic 和 Google 的集成已默认安装。

若需使用其他服务商（如 Ollama、Groq、xAI 等），请查阅"Providers"章节。这些服务商属于可选的扩展组件，详情同样请参阅相关文档。

给智能体（Agent）下达一个任务

复制代码

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

智能体在修改文件之前，会先通过差异对比（diffs）的形式提出更改建议，等待你的批准。

启用追踪（可选）

若要在 LangSmith 中查看智能体的操作、工具调用及决策过程，请将以下内容添加到 ~/.deepagents/.env 文件中，或者在你的 Shell 中导出这些变量：

~/.deepagents/.env

复制代码

LANGSMITH_TRACING=true
LANGSMITH_API_KEY=lsv2_...
LANGSMITH_PROJECT=optional-project-name  # Specify a project name or default to "deepagents-cli"

1.2 供应商

penAI、Anthropic 和 Google 是开箱即用的。其他服务商则需要单独安装，这样你只需要加载自己真正需要的组件。

复制代码

# Add extra providers to an existing install
uv tool install deepagents-cli --with langchain-xai

如需查看支持的所有服务商完整列表，请参阅"Model providers"（模型服务商）章节。

1.3 交互模式

像平时聊天一样自然地输入文字即可。智能体会利用它内置的工具、技能和记忆来协助你完成任务。

1.3.1 斜杠命令

哇，这简直就是一份完整的指令清单！看来这个智能体非常强大，不仅仅是陪聊，更像是一个全能的开发助手。

我把这些命令整理并翻译成了中文，按照功能分了个类，这样你查阅起来会更方便：

🛠️ 核心控制与模型管理

/model - 切换模型或打开交互式模型选择器。（详见"切换模型"）
/agents - 在不重新启动的情况下，热切换（Hot-swap）预配置的智能体。（详见"切换智能体"）
/clear - 清空对话历史并开始新话题。
/quit - 退出命令行界面。

🧠 记忆、技能与上下文

/remember [context] - 回顾对话并更新记忆和技能。你也可以顺便传入额外的上下文信息。
/skill: [args] - 直接通过名称调用某个技能。系统会将该技能的 SKILL.md 指令以及你提供的参数一起注入到提示词中。
/skill-creator [args] - 创建高效智能体技能的指南。
/offload (别名 /compact) - 通过将消息卸载到存储区并替换为摘要占位符，来释放上下文窗口的空间。如果需要，智能体可以从卸载的文件中检索完整历史。
/tokens - 显示当前上下文窗口的 Token 使用情况明细。

⚙️ 系统与配置

/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 - 显示帮助信息和可用命令。

1.3.2 Shell 命令

输入 ! 进入 Shell 模式，然后输入你的命令。

复制代码

git status
npm test
ls -la

1.3.3 键盘快捷键

快捷键	功能说明
Enter	提交提示词
Shift+Enter / Ctrl+J / Alt+Enter / Ctrl+Enter	插入新行（换行）
Ctrl+A	选中输入框内的所有文本
@文件名	自动补全文件路径并将文件内容注入到上下文中
Shift+Tab / Ctrl+T	切换"自动批准"模式
Ctrl+U	删除光标到行首的所有内容
Ctrl+X	在外部编辑器中打开提示词进行编辑
Ctrl+O	展开/折叠最近一次的工具输出结果
Escape	中断当前操作
Ctrl+C	中断操作或退出
Ctrl+D	退出程序

1.4 非交互模式管道

使用 -n 参数来运行单个任务，而无需启动交互式界面**。**

复制代码

deepagents -n "Write a Python script that prints hello world"

你也可以通过标准输入（stdin）以管道方式传入内容。当通过管道传入内容时，命令行界面会自动以非交互式模式运行。

复制代码

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"），这是推荐的安全默认做法；或者使用 all 来允许运行任何命令。

干净输出和缓冲

为了获得干净的输出并控制缓冲，请使用 -q 来获取适合管道传输给其他命令的纯净输出，并使用 --no-stream 在写入标准输出之前缓冲完整响应（而不是流式传输）

复制代码

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执行例子

复制代码

# Allow specific commands (validated against the list)
deepagents -n "Run the tests and fix failures" -S "pytest,git,make"

# Use the curated safe-command list
deepagents -n "Build the project" -S recommended

# Allow any shell command
deepagents -n "Fix the build" -S all

请务必谨慎使用。

-S all（或者 --shell-allow-list all）允许智能体在没有任何人工确认的情况下，执行任意的 Shell 命令

1.5 启动时运行命令

使用 --startup-cmd 可以在会话接受第一个提示词之前，先运行一次 Shell 命令。该命令的输出结果会显示在会话的最上方，这对于检查 git 状态、列出文件或验证环境设置非常方便，让你能在输入第一个提示词之前就掌握情况。

复制代码

# Interactive: show git status before the first prompt
deepagents --startup-cmd "git status"

# Combine with an initial prompt --- the command runs first, then the prompt is submitted
deepagents --startup-cmd "ls -la" -m "Summarize what's in this directory"

# Non-interactive: see env state before the task runs
deepagents --startup-cmd "git diff --stat" -n "Review these changes"

该命令会在任何 -m 提示词或 --skill 调用被发送之前运行，并且会遵循你的 Shell 环境变量。如果命令退出状态码非零（即执行出错）或发生超时，系统只会发出警告，但不会中止整个会话。在非交互式模式下，该命令的超时时间为 60 秒。

特别注意：该命令的输出结果不会被注入到智能体的消息历史中------也就是说，大语言模型（LLM）是看不到这些输出的。如果想把命令的输出交给智能体处理，请通过标准输入（stdin）管道传入（例如 git diff | deepagents -n "Review these changes"）。

1.6 模型切换

你可以使用 /model 命令在会话过程中切换模型，而无需重启命令行界面；或者在启动时使用 --model 标志来指定模型：

复制代码

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

deepagents --model openai:gpt-5.5

运行 /model 可以打开一个交互式的模型选择器，它会按服务商分组显示所有可用的模型。

关于切换模型、设置默认模型以及添加自定义模型服务商的完整详情，请查阅"模型服务商"文档。

你可以通过向启动时的 --model-params 参数，或在会话中途的 /model --model-params 命令传递 JSON 格式的数据，来覆盖模型的调用参数（例如推理力度、思考预算、最大输出 token 数等）。

复制代码

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}}'

# Mid-session --- swap model and params in one step
/model --model-params '{"temperature": 0.7}' anthropic:claude-opus-4-7

# Or open the selector and apply params to whatever you pick
/model --model-params '{"num_ctx": 16384}'

命令行标志仅在当前会话中有效。--model-params 不能与 --default 组合使用。关于持久化的服务商级默认值、针对特定模型的覆盖设置以及服务商特定的示例，请查阅服务商页面上的"模型参数"部分

1.7 智能体切换

运行 /agents 可以打开智能体选择器，让你在不重启程序的情况下，在 ~/.deepagents/ 目录下的不同智能体之间进行热切换。切换智能体会重置当前的对话线程，并刷新技能发现机制。

这个选择会被持久化保存，所以下次直接运行 deepagents（不带参数）启动时，会继续使用同一个智能体。-a 或 --agent 参数总是具有最高优先级（强制覆盖）；而 -r 或 --resume 参数则用于恢复该对话线程原本绑定的智能体。

1.8 配置

该命令行工具将所有配置都存储在 ~/.deepagents/ 目录下。在该目录中，每个智能体都有自己独立的子目录（默认为 agent）：

~/.deepagents/config.toml：存放模型默认值、服务商设置、构造函数参数、配置文件覆盖、主题以及更新设置、MCP 信任存储。
~/.deepagents/.env：存放全局 API 密钥和机密信息。
~/.deepagents/hooks.json：存放生命周期事件钩子（如会话开始/结束、任务完成等）。
~/.deepagents/<agent_name>/：存放特定智能体的记忆、技能和对话线程。
.deepagents/ (项目根目录)：存放项目特定的记忆和技能，当你在 git 仓库内运行时会被加载。

List all configured agents

deepagents agents list

如需查阅完整参考文档------包括 config.toml 的结构定义、服务商参数、配置文件覆盖设置以及钩子配置------请参阅"配置"章节。

1.9 记忆

定制任何智能体主要有两种方式：

记忆：包括 AGENTS.md 文件和跨会话持久保存的自动记忆。请使用记忆功能来存储通用的编码风格、偏好设置以及已习得的惯例。
技能：包括全局的和项目特定的上下文、惯例、指南或指令。请使用技能来处理仅在执行特定任务时才需要的上下文信息。

使用 /remember 命令可以明确提示智能体根据当前的对话内容来更新其记忆和技能。

1.9.1 自动记忆

当你使用智能体时，它会自动将信息存储在 ~/.deepagents/<agent_name>/memories/ 目录下，以 Markdown 文件的形式保存，并采用"记忆优先"协议：

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

智能体会按主题组织其记忆，并使用描述性的文件名：

复制代码

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

当你教导智能体（某种）惯例时：

复制代码

deepagents --agent backend-dev
> Our API uses snake_case and includes created_at/updated_at timestamps

它会在未来的会话中记住这些内容**：**

复制代码

> Create a /users endpoint
# Applies conventions without prompting

`1.9.2 AGENTS.md` 文件

AGENTS.md 文件提供了持久化的上下文信息，这些信息会在每次会话开始时被自动加载：

全局配置：~/.deepagents/<agent_name>/AGENTS.md ------ 在每次会话中都会被加载。
项目配置：任意 Git 项目根目录下的 .deepagents/AGENTS.md ------ 当你在该项目内运行命令行工具时会被加载。

这两个文件的内容都会在启动时被追加到系统提示词中。

工作原理

智能体在回答项目特定问题，或者当你提及过去的工作或模式时，也可能会读取其记忆文件。

当你提供关于它该如何行事的信息、对其工作的反馈，或者指示它记住某事时，智能体会更新 AGENTS.md。如果它从你的互动中识别出某种模式或偏好，它也会更新其记忆。

若要在额外的记忆文件中添加更多结构化的项目知识，请将它们添加到 .deepagents/ 目录中，并在 AGENTS.md 文件中引用它们。你必须在 AGENTS.md 中引用额外文件，智能体才会知道它们的存在。这些额外文件不会在启动时被读取，但智能体可以在需要时引用并更新它们。

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

全局 AGENTS.md (~/.deepagents/agent/AGENTS.md)

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

项目 AGENTS.md (项目根目录下的 .deepagents/AGENTS.md)

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

1.10 使用技能

技能是智能体可复用的能力，提供专门的工作流程和领域知识。你可以使用技能为你的深度智能体提供新的能力和专长。

深度智能体的技能遵循"智能体技能标准"。一旦你添加了技能，你的深度智能体就会自动使用它们，并在你使用智能体并提供额外信息时更新它们。

使用 /remember 命令可以明确提示智能体根据当前的对话内容来更新技能和记忆。

1.10.1 添加技能

1 创建技能:

复制代码

# User skill (stored in ~/.deepagents/<agent_name>/skills/)
deepagents skills create test-skill

# Project skill (stored in .deepagents/skills/)
deepagents skills create test-skill --project

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

2 打开生成的 SKILL.md 文件，并编辑该文件以包含你的指令。

3（可选）将额外的脚本或其他资源添加到 test-skill 文件夹中。更多信息，请参阅示例。你也可以直接将现有的技能复制到智能体的文件夹中：

复制代码

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

1.10.2 安装社区技能

你可以使用像 Vercel 的 Skills CLI 这样的工具，在你的环境中安装社区提供的智能体技能，并让你的深度智能体能够使用它们

复制代码

# Install a skill globally
npx skills add vercel-labs/agent-skills --skill web-design-guidelines -a deepagents -g -y

# List installed skills
npx skills ls -a deepagents -g

全局安装（使用 -g 参数）会将技能符号链接到 ~/.deepagents/agent/skills/ ------ 这是默认智能体的用户级技能目录。

项目级安装（省略 -g 参数）会将技能放置在相对于当前目录的 .deepagents/skills/ 中，使得任何在该项目中运行的智能体都能使用这些技能，而无论智能体的名称是什么。

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

1.10.3 技能发现

在启动时，CLI 会从 Deep Agents 和共享别名目录这两个地方发现技能：

复制代码

~/.deepagents/<agent_name>/skills/
~/.agents/skills/
.deepagents/skills/
.agents/skills/
~/.claude/skills/          (experimental)
.claude/skills/            (experimental)

当存在重复的技能名称时，优先级较高的目录会覆盖优先级较低的目录（参见应用数据）。

对于项目特定的技能，项目的根文件夹必须包含一个 .git 文件夹。当你从项目文件夹内的任何位置启动 CLI 时，CLI 会通过检查包含的 .git 文件夹来找到项目的根文件夹。

对于每个技能，CLI 都会从 SKILL.md 文件的前言（frontmatter）中读取名称和描述。当你使用 CLI 时，如果任务与技能描述相匹配，智能体就会读取技能文件并遵循其指令。

你也可以使用 /skill:<name> [args] 直接调用技能。技能发现会在启动时以及执行 /reload 命令时运行。

1.10.3 从命令行调用技能

使用 --skill 参数可以在启动时直接调用技能，而无需交互式地输入斜杠命令：

复制代码

# Open the TUI and immediately run a skill
deepagents --skill code-review

# Pass a request to the skill with -m
deepagents --skill code-review -m 'review the auth module'

# Pipe content into a skill
cat diff.txt | deepagents --skill code-review

# Pipe content and add a request
cat diff.txt | deepagents --skill code-review -m 'focus on security'

--skill 参数同样适用于非交互式模式：

复制代码

# Run a skill headlessly
deepagents --skill code-review -n 'review this patch'

# Quiet mode (only agent output on stdout)
deepagents --skill code-review -n 'review this patch' -q

1.10.4 列出技能

复制代码

# List all user skills
deepagents skills list

# List project skills
deepagents skills list --project

# Get detailed info about a specific skill
deepagents skills info test-skill
deepagents skills info test-skill --project

1.11 子智能体

将自定义子代理定义为 Markdown 文件，这样 CLI 代理就可以将专门的任务委托给它们。每个子代理都拥有自己的文件夹，其中包含一个 AGENTS.md 文件**：**

复制代码

.deepagents/agents/{subagent-name}/AGENTS.md   # Project-level
~/.deepagents/{agent}/agents/{subagent-name}/AGENTS.md  # User-level

项目子代理会覆盖同名的用户子代理（参见优先级规则）。

文件头（frontmatter）必须包含 name（名称）和 description（描述）（与子代理字典规范相同）。Markdown 的主体内容将成为子代理的系统提示词（system_prompt）。

除了基础规范外，AGENTS.md 文件还支持一个可选的 model 文件头字段，用于覆盖主代理的模型。该字段使用 provider:model-name 格式（例如 anthropic:claude-opus-4-6，openai:gpt-5.5）。如果省略该字段，则继承主代理的模型

其他的子代理字段（如 tools、middleware、interrupt_on、skills）目前无法通过 AGENTS.md 的文件头（frontmatter）进行配置 ------ 以这种方式定义的自定义子代理将继承主代理的工具。如果需要完全控制，请直接使用 SDK。

文件格式

子代理的 AGENTS.md 文件采用 YAML 文件头（frontmatter），后跟 Markdown 主体：

复制代码

---
name: researcher
description: Research topics on the web before writing content
model: anthropic:claude-haiku-4-5-20251001
---

You are a research assistant with access to web search.

## Your Process
1. Search for relevant information
2. Summarize findings clearly

示例：具有成本效益的子代理

对于简单的委托任务，使用更便宜、更快的模型，同时让主代理保留使用功能更强大的模型**：**

复制代码

---
name: general-purpose
description: General-purpose agent for research and multi-step tasks
model: anthropic:claude-haiku-4-5-20251001
---

You are a general-purpose assistant. Complete the task efficiently and return a concise summary.

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

1.12 使用MCP工具

通过外部 MCP（模型上下文协议）服务器的工具来扩展 CLI。只需在项目根目录放置一个 .mcp.json 文件，CLI 就会自动发现它。

对于需要 OAuth 认证的服务器（如 Slack、GitHub、Linear、Notion 等），只需使用 deepagents mcp login <server> 进行一次认证；令牌（tokens）会被持久化存储在 ~/.deepagents/mcp-tokens/ 目录中，并自动刷新。

有关配置格式、OAuth 登录、自动发现和故障排除，请参阅 MCP 工具指南。

1.13 使用远程沙箱

CLI 采用"沙箱即工具"的模式：CLI 进程（包含 LLM 循环、记忆、工具调度）运行在你的机器上，但代理的工具调用（如读取文件、写入文件、执行命令等）针对的是远程沙箱，而不是你的本地文件系统。

若要将文件放入沙箱，请使用设置脚本或提供商的文件传输 API（请参阅"使用文件"）。

若要深入了解沙箱架构、集成模式和安全最佳实践，请参阅"沙箱"。

1 安装依赖

复制代码

#LangSmith 默认已经安装
#Daytona
uv tool install deepagents-cli --with langchain-daytona
#Modal
uv tool install deepagents-cli --with langchain-modal
#Runloop
uv tool install deepagents-cli --with langchain-runloop
#AgentCore
uv tool install deepagents-cli --with langchain-agentcore-codeinterpreter

2 设置供应商认证信息

复制代码

#LangSmith
export LANGSMITH_API_KEY="your-key"
#Daytona
export DAYTONA_API_KEY="your-key"
#Modal
modal setup
#Runloop
export RUNLOOP_API_KEY="your-key"
#AgentCore
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"

3 运行带沙箱参数的CLI

复制代码

#LangSmith
deepagents --sandbox langsmith
#Daytona
deepagents --sandbox daytona
#Modal
deepagents --sandbox modal
#Runloop
deepagents --sandbox runloop
#AgentCore
deepagents --sandbox agentcore

沙箱标志和例子

参数	描述
`--sandbox TYPE`	指定沙箱提供商：可选择 `langsmith`、`agentcore`、`modal`、`daytona` 或 `runloop`（默认值：无，即不使用沙箱）。
`--sandbox-id ID`	复用现有的沙箱：通过 ID 指定一个已经存在的沙箱，而不是创建新的。这将跳过创建和清理步骤。更多详情请参考您的沙箱文档。
`--sandbox-setup PATH`	指定设置脚本路径：指定一个脚本，在沙箱创建时立即在其中运行（用于环境初始化）。

复制代码

# Create a new Daytona sandbox
deepagents --sandbox daytona

# Reuse an existing sandbox (skips creation and cleanup)
deepagents --sandbox runloop --sandbox-id dbx_abc123

# Run a setup script after sandbox creation
deepagents --sandbox modal --sandbox-setup ./setup.sh

运行脚本

使用 --sandbox-setup 在沙箱创建后运行一个 Shell 脚本。这对于克隆代码仓库、安装依赖项以及配置环境变量非常有用

复制代码

#!/bin/bash
set -e

# Clone repository using GitHub token
git clone https://x-access-token:${GITHUB_TOKEN}@github.com/username/repo.git $HOME/workspace
cd $HOME/workspace

# Make environment variables persistent
cat >> ~/.bashrc <<'EOF'
export GITHUB_TOKEN="${GITHUB_TOKEN}"
export OPENAI_API_KEY="${OPENAI_API_KEY}"
cd $HOME/workspace
EOF
source ~/.bashrc

CLI 会使用你本地的环境变量来替换设置脚本中的 ${VAR} 引用。请将密钥（secrets）存储在本地 .env 文件中，以便设置脚本访问。

沙箱虽然隔离了代码执行，但代理（agents）在使用不受信任的输入时，仍然容易受到提示词注入（prompt injection）的攻击。

请务必使用"人工介入审批"、短效密钥（short-lived secrets），并且仅使用可信的设置脚本。有关详细信息，请参阅"安全注意事项"。

1.14 LangSmith跟踪

启用 LangSmith 追踪，以便在 LangSmith 项目中查看代理的操作、工具调用和决策过程。将你的追踪密钥添加到 ~/.deepagents/.env 文件中，这样无需在每个 Shell 中单独导出变量，就能在每次会话中自动启用追踪：

复制代码

LANGSMITH_TRACING=true
LANGSMITH_API_KEY=lsv2_...
LANGSMITH_PROJECT=optional-project-name  # Specify a project name or default to "deepagents-cli"

若要在特定项目中覆盖（全局）配置，请在项目目录下的 .env 文件中添加相同的密钥。有关完整的加载顺序，请参阅"环境变量"。

如果你愿意，也可以将这些配置设置为 Shell 环境变量。Shell 的导出（exports）设置总是优先于 .env 文件中的值，因此这是进行临时覆盖或测试的绝佳选择：

复制代码

export LANGSMITH_TRACING=false

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

当从 LangChain 应用程序中以编程方式调用 CLI 时（例如，在非交互模式下作为子进程），你的应用程序和 CLI 都会产生 LangSmith 追踪记录。默认情况下，这些记录都会落入同一个项目中。

若要将 CLI 的追踪记录发送到专用的项目，请设置 DEEPAGENTS_CLI_LANGSMITH_PROJECT：

复制代码

DEEPAGENTS_CLI_LANGSMITH_PROJECT=my-deep-agent-execution

然后为你的父应用程序（主程序）的追踪记录配置 LANGSMITH_PROJECT：

复制代码

LANGSMITH_PROJECT=my-app-traces

这样既能保持你应用层面的可观测性整洁，同时又能将代理的内部执行情况单独捕获到一个独立的项目中。你也可以使用 DEEPAGENTS_CLI_ 前缀将 LangSmith 凭证限定于 CLI 使用（例如 DEEPAGENTS_CLI_LANGSMITH_API_KEY）

配置完成后，CLI 会显示一行状态信息，其中包含指向 LangSmith 项目的链接。在支持的终端中，直接点击该链接即可打开。你也可以输入 /trace 命令来打印 URL 并在浏览器中打开它。

复制代码

✓ LangSmith tracing: 'my-project'

1.15 命令行引用

复制代码

# Use a specific agent configuration
deepagents --agent mybot

# Use a specific model (provider:model format or auto-detect)
deepagents --model anthropic:claude-opus-4-7
deepagents --model gpt-5.5

# Auto-approve tool usage (skip human-in-the-loop prompts)
deepagents -y

1.15.1 命令行选项

选项	描述
`-a, --agent NAME`	使用指定名称的代理及其独立记忆。会覆盖 `config.toml` 中的 `[agents].recent` 配置。默认值为 `agent`（或者如果设置了 `[agents].recent`，则为最近使用的代理）。
`-M, --model 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 启动命令。输出会显示在记录中供参考，但不会添加到代理的消息历史中。非零退出码和超时仅会发出警告而不会中止；非交互模式应用 60 秒超时。参见"在启动时运行命令"。
`-n, --non-interactive TEXT`	非交互式地运行单个任务然后退出。除非设置了 `--shell-allow-list`，否则 Shell 功能将被禁用。
`--max-turns N`	限制非交互模式下的代理轮数。超出时以代码 124 退出。需要 `-n` 或管道标准输入。参见"使用 --max-turns 限制轮数"。
`-q, --quiet`	用于管道的干净输出------只有代理的响应会输出到标准输出。需要 `-n` 或管道标准输入。
`--no-stream`	缓冲完整响应并一次性写入标准输出，而不是流式传输。需要 `-n` 或管道标准输入。
`--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`	信任项目级 MCP 配置及其 stdio 服务器（跳过批准提示）。
`--profile-override JSON`	以 JSON 字符串形式覆盖模型配置文件字段（例如 `'{"max_input_tokens": 4096}'`）。会在配置文件覆盖的基础上进行合并。
`--acp`	作为 ACP 服务器通过 stdio 运行，而不是启动交互式用户界面。
`-v, --version`	显示版本信息。
`-h, --help`	显示帮助信息。

1.15.2 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`	列出会话（别名：`ls`）。 • 默认限制： 20 条。 • 标志： `-n` 是 `--limit` 的简写；`--sort {created,updated}`；`--branch TEXT`（按 git 分支过滤）；`-v/--verbose`（显示所有列，包括分支、创建时间和初始提示词）；`-r/--relative`（相对时间戳）。 • 选项： `[--agent NAME]`，`[--limit N]`。
`deepagents threads delete ID`	删除指定会话。支持 `--dry-run`。
`deepagents mcp login NAME`	为标记为 `auth: "oauth"` 的 MCP 服务器运行 OAuth 登录流程。参见"MCP 工具"。 • 选项： `[--config PATH]`。
`deepagents deploy`	将您的代理部署到 LangSmith。参见"使用 CLI 部署"。

💡 通用说明

机器可读输出： 所有管理子命令均支持 --json 标志。
安全预览： 破坏性命令（agents reset、skills delete、threads delete）支持 --dry-run 以预览更改。在 JSON 模式下，这将返回包含 dry_run: true 字段的信封。

2 模型提供商

3 配置

4 MCP工具

5 应用数据

总结

本章主要介绍了deepagents命令行工具用途，看起来用处不大，毕竟没几个人喜欢敲命令。低效不直白。下篇

Deep Agents 框架-CLI

引言

🛠️ 核心能力概览

🛠️ 内置工具概览

1 使用命令行

1.1 起步

1.2 供应商

1.3 交互模式

1.3.1 斜杠命令

1.3.2 Shell 命令

1.3.3 键盘快捷键

1.4 非交互模式管道

1.5 启动时运行命令

1.6 模型切换

1.7 智能体切换

1.8 配置

List all configured agents

1.9 记忆

1.9.1 自动记忆

1.9.2 AGENTS.md 文件

1.10 使用技能

1.10.1 添加技能

1.10.2 安装社区技能

1.10.3 从命令行调用技能

1.10.4 列出技能

1.11 子智能体

1.12 使用MCP工具

1.13 使用远程沙箱

1.14 LangSmith跟踪

1.15 命令行引用

1.15.1 命令行选项

1.15.2 CLI命令

2 模型提供商

3 配置

4 MCP工具

5 应用数据

总结

`1.9.2 AGENTS.md` 文件