OpenAI Swarm

OpenAI Swarm 深度评测：优秀的 Handoff 教材，但 2026 年不应作为生产框架

OpenAI Swarm 是用两个 primitive 探索多 Agent 编排的小型 Python 框架：Agent 与 handoff。官方 README 现在明确标注它是“experimental, educational”，声明 OpenAI Agents SDK 已经取代 Swarm，并建议所有生产用例迁移。这一事实必须放在功能列表之前：Swarm 适合读源码和学习模式，不是 OpenAI 当前的生产推荐。

GitHub 仓库截至核查日并没有打开 archived 标志，最后可验证提交是 2026 年 4 月 15 日，将 pre-commit hooks 固定到 immutable commit。这属于维护与 supply-chain 收紧，不是新 runtime release。仓库没有正式 GitHub Releases，安装仍直接指向 Git repository。因此“未归档”不能推翻 README 的明确替代说明。

Swarm 仍值得学习，因为实现非常透明：routine 基本是 instructions 加 functions；某 function 返回另一个 Agent 就发生 handoff；context_variables 让应用数据影响 instruction 与 function；client loop 调用 Chat Completions、执行工具、合并 context update，并可切换 active agent。源码越小，越容易看见生产系统还缺了多少层。

2026 年项目状态

Swarm 真正教授的抽象

可执行的 Handoff 实验

做一个边界清楚的实验：triage 只把请求分给 sales 或 refund；sales 只有只读 catalog tool；refund 只能“准备退款”，不能真的执行。把经过服务端验证的 customer_id、locale 和订单归属放入 context_variables。Transfer function 返回目标 Agent，同时记录 source、destination、reason，并把 max_turns 设为 5。先用 fake provider 或 sandbox tool，证明路由逻辑，而不是把财务权限交给模型。

先分别测试 routine，再测试网络。给 triage 一组带标签的 billing、sales、ambiguous 与 adversarial 请求，统计 destination accuracy 和无必要 handoff。对每个 specialist 删除不需要的 tool，并验证超出职责时拒绝。随后测试 A→B→A 循环、parallel tool calls、畸形参数、tool exception、跨 tenant 访问，以及藏在订单备注里的 prompt injection。预期结果必须包含“安全失败”，不能只评价回答是否流畅。

context_variables 是应用在一次 run 中传递的数据，不是 secret channel，也不是自动 conversation memory。Dynamic instruction 可能把其中值插入 model prompt，function 也能返回 update。每个 key 都应标注 model-visible 或 code-only；tenant identity 不能由模型选择，长期 credential 不应放进可变 dictionary。权威状态应存入带版本的数据库，每次 run 只重建最小必要 context。

迁移与评测流程

1. 固定 Swarm Git commit、Python 环境和 model 配置，实验也不要依赖未固定的 Git install。
2. 画出所有 Agent、handoff、tool、context key 与 terminal state，标记 cycle 和 privilege increase。
3. 建立去敏 golden set：路由标签、specialist answer、refusal、tool result 与预期安全失败。
4. 在 sandbox 用 fake/只读工具运行，设置 max_turns、timeout 和 deterministic side-effect ledger。
5. 记录 active agent、handoff source/destination/reason、request、tool call ID、参数 hash、result 与 usage。
6. 用 Agents SDK 的 handoff 或 agents-as-tools 以及 typed RunContextWrapper 重建同一流程。
7. 加入 session/run-state、approval、tool guardrail、server authorization、idempotency 和 trace 隐私策略。
8. 对同一 input 做 shadow，对比 route、质量、tool success、turn、latency 和 cost。
9. 先 canary 只读流量，再开放需 approval 的极窄写操作；演练 timeout、crash 与 rollback。
10. 达到功能和安全 parity 后删除 Swarm dependency，保留测试与显式 handoff graph。

应测量什么

迁移首先盘点行为，而不是机械替换 class name。列出所有 Swarm Agent、instruction、function、transfer edge、context key、model setting、max turn、stream event 与外部副作用。画出真实 handoff graph，标记 cycle、terminal agent 和 privilege increase。对代表性 transcript 与 tool trace 去敏后固化 golden set；短期固定 Swarm commit 和 model snapshot，得到可比较 baseline。

