Typography

学习笔记

Deep Agents 学习08 CLI

发布于 # Deep Agents

如果把 Deep Agents SDK 看成底层能力，那么 CLI 更像是把这些能力真正放进了一个可长期使用的终端工作界面里。它不是“给模型套个聊天壳”，而是把读文件、改代码、跑命令、调用技能、记住偏好这些能力收拢成一条持续可用的开发工作流。

为什么值得关注

理解 CLI，重点不在于背命令清单，而在于看清它为什么能成为日常工作的入口：它既保留了终端的直接性，又把 Agent 的规划、工具调用、记忆和审批机制一起带进了开发现场。用得好的话，它不是偶尔帮你答题的助手，而是一个能长期参与项目工作的终端代理。

它的核心作用是：

可以把它理解成：

它到底是什么

Deep Agents CLI 是一个运行在终端里的 coding agent。

和普通命令行工具不同，它不是“你输一个命令，它执行一个固定逻辑”，而是：

所以它更像一个在终端里的“可执行智能工作流系统”。

界面示意

Deep Agents CLI 界面示意

这张图展示的是 CLI 的典型交互形态：上方是对话与工具输出区域，下方是持续输入任务的终端式工作界面。先从这个界面形态建立直觉会很有帮助，因为后面提到的文件工具、shell、记忆和审批，本质上都是在这个统一工作界面里协同发生的。

内置能力总览

这个 CLI 默认就具备一整套能力，不需要你自己手工拼装。

文件能力

可以直接：

适合：

shell 执行能力

可以运行命令，例如：

Web 与 HTTP 能力

可以：

适合：

任务规划与追踪

对复杂任务，Agent 会先拆步骤，再按阶段推进。

记忆能力

可以跨 session 保存：

上下文压缩与卸载

当会话过长时，会自动把历史消息摘要化并卸载到存储里，避免上下文窗口爆掉。

人工审批

对高风险操作，例如改文件、执行命令、发 Web 请求等，可以要求人工确认。

技能

可以按需扩展专项能力，例如：

MCP 工具

可以从 MCP server 加载额外工具，把 CLI 变成更大的工具系统入口。

Tracing

可以把 Agent 的操作、工具调用、决策链路发送到 LangSmith 中进行观察和调试。

内置工具怎么理解

CLI 自带的工具大致分成几类。

文件系统工具

执行与网络工具

流程控制工具

哪些工具默认要审批

通常以下工具属于高风险或潜在破坏性操作，会触发人工审批：

这里的核心思想是：

环境与平台认知

这个 CLI 主要面向类 Unix 环境。

Windows 的现实情况

它并不是官方重点支持的 Windows 原生工具。

如果你在 Windows 上使用，更推荐：

这样兼容性通常会好很多。

最小启动流程

要跑起来，最少只需要完成三件事：

  1. 配模型 API Key
  2. 安装 CLI
  3. 启动并给它任务

第一步：配置模型凭证

CLI 依赖一个支持 tool calling 的模型。

最常见的是设置环境变量。

OpenAI

export OPENAI_API_KEY="your-api-key"

Anthropic

export ANTHROPIC_API_KEY="your-api-key"

Google

export GOOGLE_API_KEY="your-api-key"

更推荐的长期方式

把 key 写到：

~/.deepagents/.env

这样每次启动终端都不需要重新 export。

为什么 .env 更适合长期使用

因为 CLI 启动时会自动读取自己的配置目录，长期使用时更稳定，也更适合：

第二步：安装 CLI

最简单安装方式

curl -LsSf https://raw.githubusercontent.com/langchain-ai/deepagents/refs/heads/main/libs/cli/scripts/install.sh | bash

带可选 provider extras 安装

DEEPAGENTS_EXTRAS="ollama,groq" curl -LsSf https://raw.githubusercontent.com/langchain-ai/deepagents/refs/heads/main/libs/cli/scripts/install.sh | bash

用 uv 安装

uv tool install 'deepagents-cli[ollama,groq]'

默认已包含哪些 provider

默认包含：

其他 provider 需要额外安装对应 integration。

第三步：启动 CLI

deepagents

启动后就可以直接输入自然语言任务，例如：

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

