microsoft/semantic-kernel · error · AgentInitializationException

Expected AzureAIAgentSettings, got {type(settings).__name__}

Error message

Expected AzureAIAgentSettings, got {type(settings).__name__}

What it means

Raised by AzureAIAgent.resolve_placeholders when the 'settings' argument is not None and not an instance of AzureAIAgentSettings. The method reads specific fields off the settings object, so a foreign settings type is rejected. Surfaced as AgentInitializationException. Note: None is allowed (it constructs a default), only wrong types are rejected.

Source

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

    def resolve_placeholders(
        cls: type[_T],
        yaml_str: str,
        settings: "KernelBaseSettings | None" = None,
        extras: dict[str, Any] | None = None,
    ) -> str:
        """Substitute ${AzureAI:Key} placeholders with fields from AzureAIAgentSettings and extras."""
        import re

        pattern = re.compile(r"\$\{([^}]+)\}")

        # Build the mapping only if settings is provided and valid
        field_mapping: dict[str, Any] = {}

        if settings is None:
            settings = AzureAIAgentSettings()

        if not isinstance(settings, AzureAIAgentSettings):
            raise AgentInitializationException(f"Expected AzureAIAgentSettings, got {type(settings).__name__}")

        field_mapping.update({
            "ChatModelId": getattr(settings, "model_deployment_name", None),
            "Endpoint": getattr(settings, "endpoint", None),
            "AgentId": getattr(settings, "agent_id", None),
            "BingConnectionId": getattr(settings, "bing_connection_id", None),
            "AzureAISearchConnectionId": getattr(settings, "azure_ai_search_connection_id", None),
            "AzureAISearchIndexName": getattr(settings, "azure_ai_search_index_name", None),
        })

        if extras:
            field_mapping.update(extras)

        def replacer(match: re.Match[str]) -> str:
            """Replace the matched placeholder with the corresponding value from field_mapping."""
            full_key = match.group(1)  # for example, AzureAI:AzureAISearchConnectionId
            section, _, key = full_key.partition(":")
            if section != "AzureAI":

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Pass an AzureAIAgentSettings instance (or None to use defaults built from env vars).
2. If you have values in another settings object, construct AzureAIAgentSettings from them before passing.
3. Double-check imports to ensure you are passing the Azure-specific settings class.

Example fix

// before
resolve_placeholders(yaml, settings=OpenAIAgentSettings())  // wrong type
// after
resolve_placeholders(yaml, settings=AzureAIAgentSettings())  // or settings=None

from semantic_kernel.agents import AzureAIAgentSettings
def ensure_azure_settings(settings):
    if settings is None:
        return AzureAIAgentSettings()
    if not isinstance(settings, AzureAIAgentSettings):
        raise TypeError(f'Expected AzureAIAgentSettings, got {type(settings).__name__}')
    return settings

def is_azure_settings(settings) -> bool:
    return settings is None or isinstance(settings, AzureAIAgentSettings)

try:
    AzureAIAgent.resolve_placeholders(yaml, settings=settings)
except AgentInitializationException as e:
    if 'Expected AzureAIAgentSettings' in str(e):
        log.error('Pass AzureAIAgentSettings or None, not another settings type')
    raise

When it happens

Trigger: Passing an OpenAIAgentSettings, KernelBaseSettings subclass, or a plain dict as the settings argument to resolve_placeholders; a custom settings class that is not AzureAIAgentSettings; mixing settings objects across connector types.

Common situations: Reusing a settings instance built for a different connector; a framework/hook that injects its own settings object into the placeholder resolver; refactoring that changed the expected settings class without updating callers.

Related errors

• OpenAPI tool '{spec.id}' is missing required 'specification'
• Tool spec must include a 'type' field.
• Missing required 'client' in AzureAIAgent._from_dict()
• model.id required when creating a new Azure AI agent
• Unsupported tool type: {spec.type}

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