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 定義列出來就能看懂在做什麼。
客戶端可除錯。在 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 的約 1 秒漲到 4-6 秒。handoff 是序列的,每跳一次就多一次 Chat Completions 來回。如果你的 handoff 鏈路是 N 跳,延遲就是 N 倍。
這兩個數字符合 Swarm 的設計預期——它沒有併發、沒有捷徑,就是一步一步走。
誰該用 / 不該用
該用:
- 想理解 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 入門」部落格都值。