DeerFlow 多 Agent 架构解析

总览

基于 DeerFlow 仓库以下版本：
  - Branch: main
  - Commit: b107444878b077517c4fef8df915446a8d21d176
  - Commit Date: 2026-04-10T09:28:57+08:00

DeerFlow 当前的多智能体机制，本质上是一套由lead agent决策拆解、工具层触发执行、线程池承接并发、前端展示进度的轻量多 agent 编排系统。

初步分析已经探明它具备如下的一些能力：

• 主 agent 可以按照任务的复杂程度决定是否拆分子任务
• 子任务可以并行执行
• 子任务具有独立的上下文

存在如下的一些边界：

• 单层委派，lead agent 委派任务，并生成 subagent 后，不支持 subagent 再次委派新的 subagent
• 内建的 agent较少，目前仅有 general-purpose 和 bash 两类
• 多个 subagent 公用一个 workspace
• 任务的交接结果主要是文本，强依赖于模型解释

架构图

flowchart TD
    A[User / API / IM Channel]

    subgraph G1[Gateway / Run 启动层]
        direction TB
        B[start_run]
        C[Runtime Config 注入<br/>subagent_enabled / max_concurrent_subagents]
    end

    subgraph G2[Lead Agent 编排层]
        direction TB
        D[make_lead_agent]
        E[lead_agent Prompt]
        F{是否拆分为子任务}
        G[主 agent 直接调用普通工具]
        H[task 工具]
        V[lead_agent 汇总结果]
    end

    subgraph G3[Subagent Runtime 执行层]
        direction TB
        I[校验 subagent_type<br/>继承 sandbox / thread_id / model]
        J[SubagentExecutor]
        K[_background_tasks 状态表]
        L[_scheduler_pool]
        M[_execution_pool]
        N[Subagent Agent]
        O[Sandbox / Files / MCP / Tools]
        P[stream_mode=values]
        Q[后端轮询状态]
        U[Tool Result 返回 lead_agent]
    end

    subgraph G4[Streaming / UI 展示层]
        direction TB
        R[task_running / task_completed 事件]
        S[Runtime custom stream / SSE]
        T[Frontend Subtask UI]
    end

    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    F -- 否 --> G
    F -- 是 --> H

    H --> I
    I --> J
    J --> K
    J --> L
    L --> M
    M --> N

    N --> O
    N --> P
    P --> K

    H --> Q
    K --> Q
    Q --> R
    R --> S
    S --> T

    Q --> U
    U --> V

    style G1 fill:#EAF3FF,stroke:#4A90E2,stroke-width:1.5px,color:#123
    style G2 fill:#EAFBF1,stroke:#2F9E44,stroke-width:1.5px,color:#123
    style G3 fill:#FFF6E8,stroke:#F08C00,stroke-width:1.5px,color:#123
    style G4 fill:#F6EEFF,stroke:#7B61FF,stroke-width:1.5px,color:#123

    classDef entry fill:#DCEBFF,stroke:#4A90E2,color:#123
    classDef orchestrator fill:#DFF5E8,stroke:#2F9E44,color:#123
    classDef runtime fill:#FFF1D6,stroke:#F08C00,color:#123
    classDef stream fill:#EFE3FF,stroke:#7B61FF,color:#123
    classDef decision fill:#FFE3E3,stroke:#E03131,color:#123

    class A,B,C entry
    class D,E,G,H,V orchestrator
    class I,J,K,L,M,N,O,P,Q,U runtime
    class R,S,T stream
    class F decision

注解：

从运行的链路，subagent 的调度大致可以分为四层：

1. 配置层（蓝色） 构建 lead agent，配置调度 subagent 参数，包括是否允许 subagent 以及并发参数设置。
2. 决策层（绿色） 由 lead agent 根据 prompt 判断是否拆解任务、拆解几个任务、是否需要分批执行
3. 执行层（黄色） 由 task 工具创建 subagent 执行器，放入后台线程池异步运行
4. 展示层（紫色） 展示子任务卡片和状态更新

这四层对应的关键代码位置：

• lead agent 构建与 subagent 开关
  backend/packages/harness/deerflow/agents/lead_agent/agent.py

• 子任务拆解 prompt 规则
  backend/packages/harness/deerflow/agents/lead_agent/prompt.py

• subagent 工具入口
  backend/packages/harness/deerflow/tools/builtins/task_tool.py

• subagent 执行器
  backend/packages/harness/deerflow/subagents/executor.py

• 前端任务状态展示
  frontend/src/core/threads/hooks.ts frontend/src/components/workspace/messages/message-list.tsx

subagent 运行机制

subagent