Swarm-OpenAI

项目概述

Swarm 是 OpenAI 发布的一个实验性、教育性框架，旨在探索轻量级、符合人体工程学的多智能体编排方式。该仓库由 OpenAI Solution 团队管理，并明确自我描述为实验性示例框架，不适用于生产环境，且没有官方支持，即拉取请求和问题不会被审查。

核心抽象

Swarm 通过两个原始抽象实现其目标：Agents（智能体）和 handoffs（交接）。一个 Agent 包含一组指令和工具，并且可以在任何时刻选择将对话交接给另一个 Agent。这两个原语被认为足以表达工具与智能体网络之间的丰富动态，同时避免了陡峭的学习曲线。

运行机制

Swarm 的 client.run() 函数类似于 Chat Completions API 中的 chat.completions.create()：它接收消息并返回消息，且调用之间不保存任何状态。此外，它还处理 Agent 函数执行、交接、上下文变量引用，并可以在返回给用户之前进行多轮交互，实现一个循环：获取补全、执行工具调用、必要时切换智能体、更新上下文变量。

Swarm 完全由 Chat Completions API 驱动，因此调用之间是无状态的。Swarm 智能体与 Assistants API 明确无关，尽管命名相似。由于几乎完全在客户端运行，Swarm 在调用之间不存储状态，这保持了框架的简单性，但意味着开发者必须自行实现记忆和状态解决方案，以应对更复杂的决策。

工具定义

在 Swarm 中，工具是普通的 Python 函数，Swarm 会自动将其转换为 Chat Completions 工具的 JSON Schema：docstring 成为函数描述，没有默认值的参数被设置为必填，类型提示映射到参数类型。如果函数返回一个 Agent 对象，执行将转移到该 Agent（即交接），函数还可以接受一个 context_variables 参数，该参数由 client.run() 填充。

安装与分发

Swarm 需要 Python 3.10+，并可通过 pip 直接从 GitHub 仓库安装（例如 pip install git+https://github.com/openai/swarm.git）。该框架也以 openai-swarm 包的形式在 PyPI 上分发，并采用 MIT 许可证。

示例与工具

该仓库提供了多个示例，包括 basic（涵盖设置、函数调用、交接和上下文变量等基础知识）、triage_agent、weather_agent、airline、support_bot 和 personal_shopper。其中 airline 示例演示了一个多智能体客户服务设置，其智能体对请求进行分类并处理航班修改、取消和行李丢失等情况，并包含基于函数的评估示例。

Swarm 还包含一些实用函数，如 run_demo_loop，它在命令行上运行一个支持流式传输的交互式 REPL。它还通过 client.run(…, stream=True) 支持流式传输，并添加了分隔事件以指示智能体之间的切换。README 鼓励开发者自带评估套件，并在 airline、weather_agent 和 triage_agent 示例中提供了参考评估。

与 OpenAI Agents SDK 的关系

Swarm 的 README 现在指出，Swarm“已被 OpenAI Agents SDK 取代，后者是 Swarm 的生产级演进”，并建议所有生产用例迁移到 Agents SDK。OpenAI 于 2025 年 3 月发布了 Agents SDK，作为一个“受 Swarm 启发”的开源编排框架，支持其他模型和追踪提供商。

背景与定位

Swarm 将 OpenAI Cookbook 中“Orchestrating Agents: Routines and Handoffs”食谱中探索的“routines and handoffs”思想打包为一个概念验证示例库。该食谱指出，该库仅作为示例，不应直接用于生产环境，并将交接描述为一个智能体通过动态交换系统指令和工具将对话交给另一个智能体。

独立分析强调，Swarm 通过专注于基本概念而不引入复杂抽象，引入了一种简化的、教育性的多智能体系统方法，使用简单的 while 循环控制流，每次只有一个智能体在控制。与 CrewAI、AutoGen、LangGraph 和 LlamaIndex 等框架相比，Swarm 的显著特点是其轻量级、无状态的交接模型。尽管处于实验状态，它仍获得了约 20,000 个 GitHub 星标，但开箱即用时缺乏护栏、追踪、重试和会话管理。