在默认设置下，CLI 会对关键修改展示 diff，并在执行高风险操作前请求确认。

Provider 扩展方式

如果你需要额外的模型 provider，可以通过 uv tool install ... --with ... 追加依赖。

例如：

uv tool install deepagents-cli --with langchain-xai

一个简单判断标准：

交互模式怎么使用

进入 CLI 后，默认就是交互模式。

在这个模式下，最核心的用法就是：

除了普通对话，还支持 slash 命令、shell 模式和快捷键。

Slash 命令体系

如果把自然语言任务看成“让 Agent 去做事”，那 slash 命令更像是“你来管理 Agent 的工作环境”。它们不直接解决业务问题，而是帮你切模型、控上下文、调能力、查状态。

Slash 命令是 CLI 的内置控制层。

最常用的一组包括：

最常用的几类场景

命令很多时，最好的记法通常不是逐个背，而是按使用场景来分。你会发现，大多数高频操作其实都落在“管上下文、管能力、管环境”这三类里。

管理上下文

管理能力

管理环境

Shell 模式

CLI 虽然强调让 Agent 自主完成任务，但它并不会把你完全排除在操作链路之外。很多时候，你只是想快速看一眼环境状态，或者临时跑一条命令，这时 shell 模式会更直接。

如果想临时手动执行命令，可以输入 ! 进入 shell 模式，然后执行：

git status
npm test
ls -la

这适合两类场景：

常用快捷键

快捷键这部分最适合在真正使用 CLI 时边用边记，不需要一次性背全。可以先把它们理解成三类：输入编辑、Agent 控制，以及文件注入。

输入与提交

输入编辑

Agent 交互控制

文件注入

这对让 Agent 快速拿到某个文件内容非常有用。

非交互模式

当你不需要长期对话，而只是想把 CLI 接进脚本、管道或者一次性自动化流程时，非交互模式会更合适。这里的思路和交互模式完全不同：重点不再是持续协作，而是把 CLI 当成一个可以被外部程序调用的任务执行器。

如果你不想进入 TUI，而是想把 CLI 当作“一次性任务执行器”，可以使用：

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

适合什么场景

只要你的需求更接近“把 CLI 嵌进一条已有自动化链路”，这一模式就会非常顺手。常见场景包括：

管道输入

一旦进入非交互模式，stdin 就会变成非常实用的接入口。很多原本需要手工复制粘贴给 Agent 的内容，都可以直接从上一条命令流过来。

CLI 可以直接从 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'

这个能力特别适合什么

一个重要规则

当你同时用了 stdin 和 -n / -m 时：

输入大小限制

最大 piped 输入大小通常是：

所以非常大的日志或 diff，仍然需要先裁剪。

非交互模式下的 shell 限制

这里有一个非常值得单独记住的边界：非交互模式默认并不会让 Agent 自由执行 shell。因为一旦没有人在场盯着审批，执行能力就必须收得更紧。

在非交互模式中，shell 默认是禁用的。

原因很合理：

如果你确实需要让 CLI 在非交互模式下执行命令，就要显式设置 shell allow list。

只允许指定命令

deepagents -n "Run the tests and fix failures" -S "pytest,git,make"

使用推荐白名单

deepagents -n "Build the project" -S recommended

放开全部命令

deepagents -n "Fix the build" -S all

风险提醒

-S all 的含义几乎等于：

这在自动化场景中风险极高，除非你非常清楚运行环境边界，否则不要随便开。

-q 与 --no-stream

如果你想让 CLI 更适合被别的命令消费，可以使用这两个参数。

-q

输出更干净，只保留 Agent 最终回答，适合重定向或管道。

例如：

deepagents -n "Generate a .gitignore for Python" -q > .gitignore

--no-stream

关闭流式输出，等完整结果生成后再一次性写到 stdout。

例如：

deepagents -n "List dependencies" -q --no-stream | sort

一个重要限制

-q 或 --no-stream 一般需要配合：

模型切换

CLI 支持在会话中动态切换模型，而不需要重启。

会话内切换

/model anthropic:claude-opus-4-6
/model openai:gpt-5.4

启动时指定模型

