Deep Agents 深度分析：不但是又一个 Agent 框架

拆解 LangChain 最新开源的 Deep Agents 项目，看看这个"batteries-included agent harness"到底"含"了哪些电池，以及背后的计划哲学是什么。

一、定位：它到底是什么？

Deep Agents 不是一个新的 Agent 框架，它是一个高度定制的 Agent Harness——站在 LangGraph 和 LangChain create_agent 的肩膀上，给你一套开箱即用的 Agent 实现。官方的比喻很精准：

LangGraph 是发动机，LangChain create_agent 是一台底子车，Deep Agents 是一台把全部选配都装好的高配车。

这意味着你可以直接用，也可以把任何一个部件换掉——不必要 fork，直接 override。
相比 LangChain create_agent，Deep Agents 多了什么？

本事LangChain create_agentDeep Agents工具调用✅✅多轮对话✅✅子 Agent 委托❌ 本身实现✅ 内置文件体系利用❌ 本身实现✅ 可插拔后端上下文管理（自动压缩）❌✅ 自动/手动Shell 实行❌✅ 可设置沙箱跨会话影象❌✅ 可插拔Human-in-the-Loop❌✅ 内置Skills 技能体系❌✅MCP 工具❌✅生产摆设必要本身搭✅ LangSmith 全链路二、焦点架构：Middleware 模式

Deep Agents 的焦点计划模式是 Middleware——每个功能都以中央件的方式注入到 Agent 的生命周期中。这种计划带来的利益是：

• 洋葱模子：每个中央件可以包裹模子调用前后，形成条理化的处理处罚管道
  
• 可组合：恣意增长、移除、更换中央件，不影响其他功能
  
• 关注点分离：每个中央件只做一件事，不相互耦合
  

1. from deepagents import create_deep_agent
3. agent = create_deep_agent(
4.     model="openai:gpt-5.5",
5.     middleware=[
6.         FilesystemMiddleware(backend=my_backend),
7.         SubAgentMiddleware(...),
8.         SummarizationMiddleware(...),
9.         HumanInTheLoopMiddleware(...),
10.     ],
11. )

复制代码

默认中央件栈

当你调用 create_deep_agent() 时，它自动组装了一套完备的中央件栈，大抵如下：

1.     请求进入
2.        │
3.        ▼
4. ┌─────────────────────────┐
5. │  PromptMiddleware        │  ← 注入系统提示词
6. ├─────────────────────────┤
7. │  TodoListMiddleware      │  ← 任务规划（TodoWrite 工具）
8. ├─────────────────────────┤
9. │  FilesystemMiddleware    │  ← 文件读写/编辑/搜索
10. ├─────────────────────────┤
11. │  SubAgentMiddleware      │  ← 子 Agent 委托
12. ├─────────────────────────┤
13. │  SummarizationMiddleware │  ← 上下文压缩
14. ├─────────────────────────┤
15. │  HumanInTheLoopMiddleware│  ← 人工审批
16. ├─────────────────────────┤
17. │  SkillsMiddleware        │  ← 动态加载技能
18. ├─────────────────────────┤
19. │  ToolsMiddleware         │  ← 用户自定义 + MCP 工具
20. └─────────────────────────┘
21.        │
22.        ▼
23.    LLM 调用

复制代码

三、子 Agent（Sub-Agent）机制

3.1 焦点标题

传统单 Agent 在复杂使掷中面对两个挑衅：

• 上下文窗口污染：子使命的分析过程占据大量 context，影响主使命质量
  
• 脚色肴杂：Agent 在处理处罚差别性子的使命时，难以维持同等的脚色定位
  

3.2 计划头脑

Sub-Agent 的本质是上下文隔离 + 委托实行 + 效果接纳。主 Agent 将子使命"外包"给一个拥有独立上下文窗口的子 Agent，子 Agent 完成使命后返回效果，主 Agent 继承推进。

