银河it-DeepAgents：当智能体开始“像工程师一样工作”

2025 年，AI Agent 领域的讨论大多集中在“能不能做”上——能不能调用工具、能不能写代码、能不能自动完成一个任务。但真正把 Agent 投入生产环境的人会发现一个更棘手的问题：当任务从 5 分钟变成 5 小时，从 3 步变成 30 步时，Agent 会“失忆”、会“跑偏”、会“烧钱”。

上下文窗口被几十轮工具调用的结果撑爆，早期设定的任务目标在截断中丢失，每一轮都把全部历史重新发一遍导致成本飙升。这些问题不是模型能力问题，而是工程架构问题。LangChain 团队在 2025 年 10 月正式推出的 DeepAgents，正是对这个问题的系统性回应。

DeepAgents 的定位很明确：它不是又一个 Agent 框架，而是一个 Agent Harness（智能体挂具） ——一种有主见的、开箱即用的运行时环境，内置了长周期任务真正需要的工程基础设施。正如 PyPI 页面所定义的：“一个有主见的、开箱即用的智能体。”

一、核心设计哲学：四个支柱，一个目标

DeepAgents 的架构建立在四个经过深思熟虑的核心支柱之上。理解这四个支柱，是理解整个框架的关键。

支柱一：规划工具（write_todos）。 最简单的 ReAct 循环让 LLM 在每一步“看情况决定下一步”。这在短任务中可行，但在长任务中会导致“冲动行为”——模型倾向于快速行动而缺乏全局视野。DeepAgents 内置了 write_todos 工具，强制 Agent 在开始执行之前先输出一个结构化的 TODO 列表，将任务分解为 pending、in_progress、completed 三个状态。这个看似简单的设计，实际上把“规划”从一个隐含的推理步骤变成了一个显式的、可审计的产物。

支柱二：虚拟文件系统。 这是 DeepAgents 最具工程价值的设计。Agent 可以通过 ls、read_file、write_file、edit_file、glob、grep 六个工具读写文件。但关键在于：这个文件系统的后端是可插拔的。在 0.2 版本中，LangChain 引入了 Backend 抽象，内置实现包括 LangGraph State（会话内虚拟文件系统）、LangGraph Store（跨线程持久化）以及真实的本地文件系统。更精妙的是“复合后端”设计：你可以把本地文件系统作为基础后端，把 /memories/ 目录映射到一个 S3 虚拟文件系统，实现跨会话的长期记忆持久化。

这意味着 Agent 可以把中间结果、长文本、代码和数据写入文件系统而不是全部保留在上下文中。上下文不再是唯一的工作内存，文件系统成为了 Agent 的“外部大脑”。

支柱三：子智能体（Subagents）。 当一个任务需要同时进行网页搜索、代码分析和文档撰写时，让一个 Agent 线性地做所有事情会导致上下文迅速膨胀。DeepAgents 的 task 工具允许主 Agent 将子任务委派给上下文隔离的子智能体。每个子智能体在自己的上下文窗口中运行，只把最终结果返回给主 Agent。

子智能体有两种定义方式。在 SDK 层面，可以通过 SubAgents 配置传入；在 Deep Agents Code（dcode）中，子智能体被定义为 .deepagents/agents/{name}/AGENTS.md 文件，YAML frontmatter 声明 name、description，可选地覆盖模型，Markdown body 作为子智能体的系统提示。一个实用的模式是为子智能体指定更便宜的模型（如 anthropic:claude-haiku-4-5），主 Agent 保持在高能力模型上，实现成本优化。

支柱四：上下文管理。 这是贯穿前三个支柱的底层能力，也是 DeepAgents 最值得深入剖析的部分。

二、上下文管理：不是“压缩”，而是“资源调度”

DeepAgents 对上下文问题的处理方式，体现了一种成熟的工程判断：它没有重造压缩算法，而是把压缩视为一个资源调度问题。

上下文管理挂在“每次调用大模型之前”这个时机上。当会话上下文越过模型可用窗口的 85% 时，DeepAgents 触发一系列分层动作。

第一层：大工具结果驱逐（Offloading）。 当一次工具调用的结果超过某个 token 阈值（比如 Agent 读取了一个大文件），结果不会直接塞进上下文，而是被写入文件系统，上下文中只保留一个引用指针。这是最便宜的优化——不消耗任何模型推理成本。

第二层：对话历史摘要。 当 token 用量继续增长，较旧的消息被压缩成摘要。但 DeepAgents 做了一个关键区分：原始对话一个字不删，只记录“怎么压的”。压缩掉的消息被归档到虚拟文件系统，Agent 需要时可以重新读取原始内容。这解决了一个根本性问题：摘要会丢失精度，但归档保留了一切。

