コンテンツにスキップ

クイックスタート

  1. プロジェクトの作成

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

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

    Terminal window
    npm install @openai/agents zod@3

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

  3. クライアントのエフェメラルトークンを生成

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

  4. はじめてのエージェントを作成

    新しい RealtimeAgent の作成は、通常の Agent の作成と非常によく似ています。

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

    通常のエージェントと異なり、音声エージェントは会話とモデルへの接続を継続的に扱う RealtimeSession の内部で常時実行・リスニングします。このセッションは、音声処理、中断、その他多くのライフサイクル機能も処理します。これらは後ほど説明します。

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

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

  6. セッションへの接続

    セッションに接続するには、先ほど生成したクライアントのエフェメラルトークンを渡す必要があります。

    await session.connect({ apiKey: 'ek_...(put your own key here)' });

    これにより、ブラウザで WebRTC を使用して Realtime API に接続し、音声の入出力のためにマイクとスピーカーを自動的に構成します。RealtimeSession をバックエンドサーバー(たとえば Node.js)で実行している場合、SDK は自動的に WebSocket を接続として使用します。各種トランスポート層の詳細は、リアルタイムトランスポート ガイドをご覧ください。

  7. すべてをまとめる

    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 code
    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.
    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 .value
    apiKey: 'ek_...(put your own key here)',
    });
    console.log('You are connected!');
    } catch (e) {
    console.error(e);
    }
    }
  8. エンジン始動、話しかけてみましょう

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

    Terminal window
    npm run dev

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