リアルタイムエージェントの構築

アーキテクチャは早い段階で選択してください。

OpenAIRealtimeWebRTC は最もシンプルなブラウザ向けの方法で、音声の入出力を自動的に処理します。組み込みの接続では、Realtime イベント用のデータチャネルも使用します。ブラウザでは音声のみを扱い、アプリケーションサーバー側で Realtime イベント、ツール、ビジネスロジックを管理する場合は、サーバー側の制御を使用したブラウザ音声を参照してください。
OpenAIRealtimeWebSocket ではより細かく制御できますが、音声のキャプチャと再生を自身で管理する必要があります。
関数ツールは、RealtimeSession が実行される場所で実行されます。セッションがブラウザで実行される場合、ツールもブラウザで実行されます。
Realtime のハンドオフでは、同じライブセッションモデルが維持されます。音声の変更は、セッションが音声出力を生成する前にのみ機能します。別のバックエンドモデルが必要な場合は、ハンドオフではなくツールを介して委譲してください。

セッションの設定

音声処理

デフォルトの OpenAIRealtimeWebRTC など、一部のトランスポートレイヤーでは音声の入出力が自動的に処理されます。OpenAIRealtimeWebSocket など、その他のトランスポート方式では、セッションの音声を自身で処理する必要があります。

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

const agent = new RealtimeAgent({ name: 'My agent' });
const session = new RealtimeSession(agent);
const newlyRecordedAudio = new ArrayBuffer(0);

session.on('audio', (event: TransportLayerAudio) => {
  // play your audio
});

// send new audio to the agent
session.sendAudio(newlyRecordedAudio);

基盤となるトランスポートが対応している場合、session.muted は現在のミュート状態を返し、session.mute(true | false) はマイクのキャプチャを切り替えます。OpenAIRealtimeWebSocket はミュートを実装していません。session.muted は null を返し、session.mute() は例外をスローします。そのため、WebSocket の構成ではクライアント側でキャプチャを一時停止し、マイクを再び有効にするまで sendAudio() の呼び出しを停止してください。

セッション構成

RealtimeSession の作成時に、通常は model オプションと config オブジェクトを介してセッション自体を構成します。connect(...) は、任意のセッションフィールドではなく、認証情報、エンドポイント URL、既存の Realtime 通話への接続など、接続時の事項に使用します。

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

const agent = new RealtimeAgent({
  name: 'Greeter',
  instructions: 'Greet the user with cheer and answer questions.',
});

const session = new RealtimeSession(agent, {
  model: 'gpt-realtime-2.1',
  config: {
    outputModalities: ['audio'],
    reasoning: {
      effort: 'low',
    },
    parallelToolCalls: true,
    audio: {
      input: {
        format: 'pcm16',
        transcription: {
          model: 'gpt-live-transcribe',
          delay: 'low',
          prompt:
            'A software support conversation about the OpenAI Agents SDK.',
          keywords: ['OpenAI Agents SDK', 'RealtimeSession'],
          languages: ['en', 'ja'],
        },
      },
      output: {
        format: 'pcm16',
      },
    },
  },
});

内部では、SDK がこの構成を Realtime の session.update 形式に正規化します。RealtimeSessionConfig に対応するプロパティがない元のセッションフィールドが必要な場合は、providerData を使用するか、session.transport.sendEvent(...) を介して元の session.update を送信してください。

outputModalities、audio.input、audio.output を使用する新しい SDK の構成形式を推奨します。modalities、inputAudioFormat、outputAudioFormat、inputAudioTranscription、turnDetection などの古い SDK エイリアスも後方互換性のために正規化されますが、新しいコードではここに示すネストされた audio 構造を使用してください。

gpt-realtime-2.1 など推論対応の Realtime モデルでは、セッション構成に reasoning.effort を設定します。推論の強度を高くすると、レイテンシーとトークン使用量が増える可能性があります。モデルが複数のツールを並列に呼び出せるかどうかを制御する場合は、parallelToolCalls も設定できます。

