microsoft/semantic-kernel · error · AgentInitializationException

Failed to create Azure OpenAI settings: {exc}

Error message

Failed to create Azure OpenAI settings: {exc}

What it means

While constructing the AsyncAzureOpenAI client, the agent builds an AzureOpenAISettings object from supplied args/env. If pydantic validation of those settings fails, the ValidationError is wrapped as AgentInitializationException("Failed to create Azure OpenAI settings"). The wrapped error text enumerates which fields failed validation.

Source

Thrown at python/semantic_kernel/agents/open_ai/azure_assistant_agent.py:99

            credential: The credential to use for authentication.
            kwargs: Additional keyword arguments

        Returns:
            An Azure OpenAI client instance and the configured deployment name (model)
        """
        try:
            azure_openai_settings = AzureOpenAISettings(
                api_key=api_key,
                base_url=base_url,
                endpoint=endpoint,
                chat_deployment_name=deployment_name,
                api_version=api_version,
                env_file_path=env_file_path,
                env_file_encoding=env_file_encoding,
                token_endpoint=token_scope,
            )
        except ValidationError as exc:
            raise AgentInitializationException(f"Failed to create Azure OpenAI settings: {exc}") from exc

        if (
            azure_openai_settings.api_key is None
            and ad_token_provider is None
            and ad_token is None
            and azure_openai_settings.token_endpoint
            and credential
        ):
            ad_token = get_entra_auth_token(credential, azure_openai_settings.token_endpoint)

        # If we still have no credentials, we can't proceed
        if not azure_openai_settings.api_key and not ad_token and not ad_token_provider and not credential:
            raise AgentInitializationException(
                "Please provide either an api_key, ad_token, ad_token_provider or credential for authentication."
            )

        merged_headers = dict(copy(default_headers)) if default_headers else {}
        if default_headers:

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Read the wrapped ValidationError in exc.__cause__ to see exactly which settings field(s) failed.
2. Correct the offending env var or constructor argument (URL format, api_version string, file path).
3. Ensure the .env file exists at env_file_path and uses the specified env_file_encoding.
4. Validate settings explicitly with AzureOpenAISettings() in isolation to surface errors before constructing the agent.

Example fix

// before
AzureOpenAIAssistantAgent(..., env_file_path="missing.env")
# -> Failed to create Azure OpenAI settings

// after
AzureOpenAIAssistantAgent(..., env_file_path=".env")  # valid file with AZURE_OPENAI_* vars

from semantic_kernel.connectors.ai.open_ai import AzureOpenAISettings

def settings_build_ok(**kwargs) -> bool:
    try:
        AzureOpenAISettings(**kwargs)
        return True
    except Exception:
        return False

from semantic_kernel.exceptions import AgentInitializationException

try:
    agent = AzureOpenAIAssistantAgent(...)
except AgentInitializationException as e:
    cause = e.__cause__  # pydantic ValidationError with field details
    logger.error("settings invalid: %s", cause)

When it happens

Trigger: Calling the agent/client factory with arguments or environment variables that fail AzureOpenAISettings validation — e.g. malformed endpoint URL, invalid api_version format, unreadable env_file_path, or a field whose value violates its type/constraint.

Common situations: Missing or malformed AZURE_OPENAI_* env vars; pointing env_file_path at a non-existent .env; supplying api_version as a non-string or unsupported value; endpoint not a valid URL; env_file_encoding mismatch.

Related errors

• Please provide an Azure OpenAI endpoint
• Please provide an Azure OpenAI deployment name
• Please provide either an api_key, ad_token, ad_token_provide
• Failed to create Anthropic settings.
• The Anthropic chat model ID is required.

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