DeerFlow 2.0 深度拆解：从 Deep Research 到 Super Agent Harness 的架构演进

1. 从 Deep Research 到 Super Agent Harness 的认知跃迁1.1 为什么 DeerFlow 2.0 值得单独拿出来聊DeerFlow 这个项目在开源社区里一直是个挺特别的存在。第一代出来的时候很多人把它当成一个能自动查资料写报告的工具本质上还是 Deep Research 的思路——给一个话题它去搜索、阅读、汇总最后吐出一份结构化的研究报告。这个定位在 2024 年到 2025 年上半年是够用的因为那时候大家对 AI 的期待还停留在帮我省掉查资料的时间。但到了 2.0字节把定位直接改成了 Super Agent Harness。这个词拆开看就很有意思Harness 在工程语境里是线束、约束框架、测试夹具的意思放到 Agent 领域它指的是一套让 Agent 能够稳定运行、可观测、可干预、可复现的运行时骨架。换句话说DeerFlow 2.0 不再只是一个研究工具而是一个让各种 Agent 能力跑得稳、管得住、看得见的底座。这个转变背后的逻辑其实很实在。我接触过不少团队他们用第一代 Deep Research 类工具的时候最头疼的不是它不够聪明而是它跑起来之后我完全不知道它在干嘛。搜索了几轮、读了哪些页面、中间有没有跑偏、最后结论是怎么来的全靠它自己说。一旦结果不对你连从哪一步开始排查都不知道。Super Agent Harness 要解决的就是这个问题——把 Agent 的执行过程从黑盒变成白盒把不可控的自主循环变成可编排、可中断、可回放的工作流。所以这篇内容适合谁看如果你是做 AI 应用开发的想找一个能承载复杂 Agent 逻辑的框架那 DeerFlow 2.0 的架构设计值得逐层拆如果你是做研究、做内容、做数据分析的想理解为什么有些 Agent 跑得稳有些跑得飘那它里面的 Harness 机制能给你很多启发哪怕你只是刚入门 Agent 开发把它当成一个工业级 Agent 系统长什么样的参考样本也比看一堆玩具 demo 强得多。1.2 Deep Research 的天花板到底在哪要理解 2.0 为什么要进化得先看清楚 1.0 那套 Deep Research 模式的天花板。Deep Research 的核心链路其实很清晰接收 query → 拆解子问题 → 并行搜索 → 抓取网页 → 抽取信息 → 汇总成报告。这条链路在信息检索摘要这个场景里是成立的但一旦任务变复杂问题就暴露了。第一个问题是状态不可持久。Deep Research 通常是一次性的跑完就结束中间状态不保留。如果你想让它在第二天接着昨天的进度继续深挖或者基于上次的结果做增量更新基本做不到。第二个问题是工具调用不可扩展。很多 Deep Research 实现里工具是硬编码的——搜索、抓取、总结就这三板斧。你想加一个调用内部数据库或者执行一段代码验证假设的能力得改核心代码。第三个问题是过程不可干预。Agent 跑到一半发现方向错了你只能等它跑完再重来没法在中途喊停、调整、继续。这三个问题归结起来就是一句话Deep Research 是一个封闭的流水线而真实世界的任务需要的是一个开放的运行时。DeerFlow 2.0 的 Super Agent Harness 就是冲着这个开放运行时去的。它把 Agent 的执行拆成了可持久化的状态、可插拔的工具、可观测的步骤让整个系统从跑一次就完变成可以长期运行、持续演进。1.3 Super Agent Harness 到底Harness了什么Harness这个词在软件工程里最经典的用法是 test harness——测试夹具它负责给被测对象提供稳定的运行环境、输入输出控制和结果记录。Super Agent Harness 借用了这个隐喻它要 harness 的是 Agent 的执行过程。具体来说它管三件事。第一是生命周期管理一个 Agent 任务从创建、执行、暂停、恢复到终止每个状态都有明确的定义和转移规则不会出现跑着跑着不知道去哪了的情况。第二是能力编排Agent 能调用哪些工具、按什么顺序调、调用的输入输出怎么校验这些都在 Harness 层统一管理而不是散落在各个 Agent 实现里。第三是可观测性每一步执行了什么、花了多久、消耗了多少 token、中间产出了什么全部记录下来支持回放和审计。这三件事听起来像是工程细节但恰恰是这些细节决定了 Agent 能不能从 demo 走向生产。我见过太多 Agent 项目demo 阶段惊艳一上生产就各种翻车根因几乎都在这三件事上没做好。DeerFlow 2.0 把这层单独抽出来做成 Harness思路是对的——把通用的运行时能力和具体的业务逻辑解耦让上层 Agent 开发者只需要关注我要做什么而不用操心怎么跑得稳。2. 核心架构拆解Harness 层到底怎么设计的2.1 状态机驱动的执行模型DeerFlow 2.0 的执行模型是状态机驱动的这是它和第一代最大的区别之一。第一代的执行更像是一个递归函数——拆解问题、递归搜索、返回结果调用栈就是它的状态。这种方式在简单场景下没问题但一旦需要中断、恢复、并行分支递归模型就捉襟见肘了。状态机模型把 Agent 的执行拆成一组离散的状态和转移。一个典型的任务会经历这些状态INIT初始化→PLANNING规划→EXECUTING执行→REVIEWING审查→COMPLETED完成中间还可能进入WAITING等待外部输入、PAUSED暂停、FAILED失败等状态。每个状态都有明确的进入条件、执行逻辑和退出条件。这种设计的好处是可持久化。因为状态是离散的你可以把当前状态序列化存到数据库里下次从任意一个状态恢复。这就解决了第一代跑完就没了的问题。你可以让一个研究任务跑三天中间每天只跑几个小时剩下的时间它就在PAUSED状态等着完全不消耗资源。另一个好处是可干预。因为状态转移是显式的你可以在任意一个状态节点插入人工审核。比如任务跑到REVIEWING状态时先暂停让人看一眼中间结果确认没问题再让它继续。这在需要高准确率的场景里非常关键——你不能让 Agent 自己跑完一百步才发现第一步就错了。提示状态机的状态粒度需要仔细设计。太粗了比如只有运行中和完成两个状态起不到干预作用太细了每一步都一个状态会让状态管理本身变成负担。DeerFlow 2.0 的粒度大致是一个语义完整的步骤一个状态这个粒度在实际使用中比较平衡。2.2 工具抽象层与能力注册机制Harness 的第二块核心是工具抽象层。在 DeerFlow 2.0 里所有 Agent 能调用的能力——不管是搜索、网页抓取、代码执行、还是调用外部 API——都被统一抽象成工具通过一套注册机制挂载到 Harness 上。这套机制的关键在于接口标准化。每个工具都要声明自己的名称、描述、输入参数 schema、输出格式。Harness 在执行时会根据 Agent 的决策去查找对应的工具校验输入参数是否符合 schema执行后把输出按标准格式返回。这样做的好处是Agent 不需要知道工具的具体实现只需要知道有这么个能力输入什么、输出什么。我特别想强调的是输入参数校验这一环。很多 Agent 项目翻车就翻在这里——Agent 生成了一个格式不对的参数工具直接报错整个任务挂掉。DeerFlow 2.0 在 Harness 层做了 schema 校验参数不对的时候不是直接抛异常而是返回一个结构化的错误信息给 Agent让它自己修正后重试。这个设计看起来小但对任务成功率的影响非常大。工具注册还支持动态加载。你可以把工具定义成独立的模块运行时按需加载而不是全部打包进主进程。这对于工具数量多的场景很重要——你可能有几十个工具但一个具体任务只需要其中三五个动态加载能显著降低启动开销和内存占用。2.3 记忆与上下文管理策略Agent 跑长任务最大的敌人是上下文窗口。DeerFlow 2.0 在 Harness 层做了一套记忆管理机制把短期上下文和长期记忆分开处理。短期上下文就是当前步骤需要的信息——当前子任务的目标、上一步的输出、相关的工具返回结果。这部分直接放在 prompt 里控制在一个合理的 token 预算内。长期记忆则是整个任务过程中积累的所有信息——搜索过的页面、抽取的事实、中间结论。这部分不直接进 prompt而是存在外部存储里需要的时候通过检索召回。这套机制的核心是分层召回。当 Agent 需要某个信息时Harness 会先从短期上下文里找找不到再从长期记忆里检索。检索用的是向量相似度加关键词混合的方式保证召回的准确性。召回的内容会经过压缩和摘要再注入到当前上下文里避免把原始的长文本直接塞进去。实测下来这套机制对长任务的稳定性提升很明显。第一代跑超过二十轮搜索之后上下文就开始混乱经常出现忘了前面查过什么的情况。2.0 因为有了分层记忆跑五十轮以上依然能保持逻辑连贯。2.4 可观测性与回放机制可观测性是 Harness 最被低估的价值。DeerFlow 2.0 会记录每一步执行的完整轨迹时间戳、状态转移、调用的工具、输入参数、输出结果、消耗的 token、耗时。这些数据存在结构化的日志里支持按任务 ID 查询和回放。回放机制特别有用。当一个任务结果不对时你可以把整个执行轨迹调出来一步步看它是在哪里跑偏的。是规划阶段就错了还是某个工具返回了错误信息还是上下文召回召回了不相关的内容有了轨迹排查效率比看最终输出猜原因高一个数量级。这套可观测性还支持指标聚合。你可以统计一类任务的平均步数、平均 token 消耗、工具调用成功率、失败原因分布。这些指标对于优化 Agent 策略非常关键——比如你发现某个工具调用失败率特别高那就去优化那个工具的 schema 或者 Agent 的调用逻辑。3. 实操从零搭一个基于 DeerFlow 2.0 的研究 Agent3.1 环境准备与依赖安装先说环境。DeerFlow 2.0 是 Python 项目建议 Python 3.10 以上3.11 或 3.12 更稳。依赖管理用 uv 或者 poetry 都行我个人偏好 uv装得快、锁得准。# 用 uv 创建虚拟环境 uv venv --python 3.11 source .venv/bin/activate # 安装核心依赖 uv pip install deerflow-core deerflow-tools # 如果需要网页抓取能力 uv pip install deerflow-tools-web # 如果需要代码执行能力 uv pip install deerflow-tools-code这里有个坑要注意deerflow-tools-code会依赖一个沙箱环境来执行代码默认用的是本地 subprocess 沙箱。如果你在生产环境用强烈建议换成容器化沙箱否则 Agent 生成的代码可能对你的宿主机造成影响。DeerFlow 2.0 支持配置沙箱后端在配置文件里指定sandbox.backend docker就行。模型方面DeerFlow 2.0 本身不绑定特定模型通过 OpenAI 兼容接口对接。你可以用任何提供兼容接口的模型服务。配置在config.yaml里llm: provider: openai_compatible base_url: https://your-endpoint/v1 api_key: ${LLM_API_KEY} model: your-model-name max_tokens: 8192 temperature: 0.3温度建议设低一点0.2 到 0.4 之间。Agent 任务需要的是稳定和可复现不是创意发散。温度太高会导致同样的输入每次跑出来的规划都不一样调试起来很痛苦。3.2 定义你的第一个 Agent 任务DeerFlow 2.0 的任务定义用的是声明式配置加代码钩子的混合模式。基础的任务描述用 YAML复杂的逻辑用 Python 钩子。一个最小的研究任务定义长这样task: name: market_research description: 调研某个细分市场的玩家、规模和趋势 max_steps: 30 timeout_minutes: 60 tools: - web_search - web_fetch - summarize - write_report states: - INIT - PLANNING - EXECUTING - REVIEWING - COMPLETEDmax_steps这个参数很关键。它限制了 Agent 最多执行多少步防止它陷入无限循环。我一般设 20 到 50 之间具体看任务复杂度。设太小任务跑不完设太大万一跑偏了浪费资源。DeerFlow 2.0 还支持max_tokens_total和max_wall_time两个限制建议都配上多重保险。工具列表里web_search和web_fetch是内置的summarize和write_report需要你自己实现或者用官方提供的。实现一个自定义工具其实很简单from deerflow.tools import BaseTool, ToolResult class SummarizeTool(BaseTool): name summarize description 把一段长文本压缩成要点 input_schema { type: object, properties: { text: {type: string, description: 待压缩的文本}, max_points: {type: integer, default: 5} }, required: [text] } async def execute(self, text: str, max_points: int 5) - ToolResult: # 这里调用你的摘要逻辑 summary await self._do_summarize(text, max_points) return ToolResult(successTrue, datasummary)注意input_schema一定要写清楚这是 Harness 做参数校验的依据。schema 写得越明确Agent 调用时出错的概率越低。3.3 配置 Harness 的运行参数Harness 的运行参数决定了 Agent 跑起来的行为特征。几个关键参数我逐个说。并发度harness.max_concurrent_tools控制同时能跑多少个工具调用。默认是 3如果你的工具都是 IO 密集型的比如搜索、抓取可以调到 5 到 8。但如果工具有资源竞争比如都写同一个文件就得调低甚至设成 1。重试策略harness.retry.max_attempts和harness.retry.backoff。工具调用失败时的重试次数和退避策略。搜索类工具建议重试 2 到 3 次退避用指数退避。代码执行类工具建议不重试或者只重试 1 次因为失败往往是逻辑错误重试也是白搭。上下文预算harness.context.max_tokens控制注入 prompt 的上下文上限。这个值要和你用的模型窗口匹配。比如模型窗口是 32k那这个值设 24k 左右比较合适留出空间给输出。设太大容易触发截断设太小信息不够。状态持久化harness.persistence.backend可以选memory、sqlite、redis。开发阶段用memory就行生产环境建议redis或者postgres支持多实例共享状态。harness: max_concurrent_tools: 5 retry: max_attempts: 3 backoff: exponential context: max_tokens: 24000 recall_top_k: 8 persistence: backend: redis url: ${REDIS_URL}recall_top_k是长期记忆召回时返回的条数。设太小可能漏掉关键信息设太大又会挤占上下文。8 到 12 之间是个比较舒服的区间实测下来召回准确率和上下文占用的平衡点大概在这里。3.4 跑起来一次完整的研究任务实录配置好之后启动任务deerflow run --task market_research --input 调研国内新能源汽车充电桩市场的头部玩家和竞争格局任务启动后Harness 会先进入PLANNING状态让模型生成一个执行计划。这个计划通常是一组子问题比如充电桩市场的主要玩家有哪些、各玩家的市场份额和布局、行业增长趋势和驱动因素、政策环境等等。然后进入EXECUTING逐个子问题去搜索、抓取、抽取。每完成一个子问题会进入REVIEWING做一次自检——检查信息是否充分、是否有矛盾、是否需要补充搜索。如果自检通过继续下一个如果不通过回到EXECUTING补充。整个过程你可以在终端看到实时日志也可以打开 Web UI 看可视化的执行轨迹。我一般会开着 Web UI因为能看到每一步的输入输出方便随时发现问题。跑完之后任务进入COMPLETED输出一份结构化的报告。报告里不仅有结论还有每个结论对应的信息来源和执行步骤。这个可追溯的设计很实用——你可以点开任何一个结论看它是从哪个页面、哪次搜索得出来的。4. 踩坑实录那些文档里不会写的问题4.1 工具调用死循环怎么破这是最常见的问题。Agent 调用一个工具返回结果不理想它决定换个参数再调一次还是不行再换……然后就卡在那里了。DeerFlow 2.0 内置了一个循环检测机制会记录最近 N 次工具调用的签名工具名参数哈希如果发现重复调用超过阈值就强制中断当前分支让 Agent 重新规划。这个阈值默认是 3可以在配置里调。但光靠自动检测不够我一般还会在工具实现里加一层保护。比如搜索工具如果同一个 query 在短时间内被调用了两次第二次直接返回缓存结果并附带一个提示这个查询刚刚执行过结果相同。这样 Agent 看到提示后通常会换策略。还有一种死循环是规划-执行-审查之间的循环。Agent 规划了一个步骤执行完审查不通过重新规划又规划出同样的步骤。这种循环的根因通常是审查标准太严或者规划能力不足。解决办法是在审查环节加一个最大重规划次数限制超过就降级处理——要么接受当前结果要么标记为部分完成。4.2 上下文污染与信息串味长任务跑到后面上下文里堆了太多信息模型开始串味——把 A 子问题的结论用到 B 子问题上或者把不相关的信息当成相关的。这个问题的根因是上下文管理不够精细。DeerFlow 2.0 虽然有分层记忆但如果召回策略没调好还是会污染。我的经验是每个子任务用独立的上下文空间子任务之间只通过结构化的结论传递信息不传递原始上下文。具体做法是在 Harness 配置里开启context.isolation per_subtask。这样每个子任务有自己的短期上下文长期记忆是共享的但召回时会带上子任务标签做过滤。实测下来这个设置能把信息串味的概率降低一大半。另一个技巧是定期压缩。任务跑到一定步数后把之前的详细上下文压缩成摘要只保留关键结论和未解决的问题。DeerFlow 2.0 支持配置context.compression_threshold超过这个步数就触发压缩。我一般设 15 到 20 步。4.3 模型输出格式不稳定Agent 任务里模型经常需要输出结构化的内容——比如一个 JSON 格式的执行计划或者一个特定格式的工具调用参数。但模型有时候会自由发挥输出格式不对导致解析失败。DeerFlow 2.0 在 Harness 层做了输出修复机制。当解析失败时它会尝试用规则修复比如补全缺失的括号、去掉多余的 markdown 标记修复不了再把错误信息返回给模型让它重新生成。这个机制能救回大部分格式问题但不是万能的。更根本的解决办法是用结构化输出能力。如果你的模型支持 function calling 或者 JSON mode一定要开启。DeerFlow 2.0 会自动检测模型能力并优先使用结构化输出。开启之后格式错误率能从百分之十几降到百分之一以下。还有一个经验是schema 要宽松。定义工具输入 schema 时不要把所有字段都设成 required能设默认值的就设默认值。required 字段越多模型出错的概率越大。宁可让工具在运行时做二次校验也不要在 schema 层面卡太死。4.4 常见问题速查表问题现象可能原因排查方向解决办法任务卡住不动工具调用死循环看日志里最近的工具调用签名调低循环检测阈值工具层加缓存结果前后矛盾上下文污染检查召回的内容是否跨子任务开启子任务上下文隔离格式解析失败模型输出不稳定看原始输出和解析错误开启结构化输出放宽 schema任务跑太久规划过于发散看执行步数和子任务数量限制 max_steps优化规划 prompt工具调用失败率高schema 定义有问题看失败调用的参数简化 schema增加默认值内存占用持续增长长期记忆未清理看记忆存储的大小配置记忆过期策略定期归档恢复后行为异常状态序列化不完整对比恢复前后的状态检查持久化配置确保所有状态字段都存了这张表是我自己踩坑总结的基本覆盖了八成以上的常见问题。遇到问题先查表能省不少时间。4.5 几个提升稳定性的独家技巧第一个技巧是给工具加超时。任何工具调用都要设超时尤其是网络相关的。DeerFlow 2.0 支持在工具定义里设timeout_seconds默认是 30 秒。搜索和抓取类工具建议设 15 到 20 秒代码执行类设 60 秒。超时后 Harness 会中断调用并返回超时错误Agent 可以选择重试或者换策略。第二个技巧是关键步骤加人工确认。不是所有步骤都需要人工但关键决策点——比如最终报告的大纲、核心结论的取舍——可以配置成需要人工确认。DeerFlow 2.0 支持在状态转移时插入human_approval钩子触发后任务暂停等人工在 UI 上点确认再继续。这个功能在需要高准确率的场景里非常有用。第三个技巧是用影子模式做灰度。新配置或者新工具上线前先用影子模式跑——Agent 正常执行但新配置的结果只记录不生效和旧配置的结果做对比。跑一段时间确认新配置确实更好再切换。DeerFlow 2.0 支持配置shadow_mode指定哪些步骤走影子逻辑。第四个技巧是日志分级。Harness 的日志默认是 INFO 级别信息量很大。生产环境建议调到 WARNING只在出问题时开 DEBUG。但有个例外——工具调用的输入输出建议始终记录哪怕在 WARNING 级别。因为这是排查问题最关键的线索丢了就得重跑。5. 从 Harness 视角看 Agent 工程的未来走向5.1 为什么框架会向运行时演进DeerFlow 从 1.0 到 2.0 的演进其实反映了一个更大的趋势Agent 领域的竞争焦点正在从能力转向可靠性。第一代 Agent 框架拼的是我能调用多少工具、我能处理多复杂的任务但用下来大家发现能力再强跑不稳都是白搭。所以下一阶段的框架会越来越像运行时——提供稳定的执行环境、完善的资源管理、细粒度的可观测性。这跟传统后端从写业务逻辑到依赖中间件的演进路径很像。早期大家什么都自己写后来发现数据库、消息队列、缓存这些通用能力应该抽出来做成中间件业务代码只关注业务。Agent Harness 就是这个思路在 Agent 领域的落地。它把状态管理、工具编排、上下文管理、可观测性这些通用能力抽出来让 Agent 开发者只关注我的 Agent 要做什么。这个分工一旦形成Agent 开发的效率和质量都会有质的提升。5.2 多 Agent 协作在 Harness 层怎么落地DeerFlow 2.0 的 Harness 设计天然支持多 Agent 协作。因为状态是持久化的、工具是注册制的、上下文是隔离的多个 Agent 可以共享同一个 Harness各自跑各自的任务通过共享的长期记忆和消息机制协作。一个典型的模式是规划 Agent 执行 Agent 审查 Agent三件套。规划 Agent 负责拆解任务执行 Agent 负责具体操作审查 Agent 负责质量把关。三个 Agent 通过 Harness 的消息队列通信规划 Agent 产出计划后发给执行 Agent执行 Agent 完成后发给审查 Agent审查不通过再打回执行 Agent。这种模式比单 Agent 全包的好处是职责清晰、可独立优化。规划不行就调规划 Agent 的 prompt执行不行就换执行 Agent 的模型互不影响。而且因为 Harness 记录了所有消息协作过程完全可追溯出问题容易定位。5.3 给正在选型 Agent 框架的人几句实在话如果你正在选 Agent 框架我的建议是先想清楚你的场景需要什么。如果只是做个 demo 或者简单任务轻量级框架就够了上 Harness 反而是过度设计。但如果你要做的是需要长期运行、需要人工干预、需要审计追溯的生产级应用那 Harness 这层能力是绕不过去的。DeerFlow 2.0 在这方面的优势是它把 Harness 做成了核心而不是附属。很多框架也有状态管理、也有工具注册但都是顺带做的深度和完整性不够。DeerFlow 2.0 是把这些当成一等公民来设计的用起来能感觉到差别。当然它也不是没有短板。生态还在建设中第三方工具的数量比不上一些老牌框架文档虽然全但有些地方不够细需要看源码才能完全理解。不过考虑到它开源不久这个成熟度已经不错了。最后说一句Agent 工程这个领域变化很快今天的最佳实践明天可能就过时了。与其纠结选哪个框架不如把 Harness 这套思路理解透——状态机、工具抽象、分层记忆、可观测性这些概念不管用什么框架都是通用的。理解了这些换框架的成本就很低因为你知道自己要的是什么。