1. 主 Agent 上下文                子 Agent 上下文
2. ┌──────────────────┐         ┌──────────────────┐
3. │ "分析项目结构"    │         │                  │
4. │ "读取 README"     │ spawn   │ 独立分析         │
5. │ "写研究报告..."   │ ──────► │ 文件读写         │
6. │                   │         │ 子任务规划       │
7. │                   │ ◄────── │                  │
8. │ 回收结果，继续... │  result │                  │
9. └──────────────────┘         └──────────────────┘

复制代码

3.3 实现亮点

从代码中可以看到，Sub-Agent 的创建支持非常机动的设置：

1. # 预设模板
2. "research"       # 研究型子 Agent
3. "coding"         # 编码型子 Agent
4. "general"        # 通用型子 Agent
6. # 通用创建
7. create_subagent(
8.     name="my_agent",
9.     description="做什么的",
10.     system_prompt="自定义提示词",
11.     tools=[...],             # 子 Agent 的专属工具
12.     middleware=[...],        # 子 Agent 的专属中间件
13.     model="...",             # 可以指定不同模型
14. )

复制代码

子 Agent 可以拥有与主 Agent 完全差别的工具集（大概共享部门工具），这意味着你可以给编码子 Agent 配备 Shell 和文件工具，而给研究子 Agent 配备搜刮引擎——按需设置，不浪费 context。
四、上下文管理（Context Management）

这是 Deep Agents 最"硬核"的三个功能之一。让我从代码层面深入分析。
4.1 标题界说

在长时间运行的 Agent 会话中，消息汗青会不停膨胀。一个复杂编程使命大概产生几百条消息、几十万 tokens——远超任何模子的上下文窗口。
4.2 三层上下文压缩战略

深入读了源码后，我发现 Deep Agents 的上下文管理实际上分三个条理：
第一层：工具参数截断（Truncate Args）

在触发完备择要之前，先对旧消息中的大参数做轻量级裁剪。代码中的 _truncate_args 方法只针对 write_file 和 edit_file 的 args 做截断：

1. 原始: write_file(path="main.py", content="(5000行代码)")
2. 截断: write_file(path="main.py", content="import os\nimport...(argument truncated)")

复制代码

这层战略的精妙之处在于：

• 触发阈值比完备择要低（默认 20 条消息或 10% context window）
  
• 只影响旧消息，最新 20 条消息保持完备
  
• 不必要 LLM 调用，纯盘算利用，零本钱
  

第二层：自动择要压缩（Auto Summarization）

当 token 使用量到达触发阈值（默认 85% context window），自动触发择要。焦点流程：

1. 1. 计算 cutoff_index（保留最近 N 条消息）
2. 2. 将 cutoff 之前的历史 → 写入后端文件 → 生成 LLM 摘要
3. 3. 用摘要 HumanMessage 替代所有旧消息
4. 4. 模型看到的是: [摘要消息] + [保留的最近消息]

复制代码

关键实现细节（从 wrap_model_call 代码中看到）：

1. # Step 1: 先尝试不摘要的调用
2. if not should_summarize:
3.     try:
4.         return handler(request.override(messages=truncated_messages))
5.     except ContextOverflowError:
6.         # 如果模型报 context overflow，fallback 到摘要路径
7.         pass
9. # Step 2: 摘要 + 重试
10. messages_to_summarize, preserved_messages = _partition_messages(...)
11. file_path = _offload_to_backend(backend, messages_to_summarize)
12. summary = _create_summary(messages_to_summarize)

复制代码

这个计划非常聪明：

• 正常环境下走 threshold 查抄
  
• 如果 provider 忽然报 ContextOverflowError（比如 token 盘算禁绝），自动 fallback 到择要
  
• 非粉碎性：使用 wrap_model_call 而非直接修改 state["messages"]，原始消息汗青完备生存
  
• 择要链式支持：第二次择要时自动过滤上一次的择要消息，不重复存储
  

第三层：手动压缩工具（compact_conversation）

Agent 本身可以自动调用 compact_conversation 工具来压缩上下文。这在以了局景特殊有效：

• 使命切换：上一个使命的分析过程不再必要
  