入力の文字起こしでは、audio.input.transcription が GA 版の文字起こしモデルとそのコンテキストオプションを受け付けます。低レイテンシーのストリーミング文字起こしには gpt-live-transcribe を使用します。このモデルの delay 設定では、部分的な文字起こしの速度と最終的な文字起こし品質のバランスを調整できます。gpt-live-transcribe と gpt-transcribe はどちらも、自由形式の prompt、リテラル値の keywords、languages 配列を受け付けます。これらのモデルでは languages を使用します。単一の言語ヒントを受け付ける古い文字起こしモデルでは、引き続き単数形の language フィールドを使用します。モデル固有のワークフローについては、公式の文字起こしコンテキストのガイダンスと Realtime 文字起こしガイドを参照してください。

音声対音声セッションでは、通常 outputModalities: ['audio'] を選択します。これにより、音声出力と文字起こしが得られます。テキストのみの応答が必要な場合に限り、['text'] に切り替えてください。

新しく追加され、RealtimeSessionConfig に対応するパラメーターがない場合は、providerData を使用できます。providerData に渡したものはすべて、元の session オブジェクトの一部として転送されます。

構築時に設定できる追加の RealtimeSession オプションは次のとおりです。

オプション	型	用途
`context`	`TContext`	セッションコンテキストにマージされる追加のローカルコンテキスト
`historyStoreAudio`	`boolean`	ローカルの履歴スナップショットに音声データを保存します（デフォルトでは無効）
`outputGuardrails`	`RealtimeOutputGuardrail[]`	セッションの出力ガードレール（ガードレールを参照）
`outputGuardrailSettings`	`{ debounceTextLength?: number }`	ガードレールの実行間隔。デフォルトは `100` です。完全なテキストが利用可能になったときに一度だけ実行するには `-1` を使用します
`tracingDisabled`	`boolean`	セッションのトレーシングを無効化します
`groupId`	`string`	セッション間またはバックエンド実行間でトレースをグループ化します。`workflowName` が必要です
`traceMetadata`	`Record<string, any>`	セッショントレースに付加するカスタムメタデータ。`workflowName` が必要です
`workflowName`	`string`	トレースワークフローのわかりやすい名前
`automaticallyTriggerResponseForMcpToolCalls`	`boolean`	MCP ツール呼び出しの完了時にモデル応答を自動的にトリガーします（デフォルト：`true`）
`toolErrorFormatter`	`ToolErrorFormatter`	モデルに返すツール承認の拒否メッセージをカスタマイズします
`toolExecution`	`RealtimeToolExecutionConfig`	ローカルの Realtime 関数ツールに対する SDK 側の実行設定。保留中の承認リクエストより前に入力ガードレールを実行するには、`preApprovalInputGuardrails: true` を設定します

connect(...) のオプションは次のとおりです。

オプション	型	用途
`apiKey`	`string \| (() => string \| Promise<string>)`	この接続で使用する API キー（または遅延ローダー）
`model`	`OpenAIRealtimeModels \| string`	トランスポートレベルのオプション型に存在します。`RealtimeSession` ではコンストラクターでモデルを設定します。元のトランスポートでは接続時にもモデルを使用できます
`url`	`string`	省略可能なカスタム Realtime エンドポイント URL
`callId`	`string`	WebRTC または SIP で確立された通話を含む既存の Realtime 通話に、WebSocket トランスポートをサイドバンド接続として接続します

会話のライフサイクル

RealtimeSession は長時間維持される Realtime 接続の上に構築されています。会話履歴のローカルコピーを保持し、トランスポートイベントをリッスンし、ツールと出力ガードレールを実行し、アクティブなエージェント構成をトランスポートと同期します。

基盤となる API の動作も重要です。

接続に成功すると session.created イベントで開始され、その後の構成変更では session.updated が生成されます。
ほとんどのセッションプロパティは時間の経過とともに変更できますが、会話の途中で model を変更することはできません。voice はセッションが音声出力を生成する前にのみ変更できます。また、Realtime API ではトレーシングを有効にした後に変更できないため、トレーシングは事前に決定しておく必要があります。
現在、Realtime API では単一セッションが 60 分に制限されています。
入力音声の文字起こしは非同期で行われるため、最新の発話の文字起こしは、応答生成がすでに開始された後に届くことがあります。

