コンテンツにスキップ

クイックスタート

  1. プロジェクトの作成

    このクイックスタートでは、ブラウザ上で利用できる音声エージェントを作成します。新しいプロジェクトをチェックしたい場合は、Next.jsVite を試すこともできます。

    Terminal window
    npm create vite@latest my-project --template vanilla-ts
  2. Agents SDK のインストール

    Terminal window
    npm install @openai/agents

    代わりにブラウザ向けのスタンドアロン パッケージである @openai/agents-realtime をインストールすることもできます。

  3. クライアント一時トークンの生成

    このアプリケーションはユーザーのブラウザで動作するため、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 が含まれます。このキーは短時間のみ有効で、再生成が必要になる点に注意してください。

  4. 最初のエージェントを作成

    新しい RealtimeAgent の作成は、通常の エージェント の作成とほとんど同じです。

    import { RealtimeAgent } from '@openai/agents-realtime';
    const agent = new RealtimeAgent({
    name: 'Assistant',
    instructions: 'You are a helpful assistant.',
    });
  5. セッションの作成

    通常のエージェントと異なり、Voice Agent は会話を継続的に処理する RealtimeSession 内で実行・待機します。このセッションは、時間を越えたモデルとの接続や音声処理、中断処理など、多くのライフサイクル機能を担当します。

    import { RealtimeSession } from '@openai/agents-realtime';
    const session = new RealtimeSession(agent, {
    model: 'gpt-4o-realtime-preview-2025-06-03',
    });

    RealtimeSession のコンストラクターは最初の引数として agent を取ります。このエージェントが、ユーザーが最初に対話できるエージェントになります。

  6. セッションへの接続

    先ほど生成したクライアント一時トークンを渡してセッションに接続します。

    await session.connect({ apiKey: '<client-api-key>' });

    これによりブラウザで WebRTC を使用して Realtime API に接続し、マイクとスピーカーが自動的に設定されます。RealtimeSession をバックエンドサーバー(Node.js など)で実行している場合、SDK は自動的に WebSocket を使用します。異なるトランスポート層については リアルタイムトランスポート ガイドをご覧ください。

  7. すべてをまとめる

    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>',
    });
  8. エンジンを始動して話しかける

    Web サーバーを起動し、新しい Realtime Agent のコードを含むページへアクセスします。マイクへのアクセス許可を求めるリクエストが表示されるはずです。許可すると、エージェントに話しかけられるようになります。

    Terminal window
    npm run dev

ここからは独自の音声エージェントを設計・構築してみてください。音声エージェントは通常のエージェントと多くの共通機能を持ちますが、独自の機能も備えています。