Harness DeepAgent 实战：长任务 Agent 的任务编排、中间件与 Demo 落地

DeepAgent：面向长任务的 Agent Harness 架构，中间件、Demo 与落地实践

本文基于 2026-07-01 对 LangChain / Deep Agents 官方文档和源码的理解整理。Deep Agents 更新较快，生产落地前建议再核对当前版本的 API 和默认中间件栈。

部分中间件未实际运用过，部分AI生成，生产环境自行研究考量。

1. 一句话理解 DeepAgent

DeepAgent 不是一个新模型，也不是完全独立的新运行时。

更准确地说：

DeepAgent 是基于 LangChain create_agent / LangGraph 的长任务 Agent Harness。

普通 Agent 更像：

模型 + 工具调用循环

DeepAgent 更像：

模型 + 工具调用循环
+ 文件工作区
+ 任务列表
+ 子代理
+ 上下文压缩
+ 大结果 offload
+ skills / memory
+ human-in-the-loop
+ prompt caching

它解决的核心问题不是"模型会不会更聪明"，而是：

• 长任务怎么规划；
• 大上下文怎么管理；
• 工具结果太大怎么处理；
• 子任务怎么隔离；
• 多步骤任务怎么持续执行；
• 生产环境里怎么加权限、审批、记忆、技能。

2. 普通 Agent 和 DeepAgent 的区别

对比项	普通 Agent：create_agent	DeepAgent：create_deep_agent
定位	通用工具调用 Agent	面向长任务的 Agent Harness
默认能力	模型 + tools + prompt	预装任务、文件、子代理、上下文压缩等能力
上下文管理	主要靠 messages 累积	支持 summarization、tool result offload、read_file 分页
文件能力	需要自己加工具或中间件	默认有 ls、read_file、write_file、edit_file、glob、grep
子代理	需要自己设计	默认通过 task 工具调用 subagent
长任务	容易上下文膨胀	更适合多轮、多步骤、长上下文任务
成本	基础 token 少，执行链路短	初始 prompt 和工具更多，但长任务中可通过 offload / caching 降低重复上下文成本
可控性	简单直接	能力强，但链路更复杂
适用场景	简单问答、单工具调用、短流程	研究、代码分析、多文件处理、复杂自动化

一句话：

普通 Agent 适合短任务；DeepAgent 适合长任务、复杂上下文和需要文件工作区的任务。

3. DeepAgent 的中间件清单

create_deep_agent 底层还是调用 create_agent，但会预先组装一套 middleware。

常见主 Agent 中间件可以分成两类。

3.1 核心中间件

Middleware	是否默认	主要作用
TodoListMiddleware	默认	提供 write_todos，让 Agent 维护任务列表
FilesystemMiddleware	默认	提供文件工具、虚拟文件系统、工具结果 offload、权限控制
SubAgentMiddleware	通常默认	提供 task 工具，让主 Agent 调用子 Agent
SummarizationMiddleware	默认	历史过长时压缩上下文
PatchToolCallsMiddleware	默认	修补悬空 tool call，避免消息历史不完整导致模型 API 报错

注意：如果没有显式传同步 subagent，DeepAgent 通常会自动加一个 general-purpose 子代理；如果通过 profile 禁用了默认子代理，则不会暴露 task 工具。

3.2 条件性中间件

Middleware	触发条件	主要作用
SkillsMiddleware	传了 skills=[...]	加载技能元信息，按需读取 SKILL.md
MemoryMiddleware	传了 memory=[...]	加载长期记忆，例如 AGENTS.md
HumanInTheLoopMiddleware	传了 interrupt_on 或权限中断	在关键工具调用前暂停，等待人工审批
AsyncSubAgentMiddleware	传了异步 subagents	管理异步 / 后台子代理任务
Prompt caching middleware	Anthropic / Bedrock 等支持场景	对稳定 prompt 片段做缓存，降低重复处理成本
_ToolExclusionMiddleware	harness profile 配了 excluded_tools	从模型可见工具列表中隐藏某些工具
自定义 middleware	传 middleware=[...]	注入业务自定义逻辑

4. 常用中间件详解

4.1 TodoListMiddleware：让 Agent 有任务列表

作用：

• 给 Agent 一个 write_todos 工具；
• 适合多步骤任务；
• 让 Agent 明确当前执行到哪一步。

