クイックスタート
-
プロジェクトの作成
このクイックスタートでは、ブラウザで使える音声エージェントを作成します。新しいプロジェクトを試したい場合は、
Next.js
やVite
を試せます。Terminal window npm create vite@latest my-project --template vanilla-ts -
Agents SDK のインストール
Terminal window npm install @openai/agents zod@3代わりにスタンドアロンのブラウザ用パッケージである
@openai/agents-realtime
をインストールすることもできます。 -
クライアントのエフェメラルトークンを生成
このアプリケーションは ユーザー のブラウザで実行されるため、Realtime API を通じてモデルに安全に接続する必要があります。そのために、バックエンド サーバー で生成する ephemeral client key を使用できます。テスト目的では、
curl
と通常の OpenAI API キーを使ってキーを生成することもできます。Terminal window curl -X POST https://api.openai.com/v1/realtime/sessions \-H "Authorization: Bearer $OPENAI_API_KEY" \-H "Content-Type: application/json" \-d '{"model": "gpt-4o-realtime-preview-2025-06-03"}'レスポンスには、後で接続に使用できる
client_secret.value
の値が含まれます。このキーは短時間のみ有効で、再生成が必要になる点に注意してください。 -
はじめてのエージェントを作成
新しい
RealtimeAgent
の作成は、通常のAgent
の作成と非常によく似ています。import { RealtimeAgent } from '@openai/agents-realtime';const agent = new RealtimeAgent({name: 'Assistant',instructions: 'You are a helpful assistant.',}); -
セッションの作成
通常のエージェントと異なり、Voice Agent は会話とモデルへの継続的な接続を扱う
RealtimeSession
の内部で常時実行・リスニングします。このセッションは、音声の処理、中断、その他多くのライフサイクル機能もあわせて処理します。import { RealtimeSession } from '@openai/agents-realtime';const session = new RealtimeSession(agent, {model: 'gpt-4o-realtime-preview-2025-06-03',});RealtimeSession
のコンストラクターは、最初の引数としてagent
を受け取ります。このエージェントが ユーザー が最初に対話できるエージェントになります。 -
セッションへの接続
セッションに接続するには、先ほど生成したクライアントのエフェメラルトークンを渡します。
await session.connect({ apiKey: '<client-api-key>' });これにより、ブラウザで WebRTC を使用して Realtime API に接続し、音声の入出力のためにマイクとスピーカーが自動的に設定されます。
RealtimeSession
をバックエンド サーバー(たとえば Node.js)で実行している場合、SDK は接続として自動的に WebSocket を使用します。異なるトランスポート層については、リアルタイムトランスポート ガイドで詳しく学べます。 -
すべてを組み合わせる
import { RealtimeAgent, RealtimeSession } from '@openai/agents/realtime';const agent = new RealtimeAgent({name: 'Assistant',instructions: 'You are a helpful assistant.',});const session = new RealtimeSession(agent);// Automatically connects your microphone and audio output// in the browser via WebRTC.await session.connect({apiKey: '<client-api-key>',}); -
エンジンを起動して話し始める
Web サーバー を起動し、新しい Realtime Agent のコードを含むページに移動します。マイクへのアクセス許可を求めるリクエストが表示されるはずです。アクセスを許可すると、エージェントと会話を開始できるようになります。
Terminal window npm run dev
次のステップ
Section titled “次のステップ”ここからは、独自の音声エージェントの設計と構築を始められます。音声エージェントには通常のエージェントと同様の機能が多く含まれますが、独自の機能もいくつか備わっています。
-
音声エージェントに以下の機能を持たせる方法を学ぶ
-
さまざまなトランスポート層についてさらに学ぶ