一、它到底是什么

先抓核心定义：
• 官方把 Deep Agents 描述为：“the easiest way to start building agents … with built-in capabilities for task planning, file systems for context management, subagent-spawning, and long-term memory”，也就是内置了任务规划、文件系统上下文管理、子代理生成、长期记忆。 
• 它是一个独立库，建立在 LangChain 的 agent 构件之上，并使用 LangGraph 作为运行时，以获得持久执行、流式输出、人类介入等能力。 
• create_deep_agent 返回的是一个已编译的 LangGraph graph，所以它天然能接 LangGraph 的流式、checkpoint、持久化等特性。 

换句话说：

LangChain 是基础积木，LangGraph 是运行时引擎，Deep Agents 是把这些能力打包成“开箱即用复杂任务智能体”的成品骨架。 这也是它和普通 create_agent 的关键区别。 

⸻

二、为什么会有 Deep Agents

普通 agent 往往适合这种任务：

问一个问题 → 调 1~3 个工具 → 给答案

但一旦任务变成：
• 先检索，再比较，再归纳，再写文档
• 先读多个文件，再修改代码，再跑命令，再修复错误
• 需要执行 20~50 次工具调用
• 中间结果很长，不能一直塞在上下文里
• 需要把子问题隔离出来，避免主上下文被污染

普通 agent 就容易出现几个问题：
1. 没有真正的规划能力
它会“边想边调”，但不擅长先拆任务、再执行、再更新状态。
2. 上下文爆炸
工具返回太长、对话太长，很快把上下文窗口塞满。
3. 没有工作区
中间报告、草稿、代码片段、检索结果没有地方放，只能硬塞 prompt。
4. 没有上下文隔离
一个子任务产生的大量细节会污染主任务上下文。
5. 长任务不稳定
任务做一半容易丢目标、重复劳动、忘记先前结论。

Deep Agents 正是为这些“长链路任务”设计的。官方明确说它适合需要planning and decomposition、filesystem tools、subagents、persistent memory 的复杂任务。 

⸻

三、Deep Agents 的核心设计思想

1）它不是“更聪明的 prompt”，而是“更完整的执行环境”

Deep Agents 的重点不是只靠 system prompt 让模型变聪明，而是给模型一个更接近“工作台”的环境：
• 有 todo 计划板
• 有文件系统
• 有 shell
• 有子代理
• 有记忆
• 有可追踪运行时

所以它更像“给 LLM 配了一个操作系统级别的工作台”，而不是单纯“帮你多写了一层 prompt”。

2）把“上下文”从纯文本对话，扩展成“对话 + 文件 + 记忆 + 子任务隔离”

普通聊天式 agent 的上下文主要是消息历史。
Deep Agents 的上下文则被拆到多个层面：
• 对话历史
• Todo 计划
• 文件系统中的中间成果
• 记忆存储
• 子代理自己的隔离上下文

这就是它能做更长任务的关键。

⸻

四、核心能力逐个讲透

1. 任务规划：write_todos

Deep Agents 内置一个 write_todos 工具，专门让 agent 把复杂任务拆成离散步骤、跟踪进度、根据新信息更新计划。官方把它作为 planning and task decomposition 的核心能力。 

这意味着它不是这样工作：

用户说一句 → 模型直接一路冲

而更像这样：
1. 理解目标
2. 拆成若干子步骤
3. 标记当前进行中的步骤
4. 执行一步
5. 根据结果调整后续 todo
6. 最终收束输出

这对复杂任务特别重要。比如“研究某个行业并出报告”时，它会更自然地形成：
• 收集资料
• 对比来源
• 归纳结论
• 写摘要
• 写完整报告
• 自检

这种机制的价值不只是“看起来更有条理”，而是能显著降低任务漂移。

⸻

2. 文件系统：把上下文从 prompt 搬到工作区

这是 Deep Agents 最有辨识度的能力之一。

官方文档列出了文件工具，例如：
• ls
• read_file
• write_file
• edit_file

GitHub README 还提到 glob、grep 等。它们用于读写上下文、管理中间成果。 

为什么这很关键？

因为在长任务里，大量信息其实不应该一直放在上下文窗口中，而应该写入“外部工作区”：
• 检索到的网页摘要
• 草拟的报告
• 代码文件
• 配置文件
• 对比结果
• 中间分析结论

这样做有几个直接好处：

第一，防止上下文爆掉。
官方明确说文件系统工具可以把大上下文卸载到内存或文件系统，避免 context window overflow。 