它不是业务数据库里的任务表，只是 Agent 运行状态里的轻量 planning 结构。

适合：

• 代码修改；
• 研究报告；
• 多文件分析；
• 多步骤排查。

容易踩坑：

• 不要把它当成可靠的业务状态存储；
• 长期业务进度应该落库，而不是只放在 todo state；
• prompt 没写好时，模型可能不主动维护 todo。

4.2 FilesystemMiddleware：DeepAgent 的工作区核心

它提供默认文件工具：

ls
read_file
write_file
edit_file
glob
grep
execute  # 只有 sandbox backend 支持时才可用

它还有一个很关键的能力：大工具结果 offload。

当某个工具返回结果太大时，DeepAgent 不会一直把完整结果塞在 messages 里，而是写到虚拟文件系统：

/large_tool_results/<tool_call_id>

messages 里只保留：

结果太大，已保存到某路径，这里是 head/tail 预览，需要时用 read_file 分页读取

read_file 支持分页：

read_file(file_path="/large_tool_results/call_xxx", offset=0, limit=100)

容易踩坑：

• read_file 本身不是 offload 工具，它只是分页读取；
• 默认 StateBackend 里的路径是虚拟路径，不一定是你本机真实磁盘目录；
• 大工具结果被 offload 后，主 Agent 看到的是摘要和路径，不是完整内容；
• 如果 Agent 没学会继续 read_file，可能只基于预览做判断；
• 并行子代理共享同一个 backend 时，写同一路径可能冲突；
• 文件权限要认真配置，尤其涉及 .env、密钥、用户上传文件时。

4.3 SubAgentMiddleware：主 Agent 调用子 Agent

它给主 Agent 增加一个 task 工具。

主 Agent 可以这样调用：

task(subagent_type="researcher", description="搜索某主题论文，并返回结构化结果")

子 Agent 的特点：

• 每次调用都是短生命周期 invocation；
• 子 Agent 有独立上下文；
• 子 Agent 不会把完整执行历史塞回主 Agent；
• 默认只把最终结果作为一个 ToolMessage 返回给主 Agent；
• 如果同一轮发出多个 task tool call，可以并行执行；
• 如果任务有依赖，就会自然串行。

例如：

并行：
task(researcher, "查主题 A")
task(researcher, "查主题 B")
task(researcher, "查主题 C")

串行：
task(researcher, "先查论文")
等 researcher 返回
task(critic, "基于 researcher 的结果评分")

容易踩坑：

• 主 Agent 的 prompt 不清楚时，它不一定调用 task；
• 如果把 search_papers、score_paper 同时暴露给主 Agent，它可能绕过子 Agent 自己调用；
• 子 Agent 的最终报告太长，也可能再次触发 offload；
• 子 Agent 的中间过程不会全量回传，调试时要看 trace；
• 子 Agent 是隔离上下文，不适合需要频繁来回对话的任务；
• 多个子 Agent 并行写同一个文件时要设计路径隔离。

4.4 SummarizationMiddleware：上下文压缩

作用：

• 当 messages / 历史过长时，对历史进行总结；
• 避免上下文窗口爆掉；
• 让长任务能继续执行。

适合：

• 长时间调试；
• 多轮研究；
• 大量工具调用；
• 多阶段报告生成。

容易踩坑：

• 总结可能丢细节；
• 不要把关键业务状态只存在自然语言历史里；
• 对强一致状态，例如订单 ID、审批状态、金额、权限，应该放结构化状态或数据库；
• 如果结果必须可审计，需要保留原始工具结果和 trace。

4.5 PatchToolCallsMiddleware：修补不完整工具调用历史

它解决的是消息协议问题。

有些模型 API 要求：

AIMessage 里有 tool_call
后面必须有对应 ToolMessage

如果中途用户插话、工具调用被取消、历史恢复不完整，就可能出现：

AIMessage(tool_calls=[call_123])
但是没有 ToolMessage(tool_call_id="call_123")

PatchToolCallsMiddleware 会补一个说明性的 ToolMessage，避免下一轮模型调用直接失败。

容易踩坑：

• 它不会重新执行失败工具；
• 它不会修复错误参数；
• 它只是补齐消息协议；
• 如果频繁触发，说明你的中断、恢复或工具执行链路需要排查。

