microsoft/semantic-kernel · critical · AgentInitializationException

Please provide an Azure OpenAI Responses deployment name

Error message

Please provide an Azure OpenAI Responses deployment name

What it means

Raised by AzureResponsesAgent's client builder when AzureOpenAISettings.responses_deployment_name is unset. The Responses API path needs the specific deployment name configured for the Responses API in Azure; without it the client cannot target a model.

Source

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

        # 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.responses_deployment_name:
            raise AgentInitializationException("Please provide an Azure OpenAI Responses 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.responses_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. Set AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME to the Responses deployment name from Azure portal > Deployments.
2. Pass deployment_name='...' to the AzureResponsesAgent constructor.
3. Do not confuse with chat_deployment_name; the Responses API requires its own deployment.
4. Confirm the deployment actually exists and is a Responses-capable model in your resource.

Example fix

# before
AzureResponsesAgent(endpoint=..., api_key=...)  # responses_deployment_name missing
# after
AzureResponsesAgent(
    endpoint="https://myresource.openai.azure.com/",
    deployment_name="my-responses-deploy",
    api_key="...",
)

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

settings = AzureOpenAISettings()
if not settings.responses_deployment_name:
    raise SystemExit(
        "AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME is not set. "
        "This must be a Responses-capable deployment."
    )

When it happens

Trigger: Constructing AzureResponsesAgent where responses_deployment_name resolves to None/empty. This is set via AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME or the deployment_name argument; chat_deployment_name does not satisfy this check.

Common situations: Setting AZURE_OPENAI_CHAT_DEPLOYMENT_NAME instead of AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME; not passing deployment_name to the constructor; using a resource that has no Responses API deployment configured.

Related errors

• Failed to create Azure OpenAI settings: {exc}
• Please provide either an api_key, ad_token, ad_token_provide
• Please provide an Azure OpenAI endpoint
• AZURE_OPENAI_ENDPOINT is not set.
• AZURE_OPENAI_ENDPOINT is not set.

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