microsoft/semantic-kernel · error · AgentInitializationException

Please provide a valid Azure AI endpoint.

Error message

Please provide a valid Azure AI endpoint.

What it means

Raised by AzureAIAgent.create_client when no endpoint argument is supplied AND AzureAIAgentSettings.endpoint resolves to empty. The AIProjectClient requires a Foundry endpoint, so without one it cannot be constructed. Surfaced as AgentInitializationException.

Source

Thrown at python/semantic_kernel/agents/azure_ai/azure_ai_agent.py:461

        endpoint: str | None = None,
        api_version: str | None = None,
        **kwargs: Any,
    ) -> AIProjectClient:
        """Create the Azure AI Project client using the connection string.

        Args:
            credential: The credential
            endpoint: The Azure AI Foundry endpoint
            api_version: Optional API version to use
            kwargs: Additional keyword arguments

        Returns:
            AIProjectClient: The Azure AI Project client
        """
        if endpoint is None:
            ai_agent_settings = AzureAIAgentSettings()
            if not ai_agent_settings.endpoint:
                raise AgentInitializationException("Please provide a valid Azure AI endpoint.")
            endpoint = ai_agent_settings.endpoint

        client_kwargs: dict[str, Any] = {
            **kwargs,
            **({"user_agent": SEMANTIC_KERNEL_USER_AGENT} if APP_INFO else {}),
        }

        if api_version:
            client_kwargs["api_version"] = api_version

        return AIProjectClient(
            credential=credential,
            endpoint=endpoint,
            **client_kwargs,
        )

    # region Declarative Spec

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Set the endpoint env var (e.g. AZURE_AI_AGENT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>).
2. Pass endpoint explicitly: create_client(credential, endpoint='https://...').
3. Load a .env file (python-dotenv) in local dev and verify the variable is present.
4. Confirm AzureAIAgentSettings().endpoint is non-empty before calling create_client.

Example fix

// before
client = AzureAIAgent.create_client(credential)  // no endpoint arg, no env
// after
client = AzureAIAgent.create_client(
    credential,
    endpoint='https://my-foundry.services.ai.azure.com/api/projects/proj',
)

def ensure_endpoint(endpoint=None):
    from semantic_kernel.agents import AzureAIAgentSettings
    endpoint = endpoint or AzureAIAgentSettings().endpoint
    if not endpoint:
        raise ValueError('Azure AI endpoint missing: set endpoint arg or AZURE_AI_AGENT_ENDPOINT env var')
    return endpoint

def has_endpoint(endpoint=None) -> bool:
    return bool(endpoint or AzureAIAgentSettings().endpoint)

try:
    client = AzureAIAgent.create_client(credential, endpoint=endpoint)
except AgentInitializationException as e:
    if 'endpoint' in str(e):
        log.error('Set AZURE_AI_AGENT_ENDPOINT or pass endpoint=...')
    raise

When it happens

Trigger: Calling create_client(credential) with endpoint=None and the AZURE_AI_AGENT_ENDPOINT/AZURE_AI_ENDPOINT environment variable unset; .env file missing or not loaded; settings misconfigured so endpoint is empty.

Common situations: Local dev without the endpoint env var set; deployment to an environment where the secret was not injected; typo in the env var name; AzureAIAgent_SETTINGS pointed at the wrong connection string field; CI pipeline missing the variable.

Related errors

• OpenAPI tool '{spec.id}' is missing required 'specification'
• Tool spec must include a 'type' field.
• Unsupported tool type: {spec.type}
• Client cannot be None
• Missing required 'client' in AzureAIAgent._from_dict()

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