4.6 SkillsMiddleware：给 Agent 挂操作手册

SkillsMiddleware 用来加载技能目录。

典型结构：

skills/
└── paper-research/
    ├── SKILL.md
    ├── scripts/
    ├── references/
    └── assets/

SKILL.md 示例：

---
name: paper-research
description: 用于论文搜索、筛选、评分和生成中文研究综述。用户要求查论文、比较论文、写综述时使用。
---

# paper-research

## 工作流程
1. 明确研究主题和筛选条件。
2. 搜索候选论文。
3. 提取标题、作者、年份、链接和摘要。
4. 对候选论文进行初筛。
5. 输出结构化中文结果。

使用方式：

from deepagents import create_deep_agent
from deepagents.backends.filesystem import FilesystemBackend

backend = FilesystemBackend(root_dir="./agent_workspace")

agent = create_deep_agent(
    model="openai:gpt-5.5",
    backend=backend,
    skills=["/skills/"],
    system_prompt="你是研究助手。遇到论文研究任务时，优先检查并使用相关 skill。",
)

运行机制：

启动时：只加载 skill 的 name / description / path
需要时：Agent 用 read_file 读取完整 SKILL.md
后续：按 SKILL.md 指令读取 scripts / references / assets

容易踩坑：

• description 太泛，Agent 不知道什么时候用；
• 多个 skill 描述重叠，Agent 可能选错；
• SKILL.md 太长，会吃上下文；
• 技能只是提示，不是硬权限；
• allowed-tools 更像建议，不等于安全隔离；
• 生产权限仍应靠 tools 暴露范围、permissions、backend policy 控制。

4.7 MemoryMiddleware：长期记忆

MemoryMiddleware 用来加载长期偏好、项目规范、开发习惯等。

它通常加载类似：

/memory/AGENTS.md

适合存：

• 代码风格；
• 项目约定；
• 用户偏好；
• 常用命令；
• 团队规范。

不适合存：

• 临时任务结果；
• 敏感密钥；
• 高频变化业务数据；
• 需要强一致的数据库状态。

容易踩坑：

• memory 是启动时常驻上下文，比 skills 更容易造成上下文污染；
• 旧 memory 可能过时；
• 多项目共用 memory 可能串上下文；
• 敏感信息不要写进 memory；
• memory 更新必须设计审核机制。

4.8 HumanInTheLoopMiddleware：关键动作前人工确认

适合在高风险动作前暂停：

• 删除文件；
• 写生产数据库；
• 发邮件；
• 调支付接口；
• 执行高成本 API；
• 修改线上配置。

示例：

from deepagents import create_deep_agent
from langgraph.checkpoint.memory import MemorySaver

checkpointer = MemorySaver()

agent = create_deep_agent(
    model="openai:gpt-5.5",
    tools=[],
    checkpointer=checkpointer,
    interrupt_on={
        "write_file": True,
        "delete": True,
    },
    system_prompt="你可以整理和分析文件，但写入或删除前必须等待人工确认。",
)

容易踩坑：

• Human-in-the-loop 通常需要 checkpointer 支持恢复；
• 不是所有工具都需要审批，审批太多会严重拖慢任务；
• 审批提示要让人看得懂：改什么、为什么改、风险是什么；
• 对真正危险的工具，不要只靠 prompt，应该从权限层限制。

5. Demo：论文研究场景

下面是一个更接近生产习惯的结构：

• Graph / 业务流程控制整体步骤；
• DeepAgent 负责开放性研究节点；
• 主 Agent 只负责协调；
• researcher 只负责搜索；
• critic 只负责评分；
• 主 Agent 不直接持有搜索和评分工具，避免绕过子 Agent。

5.1 定义工具

from typing import Any
from langchain.tools import tool


def build_doubao() -> Any:
    """构建模型客户端；实际项目中可替换为豆包 ChatModel 实例。"""
    # 为了让示例保持简洁，这里返回 LangChain 支持的模型标识字符串
    return "openai:gpt-5.5"


@tool
def search_papers(query: str, limit: int = 5) -> list[dict]:
    """根据研究主题搜索论文，返回候选论文的结构化列表。"""
    # 生产环境中可接 Semantic Scholar、arXiv、企业知识库或自建搜索服务
    return [
        {
            "title": f"Paper about {query}",
            "year": 2025,
            "url": "https://example.com/paper",
            "abstract": "A short abstract...",
        }
    ][:limit]


