microsoft/semantic-kernel · error · AgentInitializationException

Agent type '{agent_type}' not registered.

Error message

Agent type '{agent_type}' not registered.

What it means

Thrown by AgentRegistry.create_from_yaml when the YAML's 'type' field does not match any entry in AGENT_TYPE_REGISTRY. The registry is populated by @register_agent_type decorators on built-in agent modules (loaded lazily via _preload_builtin_agents) plus any types you register with AgentRegistry.register_type. The match is case-insensitive because the value is lowercased, so a wrong spelling or an unimported custom agent class is the usual cause.

Source

Thrown at python/semantic_kernel/agents/agent.py:758

        Raises:
            AgentInitializationException: If the YAML is invalid or the agent type is not supported.

        Example:
            agent = await AgentRegistry.create_agent_from_yaml(
                yaml_str, kernel=kernel, service=AzureChatCompletion(),
            )
        """
        _preload_builtin_agents()

        data = yaml.safe_load(yaml_str)

        agent_type = data.get("type", "").lower()
        if not agent_type:
            raise AgentInitializationException("Missing 'type' field in agent definition.")

        if agent_type not in AGENT_TYPE_REGISTRY:
            raise AgentInitializationException(f"Agent type '{agent_type}' not registered.")

        agent_cls = AGENT_TYPE_REGISTRY[agent_type]

        if not isinstance(agent_cls, DeclarativeSpecProtocol):
            raise AgentInitializationException(
                f"Agent class '{agent_cls.__name__}' does not support declarative spec loading."
            )

        yaml_str = agent_cls.resolve_placeholders(yaml_str, settings, extras)
        data = yaml.safe_load(yaml_str)

        return await agent_cls.from_dict(
            data,
            kernel=kernel,
            plugins=plugins,
            settings=settings,
            **kwargs,
        )

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Inspect AGENT_TYPE_REGISTRY keys (`from semantic_kernel.agents.agent import AGENT_TYPE_REGISTRY; print(list(AGENT_TYPE_REGISTRY))`) and correct the YAML `type` value to exactly one of them.
2. If using a custom agent, register it before the call: `AgentRegistry.register_type('my_custom_agent', MyCustomAgent)` or import the module that decorates it with @register_agent_type.
3. Ensure the agent's optional package is installed (e.g. `pip install semantic-kernel[azure]`) so _preload_builtin_agents imports its module successfully.
4. Confirm there are no leading/trailing spaces or YAML quoting issues around the `type` value.

Example fix

# before
type: chat_completin_agent

# after
type: chat_completion_agent

from semantic_kernel.agents.agent import AGENT_TYPE_REGISTRY, _preload_builtin_agents
_preload_builtin_agents()
agent_type = data.get('type', '').lower()
assert agent_type, 'Missing type field'
assert agent_type in AGENT_TYPE_REGISTRY, f'Unknown agent type {agent_type!r}; known: {sorted(AGENT_TYPE_REGISTRY)}'

def is_registered_agent_type(type_str: str) -> bool:
    _preload_builtin_agents()
    return isinstance(type_str, str) and type_str.lower() in AGENT_TYPE_REGISTRY

from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException
try:
    agent = await AgentRegistry.create_from_yaml(yaml_str, kernel=kernel)
except AgentInitializationException as e:
    logger.error('Agent load failed: %s. Known types: %s', e, sorted(AGENT_TYPE_REGISTRY))
    raise

When it happens

Trigger: Calling `await AgentRegistry.create_from_yaml(yaml_str, kernel=...)` where yaml_str has `type: chat_completin_agent` (typo), `type: my_custom_agent` without first calling AgentRegistry.register_type('my_custom_agent', MyCustomAgent), or a custom agent module whose @register_agent_type decorator was never imported.

Common situations: Typos in the YAML type field (e.g. 'azure_agent' vs the real 'azure_ai_agent'); forgetting to import the module containing a custom @register_agent_type class; copy-pasting a YAML sample from an older/newer Semantic Kernel version whose registered type strings differ; an optional dependency (e.g. the azure_ai or openai package) not installed so _preload_builtin_agents silently fails to register that type.

Related errors

• Missing 'type' field in agent definition.
• Agent class '{agent_cls.__name__}' does not support declarat
• Agent type '{agent_type}' is not supported.
• Failed to read agent spec file: {e}
• Kernel instance is required for tool resolution.

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