• 阶段性总结：提取关键信息后可以压缩
  

风趣的是，代码中设置了 50% 触发阈值的 eligibility gate——在上下文还没到达 auto-summarization 触发阈值的一半时，手动压缩会返回"Nothing to compact"。
4.3 大工具效果处理处罚（Large Tool Result Offloading）

代码中的 _message_eviction.py 专门处理处罚单个工具效果的 offload。当某个 ToolMessage 的内容过大时：

1. TOO_LARGE_TOOL_MSG = """Tool result too large, the result was saved at: {file_path}
3. Here is a preview showing the head and tail of the result:
4. {content_sample}
5. """

复制代码

• 完备效果写入后端文件（路径包罗 tool_call_id 供回溯）
  
• 消息中只生存 head（前5行）+ tail（后5行）预览
  
• Agent 必要用 read_file 工具按需读取完备效果
  

4.4 后端存储战略

压缩掉的消息不丢失，同一追加到：

1. /conversation_history/{thread_id}.md

复制代码

每次压缩在文件中追加一个新 section：

1. ## Summarized at 2026-05-30T22:04:00+00:00
3. Human: ...
4. AI: ...
5. Tool: ...

复制代码

这个计划让 Agent 在必要时可以 read_file 回到汗青中去查找细节。
五、文件体系中央件

5.1 计划哲学

Deep Agents 通过 CompositeBackend 和 FilesystemMiddleware 实现了同一的文件利用接口。焦点计划：

• 三层后端体系：StateBackend（对话级临时存储）、FilesystemBackend（本地磁盘）、StoreBackend（跨会话恒久化）
  
• 同一 API：全部后端实现 read/write/edit/ls/grep 等接口，对 Agent 透明
  
• 资源路由：差别级别的资源（临时文件、项目文件、恒久数据）自动路由到对应后端
  

5.2 关键机制

1.                 CompositeBackend
2.                       │
3.          ┌────────────┼────────────┐
4.          ▼            ▼            ▼
5.    StateBackend  FilesystemBackend  StoreBackend
6.    /memory_memory/       /            /store/
7.    对话级缓存          项目文件      跨会话数据

复制代码

每次工具调用时，后端会根据资源路径自动选择对应的存储层。Agent 不必要关心文件存在那里。
六、可插拔后端

6.1 协议计划

从代码中可以看到，全部后端都遵照 BackendProtocol：

1. # 核心接口
2. class BackendProtocol:
3.     # 基础 CRUD
4.     async def aread(paths) -> list[FileResponse]
5.     async def awrite(path, content) -> Result
6.     async def aedit(path, old_content, new_content) -> Result
7.    
8.     # 列表与搜索
9.     async def als(paths) -> list[DirectoryResponse]
10.     async def agrep(pattern, paths) -> list[GrepMatch]
11.    
12.     # 批量传输
13.     async def aupload(paths) -> ...
14.     async def adownload_files(paths) -> ...

复制代码

这意味着你可以把 Deep Agents 的后端从本地文件体系一键切换到：

• StateBackend：纯内存，对话级生命周期
  
• FilesystemBackend：本地磁盘或沙箱
  
• StoreBackend：跨会话恒久化（通过 LangGraph Store）
  
• CompositeBackend：组合多个后端，按路径前缀自动路由
  
• 自界说后端：实现 BackendProtocol 即可接入任何存储（S3、数据库、分布式文件体系…）
  

6.2 CompositeBackend 的资源路由

