Providers

Providers control how RealtimeAgent connects to a Realtime API backend — which WebSocket URL to use and how to authenticate.

The default is OpenAIProvider, which requires no explicit configuration when OPENAI_API_KEY is set in the environment.

OpenAI

Bases: RealtimeProvider

Realtime provider for the OpenAI API.

This is the default provider used by RealtimeAgent when no provider argument is supplied.

The API key is resolved in this order:

The api_key constructor argument.
The OPENAI_API_KEY environment variable.

Example

from rtvoice import RealtimeAgent, OpenAIProvider

agent = RealtimeAgent(
    instructions="You are a helpful assistant.",
    provider=OpenAIProvider(api_key="sk-..."),
)

Parameters:

Name	Type	Description	Default
`api_key`	`str \| None`	OpenAI API key. Falls back to the `OPENAI_API_KEY` environment variable when omitted.	`None`

Azure OpenAI

Bases: RealtimeProvider

Realtime provider for Azure OpenAI.

Constructs the Azure-specific WebSocket endpoint and authenticates using an api-key header instead of a Bearer token.

All constructor arguments fall back to environment variables when omitted:

Argument	Environment variable
`resource`	`AZURE_OPENAI_RESOURCE`
`deployment`	`AZURE_OPENAI_DEPLOYMENT`
`api_key`	`AZURE_OPENAI_API_KEY`

Example

from rtvoice import RealtimeAgent, AzureOpenAIProvider

agent = RealtimeAgent(
    instructions="You are a helpful assistant.",
    provider=AzureOpenAIProvider(
        resource="my-resource",
        deployment="gpt-4o-realtime-preview",
    ),
)

Parameters:

Name	Type	Description	Default
`resource`	`str \| None`	Azure OpenAI resource name (the subdomain of `openai.azure.com`). Falls back to the `AZURE_OPENAI_RESOURCE` environment variable.	`None`
`deployment`	`str \| None`	Deployment name that maps to a specific model. Falls back to the `AZURE_OPENAI_DEPLOYMENT` environment variable.	`None`
`api_key`	`str \| None`	Azure OpenAI API key. Falls back to the `AZURE_OPENAI_API_KEY` environment variable.	`None`
`api_version`	`str \| None`	API version string. Defaults to `2025-04-01-preview`.	`None`

Custom providers

Implement RealtimeProvider to connect to any compatible backend.

Bases: ABC

Abstract base class for Realtime API providers.

Implement this interface to add support for a new backend (e.g. a self-hosted proxy or a different cloud provider).

build_headers `abstractmethod`

build_headers() -> dict[str, str]

Return the HTTP headers required to authenticate the connection.

build_url `abstractmethod`

build_url(model: str) -> str

Return the WebSocket URL for the given model identifier.