クイックスタート
-
プロジェクトの作成
このクイックスタートでは、ブラウザ上で利用できる音声エージェントを作成します。新しいプロジェクトをチェックしたい場合は、
Next.js
やVite
を試すこともできます。Terminal window npm create vite@latest my-project --template vanilla-ts -
Agents SDK のインストール
Terminal window npm install @openai/agents代わりにブラウザ向けのスタンドアロン パッケージである
@openai/agents-realtime
をインストールすることもできます。 -
クライアント一時トークンの生成
このアプリケーションはユーザーのブラウザで動作するため、Realtime API を介してモデルに安全に接続する必要があります。そのために、一時クライアントキー をバックエンドサーバーで生成します。テスト目的であれば、
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
の作成は、通常のエージェント
の作成とほとんど同じです。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 “次のステップ”ここからは独自の音声エージェントを設計・構築してみてください。音声エージェントは通常のエージェントと多くの共通機能を持ちますが、独自の機能も備えています。
-
あなたの音声エージェントに以下を追加する方法を学ぶ
-
異なるトランスポート層についてさらに学ぶ