{"record":{"id":"da1e93c4f08cffc5","repo":"microsoft/semantic-kernel","slug":"agent-type-agent-type-not-registered","errorCode":null,"errorMessage":"Agent type '{agent_type}' not registered.","messagePattern":"Agent type '(.+?)' not registered\\.","errorType":"exception","errorClass":"AgentInitializationException","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/agent.py","lineNumber":758,"sourceCode":"\n        Raises:\n            AgentInitializationException: If the YAML is invalid or the agent type is not supported.\n\n        Example:\n            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        )","sourceCodeStart":740,"sourceCodeEnd":776,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/agent.py#L740-L776","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","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.","Ensure the agent's optional package is installed (e.g. `pip install semantic-kernel[azure]`) so _preload_builtin_agents imports its module successfully.","Confirm there are no leading/trailing spaces or YAML quoting issues around the `type` value."],"exampleFix":"# before\ntype: chat_completin_agent\n\n# after\ntype: chat_completion_agent","handlingStrategy":"validation","validationCode":"from semantic_kernel.agents.agent import AGENT_TYPE_REGISTRY, _preload_builtin_agents\n_preload_builtin_agents()\nagent_type = data.get('type', '').lower()\nassert agent_type, 'Missing type field'\nassert agent_type in AGENT_TYPE_REGISTRY, f'Unknown agent type {agent_type!r}; known: {sorted(AGENT_TYPE_REGISTRY)}'","typeGuard":"def is_registered_agent_type(type_str: str) -> bool:\n    _preload_builtin_agents()\n    return isinstance(type_str, str) and type_str.lower() in AGENT_TYPE_REGISTRY","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    logger.error('Agent load failed: %s. Known types: %s', e, sorted(AGENT_TYPE_REGISTRY))\n    raise","preventionTips":["Print AGENT_TYPE_REGISTRY keys during dev to confirm the exact type strings.","Register custom types with AgentRegistry.register_type before any declarative load.","Pin semantic-kernel and optional deps so registered type strings stay stable."],"tags":["agent-registry","yaml","declarative-spec","semantic-kernel"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}