tako 文档 GitHub

多 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”,而是:

3. 名词与对象

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 上增加:

新增 agent_task_links:

parent_task_id
child_task_id
tenant_id

约束至少包括:

具体 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 的输入由程序按顺序构造:

  1. 原始用户目标与本 Task 自己的指令;
  2. 每个 parent 的 Task ID、成功状态、结果摘要和 result_revision;
  3. 每个 parent 声明的产物路径;
  4. 权限与来源说明。

默认不把 parent 的完整模型历史和所有工具输出复制进来。否则两个调研 Agent 各读一百页材料后,汇总 Agent 会在开始前就先超上下文;需要细节时通过文件工具读取路径指向的产物。

结果质量不由“两个 Agent 都同意”推断。需要验证时另建 reviewer Task,或用独立场景 Eval 检查产物;投票不是验证器。

8. 取消、失败与恢复

这套承诺是“状态可判定、后继不提前、旧执行者不能乱写”,不是跨文件与第三方 API 的 exactly-once。

9. 并发、预算与权限

10. 页面与观测最小要求

用户从原始对话进入编排组后,可以看到:

这些页面只投影 PG 事实,不另存一份“前端任务状态”。状态变化按 doc/46 发事件,前端收事件后重拉。

11. 验收设计

机器验收分两层,不能只演示成功截图。

11.1 确定性调度验收(不打模型)

直接通过契约端点创建 A、B、C,C.parents=[A,B]:

  1. 初始只有 A、B 可领取,C 保持 pending;
  2. 只完成 A,C 仍 pending;
  3. A、B 都 succeeded,C 才 ready;
  4. 两个调度副本同时领取同一 Task,只产生一个执行 run;
  5. B failed 时 C blocked,不能启动;
  6. 重放同一完成通知,C 不重复启动;
  7. 构造循环依赖时创建请求被拒绝;
  8. 另一租户不能用伪造 parent ID 建立依赖。

11.2 活体场景验收

在隔离实例中让两个 researcher 分别生成短文件,再由 writer 汇总:

契约字节一旦实施,期望进入 scripts/acceptance/expected.json 与 doc/19-v6-04;任务效果进入场景化 Eval,不与接口验收混为一谈。

12. 分期与非目标

分期

  1. Task 线先行:单件工作可持久、执行、通知、停止与恢复;
  2. 依赖最小闭环:A/B/C 场景,ready 计算、原子领取、结果引用;
  3. 审查与策略:reviewer Task、更细的预算与失败改计划;
  4. 按需扩展:同伴互调、动态 DAG 编辑、独立 worktree。

本期不做

13. 施工前必须点头的决策

  1. 是否接受“持久 Task 先行”作为 #9 的前置,而不是直接在现有委派工具上加并行;
  2. pending → ready → running 的状态细化,以及 blocked 的失败传播语义;
  3. 第一期中断恢复坚持显式 resume,还是另开自动恢复策略;初稿推荐显式;
  4. 编排组并发上限与租户额度的交互;
  5. 第一场景是否固定为“A/B 调研+C 汇总”,以此作为能力验收而非只搭框架。

14. 所以这解决什么

它把“多个 Agent 都出现过”变成“系统能按工作关系推进多个 Agent”:谁做什么、何时能做、读谁的结果、失败后停在哪,都有程序事实可追。这样形成的才是 Agent 平台的多 Agent 编排能力,而不是一次演示里的多个角色名。