Deep Agents 1. 系统架构与核心能力

Deep Agents 并不是一个“更会思考”的新模型，而是一套用来组装长任务 Agent 的
Harness。本文先回答三个问题：Deep Agents 解决什么问题，它与 LangChain、
LangGraph 如何分工，以及什么样的任务适合使用它。

1. 为什么复杂任务需要 Agent Harness

1.1 普通 Tool Calling Agent 的边界

例如，用户可能提出下面的复杂任务：

分析第二季度的销售数据，找出收入下降的区域，查明原因，生成一份带图表的报告，审核通过后发布。

这句话看起来只有一个目标，实际执行时却可能需要：

1. 确认数据文件、时间范围和统计口径；
2. 读取 CSV、Excel 或数据库表；
3. 调用确定性程序计算指标；
4. 根据中间结果决定是否补充调查；
5. 将过长的文件和工具输出移出模型上下文；
6. 将分析、调查和审核分给不同的 subagent；
7. 生成 Markdown、图表或 PDF 产物；
8. 在发布前暂停，等待人工决策；
9. 失败后从已有状态恢复，而不是全部重做。

普通 Tool Calling Agent 的核心循环是：模型决定是否调用工具（Tool），应用执行工具，
再把结果交还模型。这个循环能够完成很多任务，但它没有自动解决长任务中的
进度跟踪、上下文治理、执行隔离和中断恢复。

工程问题	常见现象	Harness 需要补充的能力
任务复杂	做了一步忘记后续目标	Todo 规划与状态跟踪
上下文过大	文件、搜索结果和工具输出撑满窗口	文件卸载、摘要与上下文隔离
能力不断增加	Prompt 和工具列表越来越长	Skills、动态工具与渐进式披露
执行存在风险	模型生成的命令直接运行在宿主机	权限、Sandbox、HITL 与审计

1.2 Deep Agents 主要解决什么

Deep Agents 的价值不是再包装一次模型 API，而是把规划、文件、subagent、摘要、
Skills、Memory、权限和人工介入组装成可以协同工作的系统。模型仍然负责理解与
决策；Harness 负责提供工具、上下文、状态和安全边界。

因此，create_deep_agent 不会让一个 Tool Calling 能力不足的模型突然稳定完成长任务。
模型的指令遵循、工具选择和上下文窗口，仍然决定了 Agent 的能力上限。

2. Deep Agents 的定位与技术栈

2.1 Deep Agents、deepagents 与 Agent 实例

官方将 Deep Agents 定位为 Agent Harness。Harness 可以理解为已经装配好通用能力的
Agent 工作台。本系列统一使用下面三个名称：

名称	含义
Deep Agents	官方项目和 SDK 的名称
deepagents	Python 包名，例如 pip install deepagents
Agent 实例	由 create_deep_agent 编译出的可运行 LangGraph

博客目录和历史标签仍保留 deepagent，但正文讨论官方项目时使用
“Deep Agents”，不再创造另一个框架名称。

2.2 Framework、Runtime 与 Harness

本文以 Framework、Runtime 和 Harness 三个核心层次为主，并把 Model Provider 与
Observability 放在完整技术栈中一起展示。Frameworks, runtimes, and harnesses
对这三类产品职责做了官方区分。

技术层	本系列使用的组件	主要职责
Model Provider	Qwen、GPT、Claude、Gemini 等	推理、生成与 Tool Calling
Agent Framework	LangChain	模型、消息、工具、Middleware 和 Agent Loop
Agent Harness	Deep Agents	装配 Prompt、规划、文件、subagent 和上下文管理
Agent Runtime	LangGraph	State、持久执行、流式、Interrupt 和恢复
Observability	LangSmith	Trace、评估、数据集和部署观测

这些组件不是互相替代的五个框架。典型调用关系是：Deep Agents 使用 LangChain
的 Agent 组件建立 Harness，将编译后的图交给 LangGraph 运行，图中的模型节点再调用
Provider；LangSmith 在旁路收集 Trace 和评估数据。

因此，学习 Deep Agents 仍然需要理解 LangChain 工具和 LangGraph State。Deep Agents
减少的是通用 Harness 的重复装配，不是把底层概念全部隐藏。

3. 理解 Deep Agents 的四层职责模型

这是本文为了讲解系统职责整理的概念视图，不是 Deep Agents 官方规定的包结构或固定分层。

3.1 Harness 装配层

