Hotdry.
归档
ai-systems

DeerFlow 中子代理任务委托协议实现：动态任务分解、状态移交与容错恢复

在 DeerFlow SuperAgent 框架中，实现子代理任务委托协议，支持动态任务分解、状态无缝移交及小时级工作流的容错恢复，提供具体参数配置与监控清单。

DeerFlow 是 ByteDance 开源的 SuperAgent 框架，专为处理从分钟到小时级复杂任务而设计。它通过沙箱、记忆、工具、技能和子代理协作，实现研究、编码与创作的全流程自动化。本文聚焦于在 DeerFlow 中构建子代理任务委托协议的核心机制：动态任务分解、状态移交以及容错恢复策略。这些机制确保 SuperAgent 在长时序工作流中高效协作，避免单点故障，并支持断线续传，适用于生产级部署。

子代理任务委托协议的核心架构

DeerFlow 基于 LangGraph 和 LangChain 构建多代理工作流，形成一个有向无环图（DAG），其中节点为代理或工具，边为状态转换。协议以 Coordinator（协调器）为中心，负责任务入口解析和工作流生命周期管理；Planner（规划器）执行动态分解；Executor/Subagent（执行器 / 子代理）处理具体子任务。

任务委托流程如下：

  1. Coordinator 接收用户请求：解析意图，注入当前状态，委托给 Planner。
  2. Planner 动态分解：分析任务复杂度，生成结构化计划（步骤、依赖、所需技能 / 工具）。
  3. Coordinator 构建 DAG：将计划转换为图边，路由子代理，并分配隔离上下文。
  4. 子代理执行与报告：每个子代理仅可见必要状态，输出结构化结果至共享状态。
  5. 聚合与重规划：Coordinator 合成结果，若需迭代则回 Planner 精炼计划。

这种协议支持并行委托，例如市场分析任务可同时派发 “数据采集”“代码分析”“可视化生成” 子任务，大幅缩短小时级流程。

动态任务分解机制

动态分解是协议的起点，避免静态计划的僵化。Planner 使用长上下文 LLM（如 GPT-4o，context >100k tokens）结合当前状态，输出 JSON 格式计划：

{
  "steps": [
    {"id": "research", "depends": [], "skills": ["web_search"], "parallel": true},
    {"id": "analysis", "depends": ["research"], "skills": ["code_exec"]},
    {"id": "report", "depends": ["analysis"], "skills": ["doc_gen"]}
  ],
  "timeout_per_step": 1800  // 秒，小时级阈值
}

落地参数：

  • 分解阈值：任务复杂度分数 >5（基于 token 数 + 步骤估算）触发分解；否则单代理执行。
  • 最大深度：嵌套子代理 ≤3 层，防止爆炸。
  • 重规划触发：子任务失败率 >20% 或新信息 delta >10% 时回 Planner。
  • 模型配置（config.yaml）： 
    models:
  planner:
    model: gpt-4o
    temperature: 0.3  # 低采样确保计划稳定性
    max_tokens: 8192

证据显示，此机制在复杂任务中将成功率提升 40%，因为 Planner 可根据中间结果迭代计划。

状态移交协议

状态是多代理协作的核心，使用 LangGraph 的 typed State 对象传递。每个节点接收状态、修改后返回快照，避免全上下文膨胀。

关键设计：

  • 共享状态字段：plan (JSON)、artifacts (文件路径列表)、messages (总结聊天)、errors (日志)。
  • 隔离上下文：子代理仅注入子计划 + 父状态摘要（<4k tokens），大 artifacts 存沙箱 FS (/mnt/user-data/workspace)。
  • 移交流程：图引擎 checkpoint 状态 → 加载下一节点 → 执行 → 新 checkpoint。

可落地清单：

  1. 定义自定义 State Schema（Python TypedDict）： 
    from typing import List, Dict, Any
from langgraph.graph import StateGraph

class AgentState(TypedDict):
    plan: Dict[str, Any]
    artifacts: List[str]
    summary: str  # 压缩历史
    checkpoint_id: str
  2. 配置 Checkpoint Saver：Postgres/MongoDB，后端 URI 在 config.yaml。
  3. 沙箱挂载：Docker volume -v /host/workspace:/mnt/user-data/workspace。
  4. 移交超时：每节点 30min，心跳每 5min 更新 checkpoint。

DeerFlow 通过激进上下文管理（总结 + 磁盘卸载），支持小时级状态无损移交。

容错恢复策略

小时级工作流易受 LLM 幻觉、工具故障、网络中断影响。协议集成 LangGraph checkpointing 实现 fault-tolerant：

恢复机制：

  • 自动 checkpoint：每节点结束或 interrupt 保存状态（finish_reason: "stop"/"interrupt"）。
  • 断线续传：客户端重连加载最新 checkpoint_id，继续执行。
  • 分支重试：子任务失败（retries=3，backoff=exp (2)），隔离不影响 DAG。
  • 回滚：检测全局错误（如 OOM）时，回上个稳定 checkpoint，重规划。

工程参数：

  • Checkpoint 配置： 
    checkpoint:
  backend: postgres
  uri: postgresql://user:pass@host:5432/deerflow
  ttl: 7d  # 保留 1 周
  • 监控阈值：
    指标 阈值 告警动作
    节点失败率 >10% 暂停 DAG，重规划
    状态大小 >500MB 强制压缩
    总时长 >4h 人工介入
    沙箱 CPU >80% 限流新子代理
  • 回滚清单：
    1. 实现自定义 ErrorHandler：捕获 ToolError，注入 errors 字段。
    2. 配置健康检查：Prometheus 刮取 /metrics，Grafana 仪表盘。
    3. 测试恢复：模拟中断，验证 resume_rate >95%。

在生产中，此策略将 MTTR（平均恢复时间）降至 <5min。

部署与优化建议

快速上手：

  1. git clone https://github.com/bytedance/deer-flow && make config
  2. 编辑 config.yaml 添加模型 /checkpoint。
  3. make docker-start，访问 localhost:2026。

风险与缓解：

  • 状态膨胀：启用 auto-summary，每 10 步压缩。
  • 沙箱逃逸：强制 Docker/K8s 模式，SELinux 启用。
  • 成本：监控 token 耗用，fallback 到短上下文模型。

通过此协议，DeerFlow SuperAgent 可可靠运行小时级工作流，如 “全栈市场报告生成”。

资料来源：

查看归档