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() in openai_responses_agent when a ToolSpec has a falsy type attribute. The tool dispatch table is keyed by spec.type.lower(); a missing/empty type means no builder can be selected, so the library rejects it rather than throwing a confusing KeyError.

Source

Thrown at python/semantic_kernel/agents/open_ai/openai_responses_agent.py:126

        score_threshold=score_threshold,
        ranker=ranker,
    )


@_register_tool("web_search")
def _web_search(spec: ToolSpec, kernel: Kernel | None = None) -> WebSearchToolParam:
    options = spec.options or {}
    context_size = options.get("search_context_size")
    user_location = options.get("user_location")
    return OpenAIResponsesAgent.configure_web_search_tool(
        context_size=context_size,
        user_location=user_location,
    )


def _build_tool(spec: ToolSpec, kernel: "Kernel") -> ToolParam:
    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]


# endregion


# region Agent Thread


@experimental
class ResponsesAgentThread(AgentThread):

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Ensure every tool spec has a non-empty 'type' matching a registered builder (file_search, web_search).
2. Validate ToolSpec.type is truthy before calling _build_tool / before adding to spec.tools.
3. Drop malformed tool entries from the spec before agent creation.

Example fix

# before
tool_spec = {'options': {'vector_store_ids': ['vs_x']}}

# after
tool_spec = {'type': 'file_search', 'options': {'vector_store_ids': ['vs_x']}}

assert spec.get('type'), 'tool spec must include a non-empty type'

def tool_spec_has_type(spec: dict) -> bool:
    return bool(spec.get('type'))

from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException
try:
    tool = _build_tool(tool_spec, kernel)
except AgentInitializationException as e:
    if "'type' field" in str(e):
        tool_spec['type'] = 'file_search'
        tool = _build_tool(tool_spec, kernel)

When it happens

Trigger: A declarative tool entry without a 'type' field, or with type set to ''/None; a YAML tool block that is an empty mapping; deserializing a partial tool spec.

Common situations: Hand-authored YAML tool list with a tool missing its type; programmatic spec construction that omits type; schema change where type became optional but the runtime still requires it.

Related errors

• Unsupported tool type: {spec.type}
• Missing agent description: {agent.Name ?? agent.Id}
• Entry agent is not defined.
• The agent {agent.Name ?? agent.Id} cannot have a handoff to
• The following agents are not defined in the orchestration: {

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