多 Agent · hands-on

多 Agent 协作模式

这份教程把多 Agent 系统拆成三条正交轴——拓扑结构、协调机制、通信方式——并教会判断一个任务到底该不该上多 agent。基于 2026-06 的框架格局（LangGraph / AutoGen-AG2 / CrewAI / OpenAI Agents SDK / Claude Agent SDK）。读完约 2-3 小时，含动手章。下文所有代码用来演示设计判断，均未在本机执行（标 2026-06）。

·适合谁

用单 agent + 工具循环跑通过至少一个 agent（LangChain、Pydantic AI、裸 SDK 都算），手上有一个能跑的东西作参照。
懂 ReAct 循环——能说清 thought-action-observation 为什么是循环而不是单次调用。
懂 function calling——看得懂 tools=[...] 里某个工具是被模型在哪一步选中的。

·不适合谁

还没调用过任何 LLM API：先去 OpenAI function calling 指南或 Anthropic tool use 文档把单 agent 跑通一次，再回来。
只想抄一段能跑的多 agent 脚手架、不关心它该不该是多 agent：LangGraph 多 agent 文档更快。
已在生产里深用多 agent 编排半年以上：这份是回到三轴心智模型的设计课，对你偏概念，直接看 04 失败模式与 06 自测。

·读完之后你能做到什么

看到任意一个「多 agent」方案，你能先把它拆成拓扑 / 协调 / 通信三条轴上的取值，再判断它到底该不该是多 agent——这是框架文档不会替你回答的问题。

更具体地，读完后你能：

拆解任意一个多 agent 方案到三条轴上的取值——它的拓扑是 supervisor、hierarchical 还是 swarm-handoff，协调是中心调度还是去中心 handoff，通信走共享 state 还是消息传递。
选对框架并说出理由——给一个具体场景，从 LangGraph / AutoGen-AG2 / CrewAI / OpenAI Agents SDK / Claude Agent SDK 里挑一个，并讲清它在三轴上的默认取值为什么匹配。
识别常见失败模式的症状到根因——给一段异常的多 agent 行为，定位它违反了哪条原理。
判断何时该退回单 agent + 工具或 workflow——用约 15× token 这条成本线，说清这个任务的并行价值吃不吃得下这个倍数。

一句话本质

多 Agent 系统不是从框架里挑一个，而是在三条正交轴——拓扑结构、协调机制、通信方式——上各自取值再组合；认出任意系统在这三轴上落在哪，比记住任何框架名都重要。

·现状速览（截至 2026-06）

多 Agent 是一个仍在快速演进的领域，分清哪些是定论、哪些还在动、哪些已被证伪，比记住任何一个框架的 API 都重要。下表把当前状态切成三层。

表 0.1 · 多 Agent 现状三层（截至 2026-06）
层	内容	为什么这样判定
稳定（可放心建心智模型）	三轴心智模型（拓扑 / 协调 / 通信）；supervisor、orchestrator-worker、hierarchical、network/swarm-handoff 等经典拓扑。这是几年没动的地基。	这些拓扑名与协调/通信的区分，跨所有框架一致复现；换框架只换封装、不换这套坐标。
在变（盯紧版本）	框架格局——LangGraph（有状态图·精控·可持久化）、AutoGen-AG2（事件驱动 GroupChat·async-first）、CrewAI（角色 crew·快）、OpenAI Agents SDK（显式 handoff）、Claude Agent SDK（Anthropic 原生）；以及 Anthropic 实证的约 15× token 成本。何时该上多 agent 见 01 §1.5。	各框架仍在快速迭代，三轴默认取值各不相同；约 15× token 来自 2025 的公开实证，是当前最有分量的成本基准。
已过时（别当默认）	以为「多 agent 总比单 agent 强」。多数任务用单 agent + 工具或一条 workflow 就够，多 agent 只在子任务独立可并行、且价值高到吃得下约 15× token 时才划算。	Anthropic 的简单优先原则与 15× 成本实证共同指向：复杂度只在确有收益时才加。

