# [Project] 9. pi-multi-agent — 用廉价模型集群换高质量输出


## 核心命题

**3-4 个快速便宜模型组队协作，能不能胜过 1 个昂贵慢速模型？**

答案是能。不是拍脑袋说的——2024-2025 年有一系列研究支持这个结论。pi-multi-agent 就是这个思路的工程化实践：把一个大任务拆给多个 agent，每人一个角度，辩论、碰撞、互相审查，最终产出质量远超单个模型独自干活。

## 研究背景：多 Agent 为什么有效

### Google：Chain-of-Agents 框架

Google Research 在 NeurIPS 2024 发表的 Chain-of-Agents (CoA) 框架，让多个 worker agent 分段处理长文本，顺序传递聚合信息。结果：在 QA、摘要、代码补全等任务上，**比单模型强 10%，当输入长度超过 400K tokens 时优势扩大到约 100%**。关键是 training-free——不需要额外训练，纯靠协作结构。

### 临床医学：多 Agent 规模化验证

一篇 2025 年的 PubMed 论文测试了临床工作负载（信息检索、数据提取、剂量计算）。单 agent 在批量从 5 增加到 80 时，准确率从 73.1% 暴跌到 16.6%。而多 agent 系统从 90.6% 降到 65.3%——虽然也降了，但**绝对优势非常明显**。而且多 agent 用的 token 少了 65 倍，延迟增长也被控制住了。

### 代码优化：小模型团队打赢大模型

NeurIPS 2025 的"Lessons Learned"框架让多个小 LLM 组成团队，通过 "经验教训" 共享机制（成功经验 → 经验库 → 其他 agent 检索复用），**小模型团队在代码优化任务上打败了单个大模型**。

### 还有反对声音：单 Agent 强 Prompt 可能就够了

ACL 2024 一篇论文提供了一个重要反面观点：在有充分示例（few-shot demonstrations）时，强 Prompt 的单 agent 在多数推理任务上接近多 agent 讨论的效果。多 agent 的优势在**没有示例、任务需要多样技能、或者需要处理长文本时**才显著。

这个"但是"很重要——它告诉我们，多 agent 不是银弹。场景要对：**大目标、多维度、长上下文、需要交叉验证**。

## pi-multi-agent 的设计哲学

基于这些研究，pi-multi-agent 的设计围绕一个核心问题：**怎么让多个便宜模型组队干活，产出接近甚至超过一个贵模型？**

### 架构总览

<img src="/images/mermaid/pi-multi-agent-zh.svg" alt="pi-multi-agent 架构图" style="max-width:100%;">

**图 1 — pi-multi-agent 架构：编排器 + Agent 集群 + Dashboard**

### 两个核心包

| 包 | 定位 |
|---|---|
| `pi-multi-agent-core` | 编排引擎 —— 17 个工具，agent 生命周期管理、事件持久化、工作流模板 |
| `pi-multi-agent-dashboard` | 仪表盘 —— Web 实时监控 + TUI overlay，通过 public-api 单向依赖 core |

Dashboard 对 core 零侵入——core 完全不知道 dashboard 的存在。想换 UI？卸载 dashboard 包即可。

## 设计取舍：折腾过的几个关键决策

### 编排器禁止 read / write / bash

这是反复折腾后做出的最关键的取舍。

假设编排器有 read 权限——它读到一堆代码，想"帮用户直接改了"，于是调用 write。改完之后，又想验证一下——调用 bash 跑测试。测试失败——再读、再改、再跑。**三次循环，上下文从 2K 暴涨到 20K，编排器自己的"脑子"先炸了。**

这是 pi-orchestrator 开发过程中用真金白银（token 费）换来的教训。最终结论就一条：编排器**只管调度，不碰代码**。读代码、写代码、跑命令都是子 agent 的事，每个子 agent 在自己的隔离 session 里操作，上下文互不污染。

这个取舍带来两个直接好处：

- **编排器上下文始终很小**（几百到一两千 token），调度决策快速、便宜
- **子 agent 上下文膨胀有上限**——compact / clear / stop 三个工具精确控制

### 继承 pi-orchestrator 的 Token 节约思路

pi-multi-agent 在 pi-orchestrator 的基础上，保留了几个关键的 token 节约机制：