@tool
def score_paper(paper: dict) -> dict:
    """对单篇论文进行质量评分，返回多个维度的评分和原因。"""
    return {
        "title": paper.get("title", ""),
        "novelty_score": 8,
        "method_score": 7,
        "evidence_score": 7,
        "overall_score": 7.5,
        "reason": "示例评分：主题相关，方法完整，但需要进一步检查实验细节。",
    }

5.2 定义子 Agent

researcher_subagent = {
    "name": "researcher",
    "description": "负责搜索论文并返回结构化候选列表，不负责评分和最终报告。",
    "system_prompt": (
        "你是论文研究员。你的职责是根据任务描述搜索论文，"
        "返回结构化论文列表。不要评分，不要写最终综合报告。"
    ),
    "tools": [search_papers],
}

critic_subagent = {
    "name": "critic",
    "description": "负责根据论文信息评分，不负责搜索和最终报告。",
    "system_prompt": (
        "你是论文评审员。你的职责是根据输入的论文列表逐篇评分，"
        "输出结构化评分结果。不要搜索新论文，不要写最终综合报告。"
    ),
    "tools": [score_paper],
}

5.3 创建 DeepAgent

from deepagents import create_deep_agent
from deepagents.backends import StateBackend

backend = StateBackend()

agent = create_deep_agent(
    model=build_doubao(),
    backend=backend,
    tools=[],  # 主 Agent 不直接持有搜索/评分工具，避免绕过子 Agent
    subagents=[researcher_subagent, critic_subagent],
    system_prompt=(
        "你是一名研究项目主管，必须遵守：\n"
        "1. 论文搜索必须通过 task 调用 subagent_type='researcher'。\n"
        "2. 论文评分必须通过 task 调用 subagent_type='critic'。\n"
        "3. 你不得亲自搜索或评分。\n"
        "4. researcher 和 critic 返回前，不得撰写最终报告。\n"
        "5. 最终中文综合报告只能由你根据子代理结果撰写。"
    ),
)

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "请调研最近两年关于 RAG 评估方法的论文，并输出中文综合报告。",
            }
        ]
    }
)

5.4 为什么主 Agent 不直接拿工具

不推荐：

agent = create_deep_agent(
    model=build_doubao(),
    tools=[search_papers, score_paper],
    subagents=[researcher_subagent, critic_subagent],
)

因为这时主 Agent 虽然被提示"不要亲自搜索或评分"，但它仍然有能力直接调用工具。

更稳的是：

主 Agent：只拿 task，负责协调
researcher：只拿 search_papers
critic：只拿 score_paper

提示词决定模型"愿不愿意"调用子 Agent；工具权限决定它"能不能"绕过子 Agent。

6. Demo：用普通 Agent 手动组装类似能力

如果不用 create_deep_agent，也可以用 create_agent 手动组装 middleware。

这样能帮助理解 DeepAgent 本质上是一个预组装 harness。

from langchain.agents import create_agent
from langchain.agents.middleware import TodoListMiddleware
from deepagents.backends import StateBackend
from deepagents.middleware.filesystem import FilesystemMiddleware
from deepagents.middleware.subagents import SubAgentMiddleware
from deepagents.middleware.patch_tool_calls import PatchToolCallsMiddleware
from deepagents.middleware.skills import SkillsMiddleware

backend = StateBackend()

agent = create_agent(
    model=build_doubao(),
    tools=[],
    system_prompt="你是研究项目主管，通过 task 协调子代理完成研究任务。",
    middleware=[
        TodoListMiddleware(),
        SkillsMiddleware(backend=backend, sources=["/skills/"]),
        FilesystemMiddleware(backend=backend),
        SubAgentMiddleware(
            backend=backend,
            subagents=[researcher_subagent, critic_subagent],
        ),
        PatchToolCallsMiddleware(),
    ],
)

生产里一般不建议为了"像 DeepAgent"而手动拼全部中间件，除非你确实需要深度定制。大多数情况下直接用 create_deep_agent 更简单。

7. 中间件在实际项目中的常见坑

7.1 主 Agent 不一定会调用子 Agent

