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.

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.

Appendix: 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)