- **异步派发（唯一模式）**：所有 `agent_command` 立即返回句柄，编排器不阻塞。子 agent 后台跑完，结果在下一次 turn 注入 systemPrompt。编排器不会被单次任务拖住，也不需要轮询
- **摘要交付，不传全量**：子 agent 完成后只传摘要（task ID + 状态 + 前 500 字符），编排器自己决定要不要 `agent_logs` 展开。避免了"跑了一个 coder，结果它的全部输出炸了编排器的上下文"
- **黑板转发**：agent 之间通过黑板共享数据，`agent_forward` 只传 key/value，不传整个 agent 的输出。传输成本 O(1)

### 子 Agent 之间不直接通知，全部走编排器

这个设计的第一个心理反应通常是："那每次都要 LLM 处理，岂不是浪费 token？"

反过来想——如果子 agent 之间直接通知呢？agent-A 完成了一个任务，把全部输出（可能几千 token）推给 agent-B。agent-B 正在跑自己的任务，被"打扰"后上下文瞬间膨胀。如果 5 个 agent 互相广播，**O(N²) 的 token 爆炸**。

走编排器中转的实际效果：

**第一层收益：编排器充当前置过滤器。** 编排器拿到子 agent 的摘要后，自己判断"这个结果是否需要传给其他 agent"、"传给谁"、"传什么"。大部分中间结果都是"知道了，不用转"，只有真正有价值的结果才会 `agent_forward` 到黑板。**用户实际看到的 token 消耗反而更低。**

**第二层收益：AI 会"停下来问你"。** 编排器收到子 agent 返回后，常常会在回复里问用户一句："coder-1 已经完成了数据库设计，你看一下要不要调整？"这是因为 LLM 天然有"等待确认"的倾向。在没有新触发的情况下，这个"停下来"就是对话终点——用户下次打开 pi 才能看到。但因为后续又有其他 agent 返回，**新的返回触发了新 turn，编排器被动"被叫醒"**，于是它既"停了一下"让用户看到中间状态，又自动继续推进，形成了一个自然的异步节奏。

**第三层收益：编排本身就产生智能。** LLM 在"阅读子 agent 摘要 → 判断下一步动作"这个过程中，实际上做了一次元层面的思考。子 agent 关注的是"怎么做"，编排器关注的是"谁来做、按什么顺序做、要不要换人"——后者的调度决策本身就需要理解全局，这个理解过程就是额外智能的来源。

### 集群模式最适合的场景

这种模式**不是给简单问答设计的**。问一句"1+1 等于几"，不需要派三个 agent 开个会。集群模式适合：

**设定一个具体的大目标，然后集群统一思考、统一处理。** 比如：

- "重构这个模块，保证架构合规"
- "审查这份代码的安全性，覆盖 OWASP Top 10"
- "设计一套 API 并实现、测试、写文档"

流程是：架构委员会（2 个 analyzer 辩论方案）→ 工程团队（2 个 coder 并行实现 + 交叉审查）→ 质保团队（测试 + 架构审查 → 签字）→ 合并 → 清理。

**派遣不同人设去辩论，是这个模式的核心价值。** 你可以给三个 analyzer 设定截然不同的立场：

- "你是激进的重构派，认为能拆就拆"（激进）
- "你是保守派，非必要不重构"（保守）
- "你是性能至上的实用派，不管架构，只看 benchmark"（实用）

三个人在黑板里吵完，编排器综合三方观点做决策。**三个便宜模型从不同角度思考，产出的综合质量确实常常超过一个贵模型单打独斗——因为它没有"盲区"。**

## 仓库

[github.com/GOODDAYDAY/pi-multi-agent](https://github.com/GOODDAYDAY/pi-multi-agent)

## 参考

- Chain of Agents: Large Language Models Collaborating on Long-Context Tasks (Google Research, NeurIPS 2024)
- Two Heads Are Better Than One: Test-time Scaling of Multi-agent Collaborative Reasoning (NeurIPS 2025)
- Scaling LLM-based Multi-Agent Collaboration (MacNet, arXiv 2024)
- Orchestrated Multi Agents Sustain Accuracy Under Clinical-Scale Workloads (PubMed, 2025)
- Rethinking the Bounds of LLM Reasoning: Are Multi-Agent Discussions the Key? (ACL 2024)
- Lessons Learned: A Multi-Agent Framework for Code LLMs (NeurIPS 2025)