microsoft/semantic-kernel · error · AgentInitializationException

Agent class '{agent_cls.name}' does not support declarat

Error message

Agent class '{agent_cls.__name__}' does not support declarative spec loading.

What it means

Thrown by create_from_yaml after a registered agent class is found but it does not implement the DeclarativeSpecProtocol (i.e. it lacks resolve_placeholders/from_yaml/from_dict classmethods). Only agents that opt into declarative/YAML spec loading can be instantiated this way; a plain Agent subclass registered by name is rejected even though its type string exists.

Source

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

            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,
        )

    @staticmethod
    async def create_from_dict(
        data: dict,
        *,

View on GitHub (pinned to c028a0c7dc)

Solutions

Use the agent class directly (programmatic construction) instead of the YAML/dict path, since it does not support declarative loading.
If YAML loading is required, mix the declarative spec capabilities into the class (implement resolve_placeholders, from_yaml, from_dict classmethods) and re-test isinstance against DeclarativeSpecProtocol.
Switch the YAML `type` to a built-in that supports declarative specs (e.g. chat_completion_agent, azure_ai_agent).

Example fix

# before
@register_agent_type('my_agent')
class MyAgent(Agent):  # no declarative spec methods
    ...
await AgentRegistry.create_from_yaml('type: my_agent')

# after
agent = MyAgent(...)  # construct programmatically instead

Defensive patterns

Strategy: type-guard

Validate before calling

from semantic_kernel.agents.agent import AGENT_TYPE_REGISTRY, DeclarativeSpecProtocol, _preload_builtin_agents
_preload_builtin_agents()
cls = AGENT_TYPE_REGISTRY[data['type'].lower()]
assert isinstance(cls, DeclarativeSpecProtocol), f'{cls.__name__} cannot load from declarative spec'

Type guard

from semantic_kernel.agents.agent import DeclarativeSpecProtocol
def supports_declarative_spec(agent_cls: type) -> bool:
    return isinstance(agent_cls, DeclarativeSpecProtocol)

Try / catch

from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException
try:
    agent = await AgentRegistry.create_from_yaml(yaml_str, kernel=kernel)
except AgentInitializationException as e:
    if 'does not support declarative spec' in str(e):
        agent = MyAgent(...)  # fall back to programmatic construction
    else:
        raise

Prevention

Only target declarative-spec-capable agents from YAML/dict paths.
Implement resolve_placeholders/from_yaml/from_dict if you need YAML loading for a custom class.

When it happens

Trigger: Registering a raw `Agent` subclass via AgentRegistry.register_type and then calling create_from_yaml/create_agent_from_dict with that type; using a third-party agent class that subclassifies Agent but never mixed in the declarative spec support.

Common situations: Custom agent classes written only for programmatic construction that the developer later tries to load from YAML; an agent type that was registered before declarative spec support was added in that version.

Related errors

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