错误写法：

你可以在需要时使用 researcher。

这种太软。

更稳写法：

论文搜索必须调用 task，subagent_type='researcher'。
论文评分必须调用 task，subagent_type='critic'。
你不得直接执行搜索或评分。

同时，主 Agent 不要暴露子 Agent 专属工具。

7.2 subagents=[...] 只是注册，不是自动执行

传入：

subagents=[researcher_subagent, critic_subagent]

只是告诉主 Agent 有哪些子 Agent 可用。

真正执行需要主 Agent 调：

task(subagent_type="researcher", description="...")

7.3 子 Agent 返回的不是完整历史

子 Agent 执行完后，主 Agent 通常只收到最终报告。

它看不到完整的：

• 搜索过程；
• 工具调用细节；
• 子 Agent 内部 messages；
• 中间推理过程。

这有利于节省主上下文，但调试时要依赖 trace / 日志。

7.4 read_file 不负责 offload

容易误解成：

read_file 会把多余内容写出去

实际是：

• 大工具结果由 FilesystemMiddleware 写到 /large_tool_results/<tool_call_id>；
• 超大用户消息可能写到 /conversation_history/<uuid>.md；
• read_file 只是根据路径分页读取。

7.5 默认 backend 不一定是本机磁盘

默认 StateBackend 是虚拟文件系统，路径看起来像：

/large_tool_results/call_xxx

但不代表你能在本机 /large_tool_results 目录找到它。

如果要落到真实磁盘，需要配置 FilesystemBackend。

7.6 Skills 不是权限系统

SkillsMiddleware 是"操作手册"，不是"安全沙箱"。

如果某个工具不该给主 Agent 用，就不要放进主 Agent 的 tools。

7.7 Summarization 会丢信息

上下文压缩不是无损压缩。

关键业务状态要结构化保存：

• 数据库；
• state schema；
• 文件；
• 检查点；
• 审计日志。

7.8 Human-in-the-loop 不能替代权限控制

审批是最后一道保险，不是权限边界。

真正危险的操作要从工具暴露、路径权限、backend policy 上限制。

7.9 并行子 Agent 可能抢资源

多个 task 同时运行时，底层可以并行执行。

注意：

• 不要写同一个输出文件；
• 不要复用同一个临时路径；
• 外部 API 要做限流；
• 数据库写入要有事务或幂等设计。

7.10 Prompt caching 不是所有模型都有效

DeepAgent 会对支持的模型供应商使用 prompt caching。

但如果你用的是不支持的模型，或者接入方式不支持缓存，就不要把降本完全寄托在 caching 上。

8. DeepAgent 的落地场景

适合用 DeepAgent 的场景通常有几个特征：

• 任务步骤多；
• 上下文长；
• 需要读写文件；
• 需要调用多个工具；
• 需要子任务隔离；
• 执行中可能需要人工确认；
• 最终结果需要综合多个中间结果。

8.1 适合场景

场景	为什么适合
代码库分析 / 自动修复	需要读大量文件、运行测试、保存中间结果
深度研究报告	需要搜索、筛选、整理、评分、汇总
论文调研系统	researcher / critic / writer 分工明显
数据分析助手	需要读取文件、运行脚本、生成报告
企业知识库问答增强	可结合 RAG、文件工作区、长期 memory
运维排障助手	需要查日志、执行命令、整理结论
合规审查 / 合同审查	长文档、多步骤、需要人工审批
内容生产流水线	搜集素材、生成草稿、审校、定稿
多 Agent 协作工作流	子任务可并行，主 Agent 负责整合

8.2 不适合场景

场景	原因
简单 FAQ	太重，普通 Agent 或 RAG 就够
单次 API 调用	没必要引入文件系统和子代理
强确定性流程	直接写业务代码 / Graph 更稳
极低延迟接口	DeepAgent 工具链路和 prompt 更重
成本极敏感场景	多轮 ReAct 和子 Agent 会增加调用次数
高风险自动执行	需要更多确定性权限和审批设计

9. 推荐生产架构：Graph 做骨架，DeepAgent 做节点

实际业务里，不建议让一个 DeepAgent 从头管到尾。

更稳的方式是：

LangGraph / StateGraph 做流程骨架
DeepAgent 做复杂智能节点

例如：

