第 16 章 · 编排基础

Harness 锚点｜判别清单第 9 项「扩展机制」——多 Agent 的子任务调度与编排。

一个塞满七八个角色的 Agent

那个卖家的生意做大了，他想要一个“竞品情报官”：每周自动调研三家竞品，扒价格、读用户评论、看新品动向，然后写成一份对比报告，最后再校对一遍措辞发给他。

一开始他图省事，就搭了一个 Agent，把所有活儿都写进 system prompt：“你要会抓网页、会分析评论情感、会写商业报告、还要会审校……”结果这个 Agent 样样都沾、样样不精：抓数据时忘了自己还要写报告，写报告时又把之前分析的结论搞混，校对时更是敷衍了事。上下文里塞了三家竞品的原始网页、几百条评论、半成品报告，早就又乱又满。

问题不在模型不够强，而在一个 Agent 被逼着同时扮演七八个角色。人遇到这种活儿会怎么办？找几个人分工：一个专门跑调研、一个专门写、一个专门审。把工作拆给多个各司其职的 Agent，再协调它们配合起来——这就是 Orchestration（编排）。

编排的本质：分工 + 协调

多 Agent 系统听起来复杂，剥开看就两件事：

  • 分工（division of labor）：每个 Agent 负责一块清晰的职责——调研的只管调研，写作的只管写。职责单一，system prompt 就干净，上下文也不会互相污染。
  • 协调（coordination）：Agent 之间怎么把活儿接上——谁先谁后、谁的输出喂给谁、结果怎么汇总。

分工解决“各自干什么”，协调解决“怎么配合”。多 Agent 编排的所有花样，都是在这两个维度上做文章。

三种基础协调结构

具体怎么协调，有三种最基础的结构，先把它们的英文名记牢——后面几章都是它们的变体：

  • Supervisor（主管模式）：一个“主管” Agent 负责拆解任务、分派给“下属” Agent、再汇总结果。主管像项目经理，下属像专职员工。这是最常见、最好理解的结构。竞品情报官用主管模式，就是主管把“调研三家竞品”拆成三份分给调研 Agent，收回来交给写作 Agent，再过一遍审校 Agent。
  • Pipeline（流水线）：Agent A 的输出直接作为 Agent B 的输入，串成一条线，一环扣一环。适合有明确先后顺序的任务——调研 → 写作 → 审校，天然就是一条流水线。
  • Parallel（并行）：多个 Agent 同时处理各自独立的子任务，最后合并结果。适合可拆分、彼此不依赖的工作——三家竞品各查各的，互不相干，完全可以三个 Agent 一起上，省时间。

这三种可以组合：竞品情报官其实是“先 Parallel 调研三家、再 Pipeline 走写作和审校”的混合。后面几章会展开更具体的模式——DAG 工作流（第 17 章）把依赖关系画成图、Swarm（第 18 章）走去中心、Handoff（第 19 章）讲交接的细节。本章先建立整体认识。

搭之前先想清楚三个问题

多 Agent 系统很容易越搭越复杂，动手前务必先回答三个设计问题：

  1. 怎么拆：按角色拆（研究员 / 写手 / 审校），还是按任务拆（每个 Agent 管一家竞品）？拆得太细，Agent 之间协调的开销比干活还大；拆得太粗，又退回到“一个 Agent 扛所有事”的老毛病。竞品情报官通常两种混用：按任务拆调研（一家一个），按角色拆后续（写手、审校各一个）。
  2. 怎么传：Agent 之间传什么？是把完整上下文一股脑传过去，还是只传结论/摘要？传太多会污染下游 Agent 的注意力，传太少又会丢信息。这个“传多少”的分寸，是第 19 章 Handoff 的核心。
  3. 谁做主：有一个中心主管统一调度，还是让 Agent 去中心地自组织？中心化好控制、易调试、可预测；去中心更灵活、更鲁棒，但控制权到处流动，难追踪。这正是第 18 章 Supervisor vs Swarm 的分野。

还有一条压倒一切的经验：能用单 Agent 解决的，就别上多 Agent。 多 Agent 会显著增加复杂度、成本和调试难度——每多一个 Agent，就多一份 token 开销、多一处可能出错的协调环节。只有当单 Agent 确实因为职责太杂、上下文冲突、需要多视角而扛不动时，才拆。

用 pi 实现：orchestrator 包

pi 有一个专门的包 @earendil-works/pi-orchestrator 来做多 Agent 编排。

⚠️ 注意：这个包目前是实验性（Experimental）的，官方明确说“CLI、API 和行为尚不稳定，可能变动或移除”。所以本部分我们重点讲模式——模式是稳定的、跨框架通用的；具体 API 你用时以 pi 当时的文档为准。

