OpenAI Swarm 源码精读:被弃用的实验项目,藏着 multi-agent 的核心思路
21,909 stars,被 OpenAI Solution Team 放在 GitHub 上,README 顶部第一行就写着「This repo is no longer maintained. We've moved development to the OpenAI Agents SDK」。一个被官方明确弃用的项目,为什么值得读源码?
因为 Swarm 是 multi-agent 的"最小可运行单元"。它只有两个抽象:Agent 和 handoff。整个框架的 swarm/core.py 不到 400 行,没有图、没有状态机、没有持久化。把它的代码读完,multi-agent 在做什么、为什么要这么设计、坑在哪里,一清二楚。
它解决什么问题
多 Agent 协作需要一个最小心智模型。
LangGraph 太重——你得先学 StateGraph、Node、Edge、Conditional Edge 这套概念,才能跑通一个 demo。Assistants API 太黑盒——对话状态全在 OpenAI 服务端,本地调试只能看 logs。
Swarm 给你的承诺是:5 分钟跑通"交接"原语。一个 Agent 的 tools 里放一个返回另一个 Agent 的函数,运行时检测到工具返回的是 Agent 实例,就把对话所有权交出去。没有别的。
这个原语的名字叫 handoff——不是协议层的 handoff,是函数返回值的语义层 handoff。它是 LangGraph、CrewAI、AutoGen 都在做的事的最简形态。
怎么用
不能 pip install swarm。Swarm 已经从 PyPI 下架,唯一安装方式是:
pip install git+https://github.com/openai/swarm.git
这是第一个弃用信号。OpenAI 自己都告诉你,别再新项目用了。
装完之后,最少 30 行代码就能看到 handoff:
from swarm import Swarm, Agent
client = Swarm()
def transfer_to_agent_b():
return agent_b
agent_a = Agent(
name="Agent A",
instructions="你是接待员,听到用户想聊技术就交给 Agent B。",
functions=[transfer_to_agent_b],
)
agent_b = Agent(
name="Agent B",
instructions="只用俳句回答问题。",
)
response = client.run(
agent=agent_a,
messages=[{"role": "user", "content": "我想聊聊分布式系统"}],
)
print(response.messages[-1]["content"])
# 输出:
# 节点轻轻颤动,
# 数据在网络间流转,
# 共识悄然达成。
跑一遍。Agent A 拿到"分布式系统",模型判断该转交,调用 transfer_to_agent_b(),拿到 agent_b 实例,下一轮循环里上下文里的 agent 字段被替换为 B,B 用俳句回。整个流程就是这。
它怎么工作(架构)
看 swarm/core.py。整个文件就两个核心类和一个 run loop。
两个原语:
Agent:一个 dataclass,字段是name、instructions、functions、model。instructions 是 system prompt,functions 是 tools 列表。没有别的。- handoff:没有任何类。一个普通 Python 函数,返回值是 Agent 实例。仅此而已。Swarm 在 run loop 里检查工具返回值,做一个
isinstance(result, Agent)判断,是 Agent 就替换,不是就当普通结果。
run loop 干了什么:
while True:
completion = client.chat.completions.create(
model=agent.model,
messages=messages,
tools=tools_from(agent.functions),
)
if no tool_call: return
execute tool_calls
if any result is Agent: agent = that_agent; continue
append results to messages; continue
无状态。无持久化。每轮 messages 数组完整发给 OpenAI。
Swarm 的"客户端运行"是这个意思:所有对话历史在你本地内存里,每次 run 都是从头构造 messages 数组传过去。这跟 Assistants API 的服务端 thread 完全相反。
跟你手写 Chat Completions 几乎一样。Swarm 帮你做了什么?帮你把 tools 从 Python 函数转成 OpenAI schema,帮你处理 tool_call 的 dispatch,帮你写好"if result is Agent then handoff"的几行代码。剩下的全是 OpenAI API 原生调用。
它哪里好
心智模型极简。两个概念(Agent + handoff 函数)撑起所有例子。examples/ 目录里 6 个 demo:basic、triage_agent、weather_agent、airline、support_bot、personal_shopper。每个文件 100-200 行,把 agent 定义列出来你就能看懂它在干嘛。
客户端可调试。break point 打 client.run 里,所有 messages、tool calls、handoff 决策都在本地,断点下去全看见。Assistants API 永远做不到这点。
代码量小到可以通读。我读完 swarm/core.py 和两个 utility 文件花了不到两小时,加上把 examples 跑了一遍大概三小时。出来之后我对 multi-agent 的运行时机制比读十篇博客清楚。
对工具的定义就是普通的 Python 函数。没有 magic decorator,没有注册中心。def 一个函数,传给 Agent 就行。如果函数返回字符串,放进 messages 里。如果返回 Agent,做 handoff。就这一个分支。
它哪里不好
没持久化。进程一停,对话历史全丢。要重连就得你手动序列化 messages。生产环境基本等于不可用。
没错误恢复。tool call 失败、网络抖动、超时——Swarm 不管这些。它假设 OpenAI API 永远稳定返回。
没 tracing。没有 span、没有 token usage 统计(除了 OpenAI 返回的那个 usage 字段)、没有工具调用层级视图。调试复杂 multi-agent 对话你只能 print。
没图编排。handoff 是串行单向的。要 A→B→A→C 这种带循环、带条件分支的流程?Swarm 写不出来。LangGraph 写出来一行。
每次 handoff 都把完整 messages 重发。这是隐藏成本。Agent A 聊了 10 轮,handoff 到 B,B 的 system prompt 替换了,但前面 10 轮的 messages 一字不漏全发给模型。tokens 翻倍往上走。
README 里 OpenAI 自己写了一段免责:Swarm 不是 Assistants API、不生产就绪、不要用于真实场景。说得很清楚,免得大家把 Swarm 当作 OpenAI 的"官方 multi-agent 框架"——它不是。
我试了下
跑 examples/weather_agent:"北京天气怎么样",5 个工具调用一轮搞定。triage agent 路由到 weather agent,查位置、调天气 API、格式化输出。整轮 ~2 秒,~800 tokens。单 Agent 体验流畅,没有 handoff 跳跃。
跑 examples/airline:复杂得多。这是个客服场景,五个子 Agent:booking、refund、seat、flight_status、triage。我问"我想把下周的 SF 航班改到 LA、再要个靠窗座位、再改个时间",触发了 3-4 次 handoff:triage → booking(改签)→ seat(靠窗)→ booking(改时间)。
观察到的两件事:
- tokens 消耗大约是单 Agent 的 2-3 倍。每次 handoff 完整 messages 重发,加上每个 sub-agent 自己的 system prompt 也叠加进总 tokens。我这一轮总消耗 ~3,500 tokens。
- 延迟从单 Agent 的 ~1s 涨到 4-6s。handoff 是串行的,每跳一次就多一次 Chat Completions 往返。如果你的 handoff 链路是 N 跳,延迟就是 N 倍。
这两个数字符合 Swarm 的设计预期——它没有并发、没有 shortcuts,就是一步一步走。
谁该用 / 不该用
该用:
- 想理解 multi-agent 心智模型的工程师。读 Swarm 源码比读任何教程都直接。
- 教学场景。教 handoff、tool call、context 传递,Swarm 是最干净的例子。
- 快速 prototype 试 handoff 思路。如果你在评估要不要上 LangGraph,先用 Swarm 跑一版看 multi-agent 到底对不对路。
不该用:
- 任何生产系统。官方明确写了,去用 OpenAI Agents SDK(swarm 的官方继任者,有持久化、有 tracing、有 session 管理)。
- 需要并行、持久化、条件分支的复杂场景。直接上 LangGraph 或 AutoGen,不要在 Swarm 上硬补功能。
结论很直接:把 Swarm 当教材,不当工具。它的源码是 2024-2025 年间最值得通读的多 Agent 实现之一,因为它没什么东西好读——整个心智模型就是"Agent + handoff 函数"。从这出发,再去看 LangGraph 的图、Agents SDK 的 session,你才知道那些框架在解决什么、它们多出来的复杂度换来了什么。
源码在 github.com/openai/swarm,clone 下来两小时读完,比你看十篇"multi agent 入门"博客都值。
来源
https://github.com/openai/swarm