Realtime API を使って、音声変換に対応した音声エージェントを構築します。モデルは音声を直接処理し、会話の状態を維持しながら、必要に応じてツールを呼び出せます。このガイドでは、まず Agents SDK を使ってブラウザアプリケーションを構築します。接続を直接制御する必要がある場合は、より低レベルな接続方法を扱うガイドを参照してください。
処理を別のバックエンドに委任して全二重通信で会話する場合は、GPT-Live を参照してください。音声アーキテクチャや複数の処理を直列につなぐパイプラインを比較するには、音声エージェントを参照してください。
音声変換に対応した音声エージェントの構築
自然な会話のテンポで応答を返したい場合は、Realtime API を使用します。ユーザーが応答の途中で話し始められること、音声が返り始めるまでの時間が短いこと、自然に話者を交代できること、リアルタイムでツールを使えることが求められる音声エージェントの開発には、Realtime API が最適な出発点です。
ブラウザアプリケーションでの一般的な流れは次のとおりです。
- アプリケーションサーバーで、Realtime セッション用の一時的なクライアントシークレットを作成します。
- フロントエンドで
RealtimeSessionを作成します。 - セッションは、ブラウザでは WebRTC、サーバーでは WebSocket を使って接続します。
- エージェントはそのセッション内で、音声でのやり取り、ツールの呼び出し、割り込み、ハンドオフを処理します。
import { RealtimeAgent, RealtimeSession } from "@openai/agents/realtime";
const ephemeralKey = process.env.OPENAI_REALTIME_EPHEMERAL_KEY;
if (!ephemeralKey)
throw new Error("Set OPENAI_REALTIME_EPHEMERAL_KEY from your server.");
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: ephemeralKey,
});次に、テキストエージェントの場合と同じように、ツール、ハンドオフ、ガードレールを RealtimeAgent に追加します。音声の伝送はセッション層で扱い、ビジネスロジックはエージェント定義に記述します。
接続をより低レベルで制御する必要がある場合は、まず次のドキュメントを参照してください。
安全性識別子
アプリケーションがエンドユーザーを個別に識別している場合は、Realtime API へのリクエストに安全性識別子を含めてください。OpenAI は安全性識別子の使用を推奨していますが、必須ではありません。この識別子があると、OpenAI は有害な行為を検出し、組織全体ではなく該当するユーザーに限定して措置を講じることができます。ハッシュ化した内部ユーザー ID など、同じユーザーに対して一貫して使用でき、プライバシーを保護できる値を使ってください。
Realtime API へのリクエストでは、OpenAI-Safety-Identifier ヘッダーで識別子を送信します。一時トークンを使用する場合は、クライアントシークレットを作成するサーバー側のリクエストにこのヘッダーを設定し、識別子をセッションに関連付けます。信頼できるサーバーから WebSocket または統合 WebRTC インターフェースを使って接続する場合は、接続リクエストにこのヘッダーを設定します。
Responses API へのリクエストや他のセッションで指定した安全性識別子は引き継がれません。アプリケーションの別の箇所で Responses API の safety_identifier パラメータを使用している場合は、各 Realtime セッションの作成時または接続時に、そのユーザーに割り当てた同じ値を渡してください。
ベータ版から一般提供版への移行
現在もベータ版の Realtime API を使用している場合は、新たな開発に着手する前に、一般提供（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 版での実装手順については、Realtime クライアントイベントのリファレンス、Realtime セッションのリファレンス、ブラウザでの実装例を参照してください。
次のステップ
- 会話の管理：セッションを設定し、音声、テキスト、イベントを処理します。
- 音声区間検出：発話ターンの自動検出を設定します。
- ツールと MCP：関数、MCP サーバー、コネクタを追加します。
- 音声モデル向けのプロンプト作成：使用する Realtime モデルに対応したガイドを参照してください。
- コストの最適化：Realtime API の使用量の計算方法とキャッシュの仕組みを確認します。
- サーバー側での制御：ツールの実行とセッションの制御をサーバー側で行います。
その他の音声ワークフロー
ワークフローの選び方と各ワークフローに共通する音声用語は、現在、オーディオと音声にまとめられています。音声を継続的に翻訳する場合は、ライブ翻訳を参照してください。リアルタイムで字幕を表示する場合はライブ文字起こし、録音済みの音声を文字にする場合はファイルの文字起こしを参照してください。