入口 create_deep_agent 将模型、业务工具、System Prompt、Middleware、subagent、
Skills、Memory、Backend、权限、Checkpointer 和 Store 组装成一个可运行的
CompiledStateGraph。

这一层负责：

• 组合默认 Harness Prompt 与业务 Prompt；
• 注册文件、Todo、subagent 和业务工具；
• 根据配置加载 Skills、Memory 和自定义 Middleware；
• 组合文件权限与 interrupt_on；
• 将图编译后交给 LangGraph Runtime。

Deep Agents 可以向模型提供 execute 工具，但“看得到工具”不等于“能执行 Shell”。
只有实现 Sandbox Backend Protocol 的 Backend 才能真正执行命令；其他 Backend 下调用
execute 会返回不支持执行的错误。

3.2 上下文与任务管理层

这一层解决两个问题：当前应该做什么，以及哪些信息应该继续留在模型上下文中。

• write_todos 允许模型拆分和更新复杂任务；
• Filesystem Offloading 将过长结果保存为文件；
• Summarization 在达到阈值时压缩较早的消息；
• Memory 加载项目或用户约定；
• Skills 按需披露任务专用说明和资源；
• subagent 隔离中间工具输出，避免主上下文持续膨胀。

文件系统因此不只是为了生成产物。它也是上下文工程的一部分：模型可以先保存
大文本，再通过 grep 和 read_file 只取回当前决策需要的片段。

3.3 工具、Skills 与 subagent 层

能力	入口	职责与边界
自定义工具	tools=	调用业务函数、数据库或 API
MCP 工具	MCP Client 转换后的工具	连接独立工具服务
同步 subagent	subagents= 与 task	在独立上下文中完成可等待的子任务
异步 subagent	AsyncSubAgent	后台长任务或远端 Agent Server
Skill 资源与脚本	SKILL.md、scripts/、references/	提供按需加载的说明和确定性脚本；脚本执行仍依赖 execute、Backend 和权限

subagent 的主要价值之一是 Context Quarantine。它可以把大量中间工具结果留在
子任务上下文中，再将整理后的结论返回主 Agent。如果主 Agent 和 subagent 共享合适的
Backend 或文件命名空间，较大产物还可以写入 Backend，由主 Agent 按路径继续读取。
“返回摘要和路径”是推荐的上下文管理模式，不是框架强制的返回协议。

3.4 Backend、Sandbox 与持久化层

后端（Backend）决定文件存放在哪里，以及 execute 是否具备命令执行能力。

组件	解决的问题
StateBackend	在当前线程 State 中保存临时虚拟文件；不提供 Shell 执行
FilesystemBackend	将虚拟路径映射到本地磁盘
StoreBackend	跨线程保存长期文件或 Memory
CompositeBackend	根据路径将文件路由到不同 Backend
Sandbox Backend	实现 Sandbox Backend Protocol，在隔离环境执行命令并传输文件
Checkpointer	保存某个线程的图执行状态，支持中断与恢复
Store	保存跨线程、跨会话的数据

Backend 与 Checkpointer 不是同一个东西。Backend 面向文件和可选的执行能力，Checkpointer
面向图的执行状态。即使它们最终都使用数据库，也应该分别设计生命周期和租户隔离。

4. 一次复杂任务如何运行

下面是一个典型运行示例，不是每次调用都必须严格经过的固定状态机。具体的工具选择与调用顺序由当前模型、Prompt、任务复杂度和运行状态共同决定。

4.1 典型决策循环

以“生成季度销售分析报告”为例：

1. 用户消息进入 LangGraph State；
2. Harness 组合当前消息、Memory、工具描述和系统指令；
3. 对较复杂的任务，模型通常会调用 write_todos 建立计划；简单任务也可能直接执行，而不创建 Todo；
4. 模型在 Agent Loop 中决定读写文件、调用业务工具，或通过 task 委派 subagent；
5. subagent 可以把中间工具结果留在独立上下文中，将整理后的结论返回主 Agent；大型产物也可写入共享 Backend；
6. 如果需要执行脚本，execute 将请求交给 Backend；只有支持 Sandbox Backend Protocol 的 Backend 才会真正执行命令；
7. 模型根据工具结果继续决策，并可更新 Todo；
8. 只有当上下文达到配置阈值时，Summarization 才会压缩较早的消息；
9. 只有当工具命中 interrupt_on 等人工审批规则时，图才会在副作用发生前 Interrupt，Checkpointer 保存当前线程状态；
10. 人工完成 approve、edit 或 reject 后，应用使用相同 thread_id，并通过 LangGraph Resume 机制提交决策，图才会从 Interrupt 位置继续。

