Skip to main content

DeepAgents 调研与企业级实战

本文为 LangChain 团队发布的 DeepAgents 框架的调研与企业级实战笔记。DeepAgents 是一个基于 LangChain + LangGraph 构建的开源 Agent Harness（智能体套件），旨在简化长周期自主智能体的开发。

开源地址：https://github.com/langchain-ai/deepagents

官方文档：https://docs.langchain.com/oss/python/deepagents/overview

当前版本：v0.6（2026 年 5 月）

这篇文章说了什么​

DeepAgents 是 LangChain 团队在做了几年 Agent 框架后给出的"最佳实践封装"。它的核心定位是 Agent Harness（智能体套件）——如果说 LangChain 是积木、LangGraph 是地基，那 DeepAgents 就是一套成品级的框架，把规划、文件系统、子智能体、上下文管理这些长周期 Agent 的必需品都预设好了。

它解决的核心问题是浅层 Agent 问题（Shallow Agent Problem）：传统 Agent 就是"思考→调工具→观察→重复"的死循环，遇到多步骤的复杂任务（比如写一份深度研报、做一个全栈项目）就容易迷失、遗忘、上下文爆炸。DeepAgents 通过四点来解决——先做计划、用文件系统管记忆、复杂任务外包给子 Agent、长对话自动摘要。

目前最新的 v0.6 版本还加入了 Code Interpreter（让 Agent 写代码来编排工具调用，减少模型 round-trip）、Harness Profiles（为不同模型定制 prompt 以榨干性能）、Streaming 和 DeltaChannel（优化长运行 Agent 的传输和存储）。

LangChain 自己也在生产环境吃自己的狗粮——他们的 GTM Agent 基于 DeepAgents 构建，把 lead 转化率提升了 250%，销售每人每月省 40 小时。

观后感​

  • DeepAgents 本质上是把 Claude Code / Deep Research 这些应用的最佳实践抽象成了通用框架，让每个开发者都能快速搭出自己的"Deep Xxx"
  • 最大价值不在代码量（核心代码其实不多），而在预设的系统 prompt 和方法论——教模型怎么规划、怎么用文件系统、什么时候 spawn 子 agent
  • Middleware 架构是真正的亮点：文件系统、TodoList、子 Agent、摘要、记忆都是可插拔的中间件，你可以只用自己需要的部分
  • 企业部署选 LangSmith 可以开箱即用（deploy 一行命令），但要注意 LangGraph Platform 的 license 限制
  • Sub-agent 的 context isolation 设计很聪明——每个子 agent 独立的上下文窗口，不会污染主 agent 的对话历史

一、框架定位与要解决的问题​

1.1 什么是 DeepAgents​

DeepAgents 定位为 Agent Harness（智能体套件/装备），位于 LangGraph（底层运行时）和 LangChain（工具/模型层）之上。它不是一个简单的 tool-calling wrapper，而是内置了长周期任务所需的全部基础设施：

  • Planning：write_todos / read_todos 自动做任务拆解和进度跟踪
  • Filesystem：read_file / write_file / edit_file / ls / glob / grep 用于上下文读写
  • Shell access：execute 执行命令（支持沙箱隔离）
  • Sub-agents：task 工具创建子智能体，上下文隔离的独立工作区
  • Context management：长对话自动摘要压缩，大输出自动存到文件

一句话概括：pip install deepagents 之后，你得到一个会规划、会读写文件、会 spawn 子 agent 的完整 Agent，而不是一个空的 tool-calling loop。

1.2 要解决的「浅层 Agent 问题」​

传统 Agent 的核心问题是：LLM 在 tool-calling loop 里是"走一步看一步"的，这在长周期任务中会暴露五个致命缺陷：

