feat(realtime): make websocket URL configurable (#238)

Author: dkundel-openai

.changeset/realtime-url-configurable.md

@@ -0,0 +1,5 @@
+---
+'@openai/agents-realtime': minor
+---
+
+Expose configurable URL in OpenAIRealtimeWebSocket constructor and RealtimeSession.connect.

packages/agents-realtime/src/openaiRealtimeWebsocket.ts

@@ -47,6 +47,10 @@ export type OpenAIRealtimeWebSocketOptions = {
    * @see https://platform.openai.com/docs/guides/realtime#creating-an-ephemeral-token
    */
   useInsecureApiKey?: boolean;
+  /**
+   * The URL to use for the WebSocket connection.
+   */
+  url?: string;
 } & OpenAIRealtimeBaseOptions;
 
 /**
@@ -59,7 +63,7 @@ export class OpenAIRealtimeWebSocket
   implements RealtimeTransportLayer
 {
   #apiKey: string | undefined;
-  #url: string;
+  #url: string | undefined;
   #state: WebSocketState = {
     status: 'disconnected',
     websocket: undefined,
@@ -80,7 +84,7 @@ export class OpenAIRealtimeWebSocket
 
   constructor(options: OpenAIRealtimeWebSocketOptions = {}) {
     super(options);
-    this.#url = `wss://api.openai.com/v1/realtime?model=${this.currentModel}`;
+    this.#url = options.url;
     this.#useInsecureApiKey = options.useInsecureApiKey ?? false;
   }
 
@@ -169,7 +173,7 @@ export class OpenAIRealtimeWebSocket
           },
         };
 
-    const ws = new WebSocket(this.#url, websocketArguments as any);
+    const ws = new WebSocket(this.#url!, websocketArguments as any);
     this.#state = {
       status: 'connecting',
       websocket: ws,
@@ -260,9 +264,11 @@ export class OpenAIRealtimeWebSocket
     const model = options.model ?? this.currentModel;
     this.currentModel = model;
     this.#apiKey = await this._getApiKey(options);
-    this.#url =
+    const url =
       options.url ??
+      this.#url ??
       `wss://api.openai.com/v1/realtime?model=${this.currentModel}`;
+    this.#url = url;
 
     const sessionConfig: Partial<RealtimeSessionConfig> = {
       ...(options.initialSessionConfig || {}),

packages/agents-realtime/src/realtimeSession.ts

@@ -672,6 +672,7 @@ export class RealtimeSession<
     await this.#transport.connect({
       apiKey: options.apiKey ?? this.options.apiKey,
       model: this.options.model,
+      url: options.url,
       initialSessionConfig: await this.#getSessionConfig(this.options.config),
     });
 

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

@@ -58,6 +58,14 @@ describe('OpenAIRealtimeWebSocket', () => {
     expect(statuses).toEqual(['connecting', 'connected']);
   });
 
+  it('uses custom url from constructor', async () => {
+    const ws = new OpenAIRealtimeWebSocket({ url: 'ws://test' });
+    const p = ws.connect({ apiKey: 'ek_test', model: 'm' });
+    await vi.runAllTimersAsync();
+    await p;
+    expect(lastFakeSocket!.url).toBe('ws://test');
+  });
+
   it('handles audio delta, speech started and created/done events', async () => {
     const ws = new OpenAIRealtimeWebSocket();
     const audioSpy = vi.fn();

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

@@ -113,6 +113,14 @@ describe('RealtimeSession', () => {
     expect(transport.closeCalls).toBe(1);
   });
 
+  it('forwards url 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', url: 'ws://example' });
+    expect(t.connectCalls[0]?.url).toBe('ws://example');
+  });
+
   it('updateHistory accepts callback', () => {
     const item = createMessage('1', 'hi');
     session.updateHistory([item]);