microsoft/semantic-kernel · error · AgentInitializationException

Unsupported tool type: {spec.type}

Error message

Unsupported tool type: {spec.type}

What it means

Raised when a tool's type is present but does not match any builder registered via @_register_tool. _TOOL_BUILDERS is keyed by lowercased type, so the lookup raises KeyError which is converted to AgentInitializationException. Only types that have an explicit builder (azure_ai_search, code_interpreter, file_search, bing_grounding, openapi) are accepted.

Source

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

    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):
            resources["azure_ai_search"] = tool.resources.azure_ai_search
        elif isinstance(tool, FileSearchTool):
            resources["file_search"] = tool.resources.file_search

    return ToolResources(**resources) if resources else None

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Use one of the registered builder types: azure_ai_search, code_interpreter, file_search, bing_grounding, openapi (function tools are filtered out before _build_tool).
2. Upgrade semantic-kernel to the version that supports the tool type you need.
3. Check for typos and normalize to lowercase with underscores.
4. Inspect _TOOL_BUILDERS keys at runtime to see exactly which types are registered in your version.

Example fix

// before
tools:
  - type: open_api      # wrong
    id: weather
// after
tools:
  - type: openapi       # registered key
    id: weather

from semantic_kernel.agents.azure_ai.azure_ai_agent import _TOOL_BUILDERS
def validate_tool_types_supported(spec_dict):
    for t in spec_dict.get('tools', []):
        ty = (t.get('type') or '').lower()
        if ty and ty != 'function' and ty not in _TOOL_BUILDERS:
            raise ValueError(f"unsupported tool type '{t.get('type')}'. supported: {sorted(_TOOL_BUILDERS)}")
    return spec_dict

def is_supported_tool_type(type_str: str) -> bool:
    return (type_str or '').lower() in _TOOL_BUILDERS or (type_str or '').lower() == 'function'

try:
    agent = await AzureAIAgent._from_dict(data, kernel=kernel, client=client)
except AgentInitializationException as e:
    if 'Unsupported tool type' in str(e):
        log.error('Check tool type against registered builders: %s', sorted(_TOOL_BUILDERS))
    raise

When it happens

Trigger: Declaring a tool type like 'web_search', 'retrieval', 'function_call', or a typo such as 'open_api' or 'azure-ai-search'; referencing a tool type added in a newer library version while running an older one; passing an OpenAI-Assistants tool type string verbatim.

Common situations: Version mismatch between documentation/examples and the installed semantic-kernel release; copying a tool type name from Azure REST API docs (which differ from the SK aliases); case or separator differences (hyphen vs underscore).

Related errors

• Tool spec must include a 'type' field.
• OpenAPI tool '{spec.id}' is missing required 'specification'
• Client cannot be None
• Please provide a valid Azure AI endpoint.
• Missing required 'client' in AzureAIAgent._from_dict()

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