microsoft/semantic-kernel · error · AgentInitializationException

Failed to create OpenAI settings.

Error message

Failed to create OpenAI settings.

What it means

Raised by OpenAIAssistantAgent.create_client_and_model() when constructing OpenAISettings() from the supplied args/env raises a pydantic ValidationError. OpenAISettings parses environment variables and the explicit overrides; a ValidationError means a field failed pydantic validation (bad type, bad format, required field malformed). The library wraps it in AgentInitializationException so callers catch one agent-level exception type.

Source

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

            org_id: The organization ID
            env_file_path: The environment file path
            env_file_encoding: The environment file encoding, defaults to utf-8
            default_headers: The default headers to add to the client
            kwargs: Additional keyword arguments

        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,

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Inspect the wrapped ValidationError in __cause__ (ex) for the exact failing field and fix that field's value/type.
2. Validate your .env / OpenAISettings by instantiating OpenAISettings() standalone before calling create_client_and_model.
3. Pass api_key and ai_model_id explicitly to bypass env parsing and isolate the failure.

Example fix

# before
client, model = await OpenAIAssistantAgent.create_client_and_model(env_file_path='.env')

# after
from semantic_kernel.connectors.ai.open_ai.settings.open_ai_settings import OpenAISettings
settings = OpenAISettings(env_file_path='.env')  # surfaces the real ValidationError
client, model = await OpenAIAssistantAgent.create_client_and_model(api_key=settings.api_key.get_secret_value(), ai_model_id=settings.chat_model_id)

from semantic_kernel.connectors.ai.open_ai.settings.open_ai_settings import OpenAISettings
try:
    OpenAISettings(env_file_path=env_file_path)
except Exception as e:
    print('settings invalid:', e)

null

from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException
try:
    client, model = await OpenAIAssistantAgent.create_client_and_model(env_file_path='.env')
except AgentInitializationException as e:
    cause = e.__cause__  # the ValidationError with field details
    log.error('settings error: %s', cause)

When it happens

Trigger: Calling OpenAIAssistantAgent.create_client_and_model(env_file_path='...') where the .env file has a malformed value, or passing an api_key/org_id of the wrong type, or a required OpenAISettings field that fails its validator. Triggered in both explicit-arg and env-only flows.

Common situations: Missing or malformed .env entries; passing ai_model_id as non-string; env_file_encoding set to an unsupported codec; typo'd env var names that leave a field un-parseable; migrating config where a field type changed between SK versions.

Related errors

• The OpenAI API key is required.
• The OpenAI model ID is required.
• Unable to configure learn resources settings.
• Failed to create Azure OpenAI settings: {exc}
• Missing required 'client' in OpenAIAssistantAgent._from_dict

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