多Agent Harness实现实战：Lead、Worker与Spawn详解

对照项目 Agentium 的背景：Agentium 论文与开源项目介绍。本文图表及核心设计均来自开源项目 Agentium，源码详见 GitHub。

若你正着手将 Deep Research 产品化，不妨深入 Agentium 看看这条研究链路如何落地为可运营的 Job——请求如何进入、分支如何受预算约束、Steer 如何被消耗、Milestone 如何验收。一套能跑通的闭环，远比堆砌概念更有价值。

Agentium 借鉴了 DeerFlow、GPT Researcher、Anthropic 等 Orchestrator–Worker 体系的整体架构，在工程实现上补齐了 SpawnBudget 硬闸、全阶段 Steer 审计、租户隔离的 Job Store 和 Milestone CI。建议先厘清 v1 / v2 / Workflow / Agentic 四条线的边界，再深入 v2 全链路。

先把链路跑活

接入业务时，首要任务是将主干请求跑通。开启 AGENTIUM_RESEARCH_V2_ENABLED=1，通过 Chat 分流（POST /v1/chat/messages + orchestration_mode=research）或控制面直调（POST /v1/research/v2/jobs）创建任务。获取 job_id 后，通过 GET /v1/research/v2/jobs/{id}/events 查看事件流，在 GET /v1/research/v2/jobs/{id} 中读取 payload.report 和 payload.graph，复盘时再拉取 .../trajectory。只有链路跑顺了，后面的 DyTopo、HITL、Milestone 才有意义。

一个最小的 v2 创建 Payload 通常如下：

 复制代码{
    "query": "请检索并对比近几年 ACL 系列会议与 arXiv 的 multi-agent research 代表论文：列出方法、评测基准、代码可用性与局限，并总结可用于企业 Deep Research Harness 的设计要点。",
    "request_id": "req-001",
    "trace_id": "trace-001",
    "max_workers": 3,
    "max_depth": 3,
    "spawn_mode": "parallel"
}

Payload 如上示意，用于建立可观测主干：任务是否创建、Spawn 是否发生、合成是否完成、失败卡在哪个阶段。盯住这些指标，后续才能做精细化运营。

先把几条线分清

Agentium 中的“研究”并非单一实现，下面四个概念各管一层，切忌混为一谈：

入口方面，POST /v1/chat/messages + orchestration_mode=research 返回 202（dispatch: research_job）；POST /v1/research/v2/jobs 控制面直调返回 200；POST /v1/research/run 仍走 v1 DAG。三条入口职责不同，旧版并未废弃。

注意：v2 总开关 AGENTIUM_RESEARCH_V2_ENABLED 默认关闭（0）。未开启时 v2 路由不可用或无法入队；回滚至 0，v1 依然可用。不要硬编码全站只认 v2。

至于 Agentic + Autonomous，是指单会话内模型自主调用工具；Research Harness 是后台 Job、图 SSE、Steer 队列；Workflow 是固定 DAG。三者入口与可观测面不同，混用将导致排障极其痛苦。

举一个最容易混淆的例子：同样是“ACL + arXiv 对比”这条请求，走 Chat research 会先拿到 job_id 再观察事件流；走 research/run 会直接拿到 Workflow 快照；走普通 agentic 则是会话内流式回复。入口不同，后续的调试面板也完全不同。

v1 管线与 v2 Harness：双轨、取舍

仓库中 v1 与 v2 双轨并存。v1 阶段固定、Artifact 血缘清晰；v2 是 Lead 带 Worker 的多路检索树，壳层附加预算、审计、Milestone。

v1 适用于需要与 Workflow 统一 Artifact、要求 DAG 确定性、未开启 v2 或刻意保持五段流水线的场景。代价是缺少图事件、运营 Steer、跨 Job Recall、Milestone 与 v2 不对齐；默认 Stub 下 Critique 几乎不拦截错误。

v2 适用于多分支研究图、Deep Research 工作台、Steer/HITL、Milestone 回归、跨任务 Recall。代价是开关与配置更多，DyTopo 和 Critique 仍是轻量启发式加预算闸，Live Milestone 不能与 CI Stub 等同。

v1 的 DAG 参考了 Anthropic《Building Effective Agents》中的 Workflow-first 思路；v2 则参考了《Multi-Agent Research System》中的 Orchestrator–Worker 思路。

