Twilio 上の音声エージェント
Twilio は、通話の元の音声を WebSocket サーバーに送信する Media Streams API を提供しています。この構成を使うと、音声エージェントを Twilio に接続できます(音声エージェントの概要)。デフォルトの Realtime セッショントランスポートを websocket モードで使用すると、Twilio から届くイベントを Realtime セッションに接続できます。ただし、電話では Web ベースの会話よりも遅延が大きくなるため、適切な音声形式を設定し、割り込みのタイミングを自分で調整する必要があります。
セットアップを容易にするために、割り込み処理や音声の転送など、Twilio への接続を処理する専用のトランスポートレイヤーを用意しています。
セットアップ
Section titled “セットアップ”-
Twilio アカウントと Twilio の電話番号があることを確認します。
-
Twilio からのリクエストを認証するサーバーをセットアップします。
ローカルで開発する場合は、Twilio がローカルサーバーにアクセスできるように、
ngrokや Cloudflare Tunnel などのローカルトンネルを設定する必要があります。サーバーは、トランスポートを作成したり OpenAI に接続したりする前に、着信 Webhook と WebSocket アップグレードの両方でX-Twilio-Signatureを検証しなければなりません。Twilio 公式のリクエストバリデーター、アカウントのプライマリ Auth Token、設定済みの公開 URL を使用してください。この URL をリクエストの Host ヘッダーや転送ヘッダーから導出しないでください。TwilioRealtimeTransportLayerは認証済みの WebSocket を受け取ります。このアダプターは HTTP リクエストを認証しません。 -
拡張パッケージをインストールして、Twilio アダプターをインストールします:
ターミナルウィンドウ npm install @openai/agents-extensions -
RealtimeSessionに接続するためのアダプターとモデルをインポートします:import { TwilioRealtimeTransportLayer } from '@openai/agents-extensions';import { RealtimeAgent, RealtimeSession } from '@openai/agents/realtime';const agent = new RealtimeAgent({name: 'My Agent',});// Authenticate the HTTP webhook and WebSocket upgrade in your server first.// Create a new transport mechanism that will bridge the connection between Twilio and// the OpenAI Realtime API.const twilioTransport = new TwilioRealtimeTransportLayer({twilioWebSocket: websocketConnection,});const session = new RealtimeSession(agent, {// set your own transporttransport: twilioTransport,}); -
RealtimeSessionを Twilio に接続します:import type { RealtimeSession } from '@openai/agents/realtime';// Connect only after the server has authenticated the Twilio WebSocket upgrade.async function connectAuthenticatedSession(session: RealtimeSession,apiKey: string,) {await session.connect({ apiKey });}
ツール呼び出しやガードレールなど、RealtimeSession で期待されるすべてのイベントと動作が、期待どおりに機能します。音声エージェントで RealtimeSession を使用する方法の詳細については、音声エージェントの概要 を参照してください。
ヒントと考慮事項
Section titled “ヒントと考慮事項”-
最も重要なのは速度です。
必要なイベントと音声をすべて Twilio から受信するには、認証済みの WebSocket 接続が利用可能になったらすぐに
TwilioRealtimeTransportLayerインスタンスを作成し、その直後にsession.connect()を呼び出してください。 -
Twilio の元のイベントにアクセスします。
Twilio から送信される元のイベントにアクセスするには、
RealtimeSessionインスタンスのtransport_eventイベントをリッスンします。Twilio からの各イベントはtwilio_messageという型を持ち、元のイベントデータを含むmessageプロパティを持ちます。 -
デバッグログを確認します。
問題が発生したときに、何が起きているのか、より詳しい情報が必要になることがあります。環境変数
DEBUG=openai-agents*を使用すると、Agents SDK のすべてのデバッグログが表示されます。また、DEBUG=openai-agents:extensions:twilio*を使用すると、Twilio アダプターのデバッグログのみを有効にできます。
サーバーの完全なコード例
Section titled “サーバーの完全なコード例”実行可能な Twilio のコード例 には、認証を行う Fastify ルートと Realtime セッションのセットアップが含まれています。README では、サーバー側で必要な OPENAI_API_KEY、TWILIO_AUTH_TOKEN、TWILIO_PUBLIC_BASE_URL の設定について説明しています。公開ベース URL は、パスプレフィックス、クエリ文字列、フラグメントを含まない HTTPS オリジンです。トンネルの公開オリジンが変わった場合は、この設定を更新してください。
サーバーは、Realtime 接続を開く前に、着信とアップグレードの無効な署名を拒否します。Twilio Media Stream の URL は wss:// を使用し、クエリパラメーターはサポートしていません。カスタムパラメーターについては、Twilio Stream のドキュメント を参照してください。