SDK レイヤーでは、await session.connect() は「会話を開始できる程度にトランスポートの準備が完了した」ことを意味しますが、正確なタイミングはトランスポートによって異なります。

デフォルトのブラウザ WebRTC トランスポートでは、データチャネルが開くとすぐに SDK が最初の session.update を送信し、対応する session.updated イベントを待ってから connect() の解決を試みます。WebRTC トランスポートがこの確認応答を待つのは、instructions、ツール、モダリティーが適用される前に音声がサーバーへ到達することを防ぐためです。この確認応答が届かない場合、connect() は短いタイムアウト後に解決するようフォールバックします。
デフォルトのサーバー側 WebSocket トランスポートでは、ソケットが開き、初期構成が送信されると connect() が解決します。そのため、対応する session.updated イベントは、connect() がすでに解決した後に届くことがあります。

元のイベントモデルが必要な場合は、このページとあわせて公式の Realtime 会話ガイドを参照してください。

インタラクションフロー

ターン検出と音声アクティビティ検出

デフォルトでは、Realtime セッションは組み込みの音声アクティビティ検出（VAD）を使用します。これにより、API はユーザーが発話を開始または終了したタイミングと、応答を作成するタイミングを判断できます。SDK では、これを audio.input.turnDetection を介して公開しています。

import { RealtimeSession } from '@openai/agents/realtime';
import { agent } from './agent';

const session = new RealtimeSession(agent, {
  model: 'gpt-realtime-2.1',
  config: {
    audio: {
      input: {
        turnDetection: {
          type: 'semantic_vad',
          eagerness: 'medium',
          createResponse: true,
          interruptResponse: true,
        },
      },
    },
  },
});

一般的なモードは次の 2 つです。

semantic_vad は、より自然なターン境界を目指し、ユーザーがまだ話し終えていないように聞こえる場合は少し長く待つことができます。
server_vad は、しきい値をより重視し、threshold、prefixPaddingMs、silenceDurationMs、idleTimeoutMs などの設定を公開します。

ターン境界を自身で管理する場合は、audio.input.turnDetection を null に設定します。基盤となる動作の詳細については、公式の音声アクティビティ検出ガイドと Realtime 会話ガイドを参照してください。

割り込み

VAD が有効な場合、エージェントの発話中にユーザーが話し始めると、現在の応答を中断できます。WebSocket トランスポートでは、SDK が input_audio_buffer.speech_started をリッスンし、ユーザーが実際に聞いた位置までアシスタントの音声を切り詰め、audio_interrupted イベントを発行します。このイベントは、WebSocket の構成で再生を自身で管理する場合に特に便利です。

import { session } from './agent';

session.on('audio_interrupted', () => {
  // handle local playback interruption
});

手動の停止ボタンを用意する場合は、自身で interrupt() を呼び出します。

import { session } from './agent';

session.interrupt();
// This still triggers `audio_interrupted` so your UI can stop playback

WebRTC と WebSocket はどちらも進行中の応答を停止しますが、低レベルの仕組みはトランスポートによって異なります。WebRTC では、バッファーされた出力音声が自動的に消去されます。WebSocket の構成では、引き続きローカル再生を自身で停止する必要があります。また、対応する切り詰めイベントと会話イベントがトランスポートから返されると、ローカル履歴が更新されます。

テキスト入力

ライブ会話へ入力済みのテキストや追加の構造化されたユーザーコンテンツを送信する場合は、sendMessage() を使用します。

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

const agent = new RealtimeAgent({
  name: 'Assistant',
});

const session = new RealtimeSession(agent, {
  model: 'gpt-realtime-2.1',
});

session.sendMessage('Hello, how are you?');

これは、テキストと音声を組み合わせた UI、帯域外でのコンテキスト注入、または音声入力に明示的なテキストの補足を組み合わせる場合に便利です。

画像入力

Realtime の音声対音声セッションには画像も含められます。SDK では、addImage() を使用して現在の会話に画像を添付します。

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

const agent = new RealtimeAgent({
  name: 'Assistant',
});

const session = new RealtimeSession(agent, {
  model: 'gpt-realtime-2.1',
});

const imageDataUrl = 'data:image/png;base64,...';

