OpenAIRealtimeAgentConfig
Configuration for OpenAIRealtimeAgent.
Defined in: src/providers/agent/openai/types.ts:97
Configuration for OpenAIRealtimeAgent.
Remarks
Extends BaseProviderConfig, so apiKey, proxyUrl, timeout, and debug are also available. In direct (browser) mode, authentication uses OpenAI’s documented WebSocket subprotocols ('realtime' + 'openai-insecure-api-key.<KEY>'); pass an async apiKey factory returning an ephemeral client secret (minted server-side via POST /v1/realtime/client_secrets) to avoid exposing a long-lived key. In proxy mode the proxy injects an Authorization: Bearer header.
Example
const agent = new OpenAIRealtimeAgent({
proxyUrl: '/api/proxy/openai-realtime',
model: 'gpt-realtime',
voice: 'marin',
instructions: 'You are a concise, friendly voice assistant.',
});
Extends
Properties
| Property | Type | Default value | Description | Inherited from | Defined in |
|---|---|---|---|---|---|
apiKey? | string | () => Promise<string> | undefined | API key or authentication token for the provider. Remarks Can be a static string or an async factory function that returns a fresh token on each call. Use a factory for short-lived tokens (e.g. Deepgram JWTs) so each WebSocket connection gets a valid credential. For client-side usage, consider using a proxy server to keep API keys secure. The SDK provides Express, Next.js, and Node adapters for this purpose. | BaseProviderConfig.apiKey | src/core/types/providers.ts:71 |
authType? | "token" | "bearer" | Provider-specific (typically 'token' for Deepgram, ignored for REST providers) | Authentication type for providers that support multiple auth mechanisms. Remarks Controls how the apiKey is sent to the provider: - 'token' — WebSocket subprotocol ['token', apiKey] or header Authorization: Token <key>. This is the default for Deepgram providers. - 'bearer' — WebSocket subprotocol ['bearer', token] or header Authorization: Bearer <token>. Use this for OAuth tokens or providers that expect Bearer auth. REST/SDK providers (Anthropic, OpenAI) handle auth through their SDK constructors and ignore this field. | BaseProviderConfig.authType | src/core/types/providers.ts:115 |
debug? | boolean | false | Whether to enable debug logging for this provider. Remarks When true, the provider emits detailed internal logs. This is separate from the SDK-level LoggingConfig. | BaseProviderConfig.debug | src/core/types/providers.ts:126 |
endpoint? | string | undefined | Custom endpoint URL to override the provider’s default API endpoint. Remarks Useful for self-hosted instances, proxy servers, or development environments. | BaseProviderConfig.endpoint | src/core/types/providers.ts:79 |
instructions? | string | undefined | System instructions defining the agent’s persona and behaviour. | - | src/providers/agent/openai/types.ts:106 |
language? | string | undefined | BCP-47 language hint for input transcription (e.g. 'en'). | - | src/providers/agent/openai/types.ts:131 |
model? | string | 'gpt-realtime' | Realtime model ID. | - | src/providers/agent/openai/types.ts:103 |
onFunctionCall? | (call) => Promise<{ content: string; }> | undefined | Handler invoked when the agent calls a function tool. Remarks The returned content is sent back as a function_call_output item and a new response is requested so the agent can speak the result. | - | src/providers/agent/openai/types.ts:151 |
organizationId? | string | undefined | OpenAI organization ID, sent as an auth subprotocol in direct mode. | - | src/providers/agent/openai/types.ts:154 |
projectId? | string | undefined | OpenAI project ID, sent as an auth subprotocol in direct mode. | - | src/providers/agent/openai/types.ts:157 |
proxyUrl? | string | undefined | URL of a CompositeVoice proxy server endpoint for this provider. Remarks When set, requests are routed through the proxy which injects the real API key server-side. This keeps API keys out of the browser. For WebSocket providers the HTTP URL is automatically converted to ws(s)://. At least one of apiKey or proxyUrl must be set for providers that require authentication (all except NativeSTT, NativeTTS, and WebLLM). Example proxyUrl: 'http://localhost:3000/api/proxy/deepgram' | BaseProviderConfig.proxyUrl | src/core/types/providers.ts:97 |
sessionOverrides? | Record<string, unknown> | undefined | Extra fields merged into the session.update payload’s session object, after the fields derived from this config. Remarks Escape hatch for Realtime session options this config does not model (e.g. max_output_tokens, prompt caching options). | - | src/providers/agent/openai/types.ts:167 |
temperature? | number | undefined | Sampling temperature for response generation. | - | src/providers/agent/openai/types.ts:116 |
timeout? | number | undefined | Request timeout in milliseconds. Remarks Applies to HTTP requests (REST providers) and connection establishment (WebSocket providers). Set to 0 for no timeout. | BaseProviderConfig.timeout | src/core/types/providers.ts:135 |
tools? | RealtimeAgentTool[] | undefined | Function tools the agent can call. | - | src/providers/agent/openai/types.ts:142 |
transcriptionModel? | string | 'gpt-4o-mini-transcribe' | Model used to transcribe the user’s input audio. Remarks Input transcription is what drives the SDK’s transcription.* events and conversation history — it runs alongside the speech-to-speech model. | - | src/providers/agent/openai/types.ts:128 |
turnDetection? | | RealtimeAgentTurnDetection | null | undefined | Turn-detection settings. Remarks Defaults to { type: 'server_vad' }. Pass null to disable VAD. | - | src/providers/agent/openai/types.ts:139 |
voice? | string | 'alloy' | Output voice name (e.g. 'alloy', 'marin', 'cedar'). | - | src/providers/agent/openai/types.ts:113 |