microsoft/semantic-kernel · error · AgentInitializationException

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

Error message

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

What it means

Raised by the placeholder-substitution helper when the settings argument is provided but is not an instance of OpenAISettings. The method substitutes ${OpenAI:Key}-style placeholders from settings fields; a foreign object type cannot be safely read for those fields. (If settings is None it defaults to OpenAISettings(), so this only fires for non-None wrong types.)

Source

Thrown at python/semantic_kernel/agents/open_ai/openai_responses_agent.py:605

    def resolve_placeholders(
        cls: type[_T],
        yaml_str: str,
        settings: "KernelBaseSettings | None" = None,
        extras: dict[str, Any] | None = None,
    ) -> str:
        """Substitute ${OpenAI:Key} placeholders with fields from OpenAIAgentSettings 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 = OpenAISettings()

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

        field_mapping.update({
            "ChatModelId": cls._get_setting(getattr(settings, "responses_model_id", None)),
            "AgentId": cls._get_setting(getattr(settings, "agent_id", None)),
            "ApiKey": cls._get_setting(getattr(settings, "api_key", 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, OpenAI:ApiKey
            section, _, key = full_key.partition(":")
            if section != "OpenAI":
                return match.group(0)

            # Try short key first (ApiKey), then full (OpenAI:ApiKey)

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Pass an OpenAISettings instance (or omit settings to let it default to OpenAISettings()).
2. If you have another settings object, construct OpenAISettings from its values first.
3. Add an isinstance(settings, OpenAISettings) check before calling the substitution method.

Example fix

// before
result = OpenAIResponsesAgent._substitute_placeholders(yaml, settings=azure_settings)

// after
result = OpenAIResponsesAgent._substitute_placeholders(yaml, settings=OpenAISettings())

from semantic_kernel.connectors.ai.open_ai.settings.open_ai_settings import OpenAISettings
if settings is not None and not isinstance(settings, OpenAISettings):
    settings = OpenAISettings()

from semantic_kernel.connectors.ai.open_ai.settings.open_ai_settings import OpenAISettings
def is_openai_settings(obj) -> bool:
    return isinstance(obj, OpenAISettings)

from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException
try:
    result = OpenAIResponsesAgent._substitute_placeholders(yaml, settings=settings)
except AgentInitializationException as e:
    if 'OpenAISettings' in str(e):
        result = OpenAIResponsesAgent._substitute_placeholders(yaml)  # defaults
    raise

When it happens

Trigger: Passing a settings object of the wrong class to the substitution routine — e.g. an AzureOpenAISettings, a plain dict, or an OpenAIChatCompletion settings instance — when the Responses Agent expects OpenAISettings specifically.

Common situations: Sharing a settings singleton across agent types, or passing the chat-completions settings into a Responses Agent by mistake. Also when a refactor renamed the settings class and a caller still hands in the old type.

Related errors

• Expected AzureAIAgentSettings, got {type(settings).__name__}
• The settings must be an VertexAIChatPromptExecutionSettings.
• Missing 'type' field in agent definition.
• Agent type '{agent_type}' not registered.
• Agent class '{agent_cls.__name__}' does not support declarat

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