概念上，一个主管式编排大致这样组织：

// 概念示意：主管拆解任务，分派给专职 Agent，再汇总
const supervisor = orchestrator.createSupervisor({
  agents: {
    researcher: researchAgent,   // 负责调研（可并行跑多家竞品）
    writer: writeAgent,          // 负责整合成文
    reviewer: reviewAgent,       // 负责审校措辞
  },
});

const report = await supervisor.run("调研三家竞品并产出对比报告");
// 主管内部：让 researcher 分头调研 → writer 整合成文 → reviewer 审校

关键在于理解层次：每个子 Agent 本身，就是前面几个部分讲的那种完整 Agent——有自己的工具、上下文、ReAct 循环、甚至自己的反思。编排层不替代它们，而是在它们之上协调分工与信息流。这是一种 harness（宿主）视角：把一个个能干活的 Agent 当积木，编排层负责搭。

动手看看

先别急着上 orchestrator。拿竞品情报官这个需求，在纸上画一画：如果按“分工 + 协调”来拆，你会拆出几个 Agent？它们之间是流水线、并行、还是主管分派？哪一步能并行、哪一步必须等前一步？

画完再对照 pi 的 orchestrator 文档，看它提供的抽象能不能表达你画的结构。你会发现，难的从来不是 API，而是“怎么拆、怎么传、谁做主”这三个设计决策——想清楚这三点，用哪个框架都只是填空。

实战中的几个坑

坑一：过度拆分，为了多 Agent 而多 Agent。

  • 现象：一个简单任务硬拆成五六个 Agent，跑得又慢又贵还容易出错。
  • 原因：把“多 Agent”当成了先进的象征，忽略了它的成本。
  • 对策：默认单 Agent，只有单 Agent 确实扛不动时才拆；拆之前先问“这真的需要分工吗”。

坑二：上下文全量乱传，互相污染。

  • 现象：调研 Agent 的原始网页、评论全塞给写作 Agent，写作 Agent 抓不住重点。
  • 原因：图省事，Agent 之间直接传完整上下文。
  • 对策：只传下游需要的结论/摘要（详见第 19 章 Handoff 的粒度选择）。

坑三：职责边界模糊，活儿没人干或重复干。

  • 现象：两个 Agent 都以为对方在写报告，结果都没写，或都写了。
  • 原因：分工时职责没划清，协调结构不明确。
  • 对策：每个 Agent 的职责写成一句话能说清；用主管明确“现在轮到谁”。

坑四：没有全局刹车，多 Agent 一起烧钱。

  • 现象：几个 Agent 各自循环，总成本失控。
  • 原因：只给了单个 Agent 刹车，没给编排层设全局预算/轮数上限。
  • 对策：在编排层加全局的 token/成本上限和总轮数上限（呼应第 3 章的硬刹车）。

对比：其他框架

多 Agent 编排是当前框架竞争最激烈的领域，四家的“分工 + 协调”抽象各不相同：

框架编排怎么做特点
LangGraph把多 Agent 建成状态图，Agent 是节点，协调靠边和条件边控制流最精细，也最需手工描述
CrewAI以团队 Crew + 角色 Role + 任务 Task 为核心抽象最贴近“主管带一队下属”，多 Agent 主场
PydanticAI无专门的团队/主管抽象，通常把“一个 Agent 当工具调另一个 Agent”，用普通 Python 串多 Agent 非其强项，胜在类型安全、逻辑可控
Agno一等 Team 抽象，内置 coordinate / route / collaborate 三种模式常见编排结构直接做成配置项
pi用实验性的 orchestrator 包，harness 视角，子 Agent 是完整 Agent模式稳定、API 待定

它们的底层都是“分工 + 协调”，差别在抽象层次与易用性：LangGraph 给你画图的自由，CrewAI / Agno 给你现成的团队结构，PydanticAI 让你用代码自己拼（多 Agent 确实是它相对薄弱的一环），pi 则用实验性的编排包提供 harness 式的组合。

小结

  1. 当单 Agent 职责太杂、上下文冲突、需要多视角时，就该上多 Agent 编排（Orchestration）。
  2. 编排的本质是分工 + 协调，三种基础结构：Supervisor（主管分派）、Pipeline（流水线）、Parallel（并行），可组合使用。
  3. 搭之前先答三个设计问题：怎么拆、怎么传、谁做主；一条铁律——能单 Agent 解决就别上多 Agent。
  4. pi 用实验性的 orchestrator 包编排，每个子 Agent 都是完整 Agent，编排层在其上协调——模式稳定，API 以当时文档为准。

接下来几章展开具体模式。先从最结构化的一种开始：把任务依赖关系画成图、让能并行的并行、该等待的等待——DAG 工作流。