子 Agent

当一个任务对单个推理线程来说太宽泛，或者部分任务可以并行完成时，Lead Agent 将工作委派给子 Agent。子 Agent 是一个独立的 Agent 调用，接收特定任务、执行并返回结果。

为什么子 Agent 很重要

子 Agent 解决了长时序工作流中的两个关键问题：

1. 上下文隔离：子 Agent 只看到完成其任务所需的信息，而不是整个父对话。这保持了每个 Agent 的工作上下文专注且可控。
2. 并行性：多个子 Agent 可以并发运行，允许任务的独立部分（例如同时研究多个话题）并行处理。

内置子 Agent

DeerFlow 内置两个子 Agent：

general-purpose

通用推理和执行 Agent，适合委派需要多步骤推理、网络搜索、文件操作和产出物生成的复杂子任务。

• 默认超时：1800 秒（30 分钟）
• 默认最大轮次：150

bash

专门用于在沙箱内执行命令行任务的子 Agent，适合脚本编写、数据处理、文件转换和环境设置任务。

• 默认超时：1800 秒（30 分钟）
• 默认最大轮次：60
• 可用性：仅当沙箱的 bash 工具可用时才暴露（allow_host_bash: true 或配置了容器沙箱）

委派流程

Lead Agent 使用内置 task 工具将工作委派给子 Agent：

task(
  description="研究竞争对手",
  prompt="研究 Acme Corp 的前 5 个竞争对手并总结其 B2B SaaS 定价",
  subagent_type="general-purpose"
)

运行时然后：

1. 从注册表查找子 Agent 配置，应用任何 config.yaml 覆盖。
2. 用子 Agent 自己的提示词和工具创建新的 Agent 调用。
3. 将子 Agent 运行到完成——受 max_turns、timeout 以及镜像 Lead Agent 的中间件防护链（循环检测、token 预算、摘要压缩）共同约束。详见下方失控行为防护。
4. 将子 Agent 的最终输出作为工具结果返回给 Lead Agent。

配置

子 Agent 的超时、最大轮次以及单次运行的 token 预算通过 config.yaml 中的 subagents: 部分控制：

subagents:
  # 所有子 Agent 的默认超时（秒，默认：1800 = 30 分钟）
  timeout_seconds: 1800
 
  # 可选：覆盖所有子 Agent 的最大轮次。
  # 内置默认值：general-purpose=150、bash=60。留空则保持默认。
  # max_turns: 120
 
  # 单次运行的 token 上限——防止子 Agent 在琐碎任务上烧 token 的兜底。
  # 触达硬停止时，进行中的那轮会被截断（清空 tool calls，强制 finish_reason
  # 为 "stop"），使运行自然完成；结果会被标记为 completed +
  # subagent_stop_reason=token_capped，以便 Lead/UI 区分预算截断与正常完成（#3875）。
  token_budget:
    enabled: true
    max_tokens: 2000000 # 宽松的默认值——调低以收紧成本控制
    warn_threshold: 0.7 # 预算消耗达到此比例时记录一条 warning
 
  # 可选：按 Agent 覆盖
  agents:
    general-purpose:
      timeout_seconds: 1800 # 复杂任务 30 分钟
      max_turns: 160
      # token_budget:        # 对上面全局 token_budget 的按 Agent 覆盖
      #   max_tokens: 3000000
    bash:
      timeout_seconds: 300 # 快速命令 5 分钟
      max_turns: 80

按 Agent 覆盖优先于全局 timeout_seconds、max_turns 和 token_budget 设置。

设置页管理与 Custom Agent 调用范围

管理员可以在设置 → 子智能体中添加可复用的工作智能体。每个设置页管理的子智能体可以定义派遣说明、系统提示词、模型、工具、技能、最大轮次、超时和启用状态。内置项和 config.yaml 项也会显示在同一个目录中，但保持只读。

默认 Lead Agent 可以看到全部已启用的运行时子智能体。页面创建的每个 Custom Agent 可以在自身设置中进一步收窄调用范围：

