21,909 stars を獲得し、GitHub で OpenAI Solutions Team が公開していたこのリポジトリ。README の先頭には、こう記されている。「This repo is no longer maintained. We've moved development to the OpenAI Agents SDK」。OpenAI 自身が保守終了を明言したプロジェクトにもかかわらず、なぜソースコードを読む価値があるのか。
理由は、Swarm が multi-agent における「最小の実行単位」だからだ。必要な抽象は Agent と handoff の2つだけ。フレームワークの中核である swarm/core.py は400行にも満たず、グラフ、状態永続化、状態機械すら存在しない。コードを追いさえすれば、multi-agent が何をしているのか、なぜその設計が必要なのか、そしてどのような問題があるのかが見えてくる。
何解决的问题を解くのか
multi-agent の協調を理解するには、できるだけ小さな思考モデルが必要だ。
LangGraph は少し重い。まず StateGraph、Node、Edge、Conditional Edge といった概念を学ばなければ、基本的な demo も動かせない。Assistants API はブラックボックス気味で、対話状態は OpenAI のサーバー側に置かれる。ローカルで確認できるものは、実質的に logs だけだ。
その点、Swarm が示す目標は明確だ。わずか5分で handoff の基本を動かせる。1つの Agent の tools に、別の Agent を返す関数を登録する。実行時にツールの戻り値が Agent のインスタンスなら、会話の担当をその Agent に渡す。これ以上の仕組みはない。
この primitives の名前は 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 インスタンスを返し、次の loop で context 内の agent 字段が B に置き换わる。その結果、B が俳句で回答する。全体の流れはこれだけだ。
内部構造
swarm/core.py を見てみよう。ファイルの中核は、2つの class と1つの run loop からなる。
2つの primitives:
Agent:name、instructions、functions、modelを字段に持つ dataclass だ。instructionsは system prompt、functionsは tool 一覧を表す。それ以外の仕組みはない。- handoff:専用の class すらない。通常の Python 関数が
Agentインスタンスを返す、それだけだ。Swarm は run loop 内で tool の戻り値を確認し、isinstance(result, Agent)を実行する。戻り値が Agent なら担当を切り替え、それ以外は通常の tool result として扱う。
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
stateless で、persistence もない。各 loop で messages 配列全体を OpenAI に送信する。
Swarm における「クライアント側で動く」とはこういうことだ。対話履歴はすべてローカルの memory 内に保持され、run を実行するたびに messages 配列を組み立てて送信する。Assistants API の server-side thread とは、正反対の構成である。
手書きの Chat Completions とほぼ同じだ。では Swarm は何をしてくれるのか。Python 関数を OpenAI schema に変換し、tool_call の dispatch を処理し、「戻り値が Agent なら handoff する」という数行の分岐を用意してくれる。残りはすべて OpenAI API をそのまま呼ぶだけである。
優れている点
思考モデルが極めて小さい。Agent と handoff 函数という2つの概念だけで、すべての example が成り立つ。examples/ ディレクトリには basic、triage_agent、weather_agent、airline、support_bot、personal_shopper という6つの demo がある。どの file も100〜200行程度で、Agent の定義を並べるだけで処理内容を理解できる。
client side で debug しやすい。client.run に breakpoint を張れば、すべての messages、tool calls、handoff の判断をローカルで確認できる。Assistants API では得られない可視性だ。
コード量が少なく、全体を通読できる。swarm/core.py と utility file 2つを読むのに2時間もかからず、examples をすべて動かすまで入れても3時間程度だった。multi-agent の runtime 机制は、10本の blog を読むより源码を1つ通したほうがよく分かる。
tool は通常の Python 関数として定義する。magic decorator も registry もない。def で関数を定義し、Agent に渡すだけだ。文字列を返せば messages に追加され、Agent を返せば handoff になる。分岐はこの1つだけである。
物足りない点
永続化がない。process を止めると、対話履歴がすべて失われる。再接続するには、手動で messages を serialize する必要がある。production environment で使うのは事実上不可能に近い。
error recovery がない。tool call の失敗、network の揺らぎ、timeout を Swarm は処理しない。OpenAI API が常に安定して返答することを前提としている。
tracing がない。span はなければ、token usage の集計も OpenAI が返す usage 字段以外にはない。tool call を階層表示する機能もない。複雑な multi-agent の対話を debug するには、print に頼るしかない。
graph による orchestration がない。handoff は直列かつ単方向だ。Agent A → Agent B → Agent A → Agent C のような loop や condition branch を含む処理は Swarm では表現できない。LangGraph なら簡潔に書ける。
handoff のたびに messages 全体を再送する。これが隐蔽された cost だ。Agent A が10回やり取りした後に B に渡すと、B の system prompt は切り替わるが、それまでの10回分の messages がすべて、そのまま model に送られる。token 数はそのぶん、際限なく増える。
README では OpenAI 自身が免责事项を記している。Swarm は Assistants API ではなく、production ready でもなく、実際の业务に使わないでほしいという主旨だ。Swarm を OpenAI の「公式 multi-agent framework」だと误解しないための、注意書きである。
実行してみた
examples/weather_agent を実行し、「北京天气怎么样」と入力すると、5つの tool call を含む一连の処理が完了した。triage agent が weather agent へと route し、位置を调べ、天气 API を呼び、結果を format して出力する。処理全体は約2秒、约800 tokens だった。単一 Agent の体验は顺畅で、handoff の段差も感じさせない。
examples/airline はかなり复雑だ。これは客服シナリオで、booking、refund、seat、flight_status、triage という5つの sub-agent 构成的となる。「来周の SF 行き flight を LA に変更し、窓側の席も確保して、時間も変えたい」と入力すると、3〜4回の handoff が発火した。triage → booking(変更)→ seat(窓側)→ booking(时间変更)といった流れである。
结果是っきりした点が2つある。
- token 消费は単一 Agent の约2〜3倍。每次 handoff で messages 全体が再送され、さらに各 sub-agent 自身の system prompt も総 token 数に加算される。この一连の処理では约3,500 tokens を消费した。
- latency は単一 Agent の约1秒から4〜6秒へ增加。handoff は直列で、迁移するたびに Chat Completions の往復が1回増える。handoff の連锁が N 回なら、latency も N 倍に近くなる。
この2つの数値は、Swarm の设计から予想できる结果そのものだ。concurrency も shortcut もなく、ただ一歩ずつ处理する。
向いている人、向いていない人
向いているケース:
- multi-agent の思考モデルを理解したい engineer。Swarm の源码は、どの tutorial よりも直接的だ。
- 教育现场。handoff、tool call、context の受け渡しを教えるには、Swarm ほど干净な例はない。
- handoff のアイデアを短时间で prototype したい场合。LangGraph を采用すべきか検讨しているなら、まず Swarm で実动させ、multi-agent が本当に适しているかを确认できる。
向いていないケース:
- あらゆる production system。公式が明示しているように、OpenAI Agents SDK を使うべきだ。これは Swarm の公式后継者であり、persistence、tracing、session 管理を备える。
- 并行处理、persistence、条件分岐を必要とする复雑なシナリオ。最初から LangGraph または AutoGen を使い、Swarm に不足する机能を後から継ぎ足すべきではない。
结论は明快だ。Swarm は教材として使い、ツールとして使わない。その源码は、2024〜2025年ごろに読む価値のある multi-agent 実装の1つである。読まなければならない量が少ないというのも大きい。思考モデル全体が、「Agent と handoff 函数」だけで成立しているからだ。この出発点から LangGraph の graph や Agents SDK の session を見ると、各 framework が何の問題を解き、追加された复雑性と引き換えに何を得ているのかが分かる。
源码は github.com/openai/swarm にある。clone して2时间ほど読めば、multi-agent の入门 blog を10本読むより価値がある。