コンテンツにスキップ

Twilio 上の音声エージェント

Twilio は、通話の元の音声を WebSocket サーバーに送信する Media Streams API を提供しています。この構成を使うと、音声エージェントを Twilio に接続できます(音声エージェントの概要)。デフォルトの Realtime セッショントランスポートを websocket モードで使用すると、Twilio から届くイベントを Realtime セッションに接続できます。ただし、電話では Web ベースの会話よりも遅延が大きくなるため、適切な音声形式を設定し、割り込みのタイミングを自分で調整する必要があります。

セットアップを容易にするために、割り込み処理や音声の転送など、Twilio への接続を処理する専用のトランスポートレイヤーを用意しています。

  1. Twilio アカウントと Twilio の電話番号があることを確認します。

  2. Twilio からのリクエストを認証するサーバーをセットアップします。

    ローカルで開発する場合は、Twilio がローカルサーバーにアクセスできるように、ngrok や Cloudflare Tunnel などのローカルトンネルを設定する必要があります。サーバーは、トランスポートを作成したり OpenAI に接続したりする前に、着信 Webhook と WebSocket アップグレードの両方で X-Twilio-Signature を検証しなければなりません。Twilio 公式のリクエストバリデーター、アカウントのプライマリ Auth Token、設定済みの公開 URL を使用してください。この URL をリクエストの Host ヘッダーや転送ヘッダーから導出しないでください。TwilioRealtimeTransportLayer は認証済みの WebSocket を受け取ります。このアダプターは HTTP リクエストを認証しません。

  3. 拡張パッケージをインストールして、Twilio アダプターをインストールします:

    ターミナルウィンドウ
    npm install @openai/agents-extensions
  4. 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 transport
    transport: twilioTransport,
    });
  5. 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 を使用する方法の詳細については、音声エージェントの概要 を参照してください。

  1. 最も重要なのは速度です。

    必要なイベントと音声をすべて Twilio から受信するには、認証済みの WebSocket 接続が利用可能になったらすぐに TwilioRealtimeTransportLayer インスタンスを作成し、その直後に session.connect() を呼び出してください。

  2. Twilio の元のイベントにアクセスします。

    Twilio から送信される元のイベントにアクセスするには、RealtimeSession インスタンスの transport_event イベントをリッスンします。Twilio からの各イベントは twilio_message という型を持ち、元のイベントデータを含む message プロパティを持ちます。

  3. デバッグログを確認します。

    問題が発生したときに、何が起きているのか、より詳しい情報が必要になることがあります。環境変数 DEBUG=openai-agents* を使用すると、Agents SDK のすべてのデバッグログが表示されます。また、DEBUG=openai-agents:extensions:twilio* を使用すると、Twilio アダプターのデバッグログのみを有効にできます。

実行可能な Twilio のコード例 には、認証を行う Fastify ルートと Realtime セッションのセットアップが含まれています。README では、サーバー側で必要な OPENAI_API_KEY、TWILIO_AUTH_TOKEN、TWILIO_PUBLIC_BASE_URL の設定について説明しています。公開ベース URL は、パスプレフィックス、クエリ文字列、フラグメントを含まない HTTPS オリジンです。トンネルの公開オリジンが変わった場合は、この設定を更新してください。

サーバーは、Realtime 接続を開く前に、着信とアップグレードの無効な署名を拒否します。Twilio Media Stream の URL は wss:// を使用し、クエリパラメーターはサポートしていません。カスタムパラメーターについては、Twilio Stream のドキュメント を参照してください。