• 全部已启用子智能体：不增加额外限制。
• 不允许使用子智能体：即使请求开启了委派，也不能重新打开。
• 仅允许选中的子智能体：提示词只展示所选名称，task 工具也只接受这些名称。

运行开始时，允许列表会作为快照写入 run metadata，task 工具会再次进行服务端校验，因此客户端不能通过直接填写隐藏名称绕过限制。运行时优先级为内置 → config.yaml → 设置页管理。如果运维之后在 config.yaml 中加入同名项，设置页管理的条目仍会保留并显示冲突提示，但会从运行时目录中排除。subagents.agents.<name> 的显式覆盖仍保持最高优先级，并会在设置目录中提示。

设置页管理的定义跟随 Custom Agent 现有的存储后端：agent_storage.backend: file 会在 DEER_FLOW_HOME/managed-subagents/ 下为每个定义写一个原子 JSON 文件；agent_storage.backend: db 会写入共享应用数据库，供多实例部署共同读取。当前版本是部署级全局数据，不按用户隔离。

委派限制

SubagentLimitMiddleware 控制 Lead Agent 在单次轮次中可以并行调用多少个子 Agent，也控制一次 Lead Agent run 内最多可以启动多少次子 Agent 委派。

• subagent_enabled：是否为此会话激活子 Agent 委派
• max_concurrent_subagents：单次轮次中最大并行任务调用数（默认：3）
• max_total_subagents：可选的每次请求总量上限；默认使用 config.yaml 中的 subagents.max_total_per_run（默认：6，有效范围：1-50）

如果 Agent 尝试调用超过限制的子 Agent，中间件会裁剪多余的调用。当总量上限耗尽时，它会停止本次 run 的新 task 调用，让 Agent 基于已收集结果进行综合。

失控行为防护

子 Agent 运行各自的 Agent 循环，因此需要和 Lead Agent 一样的失控兜底。子 Agent 中间件链镜像了 Lead Agent 的三个防护（#3875）：

• LoopDetectionMiddleware —— 打破子 Agent 不取得进展却反复调用同一工具的循环。子 Agent 不允许调用 task，因此这里只会触发工具循环启发式判定。硬停止会将结果标记为 completed + subagent_stop_reason=loop_capped，与下方 token 预算对称。由现有的 loop_detection 配置控制。
• TokenBudgetMiddleware —— 强制执行 subagents.token_budget 单次运行上限。预算触达时，进行中的那轮会被截断（强制产出最终答案），结果标记为 completed + subagent_stop_reason=token_capped，使 Lead Agent 能区分预算截断与正常完成。触达 max_turns 同样以 turn_capped 上报。
• SummarizationMiddleware —— 以和 Lead Agent 相同的方式压缩较长的子 Agent transcript，由同一个 summarization.enabled 开关控制，使一份配置同时覆盖两条链。

这些防护与 max_turns、timeout 限制叠加生效。token 预算的默认 max_tokens 与 summarization.enabled 联动——压缩开启时为 1M，关闭时为 2M；但显式设置的 subagents.token_budget.max_tokens（全局或按 Agent）始终优先，因此切换摘要开关绝不会悄悄改动你已固定的值。

ACP Agent（外部 Agent）

除内置子 Agent 外，DeerFlow 还通过 Agent Client Protocol (ACP) 支持委派给外部 Agent。ACP 允许 DeerFlow 调用作为独立进程运行的 Agent（包括用 ACP 适配器包装的第三方 CLI 工具）。

在 config.yaml 中配置 ACP Agent：

acp_agents:
  claude_code:
    command: npx
    args: ["-y", "@zed-industries/claude-agent-acp"]
    description: 用于实现、重构和调试的 Claude Code
    model: null
 
  codex:
    command: npx
    args: ["-y", "@zed-industries/codex-acp"]
    description: 用于仓库任务和代码生成的 Codex CLI
    model: null

Lead Agent 通过 invoke_acp_agent 内置工具调用 ACP Agent。