{"record":{"id":"bd093fa8a94d46b9","repo":"microsoft/semantic-kernel","slug":"missing-type-field-in-agent-definition","errorCode":null,"errorMessage":"Missing 'type' field in agent definition.","messagePattern":"Missing 'type' field in agent definition\\.","errorType":"exception","errorClass":"AgentInitializationException","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/agent.py","lineNumber":755,"sourceCode":"\n        Returns:\n            An instance of the requested agent.\n\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,","sourceCodeStart":737,"sourceCodeEnd":773,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/agent.py#L737-L773","documentation":"AgentRegistry.create_from_yaml (and create_from_dict) require a 'type' field in the agent spec to look up the agent class in AGENT_TYPE_REGISTRY. If 'type' is missing or empty, AgentInitializationException is raised before any class resolution. This is a declarative-spec validation error in the YAML/dict payload.","triggerScenarios":"Passing YAML/dict to create_from_yaml/dict that has no 'type' key, or whose 'type' value is empty/None; malformed YAML where the type key is nested under the wrong indentation.","commonSituations":"Hand-writing an agent YAML and forgetting the type field; indentation putting 'type' under 'model:' or 'tools:'; loading the wrong file.","solutions":["Add a top-level 'type' field to the spec matching a registered agent type (e.g. type: chat_completion_agent).","Verify the 'type' key is at the root of the YAML, not nested, and is correctly indented.","Confirm the value matches a type registered via @register_agent_type / AgentRegistry.register_type.","Validate the YAML parses to the dict shape you expect (print yaml.safe_load output)."],"exampleFix":"# before (missing type)\nname: MyAgent\ninstructions: Be helpful.\n# after\ntype: chat_completion_agent\nname: MyAgent\ninstructions: Be helpful.","handlingStrategy":"validation","validationCode":"import yaml\ndata = yaml.safe_load(yaml_str)\nassert isinstance(data, dict) and data.get('type'), \\\n    'Agent spec must be a dict with a non-empty top-level \"type\" field'","typeGuard":"def has_agent_type(spec) -> bool:\n    return isinstance(spec, dict) and bool(spec.get('type'))","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 'Missing' in str(e) and 'type' in str(e):\n        # add the 'type' field to the spec and retry\n        ...\n    raise","preventionTips":["Always include a top-level 'type' in agent YAML/dict specs.","Keep 'type' at the root, not nested under model/tools.","Validate the parsed dict shape before passing to the registry.","Use a registered type value (via @register_agent_type or AgentRegistry.register_type)."],"tags":["agents","declarative-spec","yaml","validation","semantic-kernel"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}