4.2 Interrupt 与 Resume 的最小心智模型

仅仅再次传入原 thread_id 不会自动表示“审批通过”。thread_id 用来定位原线程，
Resume Command 才携带人工决策：

from langgraph.types import Command

config = {"configurable": {"thread_id": "report-2026-q2"}}

resumed = agent.invoke(
    Command(resume={"decisions": [{"type": "approve"}]}),
    config=config,
)

edit 和 reject 的决策数据不同，但原则一样：Checkpointer 保存可恢复状态，
thread_id 定位线程，Resume 数据表达人工决策。

5. Deep Agents 的核心能力

从工程职责来看，Deep Agents 的主要能力可以归纳为规划、虚拟文件系统、任务委派、
上下文管理、代码执行、人工介入、Skills 和长期记忆。在本系列固定的
deepagents==0.6.12 中，它们大致对应下面的实现：

核心能力	主要实现	对模型呈现的能力
任务规划	TodoListMiddleware	write_todos；是可用工具，不是每次必经步骤
虚拟文件系统	FilesystemMiddleware + Backend	ls、read_file、write_file、edit_file、glob、grep
子任务委派	subagent Middleware	task 或异步任务工具
上下文管理	Summarization、Filesystem Offloading、subagent 隔离	压缩历史、按需读文件、隔离中间结果
代码执行	execute 工具 + Sandbox Backend Protocol	Backend 支持时执行命令；不支持时返回错误
人工介入	HITL Middleware + Checkpointer	approve、edit、reject 与 Resume
Skills	SkillsMiddleware	读取 SKILL.md 与其引用资源；不自动把脚本注册成工具
长期记忆	MemoryMiddleware + 持久 Store	AGENTS.md、跨线程文件或用户偏好

不需要死记 Middleware 的类名，更重要的是记住每个组件解决的工程问题。例如，
Skills 解决按需披露问题，Sandbox 解决命令执行隔离问题，两者不是同一层保障。

6. 什么时候使用 Deep Agents

6.1 普通 Agent、Workflow 与 Deep Agents 不是三选一

真实系统经常使用混合架构：外层确定性 Workflow 保证订单、审批和发布等步骤必然发生；
某个节点内部使用 Deep Agents 完成开放式调查和文件处理；高风险工具再回到固定审批节点。

维度	普通 Agent	Workflow	Deep Agents
步骤决定	模型在小型循环中决定	程序预先定义	模型动态规划，Harness 提供文件、委派和恢复能力
上下文规模	小到中等	每个节点可单独控制	面向长任务，内置卸载、摘要和隔离
文件能力	自行添加工具	节点代码直接操作	虚拟文件工具与可插拔 Backend
子任务	自行设计	使用节点或子图	内置 subagent 委派机制
可预测性	取决于工具和 Prompt	通常最高	默认较低，可通过工具约束、Middleware、权限、结构化输出和外层 Workflow 提升
开发成本	最低	随流程复杂度增加	Harness 提供通用能力，但学习和运行成本更高

Deep Agents 与 Claude Agent SDK 都属于 Agent Harness，但在模型耦合、运行时和扩展方式上
存在差异。本系列选择 Deep Agents，是因为它能够复用 LangChain、LangGraph 和 LangSmith
生态，并允许替换模型与 Backend。详细选型可参考官方
Comparison。

6.2 适合与不适合的场景

Deep Agents 通常适合：

• 步骤会随中间结果变化的长任务；
• 需要读写大量文件或长工具输出的任务；
• 需要 subagent 上下文隔离的研究、编程或分析任务；
• 需要生成产物、执行脚本、暂停审批和恢复的任务。

下面场景通常不应该直接使用 Deep Agents：

场景	更合适的方案	原因
单轮分类、摘要、翻译	直接调用模型	没有 Agent Loop 的必要
只调用一个查询工具	LangChain create_agent	规划、文件和 subagent 能力过重
步骤可枚举的强合规流程	LangGraph Workflow	显式节点和状态转换更可预测
毫秒级接口	普通服务或确定性代码	多轮模型与工具调用延迟过高
严格数值计算	Python、SQL 或计算引擎	模型负责选择和解释，不应代替计算器
无法提供命令隔离	禁止开放命令执行	不应让模型生成的代码直接运行在生产宿主机

可以把下面五个问题作为初步判断清单，而不是严格的选型规则：

