fix review comments

Author: seratch

examples/realtime-twilio-sip/server.ts

@@ -7,6 +7,7 @@ import {
   OpenAIRealtimeSIP,
   RealtimeItem,
   RealtimeSession,
+  type RealtimeSessionOptions,
 } from '@openai/agents/realtime';
 import { getStartingAgent, WELCOME_MESSAGE } from './agents';
 
@@ -44,20 +45,27 @@ async function main() {
   const activeCallTasks = new Map<string, Promise<void>>();
   const startingAgent = getStartingAgent();
 
-  function getDefaultInstructions(): string {
-    if (typeof startingAgent.instructions === 'string') {
-      return startingAgent.instructions;
-    }
-    return 'You are a helpful triage agent for ABC customer service.';
-  }
+  // Reuse the same session options when accepting the call and when instantiating the session so
+  // the SIP payload remains in sync with the live websocket session.
+  const sessionOptions: Partial<RealtimeSessionOptions> = {
+    model: 'gpt-realtime',
+    config: {
+      audio: {
+        input: {
+          turnDetection: { type: 'semantic_vad', interruptResponse: true },
+        },
+      },
+    },
+  };
 
   async function acceptCall(callId: string): Promise<void> {
     try {
-      await openai.realtime.calls.accept(callId, {
-        type: 'realtime',
-        model: 'gpt-realtime',
-        instructions: getDefaultInstructions(),
-      });
+      // Build the initial session config using the agent data and session options
+      const initialConfig = await OpenAIRealtimeSIP.buildInitialConfig(
+        startingAgent,
+        sessionOptions,
+      );
+      await openai.realtime.calls.accept(callId, initialConfig);
       console.info(`Accepted call ${callId}`);
     } catch (error) {
       if (error instanceof APIError && error.status === 404) {
@@ -97,17 +105,7 @@ async function main() {
   async function observeCall(callId: string): Promise<void> {
     const session = new RealtimeSession(startingAgent, {
       transport: new OpenAIRealtimeSIP(),
-      model: 'gpt-realtime',
-      config: {
-        audio: {
-          input: {
-            turnDetection: {
-              type: 'semantic_vad',
-              interruptResponse: true,
-            },
-          },
-        },
-      },
+      ...sessionOptions,
     });
 
     session.on('history_added', (item: RealtimeItem) => logHistoryItem(item));

packages/agents-realtime/src/index.ts

@@ -49,6 +49,7 @@ export {
   OpenAIRealtimeEventTypes,
   DEFAULT_OPENAI_REALTIME_MODEL,
   DEFAULT_OPENAI_REALTIME_SESSION_CONFIG,
+  RealtimeSessionPayload,
 } from './openaiRealtimeBase';
 
 export { RealtimeOutputGuardrail } from './guardrail';

packages/agents-realtime/src/openaiRealtimeBase.ts

@@ -48,6 +48,8 @@ export type OpenAIRealtimeModels =
   | 'gpt-4o-mini-realtime-preview-2024-12-17'
   | 'gpt-realtime'
   | 'gpt-realtime-2025-08-28'
+  | 'gpt-realtime-mini'
+  | 'gpt-realtime-mini-2025-10-06'
   | (string & {}); // ensures autocomplete works
 
 /**
@@ -105,6 +107,13 @@ export type OpenAIRealtimeEventTypes = {
   disconnected: [];
 } & RealtimeTransportEventTypes;
 
+/**
+ * Shape of the payload that the Realtime API expects for session.create/update operations.
+ * This closely mirrors the REST `CallAcceptParams` type so that callers can feed the payload
+ * directly into the `openai.realtime.calls.accept` helper without casts.
+ */
+export type RealtimeSessionPayload = { type: 'realtime' } & Record<string, any>;
+
 export abstract class OpenAIRealtimeBase
   extends EventEmitterDelegate<OpenAIRealtimeEventTypes>
   implements RealtimeTransportLayer
@@ -523,10 +532,12 @@ export abstract class OpenAIRealtimeBase
     );
   }
 
-  protected _getMergedSessionConfig(config: Partial<RealtimeSessionConfig>) {
+  protected _getMergedSessionConfig(
+    config: Partial<RealtimeSessionConfig>,
+  ): RealtimeSessionPayload {
     const newConfig = toNewSessionConfig(config);
 
-    const sessionData: Record<string, any> = {
+    const sessionData: RealtimeSessionPayload = {
       type: 'realtime',
       instructions: newConfig.instructions,
       model: newConfig.model ?? this.#model,
@@ -588,6 +599,21 @@ export abstract class OpenAIRealtimeBase
     return sessionData;
   }
 
+  /**
+   * Build the payload object expected by the Realtime API when creating or updating a session.
+   *
+   * The helper centralises the conversion from camelCase runtime config to the snake_case payload
+   * required by the Realtime API so transports that need a one-off payload (for example SIP call
+   * acceptance) can reuse the same logic without duplicating private state.
+   *
+   * @param config - The session config to merge with defaults.
+   */
+  buildSessionPayload(
+    config: Partial<RealtimeSessionConfig>,
+  ): RealtimeSessionPayload {
+    return this._getMergedSessionConfig(config);
+  }
+
   private static buildTurnDetectionConfig(
     c: RealtimeTurnDetectionConfig | undefined,
   ): RealtimeTurnDetectionConfigAsIs | undefined {
@@ -735,7 +761,7 @@ export abstract class OpenAIRealtimeBase
    * @param config - The session config to update.
    */
   updateSessionConfig(config: Partial<RealtimeSessionConfig>): void {
-    const sessionData = this._getMergedSessionConfig(config);
+    const sessionData = this.buildSessionPayload(config);
 
     this.sendEvent({
       type: 'session.update',

packages/agents-realtime/src/openaiRealtimeSip.ts

@@ -4,6 +4,14 @@ import {
   OpenAIRealtimeWebSocket,
   OpenAIRealtimeWebSocketOptions,
 } from './openaiRealtimeWebsocket';
+import type { RealtimeSessionPayload } from './openaiRealtimeBase';
+import type { RealtimeSessionConfig } from './clientMessages';
+import {
+  RealtimeSession,
+  type RealtimeSessionOptions,
+  type RealtimeContextData,
+} from './realtimeSession';
+import { RealtimeAgent } from './realtimeAgent';
 
 /**
  * Transport layer that connects to an existing SIP-initiated Realtime call via call ID.
@@ -13,6 +21,46 @@ export class OpenAIRealtimeSIP extends OpenAIRealtimeWebSocket {
     super(options);
   }
 
+  /**
+   * Build the initial session payload for a SIP-attached session, matching the config that a RealtimeSession would send on connect.
+   *
+   * This enables SIP deployments to accept an incoming call with a payload that already reflects
+   * the active agent's instructions, tools, prompt, and tracing metadata without duplicating the
+   * session logic outside of the SDK. The returned object structurally matches the REST
+   * `CallAcceptParams` interface, so it can be forwarded directly to
+   * `openai.realtime.calls.accept(...)`.
+   *
+   * @param agent - The starting agent used to seed the session instructions, tools, and prompt.
+   * @param options - Optional session options that mirror the ones passed to the RealtimeSession constructor.
+   * @param overrides - Additional config overrides applied on top of the session options.
+   */
+  static async buildInitialConfig<TBaseContext = unknown>(
+    agent:
+      | RealtimeAgent<TBaseContext>
+      | RealtimeAgent<RealtimeContextData<TBaseContext>>,
+    options: Partial<RealtimeSessionOptions<TBaseContext>> = {},
+    overrides: Partial<RealtimeSessionConfig> = {},
+  ): Promise<RealtimeSessionPayload> {
+    const sessionConfig = await RealtimeSession.computeInitialSessionConfig(
+      agent,
+      options,
+      overrides,
+    );
+    const transport = new OpenAIRealtimeSIP();
+    return transport.buildSessionPayload(sessionConfig);
+  }
+
+  override sendAudio(
+    _audio: ArrayBuffer,
+    _options: { commit?: boolean } = {},
+  ): never {
+    // SIP integrations stream audio to OpenAI directly through the telephony provider, so the
+    // transport deliberately prevents userland code from sending duplicate buffers.
+    throw new Error(
+      'OpenAIRealtimeSIP does not support sending audio buffers; audio is handled by the SIP call.',
+    );
+  }
+
   async connect(options: RealtimeTransportLayerConnectOptions): Promise<void> {
     if (!options.callId) {
       throw new UserError(

packages/agents-realtime/src/realtimeSession.ts

@@ -406,6 +406,53 @@ export class RealtimeSession<
     return fullConfig;
   }
 
+  /**
+   * Compute the initial session config that the current session will use when connecting.
+   *
+   * This mirrors the configuration payload we send during `connect`, including dynamic values
+   * such as the upstream agent instructions, tool definitions, and prompt content generated at
+   * runtime. Keeping this helper exposed allows transports or orchestration layers to precompute
+   * a CallAccept-compatible payload without opening a socket.
+   *
+   * @param overrides - Additional config overrides applied on top of the session options.
+   */
+  async getInitialSessionConfig(
+    overrides: Partial<RealtimeSessionConfig> = {},
+  ): Promise<Partial<RealtimeSessionConfig>> {
+    await this.#setCurrentAgent(this.initialAgent);
+    return this.#getSessionConfig({
+      ...(this.options.config ?? {}),
+      ...(overrides ?? {}),
+    });
+  }
+
+  /**
+   * Convenience helper to compute the initial session config without manually instantiating and connecting a session.
+   *
+   * This is primarily useful for integrations that must provide the session configuration to a
+   * third party (for example the SIP `calls.accept` endpoint) before the actual realtime session
+   * is attached. The helper instantiates a throwaway session so all agent-driven dynamic fields
+   * resolve in exactly the same way as the live session path.
+   *
+   * @param agent - The starting agent for the session.
+   * @param options - Session options used to seed the config calculation.
+   * @param overrides - Additional config overrides applied on top of the provided options.
+   */
+  static async computeInitialSessionConfig<TBaseContext = unknown>(
+    agent:
+      | RealtimeAgent<TBaseContext>
+      | RealtimeAgent<RealtimeContextData<TBaseContext>>,
+    options: Partial<RealtimeSessionOptions<TBaseContext>> = {},
+    overrides: Partial<RealtimeSessionConfig> = {},
+  ): Promise<Partial<RealtimeSessionConfig>> {
+    const session = new RealtimeSession(agent, options);
+    try {
+      return await session.getInitialSessionConfig(overrides);
+    } finally {
+      session.close();
+    }
+  }
+
   async updateAgent(newAgent: RealtimeAgent<TBaseContext>) {
     this.#currentAgent.emit('agent_handoff', this.#context, newAgent);
     this.emit('agent_handoff', this.#context, this.#currentAgent, newAgent);

packages/agents-realtime/test/openaiRealtimeWebsocket.test.ts

@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { OpenAIRealtimeBase } from '../src/openaiRealtimeBase';
 import { OpenAIRealtimeWebSocket } from '../src/openaiRealtimeWebsocket';
 import { OpenAIRealtimeSIP } from '../src/openaiRealtimeSip';
+import { RealtimeAgent } from '../src/realtimeAgent';
 
 let lastFakeSocket: any;
 vi.mock('ws', () => {
@@ -406,4 +407,31 @@ describe('OpenAIRealtimeWebSocket', () => {
     );
     sip.close();
   });
+
+  it('OpenAIRealtimeSIP buildInitialConfig returns realtime payload seeded from agent', async () => {
+    const agent = new RealtimeAgent({
+      name: 'sip-agent',
+      handoffs: [],
+      instructions: 'Respond politely.',
+    });
+    const payload = await OpenAIRealtimeSIP.buildInitialConfig(
+      agent,
+      {
+        model: 'gpt-realtime',
+        config: { audio: { output: { speed: 1.5 } } },
+      },
+      { audio: { output: { speed: 2 } } },
+    );
+    expect(payload.type).toBe('realtime');
+    expect(payload.model).toBe('gpt-realtime');
+    expect(payload.instructions).toBe('Respond politely.');
+    expect(payload.audio?.output?.speed).toBe(2);
+  });
+
+  it('OpenAIRealtimeSIP sendAudio throws', () => {
+    const sip = new OpenAIRealtimeSIP();
+    expect(() => sip.sendAudio(new ArrayBuffer(1))).toThrow(
+      'OpenAIRealtimeSIP does not support sending audio buffers',
+    );
+  });
 });

packages/agents-realtime/test/realtimeSession.test.ts

@@ -126,6 +126,14 @@ describe('RealtimeSession', () => {
     expect(t.connectCalls[0]?.url).toBe('ws://example');
   });
 
+  it('forwards callId in connect options to transport', async () => {
+    const t = new FakeTransport();
+    const agent = new RealtimeAgent({ name: 'A', handoffs: [] });
+    const s = new RealtimeSession(agent, { transport: t });
+    await s.connect({ apiKey: 'test', callId: 'call_123' });
+    expect(t.connectCalls[0]?.callId).toBe('call_123');
+  });
+
   it('includes default transcription config when connecting', async () => {
     const t = new FakeTransport();
     const agent = new RealtimeAgent({ name: 'A', handoffs: [] });