クイックスタート
-
プロジェクトの作成
このクイックスタートでは、ブラウザで使える音声エージェントを作成します。新しいプロジェクトを試すには、
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 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"}}'レスポンスにはトップレベルに “value” 文字列が含まれ、“ek_” プレフィックスで始まります。このエフェメラルキーを使って後で WebRTC 接続を確立できます。このキーは有効期間が短いため、再生成が必要になります。
-
はじめてのエージェントを作成
新しい
RealtimeAgent
の作成は、通常のエージェント
の作成と非常によく似ています。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-realtime',});RealtimeSession
コンストラクタは最初の引数としてagent
を受け取ります。このエージェントが ユーザー が最初に対話できるエージェントになります。 -
セッションへの接続
セッションに接続するには、先ほど生成したクライアントのエフェメラルトークンを渡します。
await session.connect({ apiKey: 'ek_...(put your own key here)' });これによりブラウザで WebRTC を使って Realtime API に接続し、音声の入出力用にマイクとスピーカーが自動的に設定されます。
RealtimeSession
をバックエンド サーバー(たとえば Node.js)で実行している場合、SDK は自動的に WebSocket を接続として使用します。異なるトランスポート層の詳細は、リアルタイムトランスポート ガイドをご覧ください。 -
すべてを組み合わせる
import { RealtimeAgent, RealtimeSession } from '@openai/agents/realtime';export async function setupCounter(element: HTMLButtonElement) {// ....// for quickly start, you can append the following code to the auto-generated TS codeconst 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.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"}}' | jq .valueapiKey: 'ek_...(put your own key here)',});console.log('You are connected!');} catch (e) {console.error(e);}} -
エンジンを起動して話しかける
Web サーバー を起動し、新しい Realtime Agent のコードを含むページに移動します。マイクへのアクセス許可の要求が表示されるはずです。許可すると、エージェントに話しかけられるようになります。
Terminal window npm run dev
次のステップ
Section titled “次のステップ”ここからは、独自の音声エージェントの設計と構築を始められます。音声エージェントは通常のエージェントと多くの機能を共有しますが、固有の機能もいくつかあります。
-
音声エージェントに以下を追加する方法を学ぶ
-
異なるトランスポート層について詳しく学ぶ