Open Multi-Agent：goal-first 多 Agent 编排笔记

适合：目标明确但步骤不固定、多角色多模型协作、需要 fan-out 再 synthesize 的工作。

不适合：强监管、强复现、必须固定拓扑的生产流——除非你自己外挂 checkpoint / replay。

可以把它想成「会自动画流程图的团队调度器」：你负责定义角色与工具边界，它负责把目标压成可并行的任务图。调度器越聪明，你越要警惕每次重跑图不一样——探索阶段这是优点，审计与回放阶段这是负债。

| 模式 | API | 场景 | | --- | --- | --- | | 单 Agent | runAgent() | 单角色、单 prompt | | 自动团队 | runTeam() | 自动拆 DAG、自动并行 | | 显式 pipeline | runTasks() | 你手写任务图与分配 |

多 Provider 可混在同一 team（Anthropic、OpenAI、Gemini、Bedrock、Ollama、OpenAI-compatible 等）。

内置：bash、file_read、file_write、file_edit、grep、glob；defineTool() + Zod；stdio MCP；可选 delegate_to_agent。这是标准的 tool use 面：能接 MCP 不代表每个 agent 都该拿全套工具——roster 设计时按角色裁剪。

可观测：onProgress、onTrace、跑后 HTML dashboard（DAG、输出、token）；并对 key / token / bash 输出脱敏。

生产控制：onPlanReady / onApproval、planOnly、AbortSignal、retry/backoff、loop detection、工具输出截断、可替换 SharedMemory backend。SharedMemory 本质上是跨 agent 的 记忆系统 切片：只应放下游契约化结果，而不是完整对话垃圾。

| 需求 | 更适合 | | --- | --- | | 固定拓扑 + 成熟 checkpoint | LangGraph JS | | TS 手写 Supervisor / workflow | Mastra | | Python 多 Agent 生态 | CrewAI | | App 层 streaming / tool call | Vercel AI SDK | | TS 里从目标自动拆 DAG | Open Multi-Agent |

判断：OMA 适合「目标驱动、自动拆解、轻量嵌 Node 后端」；还不是成熟 durable workflow 引擎。

换句话说：你可以用它快速得到「该拆成哪些任务、谁做、依赖是什么」；但若你要「跑到一半进程挂了还能原样续跑」，目前更稳妥的是自己在外层记 run id 与任务结果，或等上游 checkpoint 能力落地。

• Team：AgentConfig[] + MessageBus + TaskQueue + SharedMemory
• Coordinator：goal → DAG
• TaskQueue：依赖、解锁、失败级联
• AgentPool：并发执行
• AgentRunner：对话循环 + 工具分发
• LLMAdapter / ToolRegistry：provider 与工具

理解这张骨架后，调试会更容易：计划怪，先看 Coordinator；卡死，先看 TaskQueue 依赖；某角色胡说，先看它拿到的 SharedMemory 与工具集。别一上来就换更大模型。

1. 默认先 planOnly 或 onPlanReady，看完 DAG 再执行。
2. 探索用 runTeam()；稳定流程固化成 runTasks()，别每次让 coordinator 重骰子。
3. SharedMemory 只放下游要消费的结构化结果，不塞长文本垃圾。
4. 工具权限最小化；文件工具默认 sandbox，生产别随手关。
5. 高成本 fan-out 先估 token：廉价模型做 extraction，强模型做 synthesis / judgment。
6. 失败级联要想清楚：一个 leaf 失败时，是整图停、局部重试，还是走降级路径？这决定你敢不敢把它接进夜间批任务。
7. dashboard 与 trace 要进复盘笔记：下次固化 runTasks() 时，最有价值的往往是「哪条边不该存在」。

Recipe 模板（建议落笔记）

1
## <workflow name>
2
### 目标
3
### Agent roster
4
### 运行模式：runAgent / runTeam / runTasks
5
### 输入 / 输出 schema
6
### Human gates
7
### 失败处理 / 成本控制
8
### 复盘链接

Run 日志模板

Goal、Team、Provider/model、Options、Plan/DAG、Result、Token、Failures、Follow-up——每次实跑留一条，便于对比。

| 主题 | 为何重要 | | --- | --- | | Checkpoint / resume | 核心状态偏内存；crash 后难恢复；Abort ≠ resume | | SharedMemory 结构化 handoff | outputSchema 已有；跨 agent 内存契约仍在演进 | | Plan artifact + 确定性 replay | 有 planOnly，缺标准「存计划 → 原样回放」闭环 | | 跨 provider reasoning 回放 | 部分 reasoning block 可能 silent drop | | 成本 / 能力感知 model routing | 多是 per-agent 固定模型，缺策略路由 | | Consensus / 对抗验证原语 | 需内置 propose→refute→converge，而非手写 reviewer DAG | | 外部 CLI agent 入队 | 把 Claude Code / Codex 等当 teammate 仍属设计面 |

社区与个人贡献方向上，checkpoint 价值最高；structured handoff、plan replay、model routing 是较可切片的增强。具体 PR 状态会变，以 GitHub 为准。

若你准备给上游提 PR，优先选「可测、可单独立项」的切片：例如 plan artifact 的 schema + runFromPlan，或 SharedMemory 在 string store 边界上的 JSON 编解码，而不是一上来啃全量 Redis/Postgres durable runtime。

短期： 探索性 multi-agent workflow；重要 run 先 plan；DAG 贴进笔记；稳定后改 runTasks()。

中期： 跟 SharedMemory / plan replay 上游进展；长任务在外层自建 run registry 与结果 checkpoint，别干等。

长期： 等 durable state + plan 回放成熟，再当可靠 workflow substrate；外部 coding CLI 入 team 等抽象稳定后再接。

Open Multi-Agent 把「先目标、后图」做成了 TS 里好用的默认路径，可观测与 HITL 入口也够用。它的上限取决于你是否接受 coordinator 的非确定性，以及你是否补上 持久化与回放。把它当 harness 层的编排选项之一，而不是「已解决生产编排」的答案。

常见组合：

• 探索拆解：OMA runTeam 出 DAG 与角色分工；
• 落地改代码：把关键节点交给 Pi / Claude Code / Codex 等 coding agent 在隔离 worktree 执行；
• 汇总：synthesis agent 只读结构化 handoff，不重扫全仓。

在「外部 CLI agent 入队」能力成熟前，这种 外层编排 + 内层 coding harness 的拼法更务实。