フレームワーク

OpenAI Swarm 源码解剖──公式が後継へ移した最小の multi-agent 設計

OpenAI が公開した Swarm は、21,000以上の GitHub stars を集めたものの、現在では Agents SDK に開発が移行している。とはいえ、Agent と handoff だけという極めて小さい設計は、multi-agent の基本原理を理解するための最良教材でもある。

文字サイズ

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本読むより価値がある。

来源

https://github.com/openai/swarm

出典: https://github.com/openai/swarm