リアルタイムトランスポート
セッションの実行場所と、元のメディアやイベントをどの程度制御する必要があるかに応じて、トランスポートを選択してください。
| シナリオ | 推奨トランスポート | 理由 |
|---|---|---|
| ブラウザーの音声対話アプリ | OpenAIRealtimeWebRTC | 最も手軽な方法です。SDK がマイクからの音声キャプチャ、再生、WebRTC 接続を管理します。 |
| サーバー側で Realtime を制御するブラウザー音声 | アプリが管理する WebRTC 音声とサーバー側の RealtimeSession | ブラウザーが音声を送受信し、Realtime イベント、ツール、ビジネスロジックはアプリケーションサーバーで管理します。 |
| React Native モバイルアプリ | ネイティブ WebRTC を使用する、アプリ管理の RealtimeTransportLayer | SDK は React Native 向けのパッケージ条件を提供し、アプリがネイティブ WebRTC、権限、音声ルーティング、ライフサイクルを管理します。 |
| サーバー側の音声ループやカスタム音声パイプライン | OpenAIRealtimeWebSocket | 音声のキャプチャと再生をすでに制御しており、イベントに直接アクセスしたい場合に適しています。 |
| SIP またはテレフォニーブリッジ | OpenAIRealtimeSIP | callId を使って、SIP で開始された既存の Realtime 通話に RealtimeSession を接続します。 |
| Cloudflare Workers / workerd | Cloudflare 拡張トランスポート | workerd では、グローバルの WebSocket コンストラクターを使って外向きの WebSocket 接続を開くことができません。 |
| Twilio 上のプロバイダー固有の電話フロー | Twilio 拡張トランスポート | Twilio の音声転送と割り込み動作を処理します。 |
デフォルトのトランスポートレイヤー
Section titled “デフォルトのトランスポートレイヤー”ブラウザーのデフォルトとなる WebRTC
Section titled “ブラウザーのデフォルトとなる WebRTC”デフォルトのブラウザートランスポートは WebRTC を使用します。マイクからの音声キャプチャと再生が自動的に行われるため、クイックスタートでは一時トークンと session.connect(...) だけで接続できます。
この方式では、音声の送受信が始まる前に指示とツールが適用されるよう、session.connect() は初期セッション設定の確認応答である session.updated を受信するまで待機してから完了しようとします。確認応答が届かない場合には、タイムアウトによるフォールバックも用意されています。
独自のメディアストリームや音声要素を使用するには、セッションの作成時に OpenAIRealtimeWebRTC インスタンスを指定します。
import { RealtimeAgent, RealtimeSession, OpenAIRealtimeWebRTC,} from '@openai/agents/realtime';
const agent = new RealtimeAgent({ name: 'Greeter', instructions: 'Greet the user with cheer and answer questions.',});
async function main() { // Keep a handle on the stream you pass in. The transport does not stop a caller-supplied // stream on close(), so your application owns it and is responsible for ending it. const mediaStream = await navigator.mediaDevices.getUserMedia({ audio: true, });
const transport = new OpenAIRealtimeWebRTC({ mediaStream, audioElement: document.createElement('audio'), });
const customSession = new RealtimeSession(agent, { transport });
// Later, once the application is actually done with the microphone, release it. Leaving this // out keeps the microphone indicator on even after the session closes. // mediaStream.getTracks().forEach((track) => track.stop());}OpenAIRealtimeWebRTC に渡した mediaStream は、引き続きアプリケーションが所有します。トランスポートを閉じても、そのストリームのトラックは停止しないため、レベルメーター、レコーダー、再接続などに引き続き使用できます。アプリケーションでそのストリームが本当に不要になった時点で、各トラックの stop() を呼び出してください。トランスポートがデフォルトのマイクを自ら開いた場合は、close() によって SDK が所有するトラックが引き続き停止されます。
より低レベルのカスタマイズのために、OpenAIRealtimeWebRTC は changePeerConnection も受け付けます。これにより、オファーが生成される前に、新しく作成された RTCPeerConnection を検査または置換できます。
組み込みのブラウザートランスポートは、ブラウザー側の RealtimeSession が Realtime イベントを使用してセッションの設定と制御を行うため、データチャネルを作成します。これらのイベントと制御をアプリケーションサーバー側に保持する必要がある場合は、ブラウザー側のピア接続のカスタマイズをアクセス制御の境界とみなすのではなく、以下のサーバー側制御パターンを使用してください。
Azure OpenAI の GA プロトコル対応
Section titled “Azure OpenAI の GA プロトコル対応”組み込みの Realtime トランスポートは GA プロトコルで送信します。カスタム URL を設定しても、セッションの更新が Azure の従来のプレビュー形式に変換されるわけではありません。非推奨のリージョン別 realtimertc エンドポイントは、session.type や output_modalities などの GA フィールドを拒否することがあり、その場合、サーバーは同じ更新に含まれる指示とツールを適用できなくなります。
Azure WebRTC については、Microsoft の GA WebRTC セットアップガイドに従ってください。
- アプリケーションサーバーで、Azure リソースの
/openai/v1/realtime/client_secretsエンドポイントから一時クライアントトークンを取得します。Azure リソースの認証情報はサーバー上に保持してください。 RealtimeSessionコンストラクターのmodelオプションを Azure のデプロイ名に設定します。RealtimeAgentに指示と実行可能なツールを定義します。- 一時トークンを
apiKeyとして、リソースのhttps://<resource>.openai.azure.com/openai/v1/realtime/callsURL とともにsession.connect()に渡します。SDK はエージェントの設定をトランスポートに転送します。initialSessionConfigはトランスポートレベルのオプションであり、RealtimeSession.connect()のオプションではありません。
Azure が発行した一時トークンが ek_ で始まらない場合、ブラウザートランスポートのキープレフィックスチェックに対応するため、useInsecureApiKey: true を設定した OpenAIRealtimeWebRTC インスタンスを明示的に使用する必要があります。このオプションが無効にするのはプレフィックスチェックだけです。引き続き一時トークンを渡し、有効期間の長いリソースの認証情報をブラウザーコードに渡すことは絶対に避けてください。
GA を使用する場合は、session.type を削除しないでください。GA ではこのフィールドが必須です。エンドポイントとプロトコルの違いについては、Microsoft のプレビューから GA への移行ガイドを参照してください。
サーバー側の制御とブラウザー音声の組み合わせ
Section titled “サーバー側の制御とブラウザー音声の組み合わせ”アプリケーションによっては、ブラウザーでマイクからの音声キャプチャと再生を行いながら、Realtime イベント、ツール、ビジネスロジックをアプリケーションサーバーで管理する必要があります。このアーキテクチャでは、Realtime API の統合 WebRTC インターフェースとサーバー側の制御を組み合わせます。
- ブラウザーは標準の WebRTC API を使って音声のみのピア接続を作成し、その SDP オファーをアプリケーションサーバーに送信します。ブラウザーは SDK の組み込み WebRTC トランスポートを使用せず、Realtime データチャネルも作成しません。
- アプリケーションサーバーはユーザーを認証し、SDP ポリシーを適用してから、標準の API キーを使って、オファーとサーバーが管理するセッション設定を
/v1/realtime/callsに送信します。 - アプリケーションサーバーは SDP アンサーを検証し、レスポンスの
Locationヘッダーから通話 ID を読み取ります。 - アプリケーションサーバーは WebSocket トランスポートを使用するサーバー側の
RealtimeSessionを作成し、イベントリスナーを登録して、通話 ID をsession.connect(...)に渡し、最初のsession.updatedイベントを待ちます。 - アプリケーションサーバーは SDP アンサーをブラウザーに返します。ブラウザーはそのアンサーをリモートディスクリプションとして設定し、ブラウザーと Realtime API の間で音声が直接送受信されます。
- アプリケーションサーバーは Realtime イベントとツールを処理します。ブラウザーにステータスの更新を送る必要がある場合、アプリケーションサーバーは元の Realtime イベントストリームを転送するのではなく、許可リストにあるアプリケーションイベントに変換して送信します。
音声のみのブラウザーピア接続、サーバーで適用する SDP ポリシー、サイドバンドの RealtimeSession、ブラウザー向けに変換したイベント、クリーンアップ処理を備えた完全なアプリケーションについては、realtime-server-controlled のコード例を参照してください。
React Native でのアプリ管理トランスポートの使用
Section titled “React Native でのアプリ管理トランスポートの使用”@openai/agents-core と @openai/agents-realtime は、React Native 向けのパッケージ条件を公開しているため、Metro は Node.js 組み込みモジュールを使わずに、移植可能な SDK シムを解決できます。組み込みの OpenAIRealtimeWebRTC は、ブラウザーの WebRTC グローバルオブジェクトと DOM 音声要素に依存するため、引き続きブラウザー向けのトランスポートです。React Native では、ネイティブ WebRTC 実装をインストールしてアプリ側で管理し、カスタムの RealtimeTransportLayer を介して RealtimeSession に接続してください。
examples/realtime-react-native の Expo 開発ビルドのコード例では、アプリが管理する react-native-webrtc トランスポート、マイクの権限、音声ルーティング、サーバー側の一時トークンエンドポイントを示しています。react-native-webrtc にはネイティブコードが含まれるため、Expo Go はサポートされていません。標準の OpenAI API キーはサーバー上に保持し、モバイルアプリには有効期間の短い一時クライアントトークンだけを渡してください。
サーバーのデフォルトとなる WebSocket
Section titled “サーバーのデフォルトとなる WebSocket”WebRTC の代わりに WebSocket 接続を使用するには、セッションの作成時に transport: 'websocket' または OpenAIRealtimeWebSocket のインスタンスを渡します。これは、サーバー側のユースケース、テレフォニーブリッジ、カスタム音声パイプラインに適しています。
WebSocket を使用する場合、session.connect() はソケットが開かれ、初期設定が送信された時点で完了します。対応する session.updated イベントは少し遅れて届くことがあるため、connect() の完了時点で、その更新がすでに返されているとは考えないでください。
import { RealtimeAgent, RealtimeSession } from '@openai/agents/realtime';
const agent = new RealtimeAgent({ name: 'Greeter', instructions: 'Greet the user with cheer and answer questions.',});
const myRecordedArrayBuffer = new ArrayBuffer(0);
const wsSession = new RealtimeSession(agent, { transport: 'websocket', model: 'gpt-realtime-2.1',});await wsSession.connect({ apiKey: process.env.OPENAI_API_KEY! });
wsSession.on('audio', (event) => { // event.data is a chunk of PCM16 audio});
wsSession.sendAudio(myRecordedArrayBuffer);元の PCM16 音声バイト列の処理には、任意の録音・再生ライブラリを使用してください。
高度な連携向けに、OpenAIRealtimeWebSocket は独自のソケット実装を提供するための createWebSocket() を受け付けます。また、そのカスタムコネクターがソケットを接続済み状態に遷移させる役割を担う場合に使用する skipOpenEventListeners も受け付けます。@openai/agents-extensions の Cloudflare トランスポートは、これらのフックを使って構築されています。
通話プロバイダーとテレフォニーブリッジ向けの SIP
Section titled “通話プロバイダーとテレフォニーブリッジ向けの SIP”SIP で開始された既存の Realtime 通話に RealtimeSession を接続するには、OpenAIRealtimeSIP を使用します。これは SIP に対応した軽量なトランスポートです。音声は SIP 通話自体が処理し、SDK のセッションは callId を使って接続します。
OpenAIRealtimeSIP.buildInitialConfig()で初期セッション設定を生成して、着信通話を受け入れます。これにより、SIP インビテーションと後続の SDK セッションが同じデフォルト設定で開始されます。OpenAIRealtimeSIPトランスポートを使用するRealtimeSessionを接続し、プロバイダーの Webhook が発行したcallIdを使って接続します。- プロバイダー固有のメディア転送やイベントの橋渡しが必要な場合は、Twilio 拡張などの連携トランスポートを使用します。
import OpenAI from 'openai';import { OpenAIRealtimeSIP, RealtimeAgent, RealtimeSession, type RealtimeSessionOptions,} from '@openai/agents/realtime';
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY!, webhookSecret: process.env.OPENAI_WEBHOOK_SECRET!,});
const agent = new RealtimeAgent({ name: 'Receptionist', instructions: 'Welcome the caller, answer scheduling questions, and hand off if the caller requests a human.',});
const sessionOptions: Partial<RealtimeSessionOptions> = { model: 'gpt-realtime-2.1', config: { audio: { input: { turnDetection: { type: 'semantic_vad', interruptResponse: true }, }, }, },};
export async function acceptIncomingCall(callId: string): Promise<void> { const initialConfig = await OpenAIRealtimeSIP.buildInitialConfig( agent, sessionOptions, ); await openai.realtime.calls.accept(callId, initialConfig);}
export async function attachRealtimeSession( callId: string,): Promise<RealtimeSession> { const session = new RealtimeSession(agent, { transport: new OpenAIRealtimeSIP(), ...sessionOptions, });
session.on('history_added', (item) => { console.log('Realtime update:', item.type); });
await session.connect({ apiKey: process.env.OPENAI_API_KEY!, callId, });
return session;}Cloudflare Workers と workerd
Section titled “Cloudflare Workers と workerd”Cloudflare Workers およびその他の workerd ランタイムでは、グローバルの WebSocket コンストラクターを使って外向きの WebSocket 接続を開くことができません。拡張パッケージの Cloudflare トランスポートを使用してください。このトランスポートは、内部で fetch() ベースのアップグレードを実行します。
import { CloudflareRealtimeTransportLayer } from '@openai/agents-extensions';import { RealtimeAgent, RealtimeSession } from '@openai/agents/realtime';
const agent = new RealtimeAgent({ name: 'My Agent',});
// Create a transport that connects to OpenAI Realtime via Cloudflare/workerd's fetch-based upgrade.const cfTransport = new CloudflareRealtimeTransportLayer({ url: 'wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1',});
const session = new RealtimeSession(agent, { // Set your own transport. transport: cfTransport,});セットアップの全体については、Cloudflare 上の音声エージェントを参照してください。
Twilio の電話通話
Section titled “Twilio の電話通話”RealtimeSession は、元の WebSocket を使用するか、@openai/agents-extensions の専用 Twilio トランスポートを使用して Twilio に接続できます。Twilio Media Streams の割り込みタイミングと音声転送を SDK に処理させたい場合は、専用トランスポートを標準の選択肢とすることをお勧めします。
セットアップの全体については、Twilio 上の音声エージェントを参照してください。
独自のトランスポートの使用
Section titled “独自のトランスポートの使用”別の音声対話 API を使用したい場合や、独自のカスタムトランスポート機構がある場合は、RealtimeTransportLayer インターフェースを実装し、RealtimeTransportEventTypes イベントを自分で発行できます。
必要に応じた元の Realtime イベントへのアクセス
Section titled “必要に応じた元の Realtime イベントへのアクセス”基盤となる Realtime API により直接的にアクセスしたい場合は、2 つの方法があります。
方法 1 - トランスポートレイヤーへのアクセス
Section titled “方法 1 - トランスポートレイヤーへのアクセス”RealtimeSession のすべての機能を引き続き利用したい場合は、session.transport を介してトランスポートレイヤーにアクセスできます。
トランスポートレイヤーは、受信したすべてのイベントを * イベントとして発行します。また、sendEvent() を使って元のイベントを送信できます。* リスナーは、元の解析済み JSON ペイロードの構造化クローンを受け取ります。これには、現在の SDK スキーマが認識していないフィールドも含まれます。名前付きイベントおよび派生イベントのリスナーは、引き続き検証・正規化済みのイベントオブジェクトを受け取ります。これは、session.update、response.create、response.cancel などの低レベル操作を行うための手段です。
import { RealtimeAgent, RealtimeSession } from '@openai/agents/realtime';
const agent = new RealtimeAgent({ name: 'Greeter', instructions: 'Greet the user with cheer and answer questions.',});
const session = new RealtimeSession(agent, { model: 'gpt-realtime-2.1',});
session.transport.on('*', (event) => { // Event received from the underlying Realtime transport});
// Send any valid client event, for example, to trigger a new responsesession.transport.sendEvent({ type: 'response.create', // ...});方法 2 - トランスポートレイヤーのみの使用
Section titled “方法 2 - トランスポートレイヤーのみの使用”ツールの自動実行、ガードレール、ローカルでの履歴管理が不要な場合は、接続と割り込みだけを管理する「軽量」クライアントとして、トランスポートレイヤーを使用することもできます。
import { OpenAIRealtimeWebRTC } from '@openai/agents/realtime';
const client = new OpenAIRealtimeWebRTC();const audioBuffer = new ArrayBuffer(0);
await client.connect({ apiKey: '<api key>', model: 'gpt-realtime-2.1', initialSessionConfig: { instructions: 'Speak like a pirate', outputModalities: ['audio'], audio: { input: { format: 'pcm16', }, output: { format: 'pcm16', voice: 'ash', }, }, },});
// Listen for audio when you manage playback yourselfclient.on('audio', (newAudio) => {});
client.sendAudio(audioBuffer);