在 Agents SDK 中，把 Swarm Agent 映射为受维护的 Agent，把 transfer function 映射为 handoffs 或定制 handoff()，把 context_variables 映射为类型化 RunContextWrapper。Specialist 应直接接管对话时使用 handoff；manager 应保留用户交互控制权时使用 Agent.as_tool()。Conversation memory 只选 session、to_input_list() 或 OpenAI-managed continuation 之一，避免重复 history。

迁移时加入生产控制，不要复刻 Swarm 的缺口。Tool 可以要求 approval、timeout、input/output guardrail；run state 可用于 interrupt/resume；tracing 记录 generation、tool、handoff 与 guardrail。Agents SDK 的 tracing 默认开启，可能包含敏感 input/output，因此要配置删除敏感信息，或在政策要求下禁用。即使有 guardrail，服务端授权仍不能省略。

安全、状态与运维限制

Swarm 与当前替代方案

Swarm 不提供 durable state、scheduler、distributed execution、authentication、tenant isolation、retry ledger、cost budget 或生产 trace store。进程若在副作用执行后、tool result 写回前崩溃，重试会产生歧义。高影响操作要使用绑定业务操作的 idempotency key、transactional outbox、tool timeout、per-user rate limit、max turns 和 human escalation。还应检测重复 agent edge，而不只依赖全局 turn ceiling。

handoff 改变可用工具时，prompt injection 的风险会增大。用户文本、retrieved record 与 tool output 都是不可信数据，文档中的“请转交退款 Agent”不能成为真实 route instruction。Tool boundary 必须使用服务端 identity 授权，验证目标账户与金额，限制网络 destination，最小化 credential，并对不可逆行为要求批准。Policy decision 应单独记录，不能只保存模型的自然语言 reasoning。

编辑结论：Swarm 仍是理解 handoff 的最佳微型源码之一。缺少复杂 machinery 在教学上是优点，因为 loop 一眼可见；同一缺点使它不适合新生产项目，尤其官方已有 successor。正确做法是读源码、复现实验，然后迁移“模式”而非保留 dependency；最终选择 Agents SDK、LangGraph 或其他 runtime，应由 durability、provider 与组织控制需求决定。

常见问题

OpenAI Swarm 适合生产吗？

不适合。官方 README 明确称其为实验性、教育性项目，已被 Agents SDK 取代，并建议所有生产用例迁移。

仓库已经 archived 吗？

截至 2026-08-20，GitHub archived flag 为 false；但这不等于生产背书，也不能覆盖官方替代声明。

Swarm 还在维护吗？

2026-04 有维护提交，但没有正式 release。仓库活动不等于仍在演进的生产框架。

Handoff 是什么？

类似 tool 的控制权转移。在 Swarm 中，function 返回另一个 Agent 时，active agent 改变。

context_variables 是会话记忆吗？

不是。它是一次 run 的应用数据；conversation 与业务状态必须由应用权威持久化。

Swarm 能接非 OpenAI 模型吗？

实现围绕 OpenAI-compatible client/Chat Completions；兼容层可能工作，但不是选择已被替代项目的理由。

Swarm 的替代品是什么？

OpenAI 官方推荐 Agents SDK，它保留轻量 Agent/handoff 概念，并加入受维护的 state、guardrail 与 tracing 等能力。

Guardrail 能代替授权吗？

不能。它能验证或阻止阶段；身份、tenant 与资源授权必须在服务端执行。

每个流程都需要多个 Agent 吗？

不需要。先用单 Agent+tools 或 deterministic workflow；只有职责/tool scope 分离带来可测收益时才增加 handoff。

如何迁移？

固定 baseline，画 handoff graph，映射 context，使用 typed SDK primitive 重建，加入控制，然后 shadow、canary、删除 Swarm。

来源

• Official Swarm repository
• Swarm README: replacement notice
• Swarm source: core loop
• Swarm commits
• Swarm releases
• Swarm MIT license
• OpenAI Agents SDK quickstart
• Agents SDK handoffs
• Agents SDK context
• Agents SDK guardrails
• Agents SDK running and state
• Agents SDK tracing
• LangGraph overview
• AutoGen AgentChat
• AutoGen handoff pattern
• CrewAI documentation

独立核查日期：2026 年 8 月 20 日。仓库标志、commit 与 successor API 会变化；实现前请重新核对官方 README 和当前 Agents SDK。