クイックスタート

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

プロジェクトの作成

このクイックスタートでは、ブラウザーで使用できるリアルタイムエージェントを作成します。新しいプロジェクトのひな形を作成する場合は、Next.js または Vite から始められます。
Terminal window
```
npm create vite@latest my-project -- --template vanilla-ts
```
推奨パッケージのインストール（Zod v4 が必要です）
Terminal window
```
npm install @openai/agents zod
```
クライアント一時トークンの生成

このアプリケーションはユーザーのブラウザーで実行されるため、Realtime API を介してモデルに安全に接続する方法が必要です。推奨されるフローは、公式の WebRTC を使用した Realtime API ガイドに準拠しています。バックエンドで有効期間の短い一時クライアントトークンを作成し、ブラウザーでそのトークンを使用して WebRTC 接続を確立します。テスト目的では、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-2.1"
     }
   }'
```
レスポンスには、ek_ プレフィックスで始まるトップレベルの value フィールドと、実際に適用される session オブジェクトが含まれます。WebRTC 接続を確立するときは、value をクライアントシークレットとして使用してください。このトークンは有効期間が短いため、必要に応じてバックエンドで新しいトークンを発行する必要があります。ブラウザーセッションで authorization またはカスタム headers を使用するホスト型 MCP ツールが必要な場合は、それらの認証情報をブラウザーコードで公開するのではなく、POST /v1/realtime/client_secrets に送信するサーバー側の session ペイロードに、そのホスト型 MCP の設定を含めてください。

リアルタイムエージェントの作成と接続

最初のエージェントの作成

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

import { RealtimeAgent } from '@openai/agents/realtime';

const agent = new RealtimeAgent({
  name: 'Assistant',
  instructions: 'You are a helpful assistant.',
});

セッションの作成

通常のエージェントとは異なり、リアルタイムエージェントは RealtimeSession 内で継続的に実行され、時間の経過に伴う会話とモデルへの接続を処理します。このセッションは、音声処理、中断、および後で設定する会話ライフサイクル全体も管理します。
```
import { RealtimeSession } from '@openai/agents/realtime';

const session = new RealtimeSession(agent, {
  model: 'gpt-realtime-2.1',
});
```
RealtimeSession コンストラクターは、最初の引数として agent を受け取ります。このエージェントが、ユーザーが最初に対話するエージェントになります。
セッションへの接続

セッションに接続するには、先ほど生成したクライアント一時トークンを渡す必要があります。
```
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 は少し遅れて届く場合があります。トランスポートの選択肢について詳しくは、リアルタイムトランスポートガイドをご覧ください。

アプリの実行とテスト

全体の組み立て

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);

アプリの起動と会話の開始

Web サーバーを起動し、新しいリアルタイムエージェントのコードを含むページを開きます。マイクの使用許可を求めるメッセージが表示されます。アクセスを許可すると、エージェントとの会話を開始できます。
Terminal window
```
npm run dev
```

次のステップ

ここから、独自のリアルタイムエージェントの設計と構築を開始できます。

ツール、ハンドオフ、ガードレールを追加します。
ターン検出と音声アクティビティ検出、中断、手動でのレスポンス制御が会話ループに与える影響を学びます。
テキスト入力、画像入力、セッション履歴の管理を追加します。
デプロイ環境に適したトランスポートとして、WebRTC、WebSocket、またはカスタムトランスポートを選択します。