コンテンツにスキップ

クイックスタート

プロジェクトのセットアップと認証情報

Section titled “プロジェクトのセットアップと認証情報”
  1. プロジェクトの作成

    このクイックスタートでは、ブラウザーで使用できる音声エージェントを作成します。新しいプロジェクトのひな形を作成するには、Next.js または Vite から始められます。

    ターミナルウィンドウ
    npm create vite@latest my-project -- --template vanilla-ts
  2. 推奨パッケージのインストール (Zod v4 が必要)

    ターミナルウィンドウ
    npm install @openai/agents zod
  3. クライアント用の一時トークンの生成

    このアプリケーションはユーザーのブラウザーで実行されるため、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 “音声エージェントの作成と接続”
  1. はじめてのエージェントの作成

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

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

    通常のエージェントとは異なり、音声エージェントは、会話とモデルへの接続を継続的に処理する RealtimeSession 内で動作し続けます。このセッションは、音声処理、割り込み、および後で設定する会話ライフサイクル全般も管理します。

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

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

  3. セッションへの接続

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

    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 は少し遅れて届く場合があります。トランスポートの選択肢について詳しくは、リアルタイムトランスポートガイドをご覧ください。

  1. 全体のコード

    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 .value
    apiKey: 'ek_...(put your own key here)',
    });
    console.log('You are connected!');
    } catch (e) {
    console.error(e);
    }
    }
    main().catch(console.error);
  2. アプリの起動と会話の開始

    Web サーバーを起動し、新しい音声エージェントのコードを含むページを開きます。マイクの使用許可を求めるリクエストが表示されるはずです。アクセスを許可すると、エージェントとの会話を始められます。

    ターミナルウィンドウ
    npm run dev

ここから、独自の音声エージェントの設計と構築を始められます。