第三层：非破坏式压缩架构。 DeepAgents 区分了两个不同的问题：“压缩什么”是一个算法问题，“压缩后能不能找回来”是一个架构问题。它的答案是：压缩是视图层的操作，原始数据始终在存储层完好无损。每次调用模型前，它先“重建有效消息”——如果有压缩记录，就把摘要和后续新消息拼成这次实际要用的视图。

2026 年 3 月，DeepAgents 进一步引入了自主上下文压缩工具，将压缩决策权交给模型本身。模型可以根据任务状态自主判断“什么时候该清场”，而不完全依赖固定的 token 阈值触发。

三、代码视角：从配置到可运行系统

以下代码展示一个最小但完整的 DeepAgents 系统，包含规划、文件系统、子智能体和自定义工具。

# deep_agent_minimal.py — DeepAgents 最小可运行示例
# 依赖：pip install deepagents langchain-anthropic tavily-python

from deepagents import create_deep_agent
from langchain.tools import tool
from langchain_anthropic import ChatAnthropic
from tavily import TavilyClient
import os

# ============================================================
# 1. 自定义工具 — 接入外部搜索能力
# ============================================================

tavily = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])

@tool
def web_search(query: str) -> str:
    """搜索互联网获取最新信息。当需要了解当前事件或事实性数据时使用。"""
    results = tavily.search(query=query, max_results=5)
    return "\n".join(
        f"- {r['title']}: {r['content'][:300]}"
        for r in results["results"]
    )

# ============================================================
# 2. 子智能体定义 — 上下文隔离的研究员
# ============================================================

research_subagent = {
    "name": "researcher",
    "description": "专门负责深入调研某个主题，只返回结构化的调研发现。",
    "prompt": (
        "你是一个专业调研员。你的任务是：\n"
        "1. 使用 web_search 工具搜集信息\n"
        "2. 将原始搜索结果保存到 /research/raw/ 目录\n"
        "3. 提炼关键发现，写入 /research/findings.md\n"
        "4. 只向主 Agent 返回一段 200 字以内的摘要\n"
        "不要返回完整的搜索结果，那会浪费主 Agent 的上下文。"
    ),
    "model": "anthropic:claude-haiku-4-5-20251001",  # 子智能体用便宜模型
}

# ============================================================
# 3. 主 Agent 配置
# ============================================================

agent = create_deep_agent(
    model=ChatAnthropic(model="claude-sonnet-4-5-20250929"),
    tools=[web_search],
    system_prompt=(
        "你是一个高级研究助理。你的工作流程是：\n"
        "1. 收到任务后，首先用 write_todos 规划步骤\n"
        "2. 对于需要深入调研的子主题，委派给 researcher 子智能体\n"
        "3. 将调研发现整理成最终报告，保存到 /reports/ 目录\n"
        "4. 报告完成后，向用户输出一句话总结\n"
        "重要：不要把原始搜索结果放进你的上下文，让子智能体处理。"
    ),
    subagents=[research_subagent],
    # 文件系统后端：使用 LangGraph Store 实现跨会话持久化
    # backend 参数在 SDK 中通过 create_deep_agent 的配置传入
)

# ============================================================
# 4. 执行
# ============================================================

result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": "调研 2026 年 AI Agent 框架的竞争格局，写一份 800 字的报告。"
    }]
})

# result 中包含完整的消息历史、最终报告路径和摘要
print(result["messages"][-1].content)

这段代码体现了 DeepAgents 的几个关键工程决策：

子智能体的成本隔离。 研究员子智能体使用 Haiku 模型处理搜索密集型任务，主 Agent 使用 Sonnet 模型进行推理和综合。搜索的原始结果留在子智能体的上下文中，只有摘要返回主 Agent。

文件系统作为工作产物。 调研发现和最终报告都写入文件系统，而不是全部塞进对话历史。主 Agent 的上下文只包含规划步骤、摘要和文件路径引用。

显式规划。 系统提示明确要求 Agent 先调用 write_todos，这与 DeepAgents 的内置规划工具形成配合。

四、架构分层：Harness、Framework、Runtime 的清晰边界

DeepAgents 在 LangChain 技术栈中的位置，需要精确理解。LangChain 团队自己给出了清晰的区分：LangGraph 是 Agent Runtime（运行时），LangChain 是 Agent Framework（框架），DeepAgents 是 Agent Harness（挂具） 。

这个三层次划分不是营销话术，而是有实质技术含义的：

