microsoft/semantic-kernel · error · AgentInitializationException

Plugin '{plugin_name}' not found in kernel.

Error message

Plugin '{plugin_name}' not found in kernel.

What it means

Thrown by _validate_tools after splitting a tool id into plugin/function when kernel.plugins.get(plugin_name) returns nothing. The plugin namespace named in the tool id was never registered on the kernel, so the reference cannot resolve.

Source

Thrown at python/semantic_kernel/agents/agent.py:1063

        This validates the declared tools in the YAML spec, and only checks whether those references resolve
        properly in the current kernel.
        """
        if not kernel:
            raise AgentInitializationException("Kernel instance is required for tool resolution.")

        for tool in tools_list:
            tool_id = tool.get("id")
            if not tool_id or tool.get("type") != "function":
                continue

            if "." not in tool_id:
                raise AgentInitializationException(f"Tool id '{tool_id}' must be in format PluginName.FunctionName")

            plugin_name, function_name = tool_id.split(".", 1)

            plugin = kernel.plugins.get(plugin_name)
            if not plugin:
                raise AgentInitializationException(f"Plugin '{plugin_name}' not found in kernel.")

            if function_name not in plugin.functions:
                raise AgentInitializationException(f"Function '{function_name}' not found in plugin '{plugin_name}'.")


# endregion

View on GitHub (pinned to c028a0c7dc)

Solutions

  1. Register the plugin under the exact name used in the tool id: `kernel.add_plugin(WebPlugin(), plugin_name='WebPlugin')`.
  2. Correct the tool id prefix in the YAML to match the registered plugin name.
  3. List `kernel.plugins.get_directory()` (or iterate kernel.plugins) to confirm available plugin names before loading.

Example fix

# before
kernel.add_plugin(WebPlugin(), plugin_name='Web')
# yaml: id: WebPlugin.search

# after
kernel.add_plugin(WebPlugin(), plugin_name='WebPlugin')
# yaml: id: WebPlugin.search
Defensive patterns

Strategy: validation

Validate before calling

for t in spec.get('tools', []):
    if t.get('type') != 'function' or not t.get('id') or '.' not in t['id']:
        continue
    plugin_name = t['id'].split('.', 1)[0]
    assert kernel.plugins.get(plugin_name), f'Plugin {plugin_name!r} not registered on kernel'

Type guard

def plugin_is_registered(tool: dict, kernel) -> bool:
    tid = tool.get('id', '')
    if '.' not in tid:
        return True
    return kernel.plugins.get(tid.split('.', 1)[0]) is not None

Try / catch

from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException
try:
    agent = await AgentRegistry.create_from_yaml(yaml_str, kernel=kernel)
except AgentInitializationException as e:
    if 'not found in kernel' in str(e):
        name = str(e).split("'")[1]
        kernel.add_plugin(MyPlugin(), plugin_name=name)
        agent = await AgentRegistry.create_from_yaml(yaml_str, kernel=kernel)
    else:
        raise

Prevention

When it happens

Trigger: Tool id `WebPlugin.search` but the kernel only has a plugin registered under a different name (e.g. 'Web') or no plugin registered at all.

Common situations: Plugin registered with a different plugin_name than the YAML expects; plugin registration code path skipped in the current config; typo in the plugin prefix.

Related errors

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