第二，让工具结果长度不再成为瓶颈。
有些网页、日志、代码文件非常长，不适合直接塞进 messages；写到文件后，agent 可以按需局部读取。

第三，更接近真实工作方式。
人做复杂任务也是“边查边记、边写边改”，而不是把所有信息都死记在脑子里。

所以你可以把 Deep Agents 的文件系统理解为：
给 agent 配了一个可读写的外部脑。

⸻

3. 可插拔文件系统后端

Deep Agents 的文件系统不是写死的。官方强调它支持 pluggable backends，可以切换成：
• in-memory state
• local disk
• LangGraph store 用于跨线程持久化
• sandboxes
• 自定义 backend
• 复合路由 backend

这些都在文档中明确提到。 

这意味着它不仅适合本地 demo，也适合生产架构：
• 开发阶段：用内存或本地磁盘
• 线上任务：接持久化 store
• 安全执行：接 sandbox
• 多租户系统：自定义隔离 backend

这一层设计很工程化，因为它把“agent 怎么访问工作区”抽象成了基础设施，而不是写死在业务代码里。

⸻

4. 子代理：task 工具

Deep Agents 的另一个核心能力是 subagent spawning。官方说明中提到内置的 task 工具可以让 agent 生成专门的子代理来处理子任务，并通过隔离上下文防止主上下文被污染。 

这点非常重要。

很多复杂任务天然适合拆成几个不同职责的角色，例如：
• 主代理：负责总体规划与最终交付
• 子代理 A：做资料检索
• 子代理 B：做表格汇总
• 子代理 C：做代码修复
• 子代理 D：做最终校对

为什么不能全让一个 agent 干？

因为每个子任务都会产生大量局部细节。如果都塞进主上下文，主代理会越来越“脏”，后面更容易迷失主线。

子代理的作用，就是：
• 把子任务关进一个隔离的上下文空间
• 做完后只把必要结论带回来
• 不把所有中间噪声都回灌到主线程

这非常像工程里的“模块化”与“信息隐藏”。

⸻

5. 上下文管理：自动压缩与卸载

官方 README 明确提到它的 context management 包括：
• 对长对话做 auto-summarization
• 大输出结果可保存到文件
• CLI 还提到 context compaction & offloading，即把旧消息总结并把原始内容卸载到后端存储，释放上下文窗口。 

这是 Deep Agents 真正“深”的地方。

大多数人搭 agent 时，最容易忽略的不是工具，而是上下文管理。
任务一长，真正的难点往往不是“能不能调用工具”，而是：
• 哪些历史要保留
• 哪些要压缩
• 哪些写入文件
• 哪些直接丢弃
• 哪些只在子任务里保留

Deep Agents 把这层做成了框架级能力，而不是完全让开发者自己拼。

对生产系统来说，这有两个实际价值：

一是稳定性更高。
长任务不会因为上下文爆炸而迅速失控。

二是成本更低。
不需要把所有长历史都反复传给模型，token 成本和延迟都会更可控。官方网站也提到 prompt caching 和上下文压缩等思路。 

⸻

6. 长期记忆

Deep Agents 支持用 LangGraph 的 Memory Store 实现跨线程、跨会话的持久记忆。官方文档明确写到，agent 可以从之前对话中保存和检索信息。 

这意味着它能记住一些长期有效的信息，例如：
• 用户偏好的报告格式
• 项目代码风格
• 常用命令
• 某个组织内部的术语
• 特定任务领域的固定规则

这类信息不是一次任务的“短期上下文”，而是长期有效的“习惯”和“背景知识”。

在 CLI 文档里，官方也写到 Deep Agents CLI 可以在会话之间保留记忆、学习项目约定。 

⸻

7. Shell、Web、HTTP、人类审批

从 GitHub README 和 CLI 文档看，Deep Agents 不止文件读写，还能支持：
• execute 执行 shell 命令
• web search
• HTTP requests
• human-in-the-loop approval
• skills
• MCP tools

这些能力在 CLI 文档和仓库中都有明确描述。 

这意味着它很适合做“实际工作型 agent”：
• 读代码
• 改代码
• 执行测试
• 查文档
• 调接口
• 请求审批
• 最终提交结果

这也是为什么官方把 CLI 定位成一个“terminal coding agent”。 

⸻

五、它的运行方式是什么样的

你可以把 Deep Agent 的典型执行流理解成下面这样：
1. 接收用户目标
2. 生成或更新 todo
3. 判断当前步骤需要什么
• 查资料
• 读文件
• 写文件
• 开子代理
• 跑 shell
4. 执行工具
5. 将大结果写入文件/存储
6. 把必要结论回灌到主上下文
7. 继续下一个 todo
8. 最终汇总输出

