Open in

OpenAI Realtime クライアントで ThunderPhone を使用する

保存済みのエージェントまたはインラインセッション設定を使用して、OpenAI Realtime 互換のサーバークライアントを ThunderPhone に接続します。

ThunderPhone は、OpenAI Realtime イベントモデルの焦点を絞ったサブセットを実装しています。既存のサーバー側クライアントは、ThunderPhone 音声エージェントを使用しながら、WebSocket、音声、セッション、レスポンスイベントフローを維持できます。

接続前の準備

ThunderPhone 組織のシークレット API キーと、WebSocket を開けるサーバーランタイムが必要です。ブラウザーコードから接続したり、キーをブラウザーに公開したりしないでください。保存済みエージェントを使用するには、先にデプロイし、その数値エージェント ID をコピーします。

接続先:

wss://api.thunderphone.com/v1/realtime

サーバーからの WebSocket アップグレードを認証します。

Authorization: Bearer sk_live_YOUR_API_KEY

ハンドシェイクヘッダーを設定できないクライアント向けにクエリ文字列認証もありますが、 URL はログに漏洩しやすくなります。

設定の所有者を選択する

モード	接続方法	設定の取得元
保存済みエージェント	`?agent_id=12`	デプロイ済みのプロンプト、音声、プロダクト、言語、ナレッジ、および対応するサーバー実行ツール
インライン	`agent_id` なし	クライアントから最初に受理された `session.update`

保存済みエージェント

デプロイ済みエージェント ID で接続します。

wss://api.thunderphone.com/v1/realtime?agent_id=12

ソケットの接続中にエージェントが開始します。あいさつは引き続き利用できますが、 Realtime では音声による無音時の確認が無効になり、transfer_call と send_keypad_input は含まれません。その他の対応ツールは ThunderPhone 上で実行されます。このモードでは、インライン指示やクライアント実行ツールを送信しないでください。

エージェントの開始前に、input_audio_format、 output_audio_format、input_rate、output_rate クエリパラメータで通信音声を設定します。接続後に保存済み設定や音声形式を変更することはできません。

インラインセッション

agent_id なしの場合は、session.created を待ってから session.update を送信します。

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "instructions": "Answer questions clearly and keep responses brief.",
    "audio": {
      "input": {
        "format": { "type": "audio/pcm", "rate": 24000 }
      },
      "output": {
        "format": { "type": "audio/pcm", "rate": 24000 },
        "voice": "olivia"
      }
    },
    "config": {
      "product": "bolt"
    }
  }
}

最初に受理された更新で通話がプロビジョニングされます。session.updated は、セッションがライブになったことを示します。その時点以降、指示、音声、プロダクト、ツール、音声形式は変更できません。

インラインセッションには、自動あいさつや音声による無音時の確認はありません。エージェントから先に話し始めるには、システムまたはユーザーメッセージを追加して response.create を送信します。完全にアイドル状態のセッションも、プラットフォームの無音通話制限で終了します。デフォルトは 600 秒です。

公式の OpenAI SDK を使用する

末尾が /v1 の WebSocket ベース URL を渡します。SDK が /realtime を追加します。 model の値は互換性のための名前であり、ThunderPhone の製品を選択するものではありません。製品はセッション設定または保存済みエージェントで選択します。

この接続チェックでは、インライン Bolt セッションを作成し、最初の session.updated までイベントを出力してから閉じます。音声をストリーミングするには、最小 Python クライアントを使用します。

import asyncio
import os
 
from openai import AsyncOpenAI
 
 
async def main():
    client = AsyncOpenAI(
        api_key=os.environ["THUNDERPHONE_API_KEY"],
        websocket_base_url="wss://api.thunderphone.com/v1",
    )
 
    async with client.realtime.connect(
        model="thunderphone-realtime"
    ) as connection:
        await connection.session.update(session={
            "type": "realtime",
            "instructions": "Listen to the caller and help them complete the call.",
            "config": {"product": "bolt"},
        })
        async for event in connection:
            print(event.type)
            if event.type == "session.updated":
                break
 
 
if __name__ == "__main__":
    asyncio.run(main())

入力音声の追加、応答音声デルタ、割り込み、関数呼び出し、エラー、ソケットの正常な切断に関する既存の処理は維持します。インラインのカスタム関数はクライアントで実行し、その結果を Realtime プロトコル経由で返します。保存済みエージェントのツールは ThunderPhone で実行されます。

セッションのライフサイクルと失敗

1 つの WebSocket は 1 件の通話を表します。無効なエージェント ID または拒否されたインライン設定では、error イベントが生成されます。セッションを有効として扱う前に、session.updated を待機します。実際の入力・出力形式とサンプルレートを宣言します。PCM レートが一致しない場合、検証エラーではなく音声が速すぎたり遅すぎたりして再生されます。

セッション開始後、アプリケーションの処理が完了したらソケットを正常に閉じます。インラインセッションでは、クライアントで実行する関数を使用できます。保存済みエージェントのセッションでは、互換性のある ThunderPhone 実行ツールを使用し、転送やキーパッド入力は利用できません。

統合をテストする

最小 Python WAV クライアントと、宣言したレートのモノラル PCM16 WAV から始めます。以下を確認します。

サーバーが設定を受け入れ、session.updated を送信する。
入力によって、想定される速度で文字起こしイベントと応答音声イベントが生成される。
割り込みと応答のキャンセルによって、残りの出力音声が停止する。
インライン関数の結果または保存済みエージェントのツール結果がモデルに返される。
無効な入力によって、クライアントで処理する error イベントが生成される。
クライアントがソケットを閉じ、通話が通話履歴に表示される。

Realtime WebSocket リファレンスには、受け入れられるイベント、音声形式、セッションフィールド、完全な例が記載されています。

料金

Realtime 通話には、選択した製品の通常の分単位料金が適用されます。ライブ文字起こしデルタを有効にすると、セッション全体に対して分単位の追加料金が発生します。料金についてはライブ文字起こし、製品料金については料金を参照してください。

POST /v1/realtime/sessions は、別途管理される LiveKit パスです。ルームとスコープ付き参加者トークンを作成しますが、直接 WebSocket 接続には必要ありません。

フレームワーク統合については、Pipecat から ThunderPhone を使用するおよびLiveKit Agents から ThunderPhone を使用するを参照してください。