deepagents --model openai:gpt-5.4

打开交互式模型选择器

直接输入：

/model

模型参数临时覆盖

如果你想在 session 内加临时模型参数，例如 temperature：

/model --model-params '{"temperature": 0.7}' anthropic:claude-sonnet-4-5

也可以不直接指定模型，而是打开选择器后把参数应用到所选模型。

这个能力适合什么

配置目录结构

CLI 的配置都放在：

~/.deepagents/

默认 agent 名叫：

每个 agent 会有自己的独立目录。

关键路径

查看已配置 agent

deepagents agents list

记忆系统

CLI 的长期可用性，很大程度来自它的记忆系统。

主要有两层：

自动记忆

随着使用过程，CLI 会自动把信息保存到：

~/.deepagents/<agent_name>/memories/

这些记忆通常会按主题拆成独立 markdown 文件，例如：

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

记忆的工作方式

可以理解为三步：

  1. 先搜索已有记忆
  2. 任务执行中不确定时再查记忆
  3. 识别到新知识后自动保存

适合记忆什么

AGENTS.md

AGENTS.md 是始终加载的持久上下文文件。

全局位置

~/.deepagents/<agent_name>/AGENTS.md

作用：

项目位置

.deepagents/AGENTS.md

作用：

如何划分全局与项目级内容

全局 AGENTS.md

适合写：

项目级 AGENTS.md

适合写：

一个重要补充

如果你在 .deepagents/ 下还放了其他结构化知识文件，应该在 AGENTS.md 里显式引用它们。

否则：

/remember 的作用

如果你希望 Agent 主动把当前对话中的新知识沉淀进记忆和技能，可以使用：

/remember

也可以附带上下文。

这个命令适合在以下时机使用：

技能系统

技能是可复用的专项能力包。

和记忆相比：

适合做成技能的内容

如何创建技能

用户级技能

deepagents skills create test-skill

项目级技能

deepagents skills create test-skill --project

这会生成：

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

然后你需要编辑 SKILL.md，填入该技能的说明和工作方式。

也可以直接复制现成技能

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

社区技能安装

如果你想直接使用社区技能，可以用相关工具安装。

例如：

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

一个重要限制

全局安装默认会链接到默认 agent：

~/.deepagents/agent/skills/

如果你使用的是自定义 agent 名称，就要注意：

技能发现路径

CLI 启动时会自动扫描多个技能目录，例如：

~/.deepagents/<agent_name>/skills/
~/.agents/skills/
.deepagents/skills/
.agents/skills/
~/.claude/skills/
.claude/skills/

技能覆盖规则

如果同名 skill 在多个目录都存在：

项目技能为什么依赖 git 根目录

项目级技能只有在 CLI 能识别当前项目根目录时才会被发现。

通常做法是：

因此没有 git 根目录时，项目技能发现可能不生效。

手动调用技能

也可以直接：

/skill:<name> [args]

或者在启动时：

deepagents --skill code-review

配合 -m、-n 或 stdin 也都可以使用。

Subagents in CLI

CLI 也支持通过 markdown 文件定义子代理。

目录格式如下：

.deepagents/agents/{subagent-name}/AGENTS.md
~/.deepagents/{agent}/agents/{subagent-name}/AGENTS.md

覆盖规则

如果项目级和用户级存在同名子代理：

文件结构理解

子代理的 AGENTS.md：

示例

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

这个能力适合什么

目前的限制

通过 CLI 的 AGENTS.md 方式定义的 subagent，还不能完整配置：

它们默认继承主 Agent 的工具。

如果需要完全可编程控制，要回到 SDK 层实现。

MCP 工具接入

CLI 可以从 MCP server 加载额外工具。

典型做法是：

适合：

如果你想让 CLI 成为统一工作入口，MCP 是很关键的扩展方式。

远程沙箱在 CLI 中的工作方式

CLI 采用的是：

也就是说：

这意味着什么

本地负责：

远程 sandbox 负责：

这是一个非常实用的架构，因为它既保留了本地交互体验，又把执行副作用隔离出去。

在 CLI 中启用 sandbox

第一步：安装 provider 依赖

例如 Daytona：

