microsoft/semantic-kernel · error · AgentInitializationException

Kernel instance is required for tool resolution.

Error message

Kernel instance is required for tool resolution.

What it means

Thrown by the declarative spec _validate_tools classmethod when the kernel argument is falsy (None or empty). Tool validation must resolve each tool id against kernel.plugins, so a missing kernel makes that impossible. It fires only when the spec actually declares tools that need resolution.

Source

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

                # If 'instructions' is set in YAML, override the template field in config
                instructions = data.get("instructions")
                if instructions is not None:
                    prompt_template_config.template = instructions
                fields["prompt_template"] = prompt_template_config
                # Always set fields["instructions"] to the template being used
                fields["instructions"] = prompt_template_config.template

        return fields, kernel

    @classmethod
    def _validate_tools(cls: type[_D], tools_list: list[dict], kernel: Kernel) -> None:
        """Validate tool references in the declarative spec against kernel's registered plugins.

        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}'.")

View on GitHub (pinned to c028a0c7dc)

Solutions

  1. Construct and pass a real Kernel instance: `kernel = Kernel(); kernel.add_plugin(...)` then pass it to the registry call.
  2. Remove the `tools:` section from the spec if the agent does not need function calling.
  3. Register the referenced plugins on the kernel before calling the loader so validation can succeed.

Example fix

# before
agent = await AgentRegistry.create_from_yaml(yaml_with_tools, kernel=None)

# after
kernel = Kernel()
kernel.add_plugin(MyPlugin(), plugin_name='MyPlugin')
agent = await AgentRegistry.create_from_yaml(yaml_with_tools, kernel=kernel)
Defensive patterns

Strategy: validation

Validate before calling

assert kernel is not None, 'A Kernel instance is required when the spec declares tools'

Type guard

def has_kernel_for_tools(spec: dict, kernel: object) -> bool:
    tools = spec.get('tools') or []
    needs_tools = any(t.get('type') == 'function' and t.get('id') for t in tools)
    return (not needs_tools) or kernel 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 'Kernel instance is required' in str(e):
        kernel = Kernel(); kernel.add_plugin(MyPlugin(), plugin_name='MyPlugin')
        agent = await AgentRegistry.create_from_yaml(yaml_str, kernel=kernel)
    else:
        raise

Prevention

When it happens

Trigger: Loading a YAML/dict agent spec that lists `tools:` entries while passing kernel=None (or omitting kernel) to create_from_yaml / create_agent_from_dict / from_dict.

Common situations: Reusing a YAML intended for a kernel-backed agent but instantiating without a Kernel; refactoring that dropped the kernel argument; tests that build the spec dict with tools but pass a None kernel.

Related errors

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