What causes "The OpenAI realtime model ID is required." in microsoft/semantic-kernel?

Pass deployment_name= explicitly in the constructor: AzureRealtimeWebsocket(deployment_name='my-realtime-deployment', ...).

microsoft/semantic-kernel · error · ServiceInitializationError

The OpenAI realtime model ID is required.

Error message

The OpenAI realtime model ID is required.

What it means

Raised by AzureRealtimeWebsocket.__init__ after AzureOpenAISettings is successfully created. The settings object's realtime_deployment_name field (loaded from the AZURE_OPENAI_REALTIME_DEPLOYMENT_NAME env var or the deployment_name constructor argument) is checked for truthiness. If it is None or empty, the service has no model deployment target for the Realtime API and cannot proceed.

Source

Thrown at python/semantic_kernel/connectors/ai/open_ai/services/azure_realtime.py:126

                settings (OpenAIRealtimeExecutionSettings): the settings to use for the session
                chat_history (ChatHistory): the chat history to use for the session
                Otherwise they can also be passed to the context manager.
        """
        try:
            azure_openai_settings = AzureOpenAISettings(
                api_key=api_key,
                base_url=base_url,
                endpoint=endpoint,
                realtime_deployment_name=deployment_name,
                api_version=api_version,
                token_endpoint=token_endpoint,
                env_file_path=env_file_path,
                env_file_encoding=env_file_encoding,
            )
        except ValidationError as ex:
            raise ServiceInitializationError("Failed to create OpenAI settings.", ex) from ex
        if not azure_openai_settings.realtime_deployment_name:
            raise ServiceInitializationError("The OpenAI realtime model ID is required.")
        super().__init__(
            api_key=azure_openai_settings.api_key.get_secret_value() if azure_openai_settings.api_key else None,
            audio_output_callback=audio_output_callback,
            deployment_name=azure_openai_settings.realtime_deployment_name,
            endpoint=azure_openai_settings.endpoint,
            base_url=azure_openai_settings.base_url,
            api_version=azure_openai_settings.api_version,
            ad_token=ad_token,
            ad_token_provider=ad_token_provider,
            token_endpoint=azure_openai_settings.token_endpoint,
            ai_model_type=OpenAIModelTypes.REALTIME,
            service_id=service_id,
            default_headers=default_headers,
            client=async_client,
            websocket_base_url=websocket_base_url,
            credential=credential,
            **kwargs,
        )

View on GitHub (pinned to c028a0c7dc)

Solutions

Pass deployment_name= explicitly in the constructor: AzureRealtimeWebsocket(deployment_name='my-realtime-deployment', ...).
Set the AZURE_OPENAI_REALTIME_DEPLOYMENT_NAME environment variable to your Azure OpenAI realtime deployment name.
Verify the deployment exists in Azure Portal under Resource Management > Deployments and that its name matches exactly.

Example fix

# before
service = AzureRealtimeWebsocket(
    endpoint='https://myresource.openai.azure.com',
    api_key='...',
)
# after
service = AzureRealtimeWebsocket(
    deployment_name='gpt-4o-realtime',
    endpoint='https://myresource.openai.azure.com',
    api_key='...',
)

Defensive patterns

Strategy: validation

Validate before calling

import os

deployment_name = os.environ.get('AZURE_OPENAI_REALTIME_DEPLOYMENT_NAME')
if not deployment_name:
    raise ValueError(
        'AZURE_OPENAI_REALTIME_DEPLOYMENT_NAME is not set. '
        'Set it in your environment or .env file, or pass deployment_name= to the constructor.'
    )

Try / catch

from semantic_kernel.exceptions.service_exceptions import ServiceInitializationError

try:
    service = AzureRealtimeWebsocket(
        deployment_name=os.environ.get('AZURE_OPENAI_REALTIME_DEPLOYMENT_NAME'),
        endpoint='https://myresource.openai.azure.com',
        api_key='...',
    )
except ServiceInitializationError as e:
    if 'realtime model ID is required' in str(e):
        print('Set AZURE_OPENAI_REALTIME_DEPLOYMENT_NAME or pass deployment_name=')
    raise

Prevention

Set AZURE_OPENAI_REALTIME_DEPLOYMENT_NAME in your .env file.
Always pass deployment_name= explicitly in the constructor for clarity.
Verify the deployment name exists in Azure Portal > Resource Management > Deployments.
Use deployment-specific env var names (not a generic AZURE_OPENAI_DEPLOYMENT_NAME).

When it happens

Trigger: Constructing AzureRealtimeWebsocket without passing deployment_name= and without AZURE_OPENAI_REALTIME_DEPLOYMENT_NAME set in the environment or .env file. The settings were otherwise valid (endpoint, auth resolved), but the deployment identifier is missing.

Common situations: Using AZURE_OPENAI_DEPLOYMENT_NAME (generic) instead of AZURE_OPENAI_REALTIME_DEPLOYMENT_NAME (specific); .env file present but the realtime deployment variable line was commented out; switching from preview realtime (which used a different env var) to GA.

Related errors

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/a7b3e3880e2eb66b. Report an issue: GitHub.