uv tool install deepagents-cli --with langchain-daytona

第二步：设置 provider 凭证

例如 Daytona：

export DAYTONA_API_KEY="your-key"

第三步：启动 CLI 并指定 sandbox

deepagents --sandbox daytona

支持的类型

常见包括：

常用 sandbox 参数

--sandbox TYPE

指定使用哪种远程沙箱。

--sandbox-id ID

复用已存在的沙箱，而不是重新创建。

适合：

--sandbox-setup PATH

指定一个在沙箱创建后执行的初始化脚本。

适合：

setup 脚本示例

#!/bin/bash
set -e

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} 做本地环境变量展开，因此：

所以 setup script 必须可信，不能随便执行陌生来源脚本。

Tracing with LangSmith

如果你希望看到 Agent 每一步做了什么，可以开启 LangSmith tracing。

建议写入：

~/.deepagents/.env

例如：

LANGSMITH_TRACING=true
LANGSMITH_API_KEY=lsv2_...
LANGSMITH_PROJECT=optional-project-name

启用后有什么用

你可以看到：

这对调试以下问题特别重要：

CLI 内使用方式

开启后，CLI 通常会显示 tracing 状态。

你也可以使用：

/trace

快速打开当前 thread 的 LangSmith 页面。

与应用 trace 分离

如果 CLI 是被你的上层应用调用的，那么可能会出现：

都打到同一个项目里

这时可以单独设置：

DEEPAGENTS_CLI_LANGSMITH_PROJECT=my-deep-agent-execution
LANGSMITH_PROJECT=my-app-traces

这样就能把 CLI 内部轨迹和应用外层轨迹拆开。

管理命令体系

除了交互式使用，CLI 还带了一套管理命令。

agents

deepagents agents list
deepagents agents reset --agent NAME
deepagents agents reset --agent NAME --target SOURCE

作用：

skills

deepagents skills list
deepagents skills create NAME
deepagents skills info NAME
deepagents skills delete NAME

作用：

threads

deepagents threads list
deepagents threads delete ID

作用：

update

deepagents update

作用：

deploy

deepagents deploy

作用：

常见命令行参数

最常用的一组参数包括：

-y / auto-approve 的真实含义

deepagents -y

它的作用是：

这是提升效率的开关，但同时也显著提高风险。

适合：

不适合：

一个简单建议是：

CLI 的长期使用方式

如果想真正把它用成工作助手，推荐形成下面这套习惯：

1. 维护全局 AGENTS.md

把你的通用偏好写进去。

2. 为每个项目维护 .deepagents/AGENTS.md

把项目架构、命令、约定写进去。

3. 把高频专项工作沉淀成 skills

例如：

4. 用 /remember 把临时经验转成长期记忆

不要每次都重复教同一件事。

5. 对高风险操作保留审批

尤其是：

6. 开启 tracing 调试复杂问题

尤其是你在做：

常见错误与排查

启动后模型不可用

常见原因：

解决：

skill 明明创建了，但 CLI 不识别

常见原因：

解决：

项目级 AGENTS.md 没生效

常见原因：

解决：

非交互模式下 Agent 不执行 shell

这是默认行为，不一定是 bug。

解决：

sandbox 启动失败

常见原因：

解决：

tracing 没有出现

常见原因：

解决：

验收标准

可以用下面这些标准判断 CLI 是否真正进入可用状态：

推荐上手顺序

建议按这个顺序使用 CLI：

  1. 先配置模型 API key
  2. 安装 CLI 并跑通基础对话
  3. 在一个项目里试文件读写和命令执行
  4. 写项目级 .deepagents/AGENTS.md
  5. 创建一个简单 skill
  6. 体验 /remember 和 /threads
  7. 再尝试非交互模式和 piping
  8. 最后接 sandbox、MCP 和 tracing

关键要点

写在最后

Deep Agents CLI 的真正价值，在于它把“模型能力、工具能力、记忆能力、审批机制和项目上下文”统一到了一个终端工作界面里。

可以把它理解成三层：

当这三层都建立起来之后，CLI 就不再只是一个会回答问题的终端工具，而是一个能真正参与日常开发工作的长期代理。