microsoft/semantic-kernel · error · AgentInitializationException

Tool spec must include a 'type' field.

Error message

Tool spec must include a 'type' field.

What it means

Raised by _build_tool when a ToolSpec has no 'type' field at all. The type string is the dispatch key into the registered tool builders (_TOOL_BUILDERS), so a missing type means the builder cannot be selected. Thrown as AgentInitializationException during declarative agent creation for each tool that lacks a type.

Source

Thrown at python/semantic_kernel/agents/azure_ai/azure_ai_agent.py:228

    try:
        parsed_spec = json.loads(raw_spec) if isinstance(raw_spec, str) else raw_spec
    except json.JSONDecodeError as e:
        raise AgentInitializationException(f"Invalid JSON in OpenAPI 'specification' field: {e}") from e

    auth = opts.get("auth", OpenApiAnonymousAuthDetails())

    return OpenApiTool(
        name=spec.id,
        description=spec.description,
        spec=parsed_spec,
        auth=auth,
        default_parameters=opts.get("default_parameters"),
    )


def _build_tool(spec: ToolSpec, kernel: "Kernel") -> ToolDefinition:
    if not spec.type:
        raise AgentInitializationException("Tool spec must include a 'type' field.")

    try:
        builder = _TOOL_BUILDERS[spec.type.lower()]
    except KeyError as exc:
        raise AgentInitializationException(f"Unsupported tool type: {spec.type}") from exc

    sig = inspect.signature(builder)
    return builder(spec) if len(sig.parameters) == 1 else builder(spec, kernel)  # type: ignore[call-arg]


def _build_tool_resources(tool_defs: list[ToolDefinition]) -> ToolResources | None:
    """Collects tool resources from known tool types with resource needs."""
    resources: dict[str, Any] = {}

    for tool in tool_defs:
        if isinstance(tool, CodeInterpreterTool):
            resources["code_interpreter"] = tool.resources.code_interpreter
        elif isinstance(tool, AzureAISearchTool):

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Add a 'type' field to each tool entry with one of the supported values (e.g. azure_ai_search, code_interpreter, file_search, bing_grounding, openapi, function).
2. Validate the parsed spec dict to ensure every item under 'tools' contains a non-empty 'type' before calling _from_dict.
3. Check YAML indentation so 'type' is a sibling of 'id', not nested elsewhere.

Example fix

// before
tools:
  - id: search
    description: ai search
// after
tools:
  - type: azure_ai_search
    id: search
    description: ai search

def validate_tool_types(spec_dict):
    for t in spec_dict.get('tools', []):
        if not t.get('type'):
            raise ValueError(f"tool entry {t.get('id')} is missing 'type'")
    return spec_dict

def tool_has_type(tool_entry: dict) -> bool:
    return bool(tool_entry.get('type'))

try:
    agent = await AzureAIAgent._from_dict(data, kernel=kernel, client=client)
except AgentInitializationException as e:
    if "must include a 'type'" in str(e):
        log.error('A tool entry lacks a type field')
    raise

When it happens

Trigger: A tool entry in the declarative spec like {"id":"x","description":"y"} with no 'type' key; a YAML entry where 'type' is commented out or indented incorrectly so it does not parse; importing a spec produced for a different agent framework that uses a different field name.

Common situations: Hand-editing a YAML agent template and removing/renaming the type line; converting from an OpenAI-Assistants tool definition format that names the discriminator differently (e.g. 'kind'); schema drift after a library upgrade that renamed the field.

Related errors

• OpenAPI tool '{spec.id}' is missing required 'specification'
• Unsupported tool type: {spec.type}
• Missing required 'client' in AzureAIAgent._from_dict()
• model.id required when creating a new Azure AI agent
• Client cannot be None

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