OpenAI Agents SDK

OpenAI Agents SDK は、コードでエージェントを構築するための OpenAI のフレームワークである。 エージェント構築の実践ガイド はすべての実例でこのライブラリを用いているが、同じ概念は 好みの任意のライブラリで実装することも、ゼロから直接構築することもできると述べている。つまり同ガイドは、これを 自らのパターンの必須要件ではなく、パターンを実現する一つの手段として提示している。

基本単位は、名前、指示の集合、ツールのリストで宣言される Agent である。ガイドの最初の例は、単一の get_weather ツールを与えられた天気エージェントであり、関数は @function_tool デコレーターによってツールに変換される。 WebSearchTool のような組み込みツールも、開発者自身のツールと並べて列挙できる。

SDK の Python リポジトリは、これをマルチエージェントのワークフローを構築するための軽量かつ強力なフレームワークで あり、プロバイダー非依存であると説明している。OpenAI の Responses API と Chat Completions API に加えて、100 を 超える他の LLM にも対応する。Python パッケージ openai-agents は Python 3.10 以降を必要とし、MIT License で 公開されている。プルリクエストはリポジトリのコラボレーターからのみ受け付けている。SDK は JavaScript/TypeScript パッケージ @openai/agents としても配布されており、そのリポジトリには独自のエージェントパターンの実例集が 含まれている。

機能

Python の README は 10 のコア概念を挙げている。エージェント（指示、ツール、ガードレール、ハンドオフで構成された LLM）。長い時間軸にわたってコンテナで作業するようあらかじめ構成されたサンドボックスエージェント。音声向けの リアルタイムエージェント。音声認識、エージェントのワークフロー、音声合成のパイプラインとして構築される 音声エージェント。他のエージェントへの委任のためのツールとしてのエージェントとハンドオフ。関数、MCP、ホスト型ツールを 含むツール。設定可能な入力・出力の検証としてのガードレール。エージェントの実行をまたぐヒューマン・イン・ザ・ループの 仕組み。実行をまたいで会話履歴を自動的に管理するセッション。そして、エージェントの実行を記録してワークフローを 閲覧・デバッグ・最適化できるようにするトレーシングである。

README はエージェントを実行する主な方法を 4 つ示している。テキストの Agent は、永続的なリアルタイム接続も サンドボックスのワークスペースも必要としないワークフローに適する。SandboxAgent は、ファイルの検査、コマンドの 実行、パッチの適用、あるいは長いタスクにわたるワークスペース状態の保持が必要な作業のためのものである。README の 例では、マニフェストを通じて Git リポジトリをワークスペースにマウントし、macOS と Linux で対応するローカルの Unix サンドボックスクライアントで実行する。Windows では Docker クライアントまたはホスト型のサンドボックスクライアントが 代替となる。RealtimeAgent は WebSocket 上で低遅延のサーバーサイドの音声およびマルチモーダルのセッションを 提供し、VoicePipeline は音声をテキストに変換し、エージェントのワークフローを実行し、生成した音声を ストリーミングで返す。

エージェントは Runner.run() メソッドで起動され、このメソッドは終了条件が満たされるまで LLM に対するループを 回す。ガイドはこの SDK に固有の終了条件として 2 つを挙げている。特定の出力型で定義された最終出力ツールが 呼び出された場合と、モデルがツール呼び出しをまったく含まない応答を返した場合である。ガイドはこのループを、SDK の 細部ではなく、あるものをエージェントたらしめる中核的な要素として扱っている。

SDK はガイドが説明する 2 つのマルチエージェントの形態の両方に対応している。 マネージャーパターン（マネージャーパターン）では、専門エージェントを as_tool(...) でツールに変換し、 ツール名と説明を与えて、マネージャーエージェントの tools 配列に列挙する。分散型パターン （分散型パターン）では、ハンドオフそれ自体が一種のツールまたは関数である。エージェントは別のエージェントの handoffs 配列に列挙され、ハンドオフを呼び出すと、最新の会話状態を引き渡しつつ、ハンドオフ先のエージェントで 直ちに実行が始まる。

ガードレール（ガードレール）は SDK の第一級の概念と説明されている。ガードレールは @input_guardrail でデコレートされた関数として記述され、GuardrailFunctionOutput を返す。その tripwire_triggered フィールドが 処理を中断するかどうかを決める。ガードレールはエージェントの input_guardrails リストを通じてエージェントに 取り付けられ、トリップワイヤーが作動すると、呼び出し側が捕捉できる GuardrailTripwireTriggered 例外として 表面化する。ガイドによれば、SDK はデフォルトで楽観的実行に依拠している。すなわち、主エージェントが出力を生成する 間にガードレールが並行して実行され、制約違反があれば例外を送出する。ガイド自身の例では、LLM ベースの解約検知 エージェントをこのようなガードレールとして組み込んでいる。

SDK はまた、個々のツール呼び出しのレベルで ヒューマン・イン・ザ・ループ（ヒューマン・イン・ザ・ループ）の 承認ゲートを提供する。@openai/agents リポジトリの例では、ツールと、asTool(...) によってツールとして公開された エージェントに needsApproval 述語を付与している。この述語はツール全体に対してではなく、モデルがその呼び出しの ために生成した引数に対して評価されるため、同じツールがある入力では無人で実行され、別の入力では承認を必要とする ということが起こりうる。述語が作動すると呼び出しは実行されず、実行は interruptions のリストを伴って終了する。 各割り込みは、エージェント、ツール名、判断待ちの生成済み引数を特定する。ホストアプリケーションは、実行の状態 オブジェクトに対して approve または reject を呼び出して各割り込みを解決し、その同じ状態でエージェントを再び 開始する。例では割り込みが残らない状態で実行が完了するまでこれを繰り返すため、再開された実行がさらに独自の承認を 求めることもありうる。この仕組みはストリーミング実行でも機能し、例では承認ステップの前後の両方で実行のテキスト ストリームを標準出力にパイプしている。

導入とエコシステム

ガイドはこの SDK を、ガイドが宣言的フレームワークと呼ぶもの、すなわちすべての分岐、ループ、条件分岐をノードと エッジのグラフとして事前に定義することを要求するフレームワークと対比して位置づけている。ガイドによれば、その アプローチは視覚的な明快さをもたらすものの、ワークフローが動的になるにつれて扱いにくくなり、しばしば専用の ドメイン固有言語を必要とする。一方 Agents SDK は、より柔軟なコードファーストのアプローチをとり、ワークフローの ロジックを馴染みのあるプログラミング構文で表現し、グラフを事前に定義する必要がないと説明している。この比較は、 名前の挙げられていない代替手段に対してベンダー自身が自社製品を位置づけたものである。