问题传统 Agent 的表现DeepAgents 的解法
规划缺失Agent 没有全局视图，多步任务中容易迷失方向内置 write_todos 工具，强制 Agent 先做计划
遗忘与混乱超过 10-20 步后上下文窗口爆炸，Agent 忘记初始目标文件系统做外部记忆 + 自动摘要压缩
上下文污染所有工具结果堆积在对话历史里，噪声越来越大大输出自动存文件，Agent 只在需要时读取
环境交互困难文件系统、代码沙箱的配置和管理复杂可插拔的 Backend 系统，切换沙箱只需改一行配置
协作编排复杂多 Agent 场景下的任务分发和上下文隔离难以实现task 工具 spawn 子 Agent，独立上下文窗口

1.3 技术栈与依赖​

DeepAgents (Agent Harness)
    ├── LangGraph (运行时：持久化、流式、human-in-the-loop)
    ├── LangChain (模型抽象、工具定义)
    └── LangSmith (生产部署、追踪、评估 —— 可选)

DeepAgents 返回的是一个 编译好的 LangGraph Graph，这意味着你可以用 LangGraph 的全部功能：streaming、checkpointing、human-in-the-loop、Studio 可视化调试。

二、核心架构：Middleware 系统​

2.1 Middleware 是什么​

DeepAgents 的架构核心是中间件管道（Middleware Pipeline）。每个中间件都可以：

  • 拦截和修改模型调用
  • 在 Agent 执行前后注入逻辑
  • 向 Agent 提供工具

默认加载的中间件包括：

[FilesystemMiddleware] → [TodoListMiddleware] → [SubAgentMiddleware] 
→ [SummarizationMiddleware] → [MemoryMiddleware] → ... → 自定义中间件

2.2 各中间件详解​

FilesystemMiddleware​

提供虚拟文件系统操作，Agent 用它做两个事：

  • 上下文卸载：把超过 token 限制的长内容写到文件，需要时再读
  • 中间产物保存：研究中收集的资料、分析结果、草稿都存在文件系统里

后端是可插拔的：默认 in-memory → 可切换 local disk → LangGraph Store（跨 thread 持久化）→ Sandbox（隔离代码执行）

TodoListMiddleware​

提供 write_todos 和 read_todos 两个工具。Agent 在执行复杂任务前会先写一个 todo list，然后逐步完成。这个中间件的神奇之处在于它改变了 Agent 的行为模式——从"下意识反应"变成"先规划再执行"。

SubAgentMiddleware​

提供 task 工具，让 Agent 能创建子 Agent 来处理独立子任务。每个子 Agent：

  • 有独立的上下文窗口（不会污染主 Agent）
  • 可以有不同的 system prompt（比如一个写代码、一个做研究）
  • 只返回最终结果给主 Agent

这个设计直接解决了"一个长对话里混入太多东西"的问题。

SummarizationMiddleware​

当对话历史超过模型上下文窗口的 70% 时，自动触发摘要压缩。把早期的消息压缩成一段摘要文本，释放上下文空间。

ContextHubBackend (v0.6 新增)​

把 skills、policies、memories 存储在 LangSmith Context Hub 中，支持版本管理和团队协作。这意味着 Agent 从一个 run 学到的东西可以改善下一个 run。

2.3 Code Interpreter (v0.6)​

v0.6 最重要的新能力：Agent 可以写代码来编排工具调用，而不是每一步都要 round-trip 到模型。

# Agent 写这样的代码在内部 runtime 执行：
topics = ["retrieval", "memory", "evaluation"]
reports = await Promise.all(
    topics.map(t => tools.task({
        description: `Research ${t} in Deep Agents`,
        subagent_type: "general-purpose"
    }))
)
reports.join("\n\n")  # 只把汇总结果返回给模型

这个模式叫 Programmatic Tool Calling (PTC)，好处是：

  • 减少不必要的模型 round-trip（省 token、省时间）
  • 中间结果不进入模型上下文（减少噪声）
  • 可以在 runtime 里做过滤、聚合、重试等逻辑

三、系统 Prompt 策略​

DeepAgents 真正的壁垒不在代码，而在预设的系统 prompt。它教模型用一套"人类工作方法"：

3.1 工作方法论​

系统 prompt 的核心逻辑：

1. 收到任务后，先用 write_todos 拆解为子任务
2. 对每个子任务，判断是自己做还是 spawn sub-agent
3. 执行过程中，中间产物用 write_file 存下来
4. 需要长上下文（如研究资料）时，先写文件再 read_file
5. 所有任务完成后，汇总文件内容产出最终结果