1. 任务是否需要多步规划，且步骤会根据中间结果变化？
2. 是否会产生大量文件、搜索结果或工具输出？
3. 是否需要上下文隔离或专用 subagent？
4. 是否需要运行脚本、生成文件或长时间执行？
5. 是否需要中断恢复、人工审批或长期记忆？

满足的条件越多，Deep Agents 提供的规划、文件、隔离和恢复能力通常越有价值，
但最终仍然要结合任务风险、延迟、成本与可预测性要求判断。

7. 版本说明与总结

7.1 本系列的版本基线

本系列主线代码固定使用 deepagents==0.6.12，并使用 requirements-lock.txt 保存
完整依赖解析结果。其他版本的参数、Middleware 顺序和 Preview API 可能不同。

本系列遵守下面的验证原则：

1. 文章代码以安装后的稳定版签名为准；
2. Beta 或 Preview 能力放在独立示例中标注边界；
3. 默认回归测试不访问网络；
4. 需要模型、Sandbox 或远程服务的测试单独开启；
5. 外部能力没有真实验证时，不使用 Fake 结果冒充在线记录。

7.2 常见误区

Deep Agents 使用了比普通 Agent 更复杂的推理算法吗？

不是。核心仍然是模型与 Tool Calling Loop，主要增量来自 Harness 提供的上下文管理、
任务委派和运行控制。

看到 execute 工具就说明可以执行 Shell 吗？

不是。Deep Agents 可以向模型暴露 execute，但只有实现 Sandbox Backend Protocol 的
Backend 才具备真实执行能力；其他 Backend 会返回不支持执行的错误。

subagent 越多，系统就越强吗？

不是。subagent 会增加模型调用、任务描述和结果合并成本。简单任务由主 Agent 直接完成
通常更稳定。

Checkpointer 就是长期记忆吗？

不是。Checkpointer 保存线程执行状态；跨线程长期数据通常需要 Store 与相应的
Backend 路由。Sandbox 也不能替代权限控制：前者隔离执行环境，后者限制 Agent 可以读写
和调用什么。

7.3 总结

Deep Agents 是建立在 LangChain Agent 组件和 LangGraph Runtime 之上的 Agent Harness。
它没有改变模型调用工具的基本循环，而是把复杂任务所需的规划、文件、上下文压缩、
subagent、Skills、Memory、Sandbox、权限和人工介入组织成一套统一架构。

理解 Deep Agents 时，可以始终抓住三个问题：

1. 当前信息应该放在消息、文件、State 还是长期 Store 中？
2. 当前工作应该由主 Agent、工具、Skill 资源还是 subagent 完成？
3. 当前操作应该自动执行、放入 Sandbox，还是在副作用前等待人工决策？

掌握这三个判断问题后，再进入环境搭建和实际编码，就不容易把
Deep Agents 误解成单纯的模型封装，也能更早发现上下文、执行与安全边界中的问题。

7.4 附录：0.6.12 实现与代码验证

下面内容用于版本审计，不是初次阅读时必须记忆的概念。

create_deep_agent 参数分组

类别	参数
模型与行为	model、system_prompt、response_format
能力扩展	tools、middleware、skills、memory
任务委派	subagents
文件与控制	backend、permissions、interrupt_on
状态与上下文	state_schema、context_schema
持久化	checkpointer、store、cache
运行辅助	debug、name

初学阶段只需先理解 model、tools、system_prompt、backend、subagents、
skills、memory、checkpointer 和 store。其余参数在后续专题中使用时再学习。

0.6.12 Middleware 装配顺序

1. Todo 规划；
2. Skills（配置时）；
3. Filesystem；
4. 同步 subagent（存在时）；
5. Summarization；
6. Tool Call 状态修补；
7. 异步 subagent（配置时）；
8. 用户 Middleware；
9. Harness Profile（配置时）；
10. Prompt Cache（兼容时）；
11. Memory（配置时）；
12. HITL（配置时）。

这个顺序是 0.6.12 的实现细节，不是永久协议。完整 Middleware 行为在第 10 篇专题讨论。

examples/p01_architecture/inspect_agent.py 使用 inspect.signature 检查安装版本的公开参数，
不访问网络。验证命令如下：

cd source/_posts/deepagent/examples
.venv_deepagent/bin/python -m p01_architecture.inspect_agent
.venv_deepagent/bin/pytest p01_architecture -q

当后续升级依赖导致公共入口发生变化时，这组测试应该先失败，而不是等文章中的示例
运行到一半才发现版本不一致。