{"record":{"id":"bb6202437c0f85c7","repo":"microsoft/semantic-kernel","slug":"unsupported-tool-type-spec-type","errorCode":null,"errorMessage":"Unsupported tool type: {spec.type}","messagePattern":"Unsupported tool type: (.+?)","errorType":"validation","errorClass":"AgentInitializationException","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/azure_ai/azure_ai_agent.py","lineNumber":233,"sourceCode":"    auth = opts.get(\"auth\", OpenApiAnonymousAuthDetails())\n\n    return OpenApiTool(\n        name=spec.id,\n        description=spec.description,\n        spec=parsed_spec,\n        auth=auth,\n        default_parameters=opts.get(\"default_parameters\"),\n    )\n\n\ndef _build_tool(spec: ToolSpec, kernel: \"Kernel\") -> ToolDefinition:\n    if not spec.type:\n        raise AgentInitializationException(\"Tool spec must include a 'type' field.\")\n\n    try:\n        builder = _TOOL_BUILDERS[spec.type.lower()]\n    except KeyError as exc:\n        raise AgentInitializationException(f\"Unsupported tool type: {spec.type}\") from exc\n\n    sig = inspect.signature(builder)\n    return builder(spec) if len(sig.parameters) == 1 else builder(spec, kernel)  # type: ignore[call-arg]\n\n\ndef _build_tool_resources(tool_defs: list[ToolDefinition]) -> ToolResources | None:\n    \"\"\"Collects tool resources from known tool types with resource needs.\"\"\"\n    resources: dict[str, Any] = {}\n\n    for tool in tool_defs:\n        if isinstance(tool, CodeInterpreterTool):\n            resources[\"code_interpreter\"] = tool.resources.code_interpreter\n        elif isinstance(tool, AzureAISearchTool):\n            resources[\"azure_ai_search\"] = tool.resources.azure_ai_search\n        elif isinstance(tool, FileSearchTool):\n            resources[\"file_search\"] = tool.resources.file_search\n\n    return ToolResources(**resources) if resources else None","sourceCodeStart":215,"sourceCodeEnd":251,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/azure_ai/azure_ai_agent.py#L215-L251","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["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).","Upgrade semantic-kernel to the version that supports the tool type you need.","Check for typos and normalize to lowercase with underscores.","Inspect _TOOL_BUILDERS keys at runtime to see exactly which types are registered in your version."],"exampleFix":"// before\ntools:\n  - type: open_api      # wrong\n    id: weather\n// after\ntools:\n  - type: openapi       # registered key\n    id: weather","handlingStrategy":"validation","validationCode":"from semantic_kernel.agents.azure_ai.azure_ai_agent import _TOOL_BUILDERS\ndef validate_tool_types_supported(spec_dict):\n    for t in spec_dict.get('tools', []):\n        ty = (t.get('type') or '').lower()\n        if ty and ty != 'function' and ty not in _TOOL_BUILDERS:\n            raise ValueError(f\"unsupported tool type '{t.get('type')}'. supported: {sorted(_TOOL_BUILDERS)}\")\n    return spec_dict","typeGuard":"def is_supported_tool_type(type_str: str) -> bool:\n    return (type_str or '').lower() in _TOOL_BUILDERS or (type_str or '').lower() == 'function'","tryCatchPattern":"try:\n    agent = await AzureAIAgent._from_dict(data, kernel=kernel, client=client)\nexcept AgentInitializationException as e:\n    if 'Unsupported tool type' in str(e):\n        log.error('Check tool type against registered builders: %s', sorted(_TOOL_BUILDERS))\n    raise","preventionTips":["Pin your semantic-kernel version and read the supported tool types from _TOOL_BUILDERS.","Normalize tool types to lowercase-underscore form.","Add a CI lint that rejects unknown tool types in declarative specs."],"tags":["azure-ai","tools","version-mismatch","configuration","agent-initialization"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}