{"record":{"id":"81c1284d9c01103a","repo":"microsoft/semantic-kernel","slug":"tool-spec-must-include-a-type-field","errorCode":null,"errorMessage":"Tool spec must include a 'type' field.","messagePattern":"Tool spec must include a 'type' field\\.","errorType":"validation","errorClass":"AgentInitializationException","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/azure_ai/azure_ai_agent.py","lineNumber":228,"sourceCode":"    try:\n        parsed_spec = json.loads(raw_spec) if isinstance(raw_spec, str) else raw_spec\n    except json.JSONDecodeError as e:\n        raise AgentInitializationException(f\"Invalid JSON in OpenAPI 'specification' field: {e}\") from e\n\n    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):","sourceCodeStart":210,"sourceCodeEnd":246,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/azure_ai/azure_ai_agent.py#L210-L246","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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).","Validate the parsed spec dict to ensure every item under 'tools' contains a non-empty 'type' before calling _from_dict.","Check YAML indentation so 'type' is a sibling of 'id', not nested elsewhere."],"exampleFix":"// before\ntools:\n  - id: search\n    description: ai search\n// after\ntools:\n  - type: azure_ai_search\n    id: search\n    description: ai search","handlingStrategy":"validation","validationCode":"def validate_tool_types(spec_dict):\n    for t in spec_dict.get('tools', []):\n        if not t.get('type'):\n            raise ValueError(f\"tool entry {t.get('id')} is missing 'type'\")\n    return spec_dict","typeGuard":"def tool_has_type(tool_entry: dict) -> bool:\n    return bool(tool_entry.get('type'))","tryCatchPattern":"try:\n    agent = await AzureAIAgent._from_dict(data, kernel=kernel, client=client)\nexcept AgentInitializationException as e:\n    if \"must include a 'type'\" in str(e):\n        log.error('A tool entry lacks a type field')\n    raise","preventionTips":["Lint the spec so every tools[] item has a non-empty type.","Use a YAML schema/CI check to catch missing type fields.","Copy from a known-good template that already includes type on each tool."],"tags":["azure-ai","declarative-spec","tools","configuration","agent-initialization"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}