Realtime API を使って、音声変換型の音声エージェントを構築します。モデルは音声を直接処理し、会話の状態を維持しながらツールを呼び出せます。このガイドでは、まず Agents SDK を使ったブラウザアプリケーションの構築方法を紹介します。接続を直接制御する必要がある場合は、低レベルの接続ガイドを参照してください。
別のバックエンドに処理を委任する全二重の会話については、GPT-Liveを参照してください。音声アーキテクチャと複数の処理を連結するパイプラインの比較については、音声エージェントを参照してください。
音声変換型の音声エージェントの構築
自然な会話のような即応性のあるやり取りを実現するには、Realtime API を使用してください。ユーザーによる発話への割り込み、音声出力開始までの低レイテンシ、自然なターン交代、リアルタイムのツール利用が必要な音声エージェントを構築する際に、最適な出発点となります。
ブラウザでの一般的な処理の流れは次のとおりです。
- アプリケーションサーバーが、リアルタイムセッション用の一時的なクライアントシークレットを作成します。
- フロントエンドが
RealtimeSessionを作成します。 - セッションは、ブラウザでは WebRTC、サーバーでは WebSocket を介して接続します。
- エージェントは、そのセッション内で音声のターン、ツール、割り込み、ハンドオフを処理します。
import { RealtimeAgent, RealtimeSession } from "@openai/agents/realtime";
const agent = new RealtimeAgent({
name: "Assistant",
instructions: "You are a helpful voice assistant.",
});
const session = new RealtimeSession(agent, {
model: "gpt-realtime-2.1",
});
await session.connect({
apiKey: "ek_...(ephemeral key from your server)",
});続いて、テキストエージェントと同じように、RealtimeAgent にツール、ハンドオフ、ガードレールを追加します。音声の転送に関する処理はセッション層に、ビジネスロジックはエージェント定義にまとめてください。
より低レベルの制御が必要な場合は、まずトランスポートのドキュメントを参照してください。
安全性識別子
アプリケーションで個々のエンドユーザーを識別している場合は、Realtime API リクエストに安全性識別子を含めてください。OpenAI は安全性識別子を推奨していますが、必須ではありません。安全性識別子は、OpenAI が有害な行動を検知し、組織全体ではなく個々のユーザーを対象に措置を講じるのに役立ちます。ハッシュ化した内部ユーザー ID など、プライバシーを保護できる一貫した値を使用してください。
Realtime API リクエストでは、OpenAI-Safety-Identifier ヘッダーで識別子を送信します。一時トークンを使用する場合は、クライアントシークレットを作成するサーバー側のリクエストにこのヘッダーを設定し、識別子をセッションに関連付けます。信頼できるサーバーから WebSocket または統合 WebRTC インターフェースで接続する場合は、接続リクエストにヘッダーを設定します。
安全性識別子は、Responses API リクエストや他のセッションから引き継がれません。アプリケーションの別の箇所で Responses API の safety_identifier パラメーターを使用している場合は、各リアルタイムセッションの作成時または接続時に、同じ一貫した値を渡してください。
ベータ版から GA への移行
ベータ版の Realtime 連携をまだ使用している場合は、新たな開発を進める前に GA インターフェースに移行してください。特に重要な変更点は次のとおりです。
- GA インターフェースを呼び出す際は、
OpenAI-Beta: realtime=v1ヘッダーを削除してください。 - ブラウザやモバイルクライアント用の一時的な認証情報を作成するには、
POST /v1/realtime/client_secretsを使用してください。 - WebRTC セッションを確立する際は、
/v1/realtime/callsを使用してください。 - GA インターフェースに合わせて、セッションとイベントの構造を更新してください。具体的には、
session.typeを設定し、出力音声の設定をsession.audio.outputの下に移動して、response.output_text.delta、response.output_audio.delta、response.output_audio_transcript.deltaなどの新しいレスポンスイベント名を使用します。 - 音声変換アプリの移行を進める場合は、ブラウザのサンプルから始めてください。文字起こしワークフローの移行を進める場合は、リアルタイム文字起こしを参照してください。
現在の GA 版の処理の流れについては、リアルタイムクライアントイベントのリファレンス、リアルタイムセッションのリファレンス、ブラウザのサンプルを参照してください。
次のステップ
- 会話の管理：セッションを設定し、音声、テキスト、イベントを処理します。
- 音声区間検出：ターンの自動検出を設定します。
- ツールと MCP：関数、MCP サーバー、コネクタを追加します。
- 音声モデル向けのプロンプト：使用する Realtime モデルに対応したガイドを参照してください。
- コストの最適化：Realtime の使用量の計算方法とキャッシュの仕組みを理解します。
- サーバー側の制御：ツールの実行とセッションの制御をサーバー側で行います。
その他の音声ワークフロー
ワークフローの選択ツールと音声関連の共通用語は、現在音声と音声対話に掲載されています。継続的な翻訳にはリアルタイム翻訳を使用してください。リアルタイムの字幕にはリアルタイム文字起こし、録音済みの音声にはファイルの文字起こしを使用してください。