下面用同一条 Query 走两条路径，对照阶段名与图上节点。示例中的 ID、时间戳仅供示意，实际值以 Job 回包为准。

示例 A：v1 五段 DAG

入口有两种：POST /v1/research/run 直调，或 Chat 中 orchestration_mode=workflow（同一管线，返回 202 和 workflow_snapshot）。无需开启 AGENTIUM_RESEARCH_V2_ENABLED。

请求体示意：

 复制代码{
    "query": "请检索并对比近几年 ACL 系列会议与 arXiv 的 multi-agent research 代表论文：列出方法、评测基准、代码可用性与局限，并总结可用于企业 Deep Research Harness 的设计要点。",
    "request_id": "req-v1-001",
    "trace_id": "trace-v1-001"
}

编排是固定的五段，没有 Lead 随时 Spawn 的树；并行主要发生在 search 阶段（由注入的 research.search handler 决定 Fan-out），其余按 DAG 顺序执行。

v1 没有显式子 Agent：plan 产出子任务清单，search 并行执行。这条 Query 可以拆成四步：

• 先拉取 ACL/EMNLP/NAACL 的代表论文，获取方法、任务、年份等基础字段；
• 再补充 arXiv 的新近工作，避免只依赖会议信号导致“时间滞后”；
• 单独整理评测基准和代码可用性，防止将“有结果”与“可复现”混为一谈；
• 最后在 synthesize + critique 合并，形成对比结论和企业可落地建议。

这条链路中没有 b1/b2 这类显式分支 ID。若要验证“子任务是否跑到”，通常查看两处：plan 产物中是否将任务拆解出来，以及 search 阶段 Artifact 是否覆盖了这些拆分项。

单次 pipe.run() 内，逻辑顺序大致如下：

与 v2 的主要差别在可观测面：v1 没有 job_id 和图 SSE，依赖 Workflow 快照与 ArtifactStore；运行中也没有 Steer 插队，纠偏只能改 Query 重跑或换 v2；分解在 plan 一次定稿，不会像 v2 那样 DyTopo、Critique 再补 Spawn。

workflow_run 或 research/run 成功时，响应中先看：

 复制代码{
    "success": true,
    "dispatch": "workflow_run",
    "run_id": "workflow_run:session-abc:req-v1-001",
    "workflow_snapshot": {
      "nodes": [
        { "id": "plan", "status": "completed" },
        { "id": "search", "status": "completed" },
        { "id": "synthesize", "status": "completed" },
        { "id": "critique", "status": "completed" },
        { "id": "report", "status": "completed" }
      ]
    }
}

排障时顺着五个节点状态和各阶段 Artifact 查看，不必寻找 node_added。

示例 B：v2 Lead–Worker Harness

入口：POST /v1/chat/messages + orchestration_mode=research（返回 202，dispatch: research_job），或 POST /v1/research/v2/jobs（返回 200）。需 AGENTIUM_RESEARCH_V2_ENABLED=1。

创建 Job 示意：

 复制代码{
    "query": "请检索并对比近几年 ACL 系列会议与 arXiv 的 multi-agent research 代表论文：列出方法、评测基准、代码可用性与局限，并总结可用于企业 Deep Research Harness 的设计要点。",
    "request_id": "req-v2-001",
    "trace_id": "trace-v2-001",
    "max_workers": 3,
    "max_depth": 3,
    "spawn_mode": "parallel"
}

Lead 分解 → Spawn Worker → 可选 DyTopo 加深 → Critique 补 Spawn → 合成；事件写入 ResearchGraphEventBus，图上节点逐步生长。

Lead 按主题 Spawn 分支，Worker 各自检索。分支分工如下：

• b1：汇总 ACL/EMNLP/NAACL 代表论文，建立会议线索；
• b2：补充 arXiv 增量工作，覆盖最新变化；
• b3：整理 Benchmark 与代码可用性，单独评估可复现性；
• b4：DyTopo Follow-up 分支，补齐分支检索后的证据缺口；
• c1：Critique Follow-up 分支，在合成前按 Issues 定向补充证据。

