DeepAgent面向长任务的 Agent Harness 架构中间件、Demo 与落地实践本文基于 2026-07-01 对 LangChain / Deep Agents 官方文档和源码的理解整理。Deep Agents 更新较快生产落地前建议再核对当前版本的 API 和默认中间件栈。部分中间件未实际运用过部分AI生成生产环境自行研究考量。1. 一句话理解 DeepAgentDeepAgent 不是一个新模型也不是完全独立的新运行时。更准确地说DeepAgent 是基于 LangChaincreate_agent/ LangGraph 的长任务 Agent Harness。普通 Agent 更像模型 工具调用循环DeepAgent 更像模型 工具调用循环 文件工作区 任务列表 子代理 上下文压缩 大结果 offload skills / memory human-in-the-loop prompt caching它解决的核心问题不是“模型会不会更聪明”而是长任务怎么规划大上下文怎么管理工具结果太大怎么处理子任务怎么隔离多步骤任务怎么持续执行生产环境里怎么加权限、审批、记忆、技能。2. 普通 Agent 和 DeepAgent 的区别对比项普通 Agentcreate_agentDeepAgentcreate_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 调用子 AgentSummarizationMiddleware默认历史过长时压缩上下文PatchToolCallsMiddleware默认修补悬空 tool call避免消息历史不完整导致模型 API 报错注意如果没有显式传同步 subagentDeepAgent 通常会自动加一个general-purpose子代理如果通过 profile 禁用了默认子代理则不会暴露task工具。3.2 条件性中间件Middleware触发条件主要作用SkillsMiddleware传了skills[...]加载技能元信息按需读取SKILL.mdMemoryMiddleware传了memory[...]加载长期记忆例如AGENTS.mdHumanInTheLoopMiddleware传了interrupt_on或权限中断在关键工具调用前暂停等待人工审批AsyncSubAgentMiddleware传了异步 subagents管理异步 / 后台子代理任务Prompt caching middlewareAnthropic / Bedrock 等支持场景对稳定 prompt 片段做缓存降低重复处理成本_ToolExclusionMiddlewareharness profile 配了excluded_tools从模型可见工具列表中隐藏某些工具自定义 middleware传middleware[...]注入业务自定义逻辑4. 常用中间件详解4.1 TodoListMiddleware让 Agent 有任务列表作用给 Agent 一个write_todos工具适合多步骤任务让 Agent 明确当前执行到哪一步。它不是业务数据库里的任务表只是 Agent 运行状态里的轻量 planning 结构。适合代码修改研究报告多文件分析多步骤排查。容易踩坑不要把它当成可靠的业务状态存储长期业务进度应该落库而不是只放在 todo stateprompt 没写好时模型可能不主动维护 todo。4.2 FilesystemMiddlewareDeepAgent 的工作区核心它提供默认文件工具ls read_file write_file edit_file glob grep execute # 只有 sandbox backend 支持时才可用它还有一个很关键的能力大工具结果 offload。当某个工具返回结果太大时DeepAgent 不会一直把完整结果塞在 messages 里而是写到虚拟文件系统/large_tool_results/tool_call_idmessages 里只保留结果太大已保存到某路径这里是 head/tail 预览需要时用 read_file 分页读取read_file支持分页read_file(file_path/large_tool_results/call_xxx,offset0,limit100)容易踩坑read_file本身不是 offload 工具它只是分页读取默认StateBackend里的路径是虚拟路径不一定是你本机真实磁盘目录大工具结果被 offload 后主 Agent 看到的是摘要和路径不是完整内容如果 Agent 没学会继续read_file可能只基于预览做判断并行子代理共享同一个 backend 时写同一路径可能冲突文件权限要认真配置尤其涉及.env、密钥、用户上传文件时。4.3 SubAgentMiddleware主 Agent 调用子 Agent它给主 Agent 增加一个task工具。主 Agent 可以这样调用task(subagent_typeresearcher, description搜索某主题论文并返回结构化结果)子 Agent 的特点每次调用都是短生命周期 invocation子 Agent 有独立上下文子 Agent 不会把完整执行历史塞回主 Agent默认只把最终结果作为一个ToolMessage返回给主 Agent如果同一轮发出多个tasktool 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_idcall_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. 输出结构化中文结果。使用方式fromdeepagentsimportcreate_deep_agentfromdeepagents.backends.filesystemimportFilesystemBackend backendFilesystemBackend(root_dir./agent_workspace)agentcreate_deep_agent(modelopenai:gpt-5.5,backendbackend,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 可能串上下文敏感信息不要写进 memorymemory 更新必须设计审核机制。4.8 HumanInTheLoopMiddleware关键动作前人工确认适合在高风险动作前暂停删除文件写生产数据库发邮件调支付接口执行高成本 API修改线上配置。示例fromdeepagentsimportcreate_deep_agentfromlanggraph.checkpoint.memoryimportMemorySaver checkpointerMemorySaver()agentcreate_deep_agent(modelopenai:gpt-5.5,tools[],checkpointercheckpointer,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 定义工具fromtypingimportAnyfromlangchain.toolsimporttooldefbuild_doubao()-Any:构建模型客户端实际项目中可替换为豆包 ChatModel 实例。# 为了让示例保持简洁这里返回 LangChain 支持的模型标识字符串returnopenai:gpt-5.5tooldefsearch_papers(query:str,limit:int5)-list[dict]:根据研究主题搜索论文返回候选论文的结构化列表。# 生产环境中可接 Semantic Scholar、arXiv、企业知识库或自建搜索服务return[{title:fPaper about{query},year:2025,url:https://example.com/paper,abstract:A short abstract...,}][:limit]tooldefscore_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 定义子 Agentresearcher_subagent{name:researcher,description:负责搜索论文并返回结构化候选列表不负责评分和最终报告。,system_prompt:(你是论文研究员。你的职责是根据任务描述搜索论文返回结构化论文列表。不要评分不要写最终综合报告。),tools:[search_papers],}critic_subagent{name:critic,description:负责根据论文信息评分不负责搜索和最终报告。,system_prompt:(你是论文评审员。你的职责是根据输入的论文列表逐篇评分输出结构化评分结果。不要搜索新论文不要写最终综合报告。),tools:[score_paper],}5.3 创建 DeepAgentfromdeepagentsimportcreate_deep_agentfromdeepagents.backendsimportStateBackend backendStateBackend()agentcreate_deep_agent(modelbuild_doubao(),backendbackend,tools[],# 主 Agent 不直接持有搜索/评分工具避免绕过子 Agentsubagents[researcher_subagent,critic_subagent],system_prompt(你是一名研究项目主管必须遵守\n1. 论文搜索必须通过 task 调用 subagent_typeresearcher。\n2. 论文评分必须通过 task 调用 subagent_typecritic。\n3. 你不得亲自搜索或评分。\n4. researcher 和 critic 返回前不得撰写最终报告。\n5. 最终中文综合报告只能由你根据子代理结果撰写。),)resultagent.invoke({messages:[{role:user,content:请调研最近两年关于 RAG 评估方法的论文并输出中文综合报告。,}]})5.4 为什么主 Agent 不直接拿工具不推荐agentcreate_deep_agent(modelbuild_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。fromlangchain.agentsimportcreate_agentfromlangchain.agents.middlewareimportTodoListMiddlewarefromdeepagents.backendsimportStateBackendfromdeepagents.middleware.filesystemimportFilesystemMiddlewarefromdeepagents.middleware.subagentsimportSubAgentMiddlewarefromdeepagents.middleware.patch_tool_callsimportPatchToolCallsMiddlewarefromdeepagents.middleware.skillsimportSkillsMiddleware backendStateBackend()agentcreate_agent(modelbuild_doubao(),tools[],system_prompt你是研究项目主管通过 task 协调子代理完成研究任务。,middleware[TodoListMiddleware(),SkillsMiddleware(backendbackend,sources[/skills/]),FilesystemMiddleware(backendbackend),SubAgentMiddleware(backendbackend,subagents[researcher_subagent,critic_subagent],),PatchToolCallsMiddleware(),],)生产里一般不建议为了“像 DeepAgent”而手动拼全部中间件除非你确实需要深度定制。大多数情况下直接用create_deep_agent更简单。7. 中间件在实际项目中的常见坑7.1 主 Agent 不一定会调用子 Agent错误写法你可以在需要时使用 researcher。这种太软。更稳写法论文搜索必须调用 tasksubagent_typeresearcher。 论文评分必须调用 tasksubagent_typecritic。 你不得直接执行搜索或评分。同时主 Agent 不要暴露子 Agent 专属工具。7.2subagents[...]只是注册不是自动执行传入subagents[researcher_subagent,critic_subagent]只是告诉主 Agent 有哪些子 Agent 可用。真正执行需要主 Agent 调task(subagent_typeresearcher, description...)7.3 子 Agent 返回的不是完整历史子 Agent 执行完后主 Agent 通常只收到最终报告。它看不到完整的搜索过程工具调用细节子 Agent 内部 messages中间推理过程。这有利于节省主上下文但调试时要依赖 trace / 日志。7.4read_file不负责 offload容易误解成read_file 会把多余内容写出去实际是大工具结果由 FilesystemMiddleware 写到/large_tool_results/tool_call_id超大用户消息可能写到/conversation_history/uuid.mdread_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 点概括它不是模型层DeepAgent 不提供新模型它调用外部模型。它不是全新的底层运行时它底层依赖 LangChain 的 agent 构建能力和 LangGraph 的执行能力。它是模型外壳和运行支架它把 prompt、tools、middleware、backend、state、subagents 组合成一个长任务运行框架。它负责给模型“正确上下文”通过 skills、memory、filesystem、summarization、offload在合适时机给模型合适的信息。它把生产常用能力预装好文件系统、任务列表、子代理、上下文压缩、人工审批、prompt caching 等都是为了让 Agent 更像可落地系统。一句话DeepAgent 是 Harness 思想的典型实现底层仍是模型调用工具循环上层用一套工程化外壳管理上下文、工具、状态、权限和任务拆分。12. 总结DeepAgent 的价值不在于“换了一个更强的 Agent 名字”而在于它把长任务 Agent 常见的工程问题打包成默认能力用TodoListMiddleware管任务用FilesystemMiddleware管文件和大结果用SubAgentMiddleware做子任务隔离用SummarizationMiddleware控制上下文长度用PatchToolCallsMiddleware修补工具调用历史用SkillsMiddleware按需加载操作手册用MemoryMiddleware保留长期偏好用HumanInTheLoopMiddleware控制高风险动作。如果你的应用只是简单问答DeepAgent 可能太重。如果你的应用是研究、代码、多文件、多工具、多阶段、多角色协作DeepAgent 会比普通 Agent 更接近可落地的工程方案。参考资料LangChain Deep Agents OverviewLangChain AgentsDeep Agents Context EngineeringDeep Agents SubagentsDeep Agents SkillsDeep Agents MemoryDeep Agents BackendsDeep Agents PermissionsDeep Agents Human-in-the-loopdeepagents 源码create_deep_agentdeepagents 源码FilesystemMiddlewaredeepagents 源码SubAgentMiddlewaredeepagents 源码SkillsMiddlewaredeepagents 源码PatchToolCallsMiddleware