session.addImage(imageDataUrl, { triggerResponse: false });
session.sendMessage('Describe what is in this image.');

triggerResponse: false を渡すと、モデルに応答を求める前に、画像を後続のテキストまたは音声ターンとまとめられます。これは、公式の Realtime 会話における画像入力のガイダンスに沿った動作です。

手動による応答制御

上位の SDK レイヤーでは、sendMessage() と addImage() がデフォルトで応答をトリガーします。元のトランスポートイベント、プッシュトゥトークフロー、カスタムのモデレーション／検証手順を使用する場合は、手動による応答制御が重要です。

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

const agent = new RealtimeAgent({
  name: 'Greeter',
  instructions: 'Greet the user with cheer and answer questions.',
});

const session = new RealtimeSession(agent, {
  model: 'gpt-realtime-2.1',
});

session.transport.on('*', (event) => {
  // Event received from the underlying Realtime transport
});

// Send any valid client event, for example, to trigger a new response
session.transport.sendEvent({
  type: 'response.create',
  // ...
});

一般的なケースは次の 2 つです。

audio.input.turnDetection = null で VAD を完全に無効にした場合、音声ターンをコミットしてから response.create を送信する必要があります。
VAD を有効にしたまま turnDetection.interruptResponse = false と turnDetection.createResponse = false を設定した場合、API は引き続きターンを検出しますが、応答の作成は自身で行う必要があります。

turnDetection.interruptResponse と turnDetection.createResponse の両方を false に設定しながら VAD を有効にしておくと、モデルが応答する前にユーザー入力を検査またはモデレーションする場合に便利です。この構成は、公式の自動応答の無効化に関する Realtime 会話ガイダンスに沿っています。

エージェントの機能

ハンドオフ

通常のエージェントと同様に、ハンドオフを使用してエージェントを複数のエージェントに分割し、それらの間をオーケストレーションすることで、パフォーマンスを向上させ、問題のスコープをより適切に設定できます。

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

const mathTutorAgent = new RealtimeAgent({
  name: 'Math Tutor',
  handoffDescription: 'Specialist agent for math questions',
  instructions:
    'You provide help with math problems. Explain your reasoning at each step and include examples',
});

const agent = new RealtimeAgent({
  name: 'Greeter',
  instructions: 'Greet the user with cheer and answer questions.',
  handoffs: [mathTutorAgent],
});

通常のエージェントとは異なり、リアルタイムエージェントではハンドオフの動作が若干異なります。ハンドオフが実行されると、進行中のセッションが新しいエージェント構成に更新されます。そのため、新しいエージェントは進行中の会話履歴へ自動的にアクセスでき、現在のところ入力フィルターは適用されません。

セッションはライブ状態を維持するため、ハンドオフ中にそのセッションのモデルは変更されません。音声の変更は、基盤となる Realtime API のルールに従います。つまり、セッションが音声出力を生成する前にのみ機能します。Realtime のハンドオフは主に、同じセッション上で RealtimeAgent の構成を切り替えるためのものです。gpt-5.4 のような推論モデルなど別のモデルを使用する必要がある場合や、Realtime ではないバックエンドエージェントに委譲する必要がある場合は、ツールを介した委譲を使用してください。

ツール

通常のエージェントと同様に、リアルタイムエージェントはツールを呼び出してアクションを実行できます。Realtime は、 関数ツール （ローカルで実行）と リモート MCP サーバーツール （Realtime API によりリモートで実行）に対応しています。通常のエージェントで使用するものと同じ tool() ヘルパーを使用して、関数ツールを定義できます。

Responses 専用のツールオプションは、リアルタイムエージェントには引き継がれません。'programmatic' を含む関数ツールの outputSchema と allowedCallers の値は拒否されます。リモート MCP サーバーツールのプログラムによる呼び出し元も同様です。Realtime セッションでは直接呼び出し可能な関数ツールまたはリモート MCP サーバーツールを使用するか、Programmatic Tool Calling が必要な処理を Responses エージェントに委譲してください。

import { tool, RealtimeAgent } from '@openai/agents/realtime';
import { z } from 'zod';

