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 AzureAssistantAgent.resolve_placeholders() after substituting ${AzureOpenAI:Key} placeholders when one or more placeholders remain unresolvable. A placeholder is unresolved when its key is neither in the field_mapping (built from AzureOpenAISettings fields) nor in the extras dict, leaving a literal ${...} in the rendered YAML spec.

Source

Thrown at python/semantic_kernel/agents/open_ai/azure_assistant_agent.py:282

        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 != "AzureOpenAI":
                return match.group(0)

            # Try short key first (ApiKey), then full (OpenAI: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. Inspect the unresolved keys in the error message and fix typos or remove unused placeholders from the spec.
2. Supply the missing value via the extras argument: resolve_placeholders(yaml, extras={'SomeField': value}).
3. Confirm the settings object actually has the field populated (e.g. set AZURE_OPENAI_CHAT_DEPLOYMENT_NAME for ChatModelId).
4. Use only the documented placeholder keys (ChatModelId, AgentId, ApiKey, ApiVersion, BaseUrl, Endpoint, TokenEndpoint).

Example fix

# before
AzureAssistantAgent.resolve_placeholders(yaml)  # yaml has ${AzureOpenAI:OrgId} -> unresolved
# after (remove typo'd placeholder, or supply via extras)
AzureAssistantAgent.resolve_placeholders(yaml, extras={"OrgId": "my-org"})

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"Spec references unsupported/unsupplied placeholders: {unknown}")
resolved = AzureAssistantAgent.resolve_placeholders(yaml_str, settings=settings, extras=extras)

from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException

try:
    resolved = AzureAssistantAgent.resolve_placeholders(yaml_str, extras=extras)
except AgentInitializationException as e:
    # e.message lists the unresolved keys
    missing = parse_unresolved(e.args[0])
    extras = extras or {}
    extras.update(resolve_from_env(missing))
    resolved = AzureAssistantAgent.resolve_placeholders(yaml_str, extras=extras)

When it happens

Trigger: A declarative agent YAML/spec references a placeholder like ${AzureOpenAI:SomeField} that the settings object does not expose (e.g. a typo, or a field not in the mapping such as a non-existent key), and no matching value is supplied via extras.

Common situations: Typos in placeholder names (${AzureOpenAI:DepoymentName}); referencing fields not in the built-in mapping (only ChatModelId, AgentId, ApiKey, ApiVersion, BaseUrl, Endpoint, TokenEndpoint are mapped); forgetting to pass needed runtime values through extras; stale spec files 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/930074c551b7b8aa. Report an issue: GitHub.