DeerFlow 子Agent委派实现说明

May 22, 2026

概述

DeerFlow的子Agent系统是基于LangGraph构建的任务委派机制，允许主Agent将复杂任务委托给专门的子Agent执行，实现上下文隔离、并行处理和专业化分工。

核心组件

组件	位置	职责
执行引擎	`packages/harness/deerflow/subagents/executor.py`	子Agent同步/异步执行、线程池管理、任务状态跟踪、超时控制
注册中心	`packages/harness/deerflow/subagents/registry.py`	管理可用子Agent配置，支持config.yaml配置覆盖
工具入口	`packages/harness/deerflow/tools/builtins/task_tool.py`	对外暴露`task`工具，是父Agent调用子Agent的统一入口
内置子Agent	`packages/harness/deerflow/subagents/builtins/`	提供两种开箱即用的子Agent类型：`general-purpose`（通用型）、`bash`（命令行专家）
限流中间件	`packages/harness/deerflow/agents/middlewares/subagent_limit_middleware.py`	强制限制最大并发子Agent数为3，避免资源耗尽

完整委派流程

1. 触发阶段：父Agent调用`task`工具

当父Agent需要委派任务时，调用task工具，传入参数：

description: 3-5字的任务简短描述（用于日志和前端展示）
prompt: 给子Agent的详细任务指令，需要具体明确
subagent_type: 子Agent类型（general-purpose或bash）
可选max_turns: 子Agent最大交互轮次，覆盖默认配置

2. 配置加载阶段

从注册中心获取对应类型的子Agent默认配置
应用config.yaml中的自定义配置（如超时时间覆盖）
注入当前已启用的技能提示到子Agent的系统提示词
若指定了max_turns，覆盖默认配置值

3. 上下文继承阶段

子Agent自动继承父Agent的运行上下文，保持环境一致性：

沙箱状态（sandbox_state）：保持文件系统访问权限和路径映射一致
线程数据（thread_data）：共享线程级别的配置和状态
线程ID（thread_id）：关联到同一个会话线程
模型配置（parent_model）：可配置继承父Agent使用的LLM模型
追踪ID（trace_id）：统一分布式追踪ID，关联父子Agent的日志

4. 工具集过滤阶段

子Agent的工具集通过get_available_tools()获取，但强制关闭子Agent功能（subagent_enabled=False），防止递归嵌套调用
根据子Agent配置的工具白名单/黑名单进一步过滤可用工具
- general-purpose：拥有除task外的所有工具权限
- bash：仅拥有命令执行相关工具权限

5. 执行阶段

创建SubagentExecutor执行器实例
任务提交到双层线程池异步执行：
- _scheduler_pool（3 worker）：负责任务调度、状态管理、超时控制
- _execution_pool（3 worker）：负责实际的子Agent逻辑执行
子Agent创建独立的LangChain Agent实例，使用对应类型的专用系统提示词，运行在隔离上下文
以stream模式执行，实时收集AI生成的所有中间消息，用于后续调试和审计
父Agent调用task工具后会通过5秒间隔轮询等待子Agent执行完成（对当前会话是同步阻塞的），但子Agent运行在独立线程池，不会阻塞其他会话的Agent执行

6. 状态反馈阶段

执行过程中通过SSE流实时推送事件到前端：

task_started：任务开始执行
task_running：执行中，包含子Agent的中间输出消息（1-based索引）
task_completed：任务成功完成，返回最终结果
task_failed：任务执行失败，返回错误信息
task_timed_out：任务执行超时

7. 结果返回阶段

子Agent执行完成后，将最终结果返回给父Agent，父Agent可以基于这个结果继续后续处理，完成后自动清理后台任务记录，避免内存泄漏。

关键特性与保护机制

1. 强隔离设计

子Agent运行在独立的线程和执行上下文，不会污染父Agent的状态
工具集独立配置，权限按需分配

2. 防止递归

子Agent默认没有task工具权限，无法嵌套调用其他子Agent，避免无限递归

3. 双层超时保护

线程池层面的执行超时：可配置，默认15分钟
轮询层面的超时保护：超时时间+60s缓冲，作为兜底机制防止任务卡死

4. 并发控制

最大并发子Agent数为3，由SubagentLimitMiddleware中间件自动拦截超过限制的工具调用

5. 可扩展性

支持通过配置文件自定义子Agent超时时间
注册中心设计支持扩展更多内置子Agent类型

内置子Agent说明

类型	适用场景	工具权限
`general-purpose`	复杂多步骤任务、探索性研究、需要多种工具配合的工作	除`task`外的所有工具
`bash`	Git操作、构建流程、批量命令执行、大量命令输出的场景	仅命令行相关工具

配置说明

在config.yaml中可以配置子Agent的超时时间：

subagents:
  enabled: true
  timeouts:
    general-purpose: 900  # 15分钟
    bash: 300  # 5分钟