对应的检索意图是：b1 偏向“会议脉络与代表方法”，b2 偏向“最新演化与新问题”，b3 偏向“指标与代码落地”，b4/c1 偏向“发现缺口后回补证据”。

如果你发现“该补的分支没补出来”，通常先检查三件事：SpawnBudget 是否已满（max_spawn_total / max_depth）、max_dynamic_followups 与 critique_max_followups 是否过低，以及事件流中是否出现了 steer_consumed、DyTopo.route、critique 这三类信号。

异步 Job 可边拉事件边观察，时间线示意：

订阅 GET /v1/research/v2/jobs/{id}/events，事件流片段示意：

 复制代码{"type": "node_added", "node_id": "b2", "parent": "root", "label": "arXiv 候选"}
{"type": "console_line", "text": "Worker(b2).arxiv_q=multi-agent research arxiv latest"}
{"type": "node_status", "node_id": "b2", "status": "completed"}
{"type": "node_added", "node_id": "c1", "parent": "critique", "label": "citation follow-up"}
{"type": "metrics_snapshot", "spawn_used": 5, "spawn_budget_max": 8}

v2 独有的一步是 Steer 插队。假设 T3 时发现 ACL 2024 关键论文漏检，调用 POST /v1/research/v2/jobs/{id}/steer：

 复制代码{ "message": "补查 ACL 2024 多智能体研究及其开源代码可复现性" }

Lead 在 poll_steer 窗口消费后，可能 Spawn 出 steer1 分支。审计中应包含 steer_consumed 与 spawn_node_id，不能只有 Steer 入队记录。新证据先进入整合再合成，而非修改最终报告的 Prompt。

并排总览

既要 Artifact 血缘简单又要图上 Steer，常见做法是简单场景走 v1 直调、工作台用 v2。v2 开关打开也不会自动替换所有 research/run 调用方。

一条请求在服务端到底发生了什么

v2（时间线）

将 v2 请求按时间线展开，动作并不复杂。入口先按 orchestration_mode 分流，Research 请求交给 ResearchJobV2Service；服务写入 Job 记录并挂上预算参数、可选 Recall 参数。resolve_spawn_budget 算出本次任务的硬闸后，ResearchLeadLoop.run() 开始分解、Spawn、动态加深、Critique、合成，图事件持续写入 ResearchGraphEventBus。结束后再将 report、graph、可选 mind_map、evidence_tree 回写至 Job Payload，并通过 export_trajectory 与审计事件完成对账。

v1（对照时间线）

v1 路径更短：一次 DeepResearchPipeline.run() 在进程内跑完五段，没有独立 Job 事件总线。

v1 没有 GET .../events；在响应中获取 workflow_snapshot，或事后按 run_id 查询 Artifact 链。Chat workflow 与 research/run 走同一条管线，差异仅在鉴权与会话绑定。

两段流程的价值在于边界清晰：入口、编排、检索、存储、事件各管一块，排障时可以顺着链路走，不必在一个巨型函数中猜测状态。

研究图是怎么长出来的

这一节聚焦入口与 Recall。

用户携带 orchestration_mode=research（或直调 v2 Jobs API）提交后，控制面不进入 Chat SSE——长时间 Spawn、重试、动态 Follow-up 不适合用一轮对话的 Token 流承载。服务端创建 v2 Job（job_id、run_id、Phase 如 lead_loop），挂接按 Job 隔离的 EventBus。工作台订阅 node_added、node_status、console_line、metrics_snapshot，看到的是 root → branch → follow-up / critique → synthesize，而不是最后一次性吐出长文本。

可选 previous_job_id 与 recall_artifact_ids 在 Lead 入口拼接 Recall 前缀（AgentRxiv 风格）：上一轮报告摘要、制品片段、S6 黑板笔记压入 Query。租户不一致时 build_recall_prefix 整段清空，recall_artifact_ids 也会跳过非本租户制品，不能跨租户接着上次挖掘。

分解：STORM 多视角 + 可选 LLM + 质量门禁

Lead 第一拍 research_think 走 decompose_query：默认采用 STORM 多视角分支（methods / evaluation / applications …），避免永远只有三条固定话术；当 llm_decompose_enabled 时，可走进程级 Hook，失败则回退至确定性分支。

