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 的研究 Agent
3.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(success=True, data=summary)注意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 这套思路理解透——状态机、工具抽象、分层记忆、可观测性，这些概念不管用什么框架都是通用的。理解了这些，换框架的成本就很低，因为你知道自己要的是什么。
