{"record":{"id":"9ebaf9a121c15d20","repo":"microsoft/semantic-kernel","slug":"kernel-instance-is-required-for-tool-resolution","errorCode":null,"errorMessage":"Kernel instance is required for tool resolution.","messagePattern":"Kernel instance is required for tool resolution\\.","errorType":"validation","errorClass":"AgentInitializationException","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/agent.py","lineNumber":1049,"sourceCode":"                # If 'instructions' is set in YAML, override the template field in config\n                instructions = data.get(\"instructions\")\n                if instructions is not None:\n                    prompt_template_config.template = instructions\n                fields[\"prompt_template\"] = prompt_template_config\n                # Always set fields[\"instructions\"] to the template being used\n                fields[\"instructions\"] = prompt_template_config.template\n\n        return fields, kernel\n\n    @classmethod\n    def _validate_tools(cls: type[_D], tools_list: list[dict], kernel: Kernel) -> None:\n        \"\"\"Validate tool references in the declarative spec against kernel's registered plugins.\n\n        This validates the declared tools in the YAML spec, and only checks whether those references resolve\n        properly in the current kernel.\n        \"\"\"\n        if not kernel:\n            raise AgentInitializationException(\"Kernel instance is required for tool resolution.\")\n\n        for tool in tools_list:\n            tool_id = tool.get(\"id\")\n            if not tool_id or tool.get(\"type\") != \"function\":\n                continue\n\n            if \".\" not in tool_id:\n                raise AgentInitializationException(f\"Tool id '{tool_id}' must be in format PluginName.FunctionName\")\n\n            plugin_name, function_name = tool_id.split(\".\", 1)\n\n            plugin = kernel.plugins.get(plugin_name)\n            if not plugin:\n                raise AgentInitializationException(f\"Plugin '{plugin_name}' not found in kernel.\")\n\n            if function_name not in plugin.functions:\n                raise AgentInitializationException(f\"Function '{function_name}' not found in plugin '{plugin_name}'.\")\n","sourceCodeStart":1031,"sourceCodeEnd":1067,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/agent.py#L1031-L1067","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Construct and pass a real Kernel instance: `kernel = Kernel(); kernel.add_plugin(...)` then pass it to the registry call.","Remove the `tools:` section from the spec if the agent does not need function calling.","Register the referenced plugins on the kernel before calling the loader so validation can succeed."],"exampleFix":"# before\nagent = await AgentRegistry.create_from_yaml(yaml_with_tools, kernel=None)\n\n# after\nkernel = Kernel()\nkernel.add_plugin(MyPlugin(), plugin_name='MyPlugin')\nagent = await AgentRegistry.create_from_yaml(yaml_with_tools, kernel=kernel)","handlingStrategy":"validation","validationCode":"assert kernel is not None, 'A Kernel instance is required when the spec declares tools'","typeGuard":"def has_kernel_for_tools(spec: dict, kernel: object) -> bool:\n    tools = spec.get('tools') or []\n    needs_tools = any(t.get('type') == 'function' and t.get('id') for t in tools)\n    return (not needs_tools) or kernel is not None","tryCatchPattern":"from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException\ntry:\n    agent = await AgentRegistry.create_from_yaml(yaml_str, kernel=kernel)\nexcept AgentInitializationException as e:\n    if 'Kernel instance is required' in str(e):\n        kernel = Kernel(); kernel.add_plugin(MyPlugin(), plugin_name='MyPlugin')\n        agent = await AgentRegistry.create_from_yaml(yaml_str, kernel=kernel)\n    else:\n        raise","preventionTips":["Always build and pass a Kernel when your spec uses tools.","Register referenced plugins on the kernel before loading the spec."],"tags":["kernel","tools","validation","declarative-spec","semantic-kernel"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}