gate_decompose_branches 检查分支数量、多样性、是否仍为 Legacy 固定三联；结果写入 last_decompose_gate，图上标注 Lead.decompose_gate_failed。门禁失败不会 Cancel Job，仍是观测型：日志中能发现分解质量可疑，Lead 仍用已有 Branches 往下 Spawn。运维查看 Console 或报告中的 quality_gates.decompose，Gate 红了不等于停跑。

用本文的论文检索例子来看就很清楚：同一个 Query 不会只拆成“找论文”这一条，而会至少拆出“ACL 系列代表作”“arXiv 增量工作”“评测与代码可用性”三路。如果拆出来三路几乎是同义改写（比如都在重复“找最新论文”），Decompose Gate 会提示多样性不足，提醒你先调整分解策略，再看后面的检索质量。

Worker：分支检索、缺口与来源校验

Worker 不再拆分子问题；拆题、Spawn、合成都在 Lead 完成。ResearchWorkerRunner 只执行一条 SpawnRequest：按标签推断 arXiv / Web，构造查询，调用搜索与 Fetch，产出 WorkerResult（topic、contribution、citations、gaps、confidence）。如需多层展开，依赖 Lead 的 DyTopo Follow-up 或 Critique 补 Spawn。

gaps（例如 no_retrievable_sources）驱动加深与 Critique Follow-up。source_validate_enabled 开启时，低质量 Citation 可被过滤并附带 quality_score。控制台 Worker(bN).arxiv_q=… Hook 保留，排障时查看实际检索词。

Spawn 执行：并行 / 顺序 / 混合 + 预算

首批分支由 execute_spawn_requests 按 spawn_mode 执行：

SpawnBudget 对一切 Spawn 硬顶 max_spawn_total、max_depth。初始分支、Steer 插队、DyTopo、Critique 补 Spawn 共用同一账本；Dynamic Follow-up 在 can_spawn 处 Break，不会无限延伸。

每次 Spawn 前经过 EmergenceGuardrails（research.spawn）。poll_steer 有队列消息时可即时 Spawn Steer 分支，记入 steer_events（phase、consumed_at、spawn_node_id）。

可以用一组固定参数感受差异：max_workers=3, max_spawn_total=8, max_depth=3。Parallel 会先并行跑 3 条；Sequential 是一条跑完再下一条；Hybrid 会一批并行、一批带上下文继续。无论哪种模式，只要累计 Spawn 达到 8，就会停止继续补分支。

配置建议：先稳，再快

灰度起步可以保守一些：AGENTIUM_RESEARCH_V2_ENABLED 先在开发或灰度环境开启，AGENTIUM_RESEARCH_V2_SPAWN_MODE 使用 parallel，max_workers 从 2～4 起步，max_depth 先设为 2～3；AGENTIUM_RESEARCH_DYNAMIC_ROUTING 默认开启，critique_max_followups 先设 1 或 2，human_feedback_mode 从 minimal 开始。

并行、动态加深、Critique 一起拉满时，预算撞墙、检索不足、审批拖住任务会叠在一起，很难分清。先把失败路径跑顺，再逐项加量。

DyTopo 与 Critique：不是第二个 Lead，也不是辩论 Agent

分支完成后，若 dynamic_routing_enabled，仍然是同一个 LeadLoop 做轻量路由：从各 WorkerResult 抽取 Need/Offer，用 Token 重叠画语义边（DyTopo.route），再通过 plan_dynamic_spawn_chain 在 max_dynamic_hops × max_dynamic_followups 内 Spawn Follow-up。不会另起一个编排 Agent；实现上是词重叠路由，正文不展开算法。

合成前是单轮确定性 Critique（run_deterministic_critique）：检查 Integrated 中是否有 Facts、Gaps/Conflicts、分支是否跑完，没有第二个 LLM 互辩。Issues 经 plan_critique_followups 转为补 Spawn（受 critique_max_followups 与 SpawnBudget 限制），图上出现 Critique 节点。

可选 _maybe_run_code_experiment 在 SafetySandbox 下运行受控实验节点，失败记为分支 Failed。

DyTopo 补充的是“缺失的那块证据”；Critique 是合成前清单复核，缺口大时再补一两个定向分支，避免扩成无限递归辩论。

Steer 与人机检查点

