DeerFlow 的 Super Agent Harness：给 Agent 用的运行时骨架

普通聊天机器人接到「调研 2026 年 AI Agent 进展，写报告再做成 PPT」这类需求时，常见表现是一口气猜答案、没有地方落文件和跑代码、聊完上下文就丢。能真正把任务做完的 agent，至少需要跨会话记忆、可调用工具、隔离执行环境、可复用技能流程，以及把大任务拆给子代理并行推进的能力。这些基建如果每个项目从零搭，成本太高，也难保证边界一致。DeerFlow 2.0 把它们收成一套可声明、可拆组的运行时基础设施，项目定位里叫 Super Agent Harness。后面 Lead Agent、Runtime、Gateway 等模块怎么拆，都挂在这副骨架上。

Harness 指什么

Super Agent 指能力尽量拉满的智能体；Harness 原意是马具，在软件里通常指把组件组织起来并驱动它们的框架或骨架。合在一起，Harness 就是把记忆、沙箱、技能、工具、子代理等能力组织起来、并让它们真正跑起来的运行时层：整套「做成事」的基础设施。用户既可以直接跑 DeerFlow 的开箱工作流，也可以把 Harness 当 SDK，拆开重组进自己的系统。

分层可以这样读：

• 底层：文件系统、Sandbox 执行环境、Memory 存储，负责「有地方干活、有地方记住」
• 中层：Skills 加载、Tools 调用、Sub-Agents 调度，负责「会什么、怎么动手、怎么并行」
• 上层：LangGraph 多步骤任务编排，负责「多轮决策与流程」

改某一层时边界相对清楚。后续出现的 Lead Agent、Runtime、Gateway、IM Channels、Skills、Tools、Sandbox、Memory，都是挂在这副骨架上的子系统：各自独立，又通过 Harness 协同。

任务在骨架上怎么拆

同样那句「调研 + 写报告 + 做 PPT」，在 Harness 里通常会变成下面这条路径：Harness 启动 Lead Agent；Lead 负责拆解与汇总，并并行拉起多个 Sub-Agent；子代理在 Sandbox 里搜索、读写文件、跑代码；结构化结果回到 Lead；再由沙箱生成报告和 PPT 文件交给用户；Memory 在后台记录偏好。交付物落在磁盘文件上，而不仅是模型生成的一段话。

和「带工具的聊天框」比，这里多了一套稳定的运行时约定：谁拆任务、谁并行、谁落盘、谁跨会话记得住。Harness 把这些约定固化成可复用的装配。

声明式：RuntimeFeatures

你不需要手写「先加载技能、再绑定工具、再挂中间件」这类装配代码。deerflow/agents/features.py 里的 RuntimeFeatures 就是能力清单：字段勾选（或替换）后，Harness 负责组装。

@dataclass
class RuntimeFeatures:
    sandbox: bool | AgentMiddleware = True
    memory: bool | AgentMiddleware = False
    subagent: bool | AgentMiddleware = False
    vision: bool | AgentMiddleware = False
    auto_title: bool | AgentMiddleware = False

每个字段可以是 bool，也可以直接塞一个自定义 AgentMiddleware，开箱默认和替换实现共用同一入口。工厂用法很短：

from deerflow.agents.factory import create_deerflow_agent
from deerflow.agents.features import RuntimeFeatures

agent = create_deerflow_agent(
    model=my_model,
    features=RuntimeFeatures(sandbox=True, memory=True),
)

调用路径是：create_deerflow_agent 接收 model + features → _assemble_from_features 按勾选排出中间件列表和额外工具 → LangChain 的 create_agent 生成可运行图。简化后的组装逻辑大致是：sandbox is not False 时追加 ThreadDataMiddleware、SandboxMiddleware；开 memory 追加 MemoryMiddleware(agent_name=...)；开 subagent 追加 SubagentLimitMiddleware 并注册 task_tool。声明要什么，链上就加什么，读工厂代码几乎不需要猜。

中间件链与相对插队

每项能力在 Harness 里对应一个 Middleware，对话按固定顺序过链。常见顺序包括 ThreadData（准备线程数据）→ Uploads → Sandbox → ToolError → Summarization → Memory → Clarification 等。加能力等于插中间件，换实现等于换那一个中间件。整条链的顺序细节在 Lead Agent 章节展开；Harness 层先把握一点：横切能力以中间件形式挂在图上。

自定义中间件可以用 @Next / @Prev 声明相对位置，不必背绝对序号：

from deerflow.agents.features import Next
from deerflow.agents.middlewares import MemoryMiddleware

@Next(MemoryMiddleware)
class MyCustomMiddleware(AgentMiddleware):
    ...

即使你还不熟整条默认链，也能把扩展点钉在 Memory 后面或某个中间件前面。

开箱即用与拆开重组

两种用法对应两种场景。开箱即用：直接跑 DeerFlow，做研究、写报告这类默认工作流，少碰装配细节。拆开重组：用 create_deerflow_agent 按项目勾选 sandbox / memory / subagent，或替换个别中间件，把 Harness 嵌进自己的服务。设计取舍是：默认带齐常用能力，降低从零搭 agent 的成本；同时保留声明式开关和中间件替换，避免变成不可拆的黑盒。分层边界也缩小了改动面：换记忆实现不必重写编排，换沙箱不必动 Gateway。

读代码时可以从这几处下手：谁声明能力（RuntimeFeatures）、谁组装链（_assemble_from_features / 后续的 build_middlewares）、谁真正执行（Sandbox、Tools、Sub-Agents）。入口对上了，后面各模块会自然对齐。遇到「为什么默认就有沙箱」「记忆为什么是开关」一类问题，回到能力清单和组装函数，通常比在 prompt 里找答案更快。