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 (type is None or empty). The tool dispatcher keys builders by spec.type.lower(), so a missing type means it cannot select a builder and fails fast rather than producing a confusing KeyError.

Source

Thrown at python/semantic_kernel/agents/open_ai/openai_assistant_agent.py:121

# Update _code_interpreter
@_register_tool("code_interpreter")
def _code_interpreter(spec: ToolSpec, kernel: Kernel | None = None) -> tuple[list[AssistantToolParam], ToolResources]:
    file_ids = spec.options.get("file_ids")
    return OpenAIAssistantAgent.configure_code_interpreter_tool(file_ids=file_ids)


# Update _file_search
@_register_tool("file_search")
def _file_search(spec: ToolSpec, kernel: Kernel | None = None) -> tuple[list[AssistantToolParam], ToolResources]:
    vector_store_ids = spec.options.get("vector_store_ids")
    if not vector_store_ids or not isinstance(vector_store_ids, list) or not vector_store_ids[0]:
        raise AgentInitializationException(f"Missing or malformed 'vector_store_ids' in: {spec}")
    return OpenAIAssistantAgent.configure_file_search_tool(vector_store_ids=vector_store_ids)


def _build_tool(spec: ToolSpec, kernel: "Kernel") -> tuple[list[AssistantToolParam], ToolResources]:
    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


@release_candidate
class AssistantAgentThread(AgentThread):
    """An OpenAI Assistant Agent Thread class."""

    def __init__(

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Set ToolSpec.type to a supported tool type (e.g. 'code_interpreter' or 'file_search').
2. Validate the declarative spec: every tool entry must include a 'type' key.
3. If loading from YAML/dict, assert 'type' is present and non-empty before constructing ToolSpec.

Example fix

# before
tool = ToolSpec(options={"file_ids": ["file_1"]})  # no type
# after
tool = ToolSpec(type="code_interpreter", options={"file_ids": ["file_1"]})

if not getattr(spec, "type", None):
    raise ValueError("ToolSpec.type must be set (e.g. 'code_interpreter' or 'file_search').")

def has_tool_type(spec) -> bool:
    return bool(getattr(spec, "type", None))

When it happens

Trigger: Constructing a ToolSpec without setting type, or loading a declarative spec YAML where a tool entry omits the 'type' key.

Common situations: Hand-building ToolSpec(...) and forgetting type; malformed YAML spec missing the type field; deserializing partial data where type defaulted to None.

Related errors

• Missing or malformed 'vector_store_ids' in: {spec}
• Unsupported tool type: {spec.type}
• Missing 'type' field in agent definition.
• Kernel instance is required for tool resolution.
• Tool id '{tool_id}' must be in format PluginName.FunctionNam

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