Hotdry.
归档
ai-systems

Deer-Flow 子代理切换协议：状态序列化、上下文传递与故障恢复实现

在 DeerFlow 中实现子代理手off协议，包括状态 JSON 序列化、隔离上下文传递及故障自动切换的工程参数与监控要点。

在 DeerFlow 的多代理架构中，子代理（subagents）协调是处理多小时自主编码或研究任务的核心挑战。领导代理（planner）动态生成工作者代理（workers，如 researcher、coder），这些代理并行执行子任务，并将结构化结果回传合成最终输出。为确保长时任务的可靠性和连续性，必须设计 robust 的手 off 协议，包括状态序列化、上下文传递与故障恢复。本文聚焦单一技术点：基于 LangGraph 的状态管理，实现工程化参数配置，使系统支持小时级任务而不丢失上下文或陷入死循环。

状态序列化的核心设计

DeerFlow 的状态（state）是一个可序列化的 Pydantic 模型或 Python dict，包含当前计划步骤（current_plan_step）、证据集（evidence）、笔记（notes）、消息历史（messages）和控制元数据（如循环计数、停止条件）。每个图节点（node）是纯函数：接收 state_in，输出 state_out，实现 handoff 时直接传递序列化状态。

“DeerFlow 使用分层多代理 'planner → workers → reporter' 图，通过明确的状态对象在图节点间传递手 off。” 此设计避免了 ad-hoc 提示复制，确保确定性和可审计性。

工程实现时，序列化采用 JSON-safe 结构，每步前自动持久化到沙箱文件系统（/mnt/user-data/workspace/state.json）。关键参数：

  • 序列化阈值：当状态 tokens > 80% 模型上限（e.g., GPT-4o 的 128k 时设 100k）时，触发 summarization。将 evidence 压缩为 top-5 关键事实，每事实 ≤200 tokens。
  • Checkpoint 频率：每 5 个节点或 10min 序列化一次，支持 resume。使用版本号（state_version: uuid）防覆盖。
  • 安全清单：
    参数 值 说明
    max_state_size 500KB JSON 文件上限，超则 prune
    serialization_format JSON (strict) 禁用 pickle 防注入
    backup_count 10 滚动备份 state-vN.json

落地代码片段（LangGraph 集成）：

from pydantic import BaseModel
class DeerState(BaseModel):
    plan: list[dict]
    evidence: list[dict]
    # ...

@app.post("/handoff")
def handoff(state: DeerState):
    serialized = state.model_dump_json()
    with open(f"checkpoints/{uuid}.json", "w") as f:
        f.write(serialized)
    return serialized

上下文传递协议

子代理上下文隔离是 DeerFlow 的关键特性：每个工作者仅看到任务专属视图，避免主代理上下文干扰。传递协议分三步：投影（projection）、提示构建、写回（write-back）。

  1. 状态投影函数：全局状态 → 角色特定输入。

    • Researcher：{query, prior_findings[:3], tools}
    • Coder：{spec, codebase_snippets, test_cases} 示例：local_state = project_state(global_state, role="researcher") 过滤无关字段，tokens 控制在 20k 内。

  2. 提示模板标准化：system + instructions + state_summary + recent_messages。模板参数：

    模板键 长度限 作用
    state_summary 2k tokens LLM 自动摘要
    handover_note 500 chars 前代理结束语

  3. 结构化写回：子代理输出必须填充固定字段，如 state.evidence.append({"source": "web", "content": "...", "confidence": 0.8})。使用工具调用强制结构化。

参数配置：

  • 投影阈值：prior_evidence > 10 项时，LLM rerank 选 top-5 (score> 0.7)。
  • 传递超时：30s 无输出则 fallback 到 summary handoff。

此协议确保多小时任务中，代理间信息流高效：planner 分解任务 → workers 并行 → reporter 合成。

故障恢复与自动切换

长任务常见故障：模型幻觉、API 超时、沙箱崩溃。为此，handoff 协议集成 retry 逻辑与代理切换。

  1. Idempotent 节点：节点支持相同输入重跑，依赖状态哈希（hash (state_in)）跳过已完成步骤。

  2. Retry 策略：

    故障类型 重试次数 Backoff 切换阈值
    Token 超限 3 1.5x 2 次后 handoff 到 summarizer
    API 错误 5 exp(1min) 3 次后换模型 (gpt-4o-mini)
    沙箱失败 2 5min 直接 handoff 到备用代理

  3. Handoff on Failure：检测 error_flag 时，planner 评估：若 confidence < 0.5，spawn 新 subagent 并传递恢复状态（resume_from: checkpoint_uuid）。

监控要点：

  • Prometheus 指标：handoff_latency (p95 < 2min)、retry_rate (<5%)、state_size_growth (日增长 <20%)。
  • 回滚策略：任务总时 > 4h 或失败率 >10%，fallback 到单代理模式。
  • 告警清单：state_corruption (JSON parse fail)、context_drift (summary similarity <0.8)。

部署与测试清单

  1. 配置 config.yaml：sandbox.use: docker, models: 多模型 fallback。
  2. 单元测试：mock_state handoff 循环 100 次，验证不漂移。
  3. 负载测试：模拟 2h 编码任务，测量恢复时间 <1min。
  4. 生产参数：max_subagents=20, global_timeout=6h。

通过以上协议，DeerFlow 可可靠协调子代理完成自主多小时任务，如从需求到完整代码库的构建。实际部署中，结合 long-term memory，进一步提升跨会话连续性。

资料来源：

查看归档