Deer-Flow 的 Super Agent 架构实践

Deer-Flow 的 Super Agent 架构实践

学习目标

• 理解 Deer-Flow 从 Deep Research 到 Super Agent Harness 的演进路径
• 掌握 Lead Agent 的入口设计、工具装配和系统提示组装
• 学会分析一个 Super Agent 的运行时架构

前置知识

本章涉及 Super Agent Harness 的通用原理，建议先阅读：

• Super Agent 架构：从单 Agent 到运行环境

下文假设你已理解 Super Agent 的概念，直接聚焦 Deer-Flow 的具体实现。

---

项目实践

Deer-Flow 2.0 的架构演进

Deer-Flow 1.x 是一个 Deep Research 框架，专注于多步信息收集和分析。2.0 从零重写为 Super Agent Harness，核心变化：

关键差异：

维度	1.x	2.0
定位	深度研究框架	通用 Agent 运行环境
核心能力	搜索 + 分析 + 报告	技能 + 记忆 + 沙箱 + 子 Agent
扩展方式	代码修改	.skill 归档安装
入口	单一研究流程	Lead Agent 统一入口

Lead Agent 入口设计

Deer-Flow 的 Lead Agent 通过 make_lead_agent(config: RunnableConfig) 工厂函数创建，这是整个 Agent 系统的统一入口点：

# 伪代码，实际见 lead_agent/agent.py
def make_lead_agent(config: RunnableConfig):
    # 1. 动态模型选择
    model = create_chat_model(
        name=config.get("model_name"),
        thinking_enabled=config.get("thinking_enabled")
    )

    # 2. 工具装配
    tools = get_available_tools(
        groups=config.get("tool_groups"),
        include_mcp=True,
        model_name=config.get("model_name"),
        subagent_enabled=config.get("subagent_enabled")
    )

    # 3. 系统提示组装
    system_prompt = apply_prompt_template(
        skills=load_enabled_skills(),
        memory=inject_memory_facts(),
        subagent_instructions=get_subagent_docs()
    )

    # 4. 中间件链组装
    middlewares = _build_middlewares(config)

    # 5. 绑定工具 + 中间件
    return model.bind_tools(tools) | middlewares

设计特点：

• 模型通过反射动态加载，不硬编码依赖
• 工具按需加载（内置 + MCP + 社区 + 子 Agent）
• 系统提示动态组装（技能描述 + 记忆注入 + 子 Agent 文档）

工具装配策略

get_available_tools() 按以下优先级组装工具：

1. 配置定义工具：从 config.yaml 的 tools[] 解析，通过 resolve_variable() 反射加载
2. MCP 工具：从启用的 MCP 服务器懒加载发现
3. 内置工具：present_files（使输出文件可见）、ask_clarification（请求澄清）、view_image（图片理解）
4. 子 Agent 工具：仅在 subagent_enabled 时绑定 task 工具
5. 社区工具：Tavily 搜索、Jina AI 爬虫、Firecrawl 抓取

系统提示组装

apply_prompt_template() 动态组装 Lead Agent 的系统提示，包含三个可变区块：

• 技能区块：每个启用技能的名称、描述和容器路径
• 记忆区块：Top 15 相关事实 + 用户上下文，注入到 <memory> 标签
• 子 Agent 区块：可用子 Agent 列表及其能力描述

这种按需组装避免了将全部技能描述塞入系统提示，保持上下文窗口精简。

---

问题与规避

技能过多时的 Token 膨胀

当安装大量技能时，系统提示可能过大。

Deer-Flow 的规避：技能按需加载——只在任务需要时才将技能描述注入系统提示，而非启动时全部注入。

配置热重载的一致性

config.yaml 修改后，不同组件的生效时间不同。运行时字段（模型参数、记忆配置）自动生效，基础设施字段（沙箱 Provider、数据库）需要重启。这种差异可能导致调试困惑。

规避：make doctor 命令可以验证配置状态，get_app_config() 通过 mtime 自动重载。

---

设计取舍

为什么从 Deep Research 转向 Super Agent

背景：社区用户使用 Deer-Flow 1.x 构建数据管道、幻灯片、仪表板等非研究用途，远超原始设计。

取舍：放弃 1.x 的代码兼容性（“shares no code with v1”），从零设计 Super Agent 架构。代价是迁移成本，收益是更通用的能力边界。

Lead Agent 统一入口 vs 多入口

方案对比：

方案	优势	代价
统一入口	简化调用方、统一状态管理	Lead Agent 需要处理所有场景的调度
多入口	每个场景专用入口	调用方需要理解入口选择逻辑

Deer-Flow 选择：统一 Lead Agent 入口，通过 config.configurable 的运行时配置（is_plan_mode、subagent_enabled 等）控制行为。

---

参考来源

• Deer-Flow README — “From Deep Research to Super Agent Harness” 章节
• Deer-Flow CLAUDE.md — 架构描述