{"record":{"id":"afb8c8cee80947df","repo":"microsoft/semantic-kernel","slug":"agent-class-agent-cls-name-does-not-suppor","errorCode":null,"errorMessage":"Agent class '{agent_cls.__name__}' does not support declarative spec loading.","messagePattern":"Agent class '(.+?)' does not support declarative spec loading\\.","errorType":"exception","errorClass":"AgentInitializationException","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/agent.py","lineNumber":763,"sourceCode":"            agent = await AgentRegistry.create_agent_from_yaml(\n                yaml_str, kernel=kernel, service=AzureChatCompletion(),\n            )\n        \"\"\"\n        _preload_builtin_agents()\n\n        data = yaml.safe_load(yaml_str)\n\n        agent_type = data.get(\"type\", \"\").lower()\n        if not agent_type:\n            raise AgentInitializationException(\"Missing 'type' field in agent definition.\")\n\n        if agent_type not in AGENT_TYPE_REGISTRY:\n            raise AgentInitializationException(f\"Agent type '{agent_type}' not registered.\")\n\n        agent_cls = AGENT_TYPE_REGISTRY[agent_type]\n\n        if not isinstance(agent_cls, DeclarativeSpecProtocol):\n            raise AgentInitializationException(\n                f\"Agent class '{agent_cls.__name__}' does not support declarative spec loading.\"\n            )\n\n        yaml_str = agent_cls.resolve_placeholders(yaml_str, settings, extras)\n        data = yaml.safe_load(yaml_str)\n\n        return await agent_cls.from_dict(\n            data,\n            kernel=kernel,\n            plugins=plugins,\n            settings=settings,\n            **kwargs,\n        )\n\n    @staticmethod\n    async def create_from_dict(\n        data: dict,\n        *,","sourceCodeStart":745,"sourceCodeEnd":781,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/agent.py#L745-L781","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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)."],"exampleFix":"# before\n@register_agent_type('my_agent')\nclass MyAgent(Agent):  # no declarative spec methods\n    ...\nawait AgentRegistry.create_from_yaml('type: my_agent')\n\n# after\nagent = MyAgent(...)  # construct programmatically instead","handlingStrategy":"type-guard","validationCode":"from semantic_kernel.agents.agent import AGENT_TYPE_REGISTRY, DeclarativeSpecProtocol, _preload_builtin_agents\n_preload_builtin_agents()\ncls = AGENT_TYPE_REGISTRY[data['type'].lower()]\nassert isinstance(cls, DeclarativeSpecProtocol), f'{cls.__name__} cannot load from declarative spec'","typeGuard":"from semantic_kernel.agents.agent import DeclarativeSpecProtocol\ndef supports_declarative_spec(agent_cls: type) -> bool:\n    return isinstance(agent_cls, DeclarativeSpecProtocol)","tryCatchPattern":"from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException\ntry:\n    agent = await AgentRegistry.create_from_yaml(yaml_str, kernel=kernel)\nexcept AgentInitializationException as e:\n    if 'does not support declarative spec' in str(e):\n        agent = MyAgent(...)  # fall back to programmatic construction\n    else:\n        raise","preventionTips":["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."],"tags":["agent-registry","declarative-spec","protocol","semantic-kernel"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}