1. /                          → FilesystemBackend (本地/沙箱)
2. /conversation_history/*    → StoreBackend (跨会话)
3. /memory_*                  → StateBackend (对话级)
4. /large_tool_results/*      → FilesystemBackend (按需读取)

复制代码

七、生产级特性

7.1 Human-in-the-Loop

Deep Agents 内置了工具调用审批机制。Agent 在实行敏感利用（写文件、实行 Shell 下令、发送 HTTP 哀求）前，必要人工审批：

1. HumanInTheLoopMiddleware(
2.     interrupts_on={
3.         "write_file": "always",     # 文件写入：总是审批
4.         "execute": "always",        # Shell：总是审批
5.         "read_file": "never",       # 文件读取：不审批
6.     }
7. )

复制代码

支持三种审批效果：

• Approve：允许实行
  
• Edit：修改参数后允许
  
• Reject：拒绝实行，Agent 收到拒绝反馈后调解战略
  

7.2 Skills 体系

Skills 是可复用的"运动包"，Agent 在必要时动态加载：

1. # 每个 Skill 包含：
2. create_skill(
3.     name="pdf-reader",
4.     description="读取和解析 PDF 文件",
5.     tools=[PDFTool],
6.     middleware=[PDFMiddleware],
7.     system_prompt="你是一个 PDF 专家...",
8. )

复制代码

Skills 的加载方式透明——Agent 看到 load_skill 工具，调用它得到新的本事和上下文。
7.3 MCP 集成

通过 Model Context Protocol (MCP) 协议接入外部工具服务器：

1. from deepagents.middleware.tools import MCPToolsMiddleware
3. agent = create_deep_agent(
4.     middleware=[
5.         tools_middleware(
6.             mcp_servers={"search": {"command": "..."}}
7.         )
8.     ]
9. )

复制代码

这让 Deep Agents 的工具生态可以无穷扩展。
八、项目工程布局赏析

1. deepagents/
2. ├── libs/
3. │   ├── deepagents/      # Python 核心库
4. │   ├── cli/             # 命令行工具
5. │   ├── code/            # Deep Agents Code（类 Claude Code 终端编码 Agent）
6. │   ├── acp/             # Agent Communication Protocol
7. │   ├── evals/           # 评估框架
8. │   └── partners/        # 合作伙伴集成
9. ├── examples/            # 示例
10. └── .github/             # CI/CD + 自动评估 + SWE-bench

复制代码

工程上值得留意的点：

• Monorepo 布局：多个子包共享版本和 lint 规则
  
• 自动化评估：.github/workflows/evals.yml 每次 PR 自动跑评估
  
• SWE-bench 集成：.github/scripts/ 下有自动管理 SWE-bench PR 的脚本
  
• Release Please：自动 changelog 天生和版本发布
  

九、总结：Deep Agents 的代价所在

它办理了什么标题？

LangGraph 给了你做 Agent 的全部"零件"，但拼装成一套生产级的 Agent 必要大量代码——上下文压缩、子 Agent 委托、沙箱隔离、人工审批……这些都不是 Agent 框架本身的范畴，但缺了这些，Agent 没法真正干活。
Deep Agents 把这些"工程化电池"装好了，让你不消从零搭。
谁适适用？

场景得当度原型验证 → 直接想用⭐⭐⭐⭐⭐复杂多步调使命 Agent⭐⭐⭐⭐⭐生产级 Agent 摆设⭐⭐⭐⭐⭐只想要最小 Agent⭐⭐ （用 LangChain create_agent 更轻）深度定制 Agent 框架⭐⭐⭐ （可 override 任何组件）焦点计划模式

• Middleware 洋葱模子：齐备功能都是中央件，组合自由
  
• Backend 可插拔协议：存储层完全解耦
  
• Sub-Agent 上下文隔离：复杂使命举行分治而不污染 context
  
• 三层上下文压缩：truncate → summarize → compact，渐进式处理处罚
  
• 非粉碎性状态管理：原始消息汗青不丢失，压缩是可逆的
  

如果你正在构建一个必要做复杂、长周期使命的 AI Agent——研究、编码、数据分析——Deep Agents 是现在少有的把"工程化电池"装齐备的开源方案。

本文基于 Deep Agents 源码分析撰写。项目接纳 MIT 协议，由 LangChain 团队维护。

免责声明：如果侵犯了您的权益，请联系站长及时删除侵权内容，谢谢合作！qidao123.com:ToB企服之家，中国第一个企服评测及软件市场,开放入驻,技术点评得现金.