microsoft/semantic-kernel · error · AgentInitializationException

The OpenAI model ID is required.

Error message

The OpenAI model ID is required.

What it means

Raised by create_client_and_model() when openai_settings.chat_model_id resolves to empty/None. Even with a valid API key, the assistant flow needs a concrete model name to attach to the assistant definition, so the library blocks client creation rather than sending a null model to OpenAI.

Source

Thrown at python/semantic_kernel/agents/open_ai/openai_assistant_agent.py:357

        Returns:
            An OpenAI client instance and the configured model name
        """
        try:
            openai_settings = OpenAISettings(
                chat_model_id=ai_model_id,
                api_key=api_key,
                org_id=org_id,
                env_file_path=env_file_path,
                env_file_encoding=env_file_encoding,
            )
        except ValidationError as ex:
            raise AgentInitializationException("Failed to create OpenAI settings.", ex) from ex

        if not openai_settings.api_key:
            raise AgentInitializationException("The OpenAI API key is required.")

        if not openai_settings.chat_model_id:
            raise AgentInitializationException("The OpenAI model ID is required.")

        merged_headers = dict(copy(default_headers)) if default_headers else {}
        if default_headers:
            merged_headers.update(default_headers)
        if APP_INFO:
            merged_headers.update(APP_INFO)
            merged_headers = prepend_semantic_kernel_to_user_agent(merged_headers)

        client = AsyncOpenAI(
            api_key=openai_settings.api_key.get_secret_value() if openai_settings.api_key else None,
            organization=openai_settings.org_id,
            default_headers=merged_headers,
            **kwargs,
        )

        return client, openai_settings.chat_model_id

    @staticmethod

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Set the chat_model_id env var or pass ai_model_id='gpt-4o' explicitly.
2. Verify OpenAISettings.chat_model_id env var name matches what your .env provides.
3. Instantiate OpenAISettings() and print chat_model_id to confirm resolution before creating the client.

Example fix

# before
client, model = await OpenAIAssistantAgent.create_client_and_model(api_key=os.environ['OPENAI_API_KEY'])

# after
client, model = await OpenAIAssistantAgent.create_client_and_model(
    api_key=os.environ['OPENAI_API_KEY'],
    ai_model_id='gpt-4o',
)

import os
assert os.environ.get('OPENAI_CHAT_MODEL_ID') or args.ai_model_id, 'model id required'

null

from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException
try:
    client, model = await OpenAIAssistantAgent.create_client_and_model(api_key=key)
except AgentInitializationException as e:
    if 'model ID' in str(e):
        client, model = await OpenAIAssistantAgent.create_client_and_model(api_key=key, ai_model_id='gpt-4o')

When it happens

Trigger: No OPENAI_CHAT_MODEL_ID (or the configured chat_model_id env var) set and no ai_model_id argument; model name present but empty; settings loaded from a .env that omits the model field.

Common situations: Using the connector without a model env var; misnamed env var (e.g. OPENAI_MODEL_ID vs the expected key); env file missing the model line; assuming a default model exists when none is set.

Related errors

• Failed to create OpenAI settings.
• The OpenAI API key is required.
• model.id required when creating a new Azure AI agent
• Missing required 'client' in OpenAIAssistantAgent._from_dict
• Expected OpenAISettings, got {type(settings).__name__}

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