const getWeather = tool({
  name: 'get_weather',
  description: 'Return the weather for a city.',
  parameters: z.object({ city: z.string() }),
  async execute({ city }) {
    return `The weather in ${city} is sunny.`;
  },
});

const weatherAgent = new RealtimeAgent({
  name: 'Weather assistant',
  instructions: 'Answer weather questions.',
  tools: [getWeather],
});

関数ツール

関数ツールは、RealtimeSession と同じ環境で実行されます。つまり、セッションをブラウザで実行している場合、ツールもブラウザで実行されます。機密性の高いアクションを実行する必要がある場合は、ツール内からバックエンドを呼び出し、権限が必要な処理をサーバーに実行させてください。

これにより、ブラウザ側のツールをサーバー側ロジックへの薄いバックチャネルとして機能させられます。たとえば、examples/realtime-next では、ブラウザに refundBackchannel ツールを定義し、リクエストと現在の会話履歴をサーバー上の handleRefundRequest(...) に転送します。サーバーでは、別の Runner が異なるエージェントまたはモデルを使用して返金を評価し、その実行結果を音声セッションに返すことができます。

リモート MCP サーバーツール

リモート MCP サーバーツールは hostedMcpTool で構成でき、リモートで実行されます。MCP ツールの利用可能状況が変化すると、セッションは mcp_tools_changed を発行します。MCP ツール呼び出しの完了後にセッションがモデル応答を自動的にトリガーしないようにするには、automaticallyTriggerResponseForMcpToolCalls: false を設定します。

現在フィルタリングされている MCP ツールの一覧は、session.availableMcpTools でも利用できます。このプロパティと mcp_tools_changed イベントはどちらも、エージェント構成の allowed_tools フィルターを適用した後、アクティブなエージェントで有効になっているリモート MCP サーバーのみを反映します。

リモート MCP サーバーツールの設定では、安全なサーバーの選択、ヘッダー、承認を接続前の構成として扱うと理解しやすくなります。RealtimeSession.connect() がトランスポートを開く前に、SDK はアクティブなエージェントのリモート MCP サーバーツール定義を解決し、対応する MCP フィールドを Realtime API へ送信する初期セッション構成に含めます。

安全なリモート MCP 構成を connect() より前に指定することは、ブラウザの WebRTC アプリで特に重要です。一時的なクライアントシークレットは常にサーバー上で発行されます。そのため、秘匿する必要があるリモート MCP の認証情報やカスタム headers は、最初の session ペイロードの一部として、サーバー側の POST /v1/realtime/client_secrets リクエストに含めてください。長期間有効な認証情報をブラウザコードに含め、connect() の開始後に追加するような設計は避けてください。

Realtime API レベルでは、後続の session.update 呼び出しでツールやその他の変更可能なセッションフィールドを引き続き変更でき、アクティブなエージェントが変わると SDK 自体も session.update を送信します。ただしブラウザアプリでは、安全なリモート MCP の初期化をサーバー側の接続前に行う事項として扱い、ブラウザ側の RealtimeSession 構成をサーバーが発行した内容と一致させてください。

バックグラウンドの実行結果

ツールの実行中、エージェントはユーザーからの新しいリクエストを処理できません。体験を向上させる方法の 1 つは、ツールを実行する直前にその旨を伝えるようエージェントに指示したり、ツールの実行時間を確保するために特定のフレーズを発話させたりすることです。

関数ツールの完了後に別のモデル応答をすぐにトリガーしない場合は、@openai/agents/realtime の backgroundResult(output) を返します。これにより、応答のトリガーを自身で制御したまま、ツール出力をセッションへ返せます。

タイムアウト

関数ツールのタイムアウトオプション（timeoutMs、timeoutBehavior、timeoutErrorFunction）は、Realtime セッションでも同じように機能します。デフォルトの error_as_result では、タイムアウトメッセージがツール出力として送信されます。raise_exception では、セッションが ToolTimeoutError を含む error イベントを発行し、その呼び出しのツール出力は送信されません。

会話履歴へのアクセス

エージェントが特定のツールを呼び出した際の引数に加えて、Realtime セッションが追跡している現在の会話履歴のスナップショットにもアクセスできます。これは、会話の現在の状態に基づいてより複雑なアクションを実行する場合や、委譲にツールを使用する場合に便利です。

