第 12 步：多 Agent Swarm

这一节学什么

• AgentTeam 的最小用法
• 一个 agent 如何委派多个 subagent
• 多 Agent 协作和单 Agent 的边界
• 什么时候该用 swarm，什么时候不该用

你会运行什么

示例代码：

• examples/getting_started/step_12_multi_agent_swarm.py

运行：

python examples/getting_started/step_12_multi_agent_swarm.py

这一节故意使用显式 step_all() 驱动的方式，而不是直接展开 auto_start 的事件驱动生命周期。

原因很简单：

• 这一节要先讲清“怎么拆任务、怎么委派、怎么聚合”
• auto_start 会把重入、幂等、副作用重复这些 runtime 细节一起带进来

所以 getting started 先把 subagent 编排主线讲清楚，长期运行和事件驱动语义放到更进阶的 swarm 示例里。

这一节先建立最小心智

这一节先不展开完整产品级宿主，而是只回答一个问题：

什么时候单个 Agent 已经不够用，开始需要把工作拆给多个子 agent。

常见信号包括：

• 你需要把一个总任务拆成多个子任务
• 你需要 Agent 之间显式交接任务
• 你需要把子任务结果再汇总回来

核心概念

Swarm 不是“把更多工具塞给一个 Agent”。

更准确地说：

• 单 Agent 解决的是一个运行树里的决策与执行
• 多 Agent 解决的是多个角色、多个运行单元之间的协作

这一步应该建立的心智是：

• 先把单 Agent 跑顺
• 再考虑是否真的需要 subagent / swarm runtime

这个示例做了什么

这个例子现在演示的是一条最小的 fan-out / fan-in 协作链路：

• coordinator 先拿到一个总任务
• coordinator 把总任务拆成两个子任务
• coordinator 生成两个 worker
• 两个 worker 分别处理不同子任务
• coordinator 等两条回复都回来
• coordinator 把两条结果聚合成最终回复

这里没有引入复杂 LLM 规划、handoff 策略或团队级 prompt 工程。 重点只是让你看清 subagent delegation 最基本的四个动作：

• spawn
• send
• wait
• aggregate

所以这一步虽然文件名还是 multi_agent_swarm，但更贴近的心智其实是：

• 一个 coordinator agent 把工作委派给多个 subagent
• subagent 各自返回局部结果
• coordinator 再把结果收回来整合

运行后观察什么

• AgentTeam 负责持有共享 swarm runtime
• 每个 role 各自定义自己的树
• agent 之间不是共享一个 state，而是通过消息来协作
• coordinator 会拿到两个不同的 worker id
• collected_replies 里会出现两条子任务结果
• final_reply 是聚合后的结果，而不是单个 worker 的直接输出

这个最小示例里，coordinator 成功聚合后，个别 worker 仍可能显示为 RUNNING。

这是有意接受的简化：

• 这一节先聚焦“拆任务、回收结果、做聚合”
• 不在 getting started 里继续展开子 agent 生命周期回收策略

这一步学完后应该会什么

你应该能回答：

• 一个 agent 怎样把任务拆给多个 subagent
• 多 agent 和单 agent 的边界在哪里
• AgentTeam 在主路径里承担什么职责
• 为什么多 agent 编排的核心不是“更多 prompt”，而是“拆分 + 角色 + runtime + message flow”

对照文档

如果你已经明确要做多 Agent，可以继续看：

• Swarm 运行时
• Swarm Studio