microsoft/semantic-kernel · critical · AgentInitializationException

Failed to create Azure OpenAI settings: {exc}

Error message

Failed to create Azure OpenAI settings: {exc}

What it means

Raised by AzureResponsesAgent's client builder when constructing AzureOpenAISettings(...) raises a pydantic ValidationError. This is a hard fail during initialization; the wrapped ValidationError message in {exc} details which field failed validation (e.g. malformed endpoint URL, invalid type).

Source

Thrown at python/semantic_kernel/agents/open_ai/azure_responses_agent.py:106

            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,
                responses_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 message: it names the failing field and reason.
2. Ensure endpoint is a full HTTPS URL (e.g. https://<resource>.openai.azure.com/).
3. Validate env values (AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_BASE_URL) are well-formed before constructing the agent.
4. If passing api_version explicitly, pass a valid API version string.

Example fix

# before
AzureResponsesAgent(endpoint="myresource.openai.azure.com")  # missing https://
# after
AzureResponsesAgent(endpoint="https://myresource.openai.azure.com/")

from pydantic import ValidationError
from semantic_kernel.connectors.ai.open_ai.settings import AzureOpenAISettings

try:
    settings = AzureOpenAISettings(
        endpoint=endpoint, base_url=base_url, api_key=api_key,
        responses_deployment_name=deployment_name, api_version=api_version,
    )
except ValidationError as exc:
    raise ValueError(f"Invalid Azure OpenAI settings: {exc}") from exc

from pydantic import ValidationError
from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException

try:
    agent = AzureResponsesAgent(endpoint=endpoint, deployment_name=name, api_key=key)
except AgentInitializationException as e:
    if "Failed to create Azure OpenAI settings" in str(e):
        # inspect e.__cause__ which is the ValidationError
        for err in e.__cause__.errors():
            logging.error("settings field %s: %s", err.get('loc'), err.get('msg'))
    raise

When it happens

Trigger: Calling AzureResponsesAgent creation with values that fail AzureOpenAISettings validation: a non-HTTPS endpoint, a base_url that is not a valid Url, an api_version of the wrong type, or conflicting env-file values.

Common situations: Setting AZURE_OPENAI_ENDPOINT to a URL without https:// or with a typo; providing endpoint as a pydantic Url that fails HttpsUrl parsing; mixing base_url and endpoint incorrectly; corrupted .env file values.

Related errors

• Please provide either an api_key, ad_token, ad_token_provide
• Please provide an Azure OpenAI endpoint
• Please provide an Azure OpenAI Responses deployment name
• Failed to create Copilot Studio Agent settings: {exc}
• Expected AzureOpenAISettings, got {type(settings).__name__}

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