前面我写了一篇 SDK API 参考手册，按类和函数列出了所有导出。但有个问题——那是给开发者看的。如果你是一个产品经理、技术负责人，或者只是想知道"一个 Deep Agent 到底能干什么"，那篇文章帮不了你。
这篇不一样。我从 Agent 能力 的角度重新组织，按功能域拆解。不看类名、不看函数签名，只看 Agent 能做什么、怎么做、做到什么程度。
普通 Agent 是"你说一句，它做一步"。Deep Agent 不一样——它能自己规划。
Agent 有一个 write_todos 工具，用来管理任务列表。它的工作方式：
这个过程对用户完全透明——你在 Agent 的输出里能看到它内部的任务追踪。比如你说"帮我把这个 Python 项目从 Flask 迁移到 FastAPI"，Agent 内部会生成这样的计划：
□ 读取项目结构，了解 Flask 路由定义
□ 读取所有 route handler 和依赖
□ 创建 FastAPI 应用骨架
□ 逐个迁移路由
□ 更新依赖文件
□ 运行测试验证
Deep Agent 的 recursion_limit 设为 9999。对比普通 Agent 通常只有 25 轮。这意味着一个 Deep Agent 可以连续执行几千轮工具调用——对复杂任务（比如重构整个代码库）来说，这是必须的。
这是 Deep Agent 的基础能力。它有一套完整的"虚拟文件系统"，Agent 可以像人类操作电脑一样浏览和编辑文件。
ls — 列出目录内容，看到文件名、大小、修改时间、类型（文件/目录）。
Agent 通常会先用 ls 了解项目结构，再决定读哪些文件。
read_file — 支持分页读取大文件：
- offset：从第几行开始（0-indexed）
- limit：最多读多少行（默认 100）
分页读取是个被低估的设计。一个大文件可能有几万行，一次性读进来会撑爆上下文窗口。分页读取让 Agent 能精确控制"看多少"，看完一页再翻下一页。
write_file — 创建新文件或完全覆盖已有文件。Agent 用它来生成代码文件、配置文件、文档等。
edit_file — 精确的字符串替换编辑：
- old_string：要找到的文本（必须在文件中唯一，除非用 replace_all）
- new_string：替换后的文本
- replace_all：是否替换所有匹配
这种编辑方式比"读整个文件 → 改一行 → 写回整个文件"高效得多。Agent 只需要发送被修改的部分，不需要重传整个文件。
glob — 按文件名模式搜索：
- 支持 **/*.py、*.md 等标准 glob 模式
- 支持 **（递归匹配）
- 支持大括号展开 {a,b}
grep — 按内容搜索，三种输出模式：
- files_with_matches（默认）：只返回匹配的文件路径
- content：返回匹配的行和上下文
- count：返回每个文件的匹配数量
还可以用 glob 参数过滤搜索范围（比如只在 *.py 文件里搜）。
所有文件操作受 FilesystemPermission 规则约束：
permissions=[
FilesystemPermission(
operations=["read"],
paths=["/data/*"],
mode="allow"
),
FilesystemPermission(
operations=["write"],
paths=["/secrets/*"],
mode="deny"
),
]
规则按声明顺序匹配，第一个命中就生效。没匹配到任何规则的请求默认放行。
工具结果超过 tool_token_limit_before_evict（默认 20000 tokens）时，Agent 会自动把结果保存到文件，只在上下文里留一个文件路径引用。这避免了上下文窗口被一个巨大的 ls 结果撑满。
execute 工具让 Agent 能执行 shell 命令。这是 Agent 从"聊天机器人"进化为"编码助手"的关键能力。
execute — 在沙箱环境中运行 shell 命令：
- command：要执行的命令字符串
- timeout：超时秒数（可选，0 表示不限时）
- 默认最大超时 3600 秒（1 小时）
execute 工具只在后端实现了 SandboxBackendProtocol 时才可用：
| 后端 | 支持 execute |
|---|---|
| StateBackend | ❌ |
| FilesystemBackend | ❌ |
| LocalShellBackend | ✅ |
| LangSmithSandbox | ✅ |
| Daytona（Partner） | ✅ |
| Modal（Partner） | ✅ |
| Runloop（Partner） | ✅ |
如果后端不支持沙箱，execute 会返回一个明确的错误消息。
远程沙箱意味着 Agent 的代码执行和你的系统完全隔离：
- 文件系统隔离：Agent 看不到你的真实文件系统
- 网络隔离：Agent 的网络请求经过沙箱网关
- 资源限制：CPU、内存、磁盘都有上限
这是 Deep Agent 最强的能力——它不只是"一个人干活"，而是能委派子任务给专门的子代理。
通过 task 工具启动。主 Agent 会等待子代理完成后拿到结果。
每个同步子代理可以有：
- 独立的系统提示词
- 独立的工具集（默认继承主 Agent 的）
- 独立的模型（可以用不同的 LLM）
- 独立的中间件栈
- 独立的权限规则
- 独立的技能
关键设计：每个子代理有独立的上下文窗口。这意味着主 Agent 不会因子代理的大量输出而"变笨"。
默认通用子代理：每个 Deep Agent 自动附带一个 general-purpose 子代理。它继承主 Agent 的所有能力，但有全新的上下文窗口。主 Agent 用它来处理需要"从头思考"的子任务。
提供一个预先构建好的 LangGraph 图。适合已经有现成 Agent 场景的情况——不需要重新声明 prompt 和 tools，直接传入可运行对象。
连接远程 Agent Protocol 服务器，启动后台任务。5 个工具：
| 工具 | 功能 |
|---|---|
start_async_task |
启动后台任务，立即返回 task_id |
check_async_task |
查询任务状态和结果 |
update_async_task |
向运行中的任务发送新消息 |
cancel_async_task |
取消正在运行的任务 |
list_async_tasks |
列出所有追踪的任务，可按状态过滤 |
异步子代理适合：
- 长时间运行的任务（不需要主 Agent 等待）
- 并行执行多个任务
- 连接部署在 LangSmith 上的 Agent 服务
| 能力 | 继承规则 |
|---|---|
| 工具 | 默认继承主 Agent 的 tools，子代理可覆盖 |
| 模型 | 默认继承，子代理可指定不同模型 |
| 权限 | 默认继承，子代理可完全覆盖（不是追加） |
| 技能 | 不继承，子代理需要单独指定 |
| 人机协作 | 声明式子代理默认继承，可覆盖；预编译和异步子代理不继承 |
没有记忆的 Agent 就像金鱼——每次对话都从零开始。Deep Agent 有三层记忆机制。
Agent 的对话历史就是短期记忆。通过 LangGraph 的 checkpointer 可以把对话状态持久化到数据库、Redis 等。
from langgraph.checkpoint.memory import MemorySaver
agent = create_deep_agent(
checkpointer=MemorySaver() # 内存中持久化
)
配合 thread_id，Agent 能在同一线程内记住之前说过的话。
MemoryMiddleware 在 Agent 启动时加载指定的 AGENTS.md 文件，注入到系统提示词中：
agent = create_deep_agent(
memory=["/memory/AGENTS.md"]
)
AGENTS.md 里可以写：
- 项目约定和编码规范
- 常用 API key 的位置
- 架构决策和设计模式
- 团队工作流说明
这些内容会在每次对话开始时自动加载，Agent 不需要你重复说明。
通过 StoreBackend 或 CompositeBackend 把文件存储到 LangGraph 的 BaseStore，实现跨线程、跨会话的持久存储。适合需要长期保留的知识库、用户偏好等。
MemoryMiddleware 支持 Anthropic 的 prompt 缓存。记忆内容被注入系统提示词时加上 cache_control 标记，后续请求直接从缓存读取，不重新计费。
技能（Skills）是 Deep Agent 的"插件系统"。一个技能本质上是一个 SKILL.md 文件，描述了特定工作流的步骤。
SkillsMiddleware 从指定路径加载技能文件name、description、工作流定义每个技能可以包含：
- name：1-64 字符，小写字母数字 + 连字符
- description：1-1024 字符，描述技能功能
- license：许可证信息
- compatibility：兼容性说明
- allowed_tools：限制技能能使用的工具（实验性）
- module：JS/TS 入口点（实验性，用于 QuickJS 运行时）
| 技能 | 功能 |
|---|---|
skill-creator |
让 Agent 自己创建新技能 |
remember |
让 Agent 把信息写入记忆文件 |
web-research |
网络研究技能 |
技能源按路径顺序加载，后面的源会覆盖前面同名的技能（"last one wins"）。这意味着你可以：
- 用内置技能做基础
- 用项目级技能做覆盖
- 用用户级技能做个性化
LLM 的上下文窗口是有限的。对话越长，Agent 越容易"遗忘"或"注意力涣散"。Deep Agent 有四层防御机制。
当对话历史超过阈值时，自动用 LLM 生成摘要：
Agent 有一个 compact_conversation 工具，可以在自动触发阈值的一半时就手动触发压缩。Agent 自己判断什么时候需要压缩。
在摘要之前，先尝试截断过长的工具调用参数：
- 每个参数最大长度可配置（默认 2000 字符）
- 超过部分替换为 ...(argument truncated)
- 截断触发点独立于摘要触发点
工具返回的结果超过 tool_token_limit_before_evict（默认 20000 tokens）时，自动保存到文件。上下文里只保留文件路径。
ls、glob、grep、read_file、edit_file、write_file 的结果不参与驱逐（它们本身就是文件操作，输出通常是必要的）。
Deep Agent 的消息存储使用 LangGraph 的 DeltaChannel，只存增量不存全量。100 轮对话的 checkpoint 大小和 10 轮几乎一样。
不是所有操作都应该让 Agent 自动执行。interrupt_on 让你控制哪些工具调用需要人工审批。
agent = create_deep_agent(
interrupt_on={
"execute": True, # 执行命令前必须审批
"write_file": True, # 写文件前必须审批
"edit_file": True, # 编辑文件前必须审批
}
)
execute: "rm -rf /tmp/test"）interrupt_on 中，执行暂停声明式子代理默认继承主 Agent 的 interrupt_on 配置。子代理也可以用自己的配置完全覆盖。
interrupt_on 的值不只是 True/False，还可以是 InterruptOnConfig 对象，提供更细粒度的控制（比如只在特定条件下中断）。
一个 Agent 框架如果不能部署，就只是个玩具。Deep Agent 在这方面做得相当完整。
| 形态 | 安装方式 | 适用场景 |
|---|---|---|
| SDK | pip install deepagents |
嵌入 Python 应用 |
| CLI | curl -LsSf https://langch.in/gh-da-cli \| bash |
终端使用 |
| Deploy | deepagents deploy |
部署为服务 |
create_deep_agent() 返回的就是一个编译好的 LangGraph CompiledStateGraph。这意味着：
- 支持 LangGraph Studio 可视化调试
- 支持所有 LangGraph checkpointers（内存、Postgres、SQLite）
- 支持所有 LangGraph stores
- 支持流式输出（.stream()、.astream()）
- 支持 LangSmith 追踪
通过 langchain-mcp-adapters 连接任何 MCP 服务器：
from langchain_mcp_adapters import MCPToolAdapter
mcp_tools = await MCPToolAdapter.from_server("path/to/mcp-config.json")
agent = create_deep_agent(tools=mcp_tools)
MCP 让 Agent 能访问外部服务——数据库、API、文件系统等。
Agent Client Protocol 让 Deep Agent 能在 Zed 编辑器中使用：
from deepagents_acp.server import AgentServerACP
server = AgentServerACP(agent)
await run_agent(server)
在 Zed 的 Agent Panel 里直接和 Deep Agent 对话，让它读写当前项目的文件。
response_format 参数让 Agent 返回结构化数据而不是自然语言：
from pydantic import BaseModel
class AnalysisResult(BaseModel):
summary: str
key_findings: list[str]
confidence: float
agent = create_deep_agent(response_format=AnalysisResult)
支持任何实现了 init_chat_model 的模型提供商：
# 字符串格式
create_deep_agent(model="openai:gpt-4o")
create_deep_agent(model="anthropic:claude-sonnet-4-6")
create_deep_agent(model="google:gemini-2.5-pro")
create_deep_agent(model="ollama:llama3")
# 预初始化实例
create_deep_agent(model=ChatAnthropic(model="claude-opus-4-7"))
4 种沙箱提供商：
- LangSmith Sandbox — LangChain 官方
- Daytona — 远程开发环境
- Modal — Serverless GPU
- Runloop — 代码执行沙箱
内置评估套件（libs/evals/）包含：
- 文件操作能力测试
- 工具选择和使用测试
- 记忆多轮测试
- 子代理委派测试
- 外部基准测试（BFCL、MemoryAgentBench、Tau2 Airline）
- Harbor 集成（Terminal Bench 2.0）
这份清单从 Agent 实际能做什么的角度覆盖了所有能力。如果你在评估 Deep Agents 是否适合你的场景，对照这份清单就足够了。
作者: itech001
来源: 公众号：AI人工智能时代
主页: https://www.theaiera.cn，每日分享最前沿的AI新闻和技术。
本文首发于 AI人工智能时代，转载请注明出处。
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。