クイックスタート
プロジェクトのセットアップと認証情報
Section titled “プロジェクトのセットアップと認証情報”-
プロジェクトの作成
このクイックスタートでは、ブラウザーで使用できる音声エージェントを作成します。新しいプロジェクトのひな形を作成するには、
Next.jsまたはViteから始められます。ターミナルウィンドウ npm create vite@latest my-project -- --template vanilla-ts -
推奨パッケージのインストール (Zod v4 が必要)
ターミナルウィンドウ npm install @openai/agents zod -
クライアント用の一時トークンの生成
このアプリケーションはユーザーのブラウザーで実行されるため、Realtime API を介してモデルに安全に接続する方法が必要です。推奨されるフローは、公式の Realtime API と WebRTC ガイドに沿ったものです。バックエンドが有効期間の短いクライアント用の一時トークンを作成し、ブラウザーがそのトークンを使って WebRTC 接続を確立します。テスト目的であれば、
curlと通常の OpenAI API キーを使ってトークンを生成することもできます。ターミナルウィンドウ export OPENAI_API_KEY="sk-proj-...(your own key here)"curl -X POST https://api.openai.com/v1/realtime/client_secrets \-H "Authorization: Bearer $OPENAI_API_KEY" \-H "Content-Type: application/json" \-d '{"session": {"type": "realtime","model": "gpt-realtime-2.1"}}'レスポンスには、
ek_プレフィックスで始まるトップレベルのvalueフィールドと、実際に適用されるsessionオブジェクトが含まれます。WebRTC 接続を確立するときは、valueをクライアントシークレットとして使用してください。このトークンは有効期間が短いため、バックエンドで必要に応じて新しいものを発行してください。ブラウザーセッションでauthorizationやカスタムheadersを使用するリモート MCP サーバーツールが必要な場合は、その認証情報をブラウザーのコードに公開するのではなく、POST /v1/realtime/client_secretsに送信するサーバー側のsessionペイロードに、そのホスト型 MCP の設定を含めてください。
音声エージェントの作成と接続
Section titled “音声エージェントの作成と接続”-
はじめてのエージェントの作成
新しい
RealtimeAgentの作成は、通常のAgentの作成とよく似ています。import { RealtimeAgent } from '@openai/agents/realtime';const agent = new RealtimeAgent({name: 'Assistant',instructions: 'You are a helpful assistant.',}); -
セッションの作成
通常のエージェントとは異なり、音声エージェントは、会話とモデルへの接続を継続的に処理する
RealtimeSession内で動作し続けます。このセッションは、音声処理、割り込み、および後で設定する会話ライフサイクル全般も管理します。import { RealtimeSession } from '@openai/agents/realtime';const session = new RealtimeSession(agent, {model: 'gpt-realtime-2.1',});RealtimeSessionコンストラクターは、最初の引数としてagentを受け取ります。このエージェントが、ユーザーが最初にやり取りするエージェントになります。 -
セッションへの接続
セッションに接続するには、先ほど生成したクライアント用の一時トークンを渡す必要があります。
await session.connect({ apiKey: 'ek_...(put your own key here)' });ブラウザーでは、WebRTC を使って Realtime API に接続し、マイクからの音声取得と音声再生が自動的に設定されます。このデフォルトの WebRTC 接続では、SDK はデータチャネルが開くとすぐに初期セッション設定を送信し、対応する
session.updatedの確認応答を待ってからconnect()を完了するように動作します。確認応答が届かない場合は、タイムアウトによるフォールバックが行われます。Node.js などのサーバーランタイムでRealtimeSessionを実行すると、SDK は自動的に WebSocket にフォールバックします。WebSocket 接続では、ソケットが開き、初期設定が送信された後にconnect()が完了するため、session.updatedは少し遅れて届く場合があります。トランスポートの選択肢について詳しくは、リアルタイムトランスポートガイドをご覧ください。
アプリの実行とテスト
Section titled “アプリの実行とテスト”-
全体のコード
import { RealtimeAgent, RealtimeSession } from '@openai/agents/realtime';async function main() {const agent = new RealtimeAgent({name: 'Assistant',instructions: 'You are a helpful assistant.',});const session = new RealtimeSession(agent, {model: 'gpt-realtime-2.1',});// Automatically connects your microphone and audio output in the browser via WebRTC.try {await session.connect({// To get this ephemeral key string, you can run the following command or implement the equivalent on the server side:// curl -s -X POST https://api.openai.com/v1/realtime/client_secrets -H "Authorization: Bearer $OPENAI_API_KEY" -H "Content-Type: application/json" -d '{"session": {"type": "realtime", "model": "gpt-realtime-2.1"}}' | jq .valueapiKey: 'ek_...(put your own key here)',});console.log('You are connected!');} catch (e) {console.error(e);}}main().catch(console.error); -
アプリの起動と会話の開始
Web サーバーを起動し、新しい音声エージェントのコードを含むページを開きます。マイクの使用許可を求めるリクエストが表示されるはずです。アクセスを許可すると、エージェントとの会話を始められます。
ターミナルウィンドウ npm run dev
次のステップ
Section titled “次のステップ”ここから、独自の音声エージェントの設計と構築を始められます。