microsoft/semantic-kernel · error · AgentInitializationException

The OpenAI Responses model ID is required.

Error message

The OpenAI Responses model ID is required.

What it means

Raised by setup_resources() when openai_settings.responses_model_id is falsy after construction. The Responses API requires a model identifier (e.g. 'gpt-4o', 'o3'), distinct from the Chat Completions model id. The id comes from the responses_model_id argument or the corresponding env var; neither resolved to a value.

Source

Thrown at python/semantic_kernel/agents/open_ai/openai_responses_agent.py:439

        Returns:
            An OpenAI client instance and the configured Response model name
        """
        try:
            openai_settings = OpenAISettings(
                responses_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.responses_model_id:
            raise AgentInitializationException("The OpenAI Responses 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.responses_model_id

    @staticmethod

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Pass ai_model_id explicitly: setup_resources(ai_model_id='gpt-4o').
2. Set the responses-model environment variable consumed by OpenAISettings (e.g. OPENAI_RESPONSES_MODEL_ID).
3. Confirm the env var name matches what OpenAISettings.responses_model_id binds to.
4. Migrate to create_client() for the same behavior without deprecation warnings.

Example fix

// before
client, model = OpenAIResponsesAgent.setup_resources()

// after
client, model = OpenAIResponsesAgent.setup_resources(ai_model_id='gpt-4o')

from semantic_kernel.connectors.ai.open_ai.settings.open_ai_settings import OpenAISettings
s = OpenAISettings()
if not s.responses_model_id:
    raise SystemExit('Responses model id is not configured')

def has_responses_model() -> bool:
    from semantic_kernel.connectors.ai.open_ai.settings.open_ai_settings import OpenAISettings
    return bool(OpenAISettings().responses_model_id)

from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException
try:
    client, model = OpenAIResponsesAgent.setup_resources()
except AgentInitializationException as e:
    if 'model ID' in str(e):
        model = 'gpt-4o'
        client, model = OpenAIResponsesAgent.setup_resources(ai_model_id=model)
    raise

When it happens

Trigger: Calling setup_resources() without ai_model_id and with no responses-model env variable set. This is specific to the Responses Agent — the chat-completions model env var does NOT satisfy this check.

Common situations: Migrating from AzureChatAgent / OpenAIChatCompletion where OPENAI_CHAT_MODEL_ID was sufficient, but the Responses Agent needs a dedicated responses model setting. Forgetting to set the responses-specific env var, or setting a chat model id instead.

Related errors

• {nameof(executionParameters.OperationSelectionPredicate)} an
• The OpenAI model ID is required.
• model.id required when creating a new Azure AI agent
• Failed to create OpenAI settings.
• The OpenAI API key is required.

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