3.2 文件系统使用规范​

Prompt 中明确教模型什么时候用文件系统：

  • 大于 3 段的内容 → 写文件而不是堆在对话里
  • 需要后续引用的内容 → 写文件方便随时检索
  • 子 Agent 的产出 → 自动存到文件系统
  • 长工具结果 → 先写文件，读摘要再决定是否读取详情

3.3 Harness Profiles (v0.6)​

v0.6 引入了 Harness Profiles 概念，为不同模型定制 prompt。比如 Kimi、Qwen、DeepSeek 的 tool calling 行为各有特点，Profile 包含了针对每个模型调整过的系统 prompt、工具描述格式、输出格式要求。

这个设计的价值在于：你可以用便宜 20 倍的开源模型获得接近闭源模型的 Agent 性能。

四、企业级部署方案​

4.1 部署路径​

DeepAgents 支持从本地开发到生产部署的完整链路：

本地开发（uv/pip）
    │
    ├─→ DeepAgents CLI（终端交互式 Agent）
    │
    ├─→ LangSmith Deploy（一行命令部署到云）
    │      deepagents deploy
    │
    └─→ 手动 Docker + LangGraph Platform

4.2 LangSmith Deployments​

最快的生产部署方式。deepagents deploy 一行命令打包你的 agent 配置（模型、工具、memory、sandbox、skills、MCP servers）并部署到 LangSmith。自动获得：

  • Assistant / Thread / Run 管理
  • 持久化存储（Store + Checkpointer）
  • 认证与授权（Custom Auth + RBAC）
  • Webhooks / Cron Jobs
  • 可观测性追踪
  • MCP Server 和 A2A 协议暴露

4.3 持久化与容错​

DeepAgents 基于 LangGraph 的 Durable Execution：

  • 每一步执行后自动 checkpoint 到持久化存储
  • 如果 run 被中断（崩溃、超时、human-in-the-loop 暂停），从最近的 checkpoint 恢复
  • 对于会跑几小时的深度研究任务，中间挂了不会丢已完成的工作

4.4 Delta Channels (v0.6)​

长运行 Agent 的 checkpoint 会随上下文积累越来越大。DeltaChannel 优化了这个场景：

  • 只存储增量变更而非完整的 checkpoint 快照
  • 对于长时间运行的 Agent，存储空间减少最多 100x
  • 不影响 observability 和 resumability

4.5 认证三层架构​

第一层：用户身份认证（Who are you?）
第二层：Agent 以用户身份执行（On behalf of the user）
第三层：团队 RBAC 权限控制（What can your team access?）

4.6 权限控制​

DeepAgents 支持声明式权限规则，精确控制 Agent 能读写的文件：

# 示例：只允许 Agent 在 /workspace 下操作
permissions = {
    "read": ["/workspace/**"],
    "write": ["/workspace/**"],
    "deny": ["/workspace/secrets/**"]
}

Sub-agent 可以继承或覆盖父 Agent 的权限规则。

五、企业级实战案例：LangChain GTM Agent​

这是 LangChain 自己用 DeepAgents 构建的生产级 Agent，最有参考价值。

5.1 业务场景​

GTM（Go-To-Market）团队的痛点：销售代表每次 outreach 之前，需要在 Salesforce、Gong、LinkedIn、公司网站之间来回切换做 research，人均花 15 分钟。然后还要手写个性化邮件。

5.2 Agent 设计​

触发：Salesforce 出现新 lead → Agent 自动启动

流程：

  1. 检查是否应该 reach out（最近有没有 support ticket？队友是不是已经联系过？）
  2. 收集上下文信息（Salesforce 记录 → Gong 通话记录 → LinkedIn → 公司网站）
  3. 如果内部信息不够，用 Exa 搜索外部信息（了解该公司在 AI 方面的现状）
  4. 根据关系阶段（新客户 vs 老客户 vs 潜在客户）生成不同风格的邮件草稿
  5. 发送到 Slack 给销售代表审批

