重要
Swarm は OpenAI Agents SDK に置き換えられました。これは Swarm の本番環境対応版の進化版です。Agents SDK は重要な改善を備えており、OpenAI チームによって積極的に保守されます。
本番環境のすべてのユースケースでは、Agents SDK への移行をお勧めします。
Python 3.10 以上が必須です
pip install git+ssh://git@github.com/openai/swarm.gitまたは
pip install git+https://github.com/openai/swarm.gitfrom swarm import Swarm, Agent
client = Swarm()
def transfer_to_agent_b():
return agent_b
agent_a = Agent(
name="Agent A",
instructions="You are a helpful agent.",
functions=[transfer_to_agent_b],
)
agent_b = Agent(
name="Agent B",
instructions="Only speak in Haikus.",
)
response = client.run(
agent=agent_a,
messages=[{"role": "user", "content": "I want to talk to agent B."}],
)
print(response.messages[-1]["content"])Hope glimmers brightly,
New paths converge gracefully,
What can I assist?
Swarm は、エージェント間の調整と実行を軽量で、高度に制御可能で、簡単にテストできるようにすることに焦点を当てています。
これは 2 つの基本的な抽象化により実現されます：Agent とハンドオフです。Agent はinstructionsとtoolsを包含し、いつでも会話を別のAgentに引き継ぐことを選択できます。
これらの基本概念は、ツールとエージェントネットワーク間の豊かなダイナミクスを表現するのに十分な力を持ち、急な学習曲線を避けながら、スケーラブルな実世界のソリューションを構築できます。
注記
Swarm Agents は Assistants API の Assistants とは関連がありません。便宜上、同じような名前になっていますが、それ以外は完全に無関係です。Swarm は Chat Completions API によってのみ駆動され、したがってコール間でステートレスです。
Swarm は、軽量でスケーラブルかつ設計段階で高度にカスタマイズ可能なパターンを探索します。Swarm と同様のアプローチは、多数の独立した機能と指示を扱う場合に最適です。これらは単一のプロンプトにエンコードするのが難しいものです。
Assistants API は、完全にホストされたスレッドと組み込みのメモリ管理および取得機能を探している開発者にとって優れたオプションです。一方、Swarm はマルチエージェント オーケストレーションについて学ぶことに関心のある開発者向けの教育的リソースです。Swarm はほぼ完全にクライアント上で実行され、Chat Completions API と同様に、呼び出し間でステータスを保存しません。
/examples をチェックしてインスピレーションを得てください！各例の README で詳しく学べます。
basic: セットアップ、関数呼び出し、ハンドオフ、コンテキスト変数などの基礎的な簡単な例triage_agent: 基本的なトリアージステップを設定して適切なエージェントにハンドオフする簡単な例weather_agent: 関数呼び出しの簡単な例airline: 航空会社のコンテキストで異なるカスタマーサービスリクエストを処理するためのマルチエージェント設定support_bot: ユーザーインターフェースエージェントとヘルプセンターエージェント（複数のツール付き）を含むカスタマーサービスボットpersonal_shopper: 販売と注文の払い戻しを支援できるパーソナルショッピングエージェント
Swarmクライアントをインスタンス化することから始めます（内部的には単にOpenAIクライアントをインスタンス化するだけです）。
from swarm import Swarm
client = Swarm()Swarmのrun()関数はChat Completions APIのchat.completions.create()関数に相当します。これはmessagesを受け取りmessagesを返し、呼び出し間での状態を保存しません。ただし重要なことに、Agent関数の実行、ハンドオフ、コンテキスト変数の参照を処理し、ユーザーに戻る前に複数のターンを実行することができます。
本質的には、Swarmのclient.run()は以下のループを実装しています。
- 現在のAgentから完了を取得する
- ツール呼び出しを実行し、結果を追加する
- 必要に応じてAgentを切り替える
- 必要に応じてコンテキスト変数を更新する
- 新しい関数呼び出しがない場合は、返す
| 引数 | 型 | 説明 | デフォルト |
|---|---|---|---|
| agent | Agent |
呼び出される（最初の）Agent。 | （必須） |
| messages | List |
メッセージオブジェクトのリスト。Chat Completions messagesと同じです。 |
（必須） |
| context_variables | dict |
関数とAgent指示に利用可能な追加のコンテキスト変数の辞書。 | {} |
| max_turns | int |
許可される会話ターンの最大数。 | float("inf") |
| model_override | str |
Agentによって使用されるモデルをオーバーライドするオプション文字列。 | None |
| execute_tools | bool |
Falseの場合、Agentが関数を呼び出そうとするときに実行を中断し、tool_callsメッセージを即座に返します。 |
True |
| stream | bool |
Trueの場合、ストリーミング応答を有効にします。 |
False |
| debug | bool |
Trueの場合、デバッグログを有効にします。 |
False |
client.run()が完了すると（agentとツールへの複数の呼び出しの後の可能性があります）、すべての関連する更新された状態を含むResponseを返します。具体的には、新しいmessages、呼び出された最後のAgent、および最新のcontext_variablesです。これらの値（加えて新しいユーザーメッセージ）を次のclient.run()の実行に渡して、中断したところから相互作用を続けることができます。これはchat.completions.create()と同じようなものです。（run_demo_loop関数は/swarm/repl/repl.py内での完全な実行ループの例を実装しています。）
| フィールド | 型 | 説明 |
|---|---|---|
| messages | List |
会話中に生成されたメッセージオブジェクトのリスト。Chat Completions messagesと非常に似ていますが、メッセージがどのAgentから発信されたかを示すsenderフィールドを持っています。 |
| agent | Agent |
メッセージを処理した最後のAgent。 |
| context_variables | dict |
入力変数と同じですが、変更があればそれを含みます。 |
Agentはinstructionsのセットとfunctionsのセット（加えて以下の追加設定）をカプセル化したもので、実行を別のAgentにハンドオフする機能を備えています。
Agentを「Xをする誰か」として人格化したくなるかもしれませんが、instructionsとfunctionsのセットで定義された非常に特定のワークフローまたはステップ（例えば、ステップのセット、複雑な取得、データ変換の単一ステップなど）を表すのに使うこともできます。これによりAgentは「agent」「workflow」「task」のネットワークに組み合わせることができ、すべて同じプリミティブで表現されます。
| フィールド | 型 | 説明 | デフォルト値 |
|---|---|---|---|
| name | str |
エージェントの名前です。 | "Agent" |
| model | str |
エージェントで使用するモデルです。 | "gpt-4o" |
| instructions | str または func() -> str |
エージェント用の指示です。文字列または文字列を返す呼び出し可能なものです。 | "You are a helpful agent." |
| functions | List |
エージェントが呼び出せる関数のリストです。 | [] |
| tool_choice | str |
エージェントのツール選択（ある場合）です。 | None |
Agent の instructions は会話の system プロンプト（最初のメッセージとして）に直接変換されます。任意の時点で、アクティブな Agent の instructions だけが存在します（例えば、Agent ハンドオフがある場合、system プロンプトは変更されますが、チャット履歴は変更されません）。
agent = Agent(
instructions="You are a helpful agent."
)instructions は通常の str または str を返す関数です。この関数は context_variables パラメーター（client.run() に渡される context_variables で入力されます）をオプションで受け取ることができます。
def instructions(context_variables):
user_name = context_variables["user_name"]
return f"Help the user, {user_name}, do whatever they want."
agent = Agent(
instructions=instructions
)
response = client.run(
agent=agent,
messages=[{"role":"user", "content": "Hi!"}],
context_variables={"user_name":"John"}
)
print(response.messages[-1]["content"])Hi John, how can I assist you today?
- Swarm
Agentは Python 関数を直接呼び出すことができます。 - 関数は通常
strを返すべきです（値はstrにキャストされます）。 - 関数が
Agentを返す場合、実行はそのAgentに転送されます。 - 関数が
context_variablesパラメータを定義する場合、client.run()に渡されたcontext_variablesで入力されます。
def greet(context_variables, language):
user_name = context_variables["user_name"]
greeting = "Hola" if language.lower() == "spanish" else "Hello"
print(f"{greeting}, {user_name}!")
return "Done"
agent = Agent(
functions=[greet]
)
client.run(
agent=agent,
messages=[{"role": "user", "content": "Usa greet() por favor."}],
context_variables={"user_name": "John"}
)Hola, John!
Agent関数呼び出しにエラー（関数がない、引数が間違っている、エラーがある）がある場合、エラーレスポンスがチャットに追加され、Agentは正常に回復できます。Agentによって複数の関数が呼び出される場合、それらはその順序で実行されます。
Agent は関数で別の Agent を返すことによってハンドオフできます。
sales_agent = Agent(name="Sales Agent")
def transfer_to_sales():
return sales_agent
agent = Agent(functions=[transfer_to_sales])
response = client.run(agent, [{"role":"user", "content":"Transfer me to sales."}])
print(response.agent.name)Sales Agent
また、より完全な Result オブジェクトを返すことで context_variables を更新することもできます。これは value と agent も含むことができ、単一の関数が値を返し、エージェントを更新し、コンテキスト変数を更新したい場合（またはこれらの3つの任意のサブセット）に便利です。