import {
  tool,
  RealtimeContextData,
  RealtimeItem,
} from '@openai/agents/realtime';
import { z } from 'zod';

const parameters = z.object({
  request: z.string(),
});

const refundTool = tool<typeof parameters, RealtimeContextData>({
  name: 'Refund Expert',
  description: 'Evaluate a refund',
  parameters,
  execute: async ({ request }, details) => {
    // The history might not be available
    const history: RealtimeItem[] = details?.context?.history ?? [];
    // Call your backend to process the refund request
  },
});

ツール実行前の承認

needsApproval: true を指定してツールを定義すると、エージェントはツールを実行する前に tool_approval_requested イベントを発行します。

このイベントをリッスンすると、ツール呼び出しを承認または拒否するための UI をユーザーに表示できます。

await session.approve(request.approvalItem) または await session.reject(request.approvalItem) でリクエストを解決します。関数ツールでは、{ alwaysApprove: true } または { alwaysReject: true } を渡すことで、その後のセッション中に繰り返される呼び出しに同じ判断を再利用できます。また、session.reject(request.approvalItem, { message: '...' }) を使用すると、その特定の呼び出しについてカスタム拒否メッセージをモデルへ返せます。リモート MCP サーバーツールの承認では、固定の承認／拒否はサポートされません。代わりに、リモート MCP の allowedTools 構成でツールを制限してください。

呼び出しごとの拒否 message を渡さない場合、セッションは toolErrorFormatter が構成されていればそれを使用し、その後 SDK のデフォルト拒否テキストへフォールバックします。

デフォルトでは、関数ツールの入力ガードレールは承認後、ツールの実行直前に実行されます。new RealtimeSession(...) に toolExecution: { preApprovalInputGuardrails: true } を渡すと、ローカル関数ツールの入力ガードレールは、セッションが tool_approval_requested を発行する前にも実行されます。ガードレールが拒否すると、拒否メッセージがツール出力として返され、承認イベントはスキップされます。ガードレールが呼び出しを許可した場合は、引き続き承認イベントが発行され、session.approve(...) の後、実行前にガードレールが再度実行されます。

import { session } from './agent';

session.on('tool_approval_requested', (_context, _agent, request) => {
  // Show a UI to let the user approve or reject the tool call
  // Then resolve the request with `session.approve(...)` or `session.reject(...)`

  session.approve(request.approvalItem);
});

ガードレール

ガードレールは、エージェントの発言が一連のルールに違反していないかを監視し、応答を即座に打ち切るための仕組みです。これらのチェックは、エージェントの応答の出力ストリームに対して実行されます。テキストのみのセッションでは、SDK が出力テキストの差分を評価します。音声セッションでは、出力音声の文字起こしとその差分を使用するため、重要な前提条件は、別のテキスト出力モダリティーではなく文字起こしが利用可能であることです。

指定したガードレールはモデル応答が返される間に非同期で実行されるため、たとえば「特定の禁止語に言及した」など、事前定義された分類トリガーに基づいて応答を打ち切れます。

ガードレールが作動すると、セッションは guardrail_tripped イベントを発行します。このイベントは、ガードレールをトリガーした itemId を含む details オブジェクトも提供します。

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

const agent = new RealtimeAgent({
  name: 'Greeter',
  instructions: 'Greet the user with cheer and answer questions.',
});

const guardrails: RealtimeOutputGuardrail[] = [
  {
    name: 'No mention of Dom',
    async execute({ agentOutput }) {
      const domInOutput = agentOutput.includes('Dom');
      return {
        tripwireTriggered: domInOutput,
        outputInfo: { domInOutput },
      };
    },
  },
];

const guardedSession = new RealtimeSession(agent, {
  outputGuardrails: guardrails,
});

デフォルトでは、ガードレールは 100 文字ごと、および最終的な文字起こしが利用可能になった時点で再度実行されます。通常、テキストの発話には文字起こしの生成よりも時間がかかるため、多くの場合、ユーザーが安全でない出力を聞く前にガードレールで打ち切れます。

この動作を変更する場合は、outputGuardrailSettings オブジェクトをセッションに渡せます。