相比普通 agent，多出来的关键环节有三个：
• 计划层
• 工作区层
• 上下文治理层

这三层，正是它能胜任复杂任务的根本原因。

⸻

六、create_deep_agent 是什么

官方 reference 把 create_deep_agent 定义为一个 factory function，用于创建具备规划、文件系统和子代理能力的 deep agent。 

从官方示例和 README 可以看到，它的用法很直接：
• 可以零配置起一个 agent
• 也可以自定义 model、tools、system_prompt 等

例如官方最简单的例子就是：
• pip install deepagents
• from deepagents import create_deep_agent
• agent = create_deep_agent()

然后让它去 research 和写 summary。 

而在更常见的工程里，你会这样用：
• 传入一个支持 tool-calling 的模型
• 注入业务工具
• 配系统提示词
• 配内存
• 配后端
• 配子代理

这说明它的定位不是“黑盒成品”，而是开箱即用，但仍然可深度定制。 

⸻

七、它依赖哪些底层能力

从官方文档可以归纳出几个前提：

1）模型必须支持 tool calling

Quickstart 明确说明 Deep Agents 需要支持 tool calling 的模型。 

2）底层依赖 LangGraph 运行时

Deep Agents 用 LangGraph 来提供 durable execution、streaming、human-in-the-loop 等运行时特性。 

3）LangChain 负责核心 agent building blocks

也就是说，Deep Agents 不是脱离 LangChain 生态的独立体系，而是站在 LangChain/LangGraph 之上的高层抽象。 

⸻

八、和普通 LangChain Agent 的区别

官方建议写得很清楚：
• 简单 agent：考虑用 LangChain 的 create_agent
• 复杂长任务 agent：用 Deep Agents SDK
• 命令行 coding agent：用 Deep Agents CLI
• 需要完全自定义流程：直接构建 LangGraph workflow 

所以它不是替代一切，而是针对某一类问题最合适。

你可以这样理解：

普通 create_agent

适合：
• FAQ
• 轻量工具调用
• 简单助手
• 少量步骤的业务编排

Deep Agents

适合：
• 深度研究
• 复杂写作
• 代码修改与测试闭环
• 多文件读写
• 长链路任务执行
• 需要记忆、子代理、上下文治理的场景

直接 LangGraph

适合：
• 你要完全控制状态机、节点、边、恢复逻辑
• 你不想用“意见化”的默认行为
• 你要构建高度可控的企业级 workflow

⸻

九、它为什么叫 “agent harness”

这个词很关键。

Harness 不是“模型本身”，而是“把模型驾驭起来的一套骨架/装具”。
GitHub README 用了很明确的话：它是 an opinionated, ready-to-run agent out of the box。 

“Opinionated” 的意思是：
• 它已经替你做了一些设计选择
• 不要求你从零定义所有细节
• 默认鼓励你采用一套被官方认为更适合复杂任务的模式

这有好处也有边界。

好处
• 上手快
• 复杂能力现成可用
• 少踩很多上下文管理的坑
• 适合快速做 MVP 和生产化原型

边界
• 如果你想完全自定义每一步执行逻辑，可能会觉得它“帮你做得太多”
• 某些高度垂直、强约束的业务流，直接用 LangGraph 可能更合适

所以 Deep Agents 最适合的不是“极简型应用”，也不是“极致定制型底层工作流”，而是中间那一大类：

复杂，但又希望快速落地的 agent 应用。

⸻

十、Deep Agents CLI 是什么关系

官方文档写得很明确：Deep Agents CLI 是 built on the Deep Agents SDK 的 terminal coding agent。 

也就是说：
• SDK 是给开发者集成到自己系统里的
• CLI 是官方做好的一个终端 coding agent 产品形态

CLI 自带这些能力：
• 文件操作
• shell 执行
• web search
• HTTP requests
• todo planning
• memory
• 上下文压缩/卸载
• human approval
• skills
• MCP tools
• LangSmith tracing 

它有点像“官方把 Deep Agents 的典型能力做成了一个能直接在终端里用的智能编码助手”。

⸻

十一、典型应用场景

1）Deep Research

官方 quickstart 就是研究并写报告的例子。 

这是它最自然的场景之一，因为研究任务天然符合：
• 先规划
• 分多轮检索
• 汇总资料
• 写草稿
• 反复修订

2）Coding Agent

CLI 的定位就是 terminal coding agent。 