非功能性要求：

  • Human-in-the-loop：没有显式审批，绝不自动发送
  • 可解释性：每个草稿附带推理过程和引用来源
  • 学习循环：记录销售代表的每次编辑，持续优化

5.3 架构设计​

Salesforce Webhook 
    → GTM Agent (DeepAgents)
        ├── Sub-agent: 账户分析
        ├── Sub-agent: 联系人研究
        ├── Sub-agent: 邮件草稿撰写
        └── Skills: outbound best practices
    → Slack (审批)
    → LangSmith (追踪 + 评估)

5.4 核心效果​

  • Lead → qualified opportunity 转化率提升 250%
  • 销售每人每月节省 40 小时（全团队 1320 小时）
  • 低意图 lead 跟进量增加 97%
  • 日活 50%，周活 86%（销售团队自然使用率）

5.5 关键启示​

  1. 把复杂的 multi-step 流程拆给 sub-agent：账户分析、联系人研究、邮件撰写各一个 sub-agent，各自专注一件事
  2. Human-in-the-loop 不仅安全，还提高了采纳率：销售只要点击发送，不用从零手写，自然爱用
  3. 学习闭环比初始质量更重要：编辑反馈 → 自动优化，让 Agent 越用越好

六、模型选择与性能​

6.1 Provider Agnostic​

DeepAgents 支持几乎所有主流模型，统一接口：

Provider配置方式推荐的模型
Anthropicanthropic:claude-sonnet-4-6Claude Sonnet 4.6
OpenAIopenai:gpt-5.4GPT-5.4
Googlegoogle_genai:gemini-3.1-pro-previewGemini 3.1 Pro
OpenRouteropenrouter:anthropic/claude-sonnet-4-6多模型路由
Ollamaollama:devstral-2本地部署模型

6.2 Harness Profiles 的性能提升​

v0.6 的 Harness Profiles 为开源模型做了专门的 prompt 和 tool-calling 优化。据官方数据，Kimi、Qwen、DeepSeek 等开源模型在配置 Profile 后，Agent 任务完成率接近闭源模型，而成本只有 1/20。

七、Agent Client Protocol (ACP)​

DeepAgents 支持 Agent Client Protocol，可以直接在代码编辑器中使用。目前已在 Zed 编辑器中集成，未来可能扩展到 VS Code、Cursor 等。

# ACP 集成让 DeepAgents 作为编辑器的后端 Agent
# 用户：在编辑器里 @agent 写需求
# Agent：自主规划 → spawn sub-agents → 读写文件 → 回传代码

八、与其他框架的对比​

维度DeepAgentsClaude Agent SDKDeerFlow
定位Agent Harness（通用）Agent Harness（Anthropic 生态）Super Agent Harness（多 Agent 编排）
模型绑定Provider AgnosticClaude 专属Provider Agnostic
运行时LangGraphClaude Code 集成LangGraph
子 Agenttask 工具Sub-agent 支持Skills + Sub-agents
Web UI无（需自建，有 CLI）无有完整 Web UI
生产部署LangSmith Deploy（一行命令）API 调用Docker 自部署 / 火山引擎
许可证MITApache 2.0MIT

九、核心经验总结​

  1. Agent 框架的价值不在代码量，在系统 prompt：DeepAgents 核心代码不多，但 prompt 里包含了 LangChain 团队多年踩坑的方法论
  2. Middleware 架构让扩展变得简单：新增能力只需要加一个中间件，不用改核心代码
  3. Sub-agent 的 context isolation 是解决复杂任务的银弹：不是所有信息都要放在同一个对话里
  4. 在生产环境中，Durable Execution 比看起来更重要：长周期任务中间崩溃是常态，checkpoint 恢复是必须的
  5. Human-in-the-loop 不是"不信任 AI"，而是提升采纳率的手段：让人类做决策、Agent 做执行，比全自动更容易被团队接受
  6. Harness Profiles 让开源模型有了生产级的 Agent 能力：不需要最贵的模型，需要的是"对模型足够了解的 prompt 工程"