Runtime 层（LangGraph） 提供的是生产级基础设施：持久化执行、流式传输、人在回路、检查点恢复。这些能力不关心 Agent 的“智能”部分，只关心“怎么可靠地跑起来”。

Framework 层（LangChain） 提供的是抽象和集成：模型抽象、工具抽象、Agent 循环抽象、中间件。它让开发者可以用统一的方式接入不同模型和工具。

Harness 层（DeepAgents） 提供的是有主见的默认行为：内置的规划工具、虚拟文件系统、子智能体委派、上下文管理策略、详细的系统提示。它把“一个长周期 Agent 应该怎么工作”的最佳实践固化成了可运行的代码。

这个分层的一个实际含义是：DeepAgents 不是一个“更高级的 LangGraph” 。你可以用 LangGraph 手写一个具有规划、文件系统和子智能体的 Agent，但需要自己实现所有的上下文管理逻辑、工具定义和提示工程。DeepAgents 的价值在于它把这些“最佳实践”打包成了默认行为，让你只需 bring your own tools and a custom prompt。

五、生产实践：Stripe 的案例与基础设施要求

DeepAgents 在生产环境中的一个标志性案例是 Stripe 的 Kai 平台。Kai 是 Stripe 用 Deep Agents 在一周内搭出的全员 AI 平台，四个月内用户从 296 涨到超过 5000，周活跃覆盖 83% 员工。关键工程细节是：Kai 是云端生产服务而非本地进程，Stripe 用 S3 搭建了虚拟文件系统，Agent 在处理文档和分析任务时可以跨会话读写引用文件。

这个案例揭示了 DeepAgents 在生产部署中的几个硬性要求：

持久化文件系统。 如果文件系统后端是内存或会话状态，Agent 重启后所有工作产物丢失。生产环境需要 S3、数据库或分布式存储作为 Backend 实现。

多租户隔离。 当多个用户共享一个 Agent 部署时，文件系统需要按用户或会话隔离。DeepAgents 的复合后端机制允许在基础后端之上映射不同的子目录到不同的存储资源。

可观测性。 DeepAgents 与 LangSmith 原生集成，可以追踪每一次工具调用、每一次上下文压缩、每一次子智能体委派。这对于调试长周期 Agent 的行为至关重要。

人在回路。 DeepAgents 支持在关键工具调用前暂停，等待人工审批。结合 LangGraph 的检查点机制，Agent 状态在暂停期间被持久化，审批后从断点恢复执行。

六、边界与张力：DeepAgents 不解决什么

一篇有深度的技术文章，不能只谈优势。DeepAgents 有几个需要警惕的边界。

模型锁定的隐含成本。 DeepAgents 的系统提示非常长，包含大量工具使用示例。这个提示是针对 Claude 系列模型调优的。虽然框架声称“模型无关”，但在非 Claude 模型上，工具调用格式和规划行为的稳定性可能下降。

子智能体的权限继承模糊性。 在 DeepAgents 中，子智能体默认继承主 Agent 的工具集（除了 task 工具）。这意味着如果主 Agent 有删除文件的权限，子智能体也有。目前没有内置的细粒度权限隔离机制。

上下文压缩的不可观测性。 虽然 DeepAgents 记录了压缩历史，但模型在压缩后的“视图”中看到的摘要质量，取决于摘要生成的质量。如果摘要丢失了关键细节，模型可能基于不完整的信息做决策，而调试这种问题非常困难。

动态子智能体的复杂性。 dcode 支持动态子智能体——Agent 编写编排脚本来调用 task() 全局函数。这提供了极大的灵活性，但也意味着 Agent 的行为在运行时变得难以预测和测试。

结语：Harness 思维的价值

DeepAgents 的真正贡献，不在于它引入了某个全新的技术概念。规划、文件系统、子智能体、上下文压缩，这些概念在 Agent 社区中已经存在一段时间了。它的贡献在于把这些概念组合成了一个有主见的、可运行的默认行为系统。

这背后是一种“Harness 思维”：与其让每个开发者从零开始解决长周期 Agent 的工程问题，不如把最佳实践固化成默认行为，让开发者专注于业务逻辑。 这种思维在软件工程中有先例——Rails 的约定优于配置、Kubernetes 的默认行为、React 的组件模型，都是类似的选择。

但 Harness 思维也有代价：你获得的是默认行为，失去的是对细节的完全控制。DeepAgents 适合那些“需要一个能跑的长周期 Agent，但不想自己写上下文管理和文件系统”的场景。如果你需要的是对 Agent 循环的每一行代码有完全的控制权，LangGraph 直接使用仍然是更合适的选择。

理解这个 trade-off，比记住 DeepAgents 的 API 更重要。