microsoft/semantic-kernel · error · AgentInitializationException

Unresolved placeholders in spec: {', '.join(f'${{{key}}}' fo

Error message

Unresolved placeholders in spec: {', '.join(f'${{{key}}}' for key in unresolved)}

What it means

Raised by AzureResponsesAgent.resolve_placeholders() after substitution when one or more ${AzureOpenAI:Key} placeholders remain unresolved. A placeholder is unresolved when its key is absent from both the settings-derived field_mapping (ChatModelId, AgentId, ApiKey, ApiVersion, BaseUrl, Endpoint, TokenEndpoint) and the extras dict.

Source

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

        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, AzureOpenAI:ApiKey
            section, _, key = full_key.partition(":")
            if section != "AzureOpenAI":
                return match.group(0)

            # Try short key first (ApiKey), then full (AzureOpenAI:ApiKey)
            return str(field_mapping.get(key) or field_mapping.get(full_key) or match.group(0))

        result = pattern.sub(replacer, yaml_str)

        # Safety check for unresolved placeholders
        unresolved = pattern.findall(result)
        if unresolved:
            raise AgentInitializationException(
                f"Unresolved placeholders in spec: {', '.join(f'${{{key}}}' for key in unresolved)}"
            )

        return result

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Read the unresolved keys in the error and correct/remove them in the spec.
2. Supply missing values through extras: resolve_placeholders(yaml, extras={'Key': value}).
3. Ensure mapped settings fields are populated (e.g. set AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME for ChatModelId).
4. Restrict placeholders to the supported key set.

Example fix

# before
AzureResponsesAgent.resolve_placeholders(yaml)  # yaml has ${AzureOpenAI:Region}
# after (remove placeholder, or supply)
AzureResponsesAgent.resolve_placeholders(yaml, extras={"Region": "eastus"})

import re

SUPPORTED = {"ChatModelId", "AgentId", "ApiKey", "ApiVersion", "BaseUrl", "Endpoint", "TokenEndpoint"}
placeholders = set(re.findall(r"\$\{AzureOpenAI:([^}]+)\}", yaml_str))
unknown = placeholders - SUPPORTED - set(extras or {})
if unknown:
    raise ValueError(f"Unsupported/unsupplied placeholders: {unknown}")
resolved = AzureResponsesAgent.resolve_placeholders(yaml_str, settings=settings, extras=extras)

from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException

try:
    resolved = AzureResponsesAgent.resolve_placeholders(yaml_str, extras=extras)
except AgentInitializationException as e:
    missing = parse_unresolved(e.args[0])
    extras = extras or {}
    extras.update(resolve_from_env(missing))
    resolved = AzureResponsesAgent.resolve_placeholders(yaml_str, extras=extras)

When it happens

Trigger: A declarative spec contains a placeholder referencing a key that is not in the built-in mapping and not supplied via extras (e.g. ${AzureOpenAI:Region}), or the corresponding settings field is empty so the value falls back to the literal placeholder.

Common situations: Typos in placeholder keys; referencing fields outside the supported mapping; forgetting to pass runtime values via extras; spec files not updated after a schema change.

Related errors

• Unresolved placeholders in spec: {', '.join(f'${{{key}}}' fo
• Missing 'type' field in agent definition.
• Expected AzureOpenAISettings, got {type(settings).__name__}
• Failed to create Azure OpenAI settings: {exc}
• Expected AzureOpenAISettings, got {type(settings).__name__}

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