応答の最後に、完全に生成された文字起こしを一度だけ評価する場合は、debounceTextLength: -1 を設定します。

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

const agent = new RealtimeAgent({
  name: 'Greeter',
  instructions: 'Greet the user with cheer and answer questions.',
});

const guardedSession = new RealtimeSession(agent, {
  outputGuardrails: [
    /*...*/
  ],
  outputGuardrailSettings: {
    debounceTextLength: 500, // run guardrail every 500 characters or set it to -1 to run it only at the end
  },
});

会話状態と委譲

会話履歴の管理

RealtimeSession は、ユーザーメッセージ、アシスタントの出力、ツール呼び出し、切り詰め状態を追跡するローカルの history スナップショットを自動的に維持します。これを UI に表示したり、ツール内で確認したり、項目を修正または削除する必要があるときに更新したりできます。

会話が変化すると、セッションは history_updated を発行します。履歴の変更をリクエストする必要がある場合は、updateHistory() を使用します。これはトランスポートに対し、現在の履歴との差分を計算して必要な削除／作成イベントを送信するよう要求します。対応する会話イベントが返されると、ローカルの session.history ビューが更新されます。

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

const agent = new RealtimeAgent({
  name: 'Assistant',
});

const session = new RealtimeSession(agent, {
  model: 'gpt-realtime-2.1',
});

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

// listening to the history_updated event
session.on('history_updated', (history) => {
  // returns the full history of the session
  console.log(history);
});

// Option 1: explicit setting
session.updateHistory([
  /* specific history */
]);

// Option 2: override based on current state like removing all agent messages
session.updateHistory((currentHistory) => {
  return currentHistory.filter(
    (item) => !(item.type === 'message' && item.role === 'assistant'),
  );
});

制限事項

現在、関数ツールの呼び出しを後から編集することはできません。
履歴内のアシスタントテキストは、output_audio.transcript を含む利用可能な文字起こしに依存します。
割り込みによって切り詰められた応答には、最終的な文字起こしが保持されません。
入力音声の文字起こしは、モデルが音声をどのように解釈したかの正確なコピーではなく、ユーザーの発言内容を把握するための大まかな目安として扱うのが適切です。

ツールを介した委譲

会話履歴とツール呼び出しを組み合わせることで、会話を別のバックエンドエージェントに委譲してより複雑なアクションを実行し、その実行結果をユーザーに返せます。

import {
  RealtimeAgent,
  RealtimeContextData,
  tool,
} from '@openai/agents/realtime';
import { handleRefundRequest } from './serverAgent';
import z from 'zod';

const refundSupervisorParameters = z.object({
  request: z.string(),
});

const refundSupervisor = tool<
  typeof refundSupervisorParameters,
  RealtimeContextData
>({
  name: 'escalateToRefundSupervisor',
  description: 'Escalate a refund request to the refund supervisor',
  parameters: refundSupervisorParameters,
  execute: async ({ request }, details) => {
    // This will execute on the server
    return handleRefundRequest(request, details?.context?.history ?? []);
  },
});

const agent = new RealtimeAgent({
  name: 'Customer Support',
  instructions:
    'You are a customer support agent. If you receive any requests for refunds, you need to delegate to your supervisor.',
  tools: [refundSupervisor],
});

次のコードはサーバー上で実行されます。この例では、Next.js Server Action を介して実行されます。

// This runs on the server
import 'server-only';

import { Agent, run } from '@openai/agents';
import type { RealtimeItem } from '@openai/agents/realtime';
import z from 'zod';

const agent = new Agent({
  name: 'Refund Expert',
  instructions:
    'You are a refund expert. You are given a request to process a refund and you need to determine if the request is valid.',
  model: 'gpt-5.4',
  outputType: z.object({
    reason: z.string(),
    refundApproved: z.boolean(),
  }),
});

export async function handleRefundRequest(
  request: string,
  history: RealtimeItem[],
) {
  const input = `
The user has requested a refund.

The request is: ${request}

Current conversation history:
${JSON.stringify(history, null, 2)}
`.trim();

  const result = await run(agent, input);

  return JSON.stringify(result.finalOutput, null, 2);
}