ResearchJobV2Service.steer 将纠偏文案入队（Job 须为 running / cancelling）。Steer 会修改检索路径，不只修改报告措辞：poll_steer 在 Spawn 中可插队新分支；post_spawn、pre_synthesize、pre_critique 等阶段也会调用 _consume_phase_steer。新证据先进 integrate_evidence，再影响合成。

human_feedback_mode（minimal / each_phase / each_critique）可在 Decompose、Synthesize、Critique 前走 ApprovalGate。未注入 ApprovalService 时检查点标注 hitl_service_unavailable。

同一句 Steer 在不同阶段效果不同：Spawn 阶段更像新增并行检索；Pre_Synthesize 像合成前补证据；Pre_Critique 像先补齐再复核。

收束：整合证据、导图与制品

synthesize_report 先执行 integrate_branch_evidence，再合成 Summary、report_markdown、citations（带 citation_indices）。gate_synthesis_report 可检查摘要长度与引用是否达标。

报告 Payload 还可包含 mind_map、evidence_tree（长报告按 evidence_tree_min_tokens 折叠）、Critique 元数据。大段分支正文经 maybe_offload_branch_text 存入 ArtifactStore。任务完成时返回 report + graph 快照；支持 export_trajectory 导出脱敏轨迹。摘要供快速阅读，Citations 供对账，Mind_map / Evidence_tree 供结构化复盘。

共享黑板、Skills 与系统评测

S6 黑板（SharedWorkspaceMemory）是多分支 Worker 共用的带租约共享白板，在同一研究任务中共享进度、Handoff 摘要和待补证据。Claim / Post / Read 与 Recall 前缀配合，适用于进程内 Harness；跨 Pod 不是自动分布式，跨实例恢复需配合 Checkpoint / Handoff。无租约 Post 会被拒绝。

skills/deep-research 提供 Prompt 与模板边界；运行时以 Lead/Worker 代码路径为准。

Milestone 脚本 run_research_milestone_eval.py 三档语义不同：Stub 使用假 Worker、不打网；Golden 读取 Fixture；Live 真检索。CI 默认 Stub Gate（如 milestone_pass_rate ≥ 0.8），Stub 绿了不能等同 Live 达标。对外宣称生产检索质量，须显式跑 Live 并查看 Spawn 效率、引用覆盖、耗时等 KPI。

线上排障，别先怪模型

线上不要一看到最终报告不好就骂模型。顺着 Harness 倒推：入口是不是 Research Job、Events 是否在增长、预算是否撞墙、Decompose Gate 与 Critique Issues、Steer 是否有 steer_consumed、Live 评测是否支撑质量判断。

按这个顺序，5 分钟内通常能定位大头：Events 是否还在增长、预算是否打满、分解/Critique 信号是否正常，最后才看 Prompt。先确认壳层可控，再动策略；否则改 Prompt 重跑，可能只是预算早已打满。

与外部深研产品的差异（一句）

业界常见的规划 → 多路检索 → 报告，Agentium 同样参考；差异在于 SpawnBudget、全阶段 Steer 审计、租户 Job Store、Milestone CI 是否写进运行时，而不是多堆 Agent 角色名。

几个高频误区

最常见的坑在接入层：把 Research 当作 Chat SSE 来接入，而不是消费 Job 事件 API；把分解 Gate 当作阻断器，看到红灯就以为任务会停。还有预算判断：以为 Dynamic Follow-up 会一直加深，但 max_spawn_total 和 max_depth 会先把路堵住。

另两类误判也很常见：Steer 只看到入队、没核对 steer_consumed；Stub Milestone 一绿就当 Live 达标。再加上忘了开 v2 开关就认定功能坏了，最后看起来像模型问题，其实是链路理解没对齐。

收束一下，下一篇讲什么

v2 Harness 将 STORM/LLM 分解、观测型门禁、Spawn 模式、Worker 检索、DyTopo、Critique 补 Spawn、Steer/HITL、证据整合与 Mind_Map 收进 ResearchJobV2Service，与 orchestration_mode=research 对齐；与 v1 五段 DAG 双轨并存，按场景选型。入口与 Workflow、Agentic 三分法一并记住，少混线。

下一篇进入资源 Admin：MCP、Skill、Persona 的登记、Probe 与 WorkspaceAgentConfig 绑定。