microsoft/semantic-kernel · error · AgentInitializationException

Function `{spec.id}` not found in kernel.

Error message

Function `{spec.id}` not found in kernel.

What it means

Raised when the declarative function-tool builder looks up pluginName.functionName via kernel.get_list_of_function_metadata_filters and gets zero matches. The id resolves to no registered kernel function.

Source

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

    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).")
    if not spec.description:
        raise AgentInitializationException(f"OpenAPI tool '{spec.id}' requires a 'description'.")

    raw_spec = opts.get("specification")
    if not raw_spec:
        raise AgentInitializationException(f"OpenAPI tool '{spec.id}' is missing required 'specification' field.")

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Register the referenced plugin on the Kernel before building the agent: kernel.add_plugin(MyPlugin(), "MyPlugin").
2. Verify the function is decorated with @kernel_function so its metadata is discoverable.
3. Match id casing and separator exactly to the kernel's fully_qualified_name.
4. Inspect kernel.get_list_of_function_metadata_filters({'included_functions': 'PluginName-FunctionName'}) to confirm discoverability.

Example fix

// before
kernel = Kernel()  # no plugins added
tools:
  - type: function
    id: Search.Lookup

// after
kernel = Kernel()
kernel.add_plugin(SearchPlugin(), "Search")
tools:
  - type: function
    id: Search.Lookup

def ensure_function_exists(kernel, plugin: str, func: str) -> None:
    found = kernel.get_list_of_function_metadata_filters({"included_functions": f"{plugin}-{func}"})
    if len(found) != 1:
        raise ValueError(f"{plugin}.{func} not found or ambiguous: {len(found)} matches")

def function_resolvable(kernel, plugin: str, func: str) -> bool:
    found = kernel.get_list_of_function_metadata_filters({"included_functions": f"{plugin}-{func}"})
    return len(found) == 1

When it happens

Trigger: Function tool id references a plugin/function not registered on the Kernel passed to the agent factory, or the name uses wrong casing/separator.

Common situations: Plugin registered under a different name; function not decorated with @kernel_function; Kernel passed to the factory is a fresh instance without plugins; spec built against a different environment.

Related errors

• The following function tool(s) are defined on the agent but
• Function `{fqn}` must be in the form `pluginName.functionNam
• Function ID is required for function tools.
• Multiple definitions found for `{spec.id}`. Please remove du
• Kernel instance is required for tool resolution.

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