多 Agent 编排方案:依赖、调度与结果汇合
性质:方案初稿(已被取代);保留推导过程,不再作为方案或施工真源。 状态:⬜ 未施工;由 第一版方案:持久 Task 与固定 DAG 编排 取代。 日期:2026-11-09。 代码落点:—(未施工;预计涉及
yk-tako-eino/internal/runengine/、cmd/yktako/、web/与scripts/acceptance/)。 前置:持久 Task 方案。没有那里的独立 Task、执行 run、结果与通知,本篇没有可调度的对象。 调研来源:参照项目调研。 与 doc/16 的关系:给 #9“多 Agent 协作”补方案集,不把当前 🔶 状态翻成已落地。
1. 背景与失败故事
tako 已有主 Agent 委派子代理,但如果直接把“多 Agent”做成“允许主 Agent 多叫几个子代理”,会遇到一条断掉的业务链:
用户要综合报告 → 主 Agent 派 A、B 调研 → B 中途崩溃 → 主 Agent 只看到一次失败工具调用 → 用户再次追问时另起一场对话 → 已有 A 的结果和新 B 的结果散落在不同调用里 → 最后可能重新做 A,也可能在 B 缺失时直接写报告。
这里缺的不是更多角色,而是程序持有的三个事实:C 需要谁、A/B 各自做到哪、C 启动时读哪两份结果。 这些事实必须由数据库和调度程序维护,不靠模型记得。
2. 目标场景与完成线
第一期只承诺一种可验收形态:
用户目标:调研 A、B 并生成综合报告
→ 协调 Agent 创建 Task A、Task B、Task C
→ A、B 无父依赖,可并行;C 的 parents=[A,B]
→ 调度器分别启动 researcher 执行 A、B
→ A、B 把结构化摘要和报告文件路径写进各自 Task
→ A、B 都 succeeded 后,程序把 C 从 pending 改为 ready
→ 调度器启动 writer 执行 C;输入 = 原目标+A、B 的结果引用
→ C 的最终产物由协调 Agent 交付给用户
完成线不是“页面上出现三个 Agent”,而是:
- C 在 A、B 未成功时绝不执行;
- A、B 可以受并发上限控制地并行;
- C 确实读到两份结果,而不是凭主 Agent 印象编写;
- 一个执行者中断后,依赖不丢、结果不冒充成功、恢复不盲目重复副作用;
- 最终只有一份可检查的汇总产物。
3. 名词与对象
- 协调 Agent:理解用户目标、决定拆哪些 Task、选择执行者规格并负责最终交付。它不应亲自执行所有子工作。
- 执行 Agent:某件 Task 的实际执行者,使用独立 run、模型上下文、工具权限和项目围栏。
- 编排组
orchestration_id:同一用户目标产生的一组 Task 共有的查询与取消标识。它不是另一个 Agent,也不是另一份聊天历史。 - 依赖边:
parent_task_id → child_task_id,意思是父 Task 成功后子 Task 才具备执行资格。它是数据库记录,不是提示词里的一句“请先完成 A”。 - 调度器:程序组件。它读取 Task 与依赖,计算 ready,原子取得执行权,启动既有 run;不让模型自己决定“数据库里现在是否该 running”。
- 结果引用:下游 Task 可见的摘要、结构化元数据和文件路径。默认不传递上游全部聊天记录。
4. 状态机:在持久 Task 上增加依赖准入
Task 线的基础状态在本方案中细化为:
pending(仍有依赖未满足)
→ ready(依赖全部满足,等待执行容量)
→ running(已经取得执行权)
→ succeeded / failed / cancelled
pending / ready → blocked(父任务失败或取消,需要协调者改计划)
running+执行租约过期 → interrupted(读侧派生)→ 显式 resume → running
没有 parents 的 Task 创建后可直接成为 ready。blocked 不是模型随便写的解释文字,它必须带机器原因,例如 dependency_failed;协调 Agent 可以新建修正 Task 或取消整组,但不能把失败父任务当成成功输入。
每次状态转换都在 PG 事务中检查当前状态、当前执行 run 与执行代次。Redis/asynq 若用于叫醒,只携带 Task ID;丢失后由 PG 扫描对账,不能成为依赖真相。
5. 数据需求:最小增加两类事实
在持久 Task 方案的 agent_tasks 上增加:
orchestration_id:同组查询、取消与预算归集;result_revision:下游能指出自己读到的是哪一版结果;- 必要的阻塞原因与调度时间字段。
新增 agent_task_links:
parent_task_id
child_task_id
tenant_id
约束至少包括:
(parent_task_id, child_task_id)唯一,防止重复边;- 不允许自依赖;
- 创建边时检查同租户、同编排组;
- 通过事务内图检查或受约束的创建协议防止成环;不能只靠前端检查;
- 删除/归档策略跟随 Task 生命周期,不留下可被另一项目引用的悬空边。
具体 DDL 与是否把 orchestration_id 另立表,待 Task 线的存储复核后决定。初稿不为了“未来也许需要”再建 Goal、Swarm、Blackboard 三套实体。
6. 调度器每一步做什么
6.1 计算谁可以 ready
输入是 Task 行与依赖边。程序把“所有 parents 都 succeeded”的 pending Task 改为 ready;父任务 failed/cancelled 时,把尚未执行的子任务标为 blocked。
不做的后果:C 是否可执行只能由模型看列表后猜,重复唤醒或并发下容易提前启动。
6.2 原子领取 ready Task
调度事务内完成:重新确认状态与依赖 → 检查编排组与租户并发容量 → 创建或绑定执行 run → Task 改为 running 并写 current_run_id。多个副本可用 PostgreSQL 行锁/SKIP LOCKED 避免领到同一件工作;执行权最终仍受 run 的唯一约束与租约保护。
不做的后果:两个副本都读到 ready,各自启动一个 Agent,同一文件或外部动作被执行两次。
6.3 启动既有 Agent 运行链
Task 的 agent_name、model_ref、workspace_id 与自包含 command 成为执行 run 的装配输入。工具权限、沙箱、折叠、用量、trace 与 journal 复用现有实现。
不做的后果:多 Agent 另起一套简化执行器,短期演示很快,长期失去恢复、安全和观测能力。
6.4 写入结果并唤醒后继
执行 run 成功收尾时,程序把结构化结果与产物路径写入 Task,再计算后继是否可 ready,最后向协调者写持久通知。状态、结果和后继推进需要在同一事务或可对账的事务链里,不能出现“结果显示成功,但 C 永远没被推进”。
不做的后果:用户看到子任务都完成,汇总任务却永远不开始。
6.5 让协调者交付
协调 Agent 收到的是本组状态变化与最终 Task 引用。它读取最终产物、检查是否存在 blocked/failed/未完成任务,再向用户交付或解释缺口。
不做的后果:系统只完成若干子工作,却没有人对原始用户目标负责。
7. 结果汇合规则
下游 Task 的输入由程序按顺序构造:
- 原始用户目标与本 Task 自己的指令;
- 每个 parent 的 Task ID、成功状态、结果摘要和
result_revision; - 每个 parent 声明的产物路径;
- 权限与来源说明。
默认不把 parent 的完整模型历史和所有工具输出复制进来。否则两个调研 Agent 各读一百页材料后,汇总 Agent 会在开始前就先超上下文;需要细节时通过文件工具读取路径指向的产物。
结果质量不由“两个 Agent 都同意”推断。需要验证时另建 reviewer Task,或用独立场景 Eval 检查产物;投票不是验证器。
8. 取消、失败与恢复
- 取消整组:pending/ready/blocked 直接 cancelled;running 通过现有 stop 链路停止;已发生的外部副作用不自动撤销。
- 父任务失败:未开始的后代 blocked;已运行的独立分支可继续,协调者决定是否有保留价值。
- 执行者崩溃:执行 run 租约过期,Task 显示 interrupted;第一期坚持显式 resume,不因依赖图存在就自动重跑未知副作用。
- 恢复成功:结果按当前执行代次写入,再推进后继;旧 worker 醒来后不能覆盖新结果。
- 重复通知:通知去重键至少包含 Task、终态和
result_revision;重复投递不能创建第二个汇总 Task。
这套承诺是“状态可判定、后继不提前、旧执行者不能乱写”,不是跨文件与第三方 API 的 exactly-once。
9. 并发、预算与权限
- 现有租户并发上限仍是总容量;编排组内另设小上限,第一场景可用 2,防止一次拆出几十个子任务挤满租户;
- 每个 Task 独立记录模型与用量,编排组可汇总成本;超过预算时停止创建新工作,不悄悄换更便宜模型;
- 执行者只能选择当前租户可用规格,权限不能超过授权父池;跨项目读取必须由显式归属与授权决定;
- 同项目文件写入继续使用文件锁与指纹检查;需要真正并行改同一仓库时,再单独立项 worktree/分支与合并,不在第一期伪装已经解决。
10. 页面与观测最小要求
用户从原始对话进入编排组后,可以看到:
- Task 列表、执行者、状态与依赖关系;
- 某 Task 为什么还未开始:缺哪个 parent、容量不足、还是已经 blocked;
- 每次执行 run 的 trace、结果和产物;
- 取消与显式恢复入口。
这些页面只投影 PG 事实,不另存一份“前端任务状态”。状态变化按 doc/46 发事件,前端收事件后重拉。
11. 验收设计
机器验收分两层,不能只演示成功截图。
11.1 确定性调度验收(不打模型)
直接通过契约端点创建 A、B、C,C.parents=[A,B]:
- 初始只有 A、B 可领取,C 保持 pending;
- 只完成 A,C 仍 pending;
- A、B 都 succeeded,C 才 ready;
- 两个调度副本同时领取同一 Task,只产生一个执行 run;
- B failed 时 C blocked,不能启动;
- 重放同一完成通知,C 不重复启动;
- 构造循环依赖时创建请求被拒绝;
- 另一租户不能用伪造 parent ID 建立依赖。
11.2 活体场景验收
在隔离实例中让两个 researcher 分别生成短文件,再由 writer 汇总:
- 最终文件同时包含 A、B 的预定证据锚点;
- 时间线证明 C 的 run 晚于两份成功结果;
- 中途
kill -9自己启动的一个执行实例,恢复前 C 不启动,显式恢复后只产生一个 C; - 记录每个 Task 的 run ID、模型、用量和最终文件;
- 模型未按预期拆任务时按 doc/45 登记为模型行为/未覆盖,不能用假数据冒充引擎调度已通过。
契约字节一旦实施,期望进入 scripts/acceptance/expected.json 与 doc/19-v6-04;任务效果进入场景化 Eval,不与接口验收混为一谈。
12. 分期与非目标
分期
- Task 线先行:单件工作可持久、执行、通知、停止与恢复;
- 依赖最小闭环:A/B/C 场景,ready 计算、原子领取、结果引用;
- 审查与策略:reviewer Task、更细的预算与失败改计划;
- 按需扩展:同伴互调、动态 DAG 编辑、独立 worktree。
本期不做
- Agent 自由群聊与无限共享历史;
- 让模型绕过调度器直接改 running/ready;
- 自动重放结果未知的外部动作;
- 多 Agent 投票当质量证明;
- 动态创建不受约束的高权限 Agent;
- 受限 RSI、自我修改 Harness。
13. 施工前必须点头的决策
- 是否接受“持久 Task 先行”作为 #9 的前置,而不是直接在现有委派工具上加并行;
pending → ready → running的状态细化,以及blocked的失败传播语义;- 第一期中断恢复坚持显式 resume,还是另开自动恢复策略;初稿推荐显式;
- 编排组并发上限与租户额度的交互;
- 第一场景是否固定为“A/B 调研+C 汇总”,以此作为能力验收而非只搭框架。
14. 所以这解决什么
它把“多个 Agent 都出现过”变成“系统能按工作关系推进多个 Agent”:谁做什么、何时能做、读谁的结果、失败后停在哪,都有程序事实可追。这样形成的才是 Agent 平台的多 Agent 编排能力,而不是一次演示里的多个角色名。