microsoft/semantic-kernel · error · AgentInitializationException

Function ID is required for function tools.

Error message

Function ID is required for function tools.

What it means

Raised when a function tool spec has no id. The id is the plugin.function lookup key used to resolve the tool against the Kernel.

Source

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

@_register_tool("file_search")
def _file_search(spec: ToolSpec) -> FileSearchTool:
    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 FileSearchTool(vector_store_ids=vector_store_ids)


@_register_tool("function")
def _function(spec: ToolSpec, kernel: "Kernel") -> ToolDefinition:
    def parse_fqn(fqn: str) -> tuple[str, str]:
        parts = fqn.split(".")
        if len(parts) != 2:
            raise AgentInitializationException(f"Function `{fqn}` must be in the form `pluginName.functionName`.")
        return parts[0], parts[1]

    if not spec.id:
        raise AgentInitializationException("Function ID is required for function tools.")
    plugin_name, function_name = parse_fqn(spec.id)
    funcs = kernel.get_list_of_function_metadata_filters({"included_functions": f"{plugin_name}-{function_name}"})

    match len(funcs):
        case 0:
            raise AgentInitializationException(f"Function `{spec.id}` not found in kernel.")
        case 1:
            return kernel_function_metadata_to_function_call_format(funcs[0])  # type: ignore[return-value]
        case _:
            raise AgentInitializationException(f"Multiple definitions found for `{spec.id}`. Please remove duplicates.")


@_register_tool("openapi")
def _openapi(spec: ToolSpec) -> OpenApiTool:
    opts = spec.options or {}

    if not spec.id:
        raise AgentInitializationException("OpenAPI tool requires a non-empty 'id' (used as name).")

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Add a non-empty id in pluginName.functionName format to the function tool spec.
2. Validate that every function-typed tool entry has a populated id before building the agent.

Example fix

// before
tools:
  - type: function
    description: Does a thing

// after
tools:
  - type: function
    id: MyPlugin.MyFunc
    description: Does a thing

def ensure_function_id(tool_spec: dict) -> None:
    if not tool_spec.get("id"):
        raise ValueError("function tool requires non-empty 'id'")

def has_function_id(tool_spec: dict) -> bool:
    return bool(tool_spec.get("id"))

When it happens

Trigger: Declarative spec includes a function tool entry without an id field, or id is an empty string.

Common situations: Developer assumes the function is inferred from options; spec template leaves id blank.

Related errors

• Missing or malformed 'tool_connections' in: {spec}
• Missing or malformed 'index_name' in: {spec}
• Missing or malformed 'vector_store_ids' in: {spec}
• Function `{fqn}` must be in the form `pluginName.functionNam
• Function `{spec.id}` not found in kernel.

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