これは OpenAI Realtime API と OpenAI Agents SDK を使用した、音声エージェントのより高度なパターンのデモンストレーションです。
このプロジェクトは OpenAI Agents SDK を使用しており、高度な AI エージェントの構築、管理、デプロイメントのためのツールキットです。SDK は以下を提供します：
- エージェントの動作とツール統合を定義するための統一インターフェース。
- エージェントオーケストレーション、状態管理、イベントハンドリングの組み込みサポート。
- OpenAI Realtime API との簡単な統合により、低遅延でストリーミングなインタラクションが可能です。
- マルチエージェント協業、ハンドオフ、ツール使用、ガードレールのための拡張可能なパターン。
完全なドキュメント、ガイド、API リファレンスについては、公式の OpenAI Agents SDK ドキュメント を参照してください。
注意： OpenAI Agents SDK を使用しないバージョンについては、without-agents-sdk ブランチ を参照してください。
以下の 2 つの主要なパターンが示されています：
- チャット-スーパーバイザー： リアルタイムベースのチャットエージェントはユーザーと対話し、ユーザーへのグリーティング、カジュアルな会話、情報収集などの基本的なタスクを処理します。より知的でテキストベースのスーパーバイザーモデル（例：
gpt-4.1）がツールコールや、より複雑な応答を処理するために広く使用されます。このアプローチは簡単なオンランプと高品質な回答を提供し、わずかなレイテンシの増加があります。 - 連続的なハンドオフ： 特殊化されたエージェント（リアルタイム API で搭載）がユーザーを転送して、特定のユーザーインテント を処理します。これは、ユーザーのインテントが特定のドメインで優れた専門家モデルによって順序立てて処理できるカスタマーサービスに最適です。これは、すべての指示とツールを単一エージェントに含めることで、パフォーマンスが低下するのを避けるのに役立ちます。
- これは Next.js TypeScript アプリです。
npm iで依存関係をインストールしてください。 OPENAI_API_KEYを環境に追加してください。.bash_profileまたはそれに相当するものに追加するか、.env.sampleを.envにコピーして追加してください。npm run devでサーバーを起動してください。- ブラウザを http://localhost:3000 で開いてください。デフォルトは
chatSupervisorエージェント設定になります。 - 右上の「Scenario」ドロップダウンで例を変更できます。
これは chatSupervisor エージェント設定で示されています。チャットエージェントは Realtime モデルを使用してユーザーと会話し、ユーザーへのグリーティング、カジュアルな会話、情報収集などの基本的なタスクを処理します。より知的でテキストベースのスーパーバイザーモデル（例：gpt-4.1）がツールコールと、より複雑な応答を処理するために広く使用されます。決定境界を「オプトイン」することで、必要に応じて特定のタスクをチャットエージェントに処理させるように制御できます。
ビデオウォークスルー：https://x.com/noahmacca/status/1927014156152058075
このやり取りでは、電話番号を収集するための即座の応答と、ツールコールを処理して応答を作成するスーパーバイザーエージェントへの転送に注目してください。「give me a moment to check on that.」が話されるのが終わるのと、「Thanks for waiting. Your last bill...」が始まるのの間には約 2 秒です。
sequenceDiagram
participant User
participant ChatAgent as Chat Agent<br/>(gpt-4o-realtime-mini)
participant Supervisor as Supervisor Agent<br/>(gpt-4.1)
participant Tool as Tool
alt Basic chat or info collection
User->>ChatAgent: User message
ChatAgent->>User: Responds directly
else Requires higher intelligence and/or tool call
User->>ChatAgent: User message
ChatAgent->>User: "Let me think"
ChatAgent->>Supervisor: Forwards message/context
alt Tool call needed
Supervisor->>Tool: Calls tool
Tool->>Supervisor: Returns result
end
Supervisor->>ChatAgent: Returns response
ChatAgent->>User: Delivers response
end
- オンボーディングの簡素化。 既に性能の良いテキストベースのチャットエージェントがあれば、同じプロンプトとツールセットをスーパーバイザーエージェントに提供し、チャットエージェントのプロンプトに若干の調整を加えるだけで、テキストエージェント同等のパフォーマンスを発揮する自然な音声エージェントを構築できます。
- 完全なリアルタイムエージェントへのシンプルな段階的移行: エージェント全体をリアルタイム API に切り替えるのではなく、1 つずつタスクを移行でき、本番環境にデプロイする前に各タスクを検証して信頼を構築する時間が持てます。
- 高い知能:
gpt-4.1のようなモデルの高い知能、優れたツール呼び出し能力、命令遵守能力の恩恵を音声エージェントで受けられます。 - コストの削減: チャットエージェントが基本的なタスクにしか使用されていない場合、realtime-mini モデルを使用できます。これは gpt-4.1 と組み合わせても、完全な 4o-realtime モデルを使用するより安価です。
- ユーザーエクスペリエンス: ユーザーが話し終わった後のレスポンスレイテンシーが 1.5 秒以上になることが多い複合モデルアーキテクチャよりも、より自然な会話体験です。このアーキテクチャでは、スーパーバイザーエージェントに頼ることになっても、モデルはユーザーに即座に応答します。
- ただし、すぐに完全な応答をするのではなく、より多くのアシスタントレスポンスが「Let me think」で始まります。
- supervisorAgent を更新します。
- 既存のテキストエージェントのプロンプトとツールがあれば、それらを追加してください。これは音声エージェントロジックの「中核部分」を含む必要があり、何をするべき・すべきでないか、また正確にどのように応答すべきかについて非常に具体的である必要があります。この情報を
==== Domain-Specific Agent Instructions ====の下に追加してください。 - このプロンプトは音声に適したものに更新することをお勧めします。例えば、簡潔さを心がけ、長いリストの項目を避けるなどの指示を含めるとよいでしょう。
- chatAgent を更新します。
- chatAgent の指示を自分のトーン、挨拶などでカスタマイズしてください。
- chatAgentInstructions にツール定義を追加してください。モデルが混乱してツールを直接呼び出そうとしないよう、JSON ではなく簡潔な YAML 説明をお勧めします。
# Allow List of Permitted Actionsセクションに新しい項目を追加することで、判定境界を変更できます。
- コストを削減するために、chatAgent に
gpt-4o-mini-realtimeを、スーパーバイザーモデルにgpt-4.1-miniを使用してみてください。特に難しいまたはハイリスクなタスクで知能を最大化するには、レイテンシーと引き換えにスーパーバイザープロンプトに連鎖思考を追加することを検討するか、o4-miniを使用する追加の推論モデルベースのスーパーバイザーを使用してください。