适合：
• 改代码
• 跑测试
• 分析日志
• 修改文档
• 执行 shell 命令
• 记录项目约定

3）企业内部知识工作流

例如：
• 读多个文档
• 提取重点
• 生成方案
• 输出报告
• 保存中间结果
• 长期记住团队偏好

4）多阶段业务自动化

例如：
• 接收任务
• 查询系统
• 做对比分析
• 生成交付物
• 人工审批
• 继续执行

⸻

十二、它适合什么团队

Deep Agents 尤其适合这几类团队：

A. 想尽快把复杂 Agent 跑起来的应用团队

不想从零搭：
• planning
• context compaction
• file workspace
• subagents
• memory

这时 Deep Agents 很合适。

B. 做“研究/写作/代码/运维型” Agent 的团队

因为这些任务都不是一跳完成，而是需要持续工作。

C. 已经在 LangChain / LangGraph 生态里的团队

因为接入成本更低，生态兼容也更自然。 

⸻

十三、它不一定适合什么场景

Deep Agents 很强，但不是所有场景都该用。

1）非常简单的问答助手

比如只查一个知识库、调一个工具、返回一段答案。
这类任务直接用 create_agent 往往更轻。 

2）强流程、强状态机、强审计的企业流程

比如审批流、固定分支业务流。
如果每个节点都要严格控制，手写 LangGraph 往往更稳。

3）对工具权限极其敏感的环境

虽然它支持 human-in-the-loop 和 sandbox，但如果你环境对 shell/file/http 权限非常保守，就需要额外设计安全边界。 

⸻

十四、一个更工程化的理解方式

你可以把 Deep Agents 拆成 5 层：

第 1 层：模型层

支持 tool calling 的 LLM。 

第 2 层：运行时层

LangGraph 提供持久化、流式、checkpoint、人机协同。 

第 3 层：执行骨架层

Deep Agents 提供：
• write_todos
• 文件工具
• 子代理
• 上下文治理
• 记忆接入 

第 4 层：业务工具层

你自己的 search、DB、API、知识库、业务操作工具。

第 5 层：产品层

CLI、研究助手、编码助手、企业工作台等。

这样看，它其实是一个“把复杂任务智能体标准件化”的框架。

⸻

十五、一个实际例子：为什么它比普通 Agent 更合适

假设你要做一个“招投标文件分析助手”：

用户说：

读取 20 份招标文件，提取资格要求、评分项和商务条款，做对比并输出总结报告。

普通 agent 会遇到的问题：
• 文件太多
• 内容太长
• 中间提取结果太多
• 最终要写正式报告
• 还要支持后续修订

Deep Agents 的处理方式更自然：
1. write_todos 先拆任务
2. 每份文件读取后，把提取结果写到单独文件
3. 子代理分别负责不同文件或不同维度
4. 主代理只拿关键摘要做汇总
5. 报告草稿写到文件
6. 用户要求“再加商务风险分析”时，继续读已有文件产物而不是重来

这就是它的工程优势。

⸻

十六、官方生态信号

从官方资料可以看到几个重要信号：
• 它是 MIT 开源。 
• 它是 provider agnostic，适配任何支持 tool calling 的模型。 
• 官方文档既提供 SDK，也提供 CLI，也有 JS 方向项目链接，说明它不是一次性 demo，而是持续建设中的产品化框架。 
• 官方推荐结合 LangSmith 做 tracing/debug/evaluation。 

这说明它的目标不是只让你“玩一下 agent”，而是让你把 agent 做成可调试、可观察、可持续迭代的工程系统。

⸻

十七、你该如何判断要不要选它

你可以用一个简单标准：

选 Deep Agents，当你满足其中 3 条以上时：
• 任务不是一步完成，而是长链路
• 需要规划和 todo 跟踪
• 需要大量中间结果存储
• 需要文件读写或代码修改
• 需要子任务隔离
• 需要会话外记忆
• 需要人类审批
• 需要可观测的运行时

不一定选它，当你的需求更像：
• 单轮问答
• 简单工具调用
• 固定流程编排
• 极小上下文
• 不需要文件系统/子代理/记忆

⸻

十八、一句话总结

LangChain 的 Deep Agents / deepagents，本质上是一个面向复杂长任务的“智能体执行骨架”。它在普通 tool-calling agent 之上，预置了规划、文件系统、子代理、上下文治理、长期记忆和 LangGraph 运行时能力，使 agent 可以像“真正工作的执行者”一样完成研究、写作、编码和多步骤业务任务。