microsoft/semantic-kernel · error · AgentInitializationException

Missing 'type' field in agent definition.

Error message

Missing 'type' field in agent definition.

What it means

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.

Source

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

        Returns:
            An instance of the requested agent.

        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,

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Add a top-level 'type' field to the spec matching a registered agent type (e.g. type: chat_completion_agent).
2. Verify the 'type' key is at the root of the YAML, not nested, and is correctly indented.
3. Confirm the value matches a type registered via @register_agent_type / AgentRegistry.register_type.
4. Validate the YAML parses to the dict shape you expect (print yaml.safe_load output).

Example fix

# before (missing type)
name: MyAgent
instructions: Be helpful.
# after
type: chat_completion_agent
name: MyAgent
instructions: Be helpful.

import yaml
data = yaml.safe_load(yaml_str)
assert isinstance(data, dict) and data.get('type'), \
    'Agent spec must be a dict with a non-empty top-level "type" field'

def has_agent_type(spec) -> bool:
    return isinstance(spec, dict) and bool(spec.get('type'))

from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException
try:
    agent = await AgentRegistry.create_from_yaml(yaml_str, kernel=kernel)
except AgentInitializationException as e:
    if 'Missing' in str(e) and 'type' in str(e):
        # add the 'type' field to the spec and retry
        ...
    raise

When it happens

Trigger: 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.

Common situations: Hand-writing an agent YAML and forgetting the type field; indentation putting 'type' under 'model:' or 'tools:'; loading the wrong file.

Related errors

• Unresolved placeholders in spec: {', '.join(f'${{{key}}}' fo
• Unresolved placeholders in spec: {', '.join(f'${{{key}}}' fo
• Missing or malformed 'vector_store_ids' in: {spec}
• Tool spec must include a 'type' field.
• Unsupported tool type: {spec.type}

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