microsoft/semantic-kernel · error · AgentInitializationException

Please provide an Azure OpenAI deployment name

Error message

Please provide an Azure OpenAI deployment name

What it means

The final factory check requires azure_openai_settings.chat_deployment_name (sourced from deployment_name arg or env). Without a deployment name the client cannot be tied to a deployed model, so AgentInitializationException("Please provide an Azure OpenAI deployment name") is raised.

Source

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

        # 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:
            merged_headers.update(default_headers)
        if APP_INFO:
            merged_headers.update(APP_INFO)
            merged_headers = prepend_semantic_kernel_to_user_agent(merged_headers)

        if not azure_openai_settings.endpoint:
            raise AgentInitializationException("Please provide an Azure OpenAI endpoint")

        if not azure_openai_settings.chat_deployment_name:
            raise AgentInitializationException("Please provide an Azure OpenAI deployment name")

        client = AsyncAzureOpenAI(
            azure_endpoint=str(azure_openai_settings.endpoint),
            api_version=azure_openai_settings.api_version,
            api_key=azure_openai_settings.api_key.get_secret_value() if azure_openai_settings.api_key else None,
            azure_ad_token=ad_token,
            azure_ad_token_provider=ad_token_provider,
            default_headers=merged_headers,
            **kwargs,
        )

        return client, azure_openai_settings.chat_deployment_name

    @staticmethod
    def create_client(
        *,
        ad_token: str | None = None,
        ad_token_provider: Callable[[], str | Awaitable[str]] | None = None,

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Pass deployment_name explicitly, e.g. deployment_name='gpt-4o'.
2. Set AZURE_OPENAI_CHAT_DEPLOYMENT_NAME in env/.env (note the exact variable name).
3. Verify the deployment exists in the Azure OpenAI resource and matches the name you supply.

Example fix

// before
AzureOpenAIAssistantAgent(..., api_key=k, endpoint=e)  # no deployment
# -> Please provide an Azure OpenAI deployment name

// after
AzureOpenAIAssistantAgent(..., api_key=k, endpoint=e, deployment_name='gpt-4o')

def has_deployment(settings) -> bool:
    return bool(settings.chat_deployment_name)

def has_azure_deployment(settings) -> bool:
    return getattr(settings, 'chat_deployment_name', None) not in (None, "")

When it happens

Trigger: Instantiating the Azure assistant without a deployment_name argument and without AZURE_OPENAI_CHAT_DEPLOYMENT_NAME in the environment, or with an empty deployment name.

Common situations: Forgetting the deployment_name kwarg; env var typo (e.g. AZURE_OPENAI_DEPLOYMENT_NAME instead of AZURE_OPENAI_CHAT_DEPLOYMENT_NAME); deployment not yet created in Azure; .env not loaded.

Related errors

• Failed to create Azure OpenAI settings: {exc}
• Please provide an Azure OpenAI endpoint
• 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/81cd6b24a1d93cba. Report an issue: GitHub.