1. Graph 校验用户输入
2. Graph 判断任务类型
3. DeepAgent 节点执行论文研究
4. Graph 校验 DeepAgent 输出结构
5. Graph 进入人工审核
6. Graph 生成最终文件并落库

对应分工：

Graph：确定性流程、状态机、重试、审批、落库
DeepAgent：开放性搜索、分析、长上下文、多工具探索

这样比"一个 DeepAgent 全包"更适合生产。

10. 从成本和耗时看 DeepAgent 的优缺点

10.1 成本优点

• 大工具结果 offload 后，后续 ReAct 循环不用反复携带完整内容；
• read_file 分页读取，避免一次性塞大文件；
• 子 Agent 隔离上下文，主 Agent 只拿最终结果；
• 支持 prompt caching 的模型上，稳定 prompt 可减少重复处理成本；
• skills 采用 progressive disclosure，不会启动时加载所有完整说明。

10.2 成本缺点

• 默认系统提示词更长；
• 默认工具 schema 更多；
• 中间件注入内容更多；
• 子 Agent 会产生额外模型调用；
• 长任务通常 ReAct 轮数更多；
• 如果 prompt 没写好，可能产生无效 task、无效搜索、重复读取。

10.3 耗时优点

• 独立子任务可以并行；
• 文件工作区减少重复搜索和重复读取；
• 长任务不容易因为上下文爆掉而中断；
• 复杂任务中，整体成功率可能高于普通 Agent。

10.4 耗时缺点

• 单次简单任务比普通 Agent 慢；
• 子 Agent 启动、工具调用、总结压缩都有额外开销；
• human-in-the-loop 会引入人工等待；
• 如果 backend / sandbox / 外部搜索服务慢，整体链路会明显变长。

10.5 简单判断标准

可以用这个判断：

如果 1-2 次工具调用能解决，用普通 Agent。
如果需要 10+ 步、读写文件、多个角色协作、长期上下文，用 DeepAgent。

11. DeepAgent 是 Harness 思想架构吗？

是。

可以用 5 点概括：

1. 它不是模型层

   DeepAgent 不提供新模型，它调用外部模型。

2. 它不是全新的底层运行时

   它底层依赖 LangChain 的 agent 构建能力和 LangGraph 的执行能力。

3. 它是模型外壳和运行支架

   它把 prompt、tools、middleware、backend、state、subagents 组合成一个长任务运行框架。

4. 它负责给模型"正确上下文"

   通过 skills、memory、filesystem、summarization、offload，在合适时机给模型合适的信息。

5. 它把生产常用能力预装好

   文件系统、任务列表、子代理、上下文压缩、人工审批、prompt caching 等，都是为了让 Agent 更像可落地系统。

一句话：

DeepAgent 是 Harness 思想的典型实现：底层仍是模型调用工具循环，上层用一套工程化外壳管理上下文、工具、状态、权限和任务拆分。

12. 总结

DeepAgent 的价值不在于"换了一个更强的 Agent 名字"，而在于它把长任务 Agent 常见的工程问题打包成默认能力：

• 用 TodoListMiddleware 管任务；
• 用 FilesystemMiddleware 管文件和大结果；
• 用 SubAgentMiddleware 做子任务隔离；
• 用 SummarizationMiddleware 控制上下文长度；
• 用 PatchToolCallsMiddleware 修补工具调用历史；
• 用 SkillsMiddleware 按需加载操作手册；
• 用 MemoryMiddleware 保留长期偏好；
• 用 HumanInTheLoopMiddleware 控制高风险动作。

如果你的应用只是简单问答，DeepAgent 可能太重。

如果你的应用是研究、代码、多文件、多工具、多阶段、多角色协作，DeepAgent 会比普通 Agent 更接近可落地的工程方案。

参考资料

• LangChain Deep Agents Overview
• LangChain Agents
• Deep Agents Context Engineering
• Deep Agents Subagents
• Deep Agents Skills
• Deep Agents Memory
• Deep Agents Backends
• Deep Agents Permissions
• Deep Agents Human-in-the-loop
• deepagents 源码：create_deep_agent
• deepagents 源码：FilesystemMiddleware
• deepagents 源码：SubAgentMiddleware
• deepagents 源码：SkillsMiddleware
• deepagents 源码：PatchToolCallsMiddleware