来源：Anthropic「How we built our multi-agent research system」（2025）、Anthropic「Building Effective Agents」。

流畅感警告

这一页读起来会很顺，正因为顺，三种假象最容易出现：

「我读得很顺」——顺只证明句子通顺，不证明你能在陌生方案上复用这三条轴。

「我做题很快」——题做得快，常常是答案就在上一段，换个场景就卡住。

「我没卡壳」——没卡壳意味着没触到边界；真正的理解发生在被迫做判别、而不是被讲解抚平的时刻。

下面这道题用来戳破假象：一个「supervisor 调度 3 个并行 subagent、各自带独立上下文窗口」的系统，它在拓扑 / 协调 / 通信三条轴上分别取了什么值？先在心里答，再展开。

展开答案（先答再展开）

拓扑 = supervisor（也即 orchestrator-worker，一个 lead 调度多个 worker）；协调 = 中心调度（subagent 不互相对话，全部经由 supervisor）；通信 = 偏消息传递且上下文 per-subagent 隔离（各 subagent 独立窗口，结果回传给 lead 汇总）。三个取值彼此独立——把同一拓扑换成共享 state 通信、或把中心调度换成去中心 handoff，都是另一个系统。这正是 01 §1.1 要建立的坐标。

·概念地图

图 0.1读这张图盯三件事：一，拓扑 / 协调 / 通信是三条正交轴——动其中一条不强制动另外两条。二，三轴可任意组合，组合数远多于"几个框架各代表一种范式"。三，底部的框架只是某一组三轴取值的封装，认出取值比认出框架名更要紧。

·学习路径建议

这是一份 hands-on 教程（含动手章），按目的挑路径：

理解三轴心智模型：从 01 概念的三轴总览逐节走，重点记每个拓扑 / 协调 / 通信取值的判别特征；再到 02 原理看三轴各自的权衡。这条线的重心是 01 与 02。
做框架选型：先看本页"现状速览"三层表，再跳 02 章的 §2.2 拓扑权衡、§2.3 协调权衡、§2.4 通信与上下文隔离，对照各框架在三轴上的默认取值是否匹配你的场景；想动手对比就到 03 实操。
诊断多 agent 失败：直接进 04 失败模式逐条对症状，再回 §2.1（约 15× token 机制）与 §2.5（何时不该用）追根因；想复现某个失败就到 03 实操自己搭一遍。

·目录

01 概念——三轴总览、拓扑结构、协调机制、通信方式，以及单 agent + 工具与多 agent 的分界，每个概念配可走查的例子。
02 原理——为什么多 agent 贵（约 15× token 的机制）、拓扑 / 协调 / 通信三轴各自的权衡、上下文 per-subagent 隔离，以及何时不该用多 agent。
03 实操——三阶动手：worked supervisor → partial（留关键决策点）→ 开放的最小 research agent，每步指回 01 的三轴取值。
04 失败模式——具体失败模式逐条：症状 → 根因（回到 02 的某条原理）→ 修复方向。
05 综合——一个跨章判别项目：在拓扑 / 协调 / 通信上做多个设计决策，并判断该不该上多 agent。
06 自测——分层题库，重心在 recall 与跨章的 trace 诊断判别。

·学完之后

多 agent 的可观测与评估——给"多个 agent 的协作轨迹"加上 trace 与评测集，让你看见每个 subagent 的输入输出和决策点，把三轴上的抽象取值变成可量化的对象。
部署与编排运行时——把一张设计好的多 agent 图放到能持久化、能恢复、能并发的运行时上（如 LangGraph 的 checkpoint / 持久执行），让"拓扑"从一张图变成一套可上线的系统。
成本控制——围绕约 15× token 这条线做工程：上下文裁剪、subagent 数量与深度的预算、缓存与早停，把"吃不吃得下这个倍数"从一句判断变成一组可调的旋钮。
Agent 长期记忆——从"对话历史"到"跨会话记忆"，是另一条独立子线，决定多 agent 在长任务里能否复用此前的发现，而不是每轮从零开始。