OpenAI Swarm：轻量级多智能体编排框架

图1：OpenAI Swarm 官方 Logo

一、背景故事：为什么 OpenAI 要做一个"教育框架"？

2024年末，OpenAI 发布了一个颇为另类的开源项目——Swarm。它不是一个新模型，不是一个新 API，而是一个纯粹的"教育性质多智能体编排框架"。

这背后有一个重要的行业背景。随着大语言模型（LLM）能力越来越强，如何让多个 AI Agent 协作完成复杂任务，成了业界最热门的研究课题之一。从 LangChain Agents 到 AutoGen，从 CrewAI 到 Microsoft 的 Semantic Kernel，各路框架都在争夺"最佳 Agent 编排方案"的称号。

OpenAI 在这个时间点入场，选择了"教育"而非"生产"——他们坦诚地告诉开发者：Swarm 不是为生产环境设计的，它是用来探索和学习的。这种坦诚反而让它成为了理解多智能体协作原理的最佳起点。

图2：Swarm 核心架构图：两个 Agent 之间通过 Handoff 实现任务交接

二、核心概念：用最少的抽象，讲清楚 Agent 协作

Swarm 的设计哲学是"以少胜多"。整个框架只有两个核心抽象：

1. Agent（智能体）

Agent 是最小的执行单元，包含三个组成部分：

组成部分	说明
instructions	Agent 的行为指令，可以是字符串，也可以是一个动态生成指令的函数
functions	Agent 可以调用的工具函数列表
model	底层调用的模型，默认 gpt-4o

一个最简单的 Agent 长这样：

from swarm import Swarm, Agent

client = Swarm()

agent_a = Agent(
    name="Agent A",
    instructions="You are a helpful agent.",
    functions=[some_function],
)

response = client.run(agent=agent_a, messages=[...])

2. Handoff（交接）

Handoff 是 Swarm 最精妙的设计。当一个 Agent 认为另一个 Agent 更适合处理当前任务时，它可以"交接"——把对话控制权完全转移给另一个 Agent。这个过程是完全透明的，第二个 Agent 继承了整个对话上下文。

这解决了多 Agent 协作中最棘手的问题：上下文如何传递？谁是当前主 Agent？如何优雅地退出和交接？

传统的方案需要开发者自己维护复杂的状态机，而 Swarm 把这一切简化成了函数返回值。

三、技术架构：200行核心代码讲清楚一切

Swarm 的代码库极简，整个 swarm/ 目录只有 4 个文件，总计约 13KB：

文件	行数	职责
core.py	~300行	核心逻辑：Swarm 类、run() 方法、流式输出处理
types.py	~50行	数据模型：Agent、Response、Result（Pydantic）
util.py	~100行	工具函数：function_to_json、debug_print、merge_chunk
__init__.py	~5行	公共 API 导出

核心运行流程（Swarm.run() 方法）：

1. 初始化对话历史，加入 Agent 的 instructions 作为 system prompt
2. 调用 Chat Completions API（底层仍是熟悉的 gpt-4o）
3. 若返回 tool_calls → 执行工具函数 → 更新上下文
4. 若工具函数返回另一个 Agent → 切换 active_agent
5. 若无需工具调用 → 结束，返回 Response

关键实现细节：

• 无状态设计：Swarm 完全依赖 Chat Completions API，每次调用是独立的，不存储任何会话状态。这与 Assistants API 有本质区别——后者有内置的线程管理，而 Swarm 把状态管理完全交给了开发者。
• 流式输出：支持 SSE 流式响应，方便实时展示 Agent 思考过程。
• 并行工具调用：默认开启 parallel_tool_calls，允许模型同时调用多个函数。

四、9个示例场景：从入门到实战

Swarm 提供了 9 个精心设计的示例，覆盖了不同复杂度的应用场景：

示例	场景描述	涉及概念
basic	最简单的 Agent 调用入门	Agent、run()
triage_agent	分诊 Agent 路由到对应专家	Handoff、条件路由
customer_service	完整客服场景，多 Agent 协作	多 Agent 切换、工具调用
customer_service_streaming	客服场景 + 流式输出	流式响应
customer_service_lite	轻量版客服	简化版协作
airline	航空客服场景	领域特定工具
weather_agent	天气查询 Agent	外部 API 集成
personal_shopper	个人购物助理	多轮对话、工具组合
support_bot	通用支持机器人	综合示例

这些示例的设计思路非常明确：用最少的代码展示最多的模式。每个示例都在 100-200 行以内。

五、依赖与技术栈

Swarm 的依赖极为克制：

openai >= 1.33.0   # 必须依赖，调用 Chat Completions API
numpy              # 数据处理
requests           # HTTP 请求
tqdm               # 进度条（调试用）
instructor          # 结构化输出（工具调用相关）
pytest             # 测试框架

Python 版本要求 ≥ 3.10，这意味着它可以利用结构化类型注解（typing.Annotated 等新特性）。

六、部署体验：两分钟跑起来

作为纯 Python 库，Swarm 的部署没有门槛：

pip install git+https://github.com/openai/swarm.git

安装完成后，两行代码即可运行第一个 Agent。无需 Docker，无需 GPU，CPU 即可运行，内存占用不超过 512MB。

这与同期的一些重型 Agent 框架形成了鲜明对比——那些框架动辄需要 GPU、复杂的容器编排，而 Swarm 让你可以在任何一台笔记本上开始实验。

七、重要警告：它已被官方放弃

⚠️ OpenAI 官方已明确表示：Swarm 被 OpenAI Agents SDK 取代。

这意味着：

• Swarm 不会再有新功能
• 不会有 Bug 修复
• OpenAI 官方推荐所有用户迁移到 Agents SDK

但 Swarm 的设计思想（Agent + Handoff 模式）会在 Agents SDK 中延续。因此，学习 Swarm 仍然是理解 OpenAI 多 Agent 理念的最佳途径——它足够简单、足够透明。

八、行业意义与启示

Swarm 虽然已停止维护，但它揭示了几个重要的行业趋势：

1. 多 Agent 协作是下一个主战场。 单 Agent 的能力有上限，而多 Agent 协作可以突破这个上限。Swarm 证明了用极简抽象就能表达复杂的协作模式。

2. "教育优先"正在成为大厂策略。 OpenAI、Google、Meta 都开始通过开源教育性代码来建立生态影响力，而非直接推出封闭产品。这种策略让开发者以低成本探索前沿技术，同时也为未来的商业产品培育了用户习惯。

3. 框架的终局可能是语言特性。 当前 Agent 编排还需要大量框架代码，未来这些模式可能会被直接嵌入到编程语言或模型 API 中。Swarm 的探索为这个方向提供了宝贵的经验。

---

总结：OpenAI Swarm 是一个设计极为精炼的多 Agent 编排实验性框架，用约 200 行核心代码阐明了 Agent + Handoff 的协作模式。它不是生产工具，而是理解多智能体系统的最佳教科书。对于想深入理解 AI Agent 协作原理的开发者而言，Swarm 值得细细研读。