microsoft/semantic-kernel · error · AgentInitializationException

Tool id '{tool_id}' must be in format PluginName.FunctionNam

Error message

Tool id '{tool_id}' must be in format PluginName.FunctionName

What it means

Thrown by _validate_tools when a function-type tool's `id` does not contain a '.' separator. The loader splits on '.' to derive PluginName.FunctionName, so an id like 'search' is rejected. Non-function tools or tools without an id are skipped, so this only applies to entries with type=='function' and a non-empty id.

Source

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

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


# endregion

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Format every function tool id as `PluginName.FunctionName` in the spec.
2. Ensure the plugin name matches the name used when kernel.add_plugin(..., plugin_name=...) was called.
3. Validate tool ids programmatically before loading (see validationCode).

Example fix

# before
tools:
  - id: search
    type: function

# after
tools:
  - id: WebPlugin.search
    type: function

for t in spec.get('tools', []):
    if t.get('type') == 'function' and t.get('id') and '.' not in t['id']:
        raise ValueError(f"tool id {t['id']!r} must be PluginName.FunctionName")

def tool_id_is_well_formed(tool: dict) -> bool:
    tid = tool.get('id')
    return not (tool.get('type') == 'function' and tid) or '.' in tid

from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException
try:
    agent = await AgentRegistry.create_from_yaml(yaml_str, kernel=kernel)
except AgentInitializationException as e:
    if 'must be in format' in str(e):
        # fix tool ids to PluginName.FunctionName then retry
        raise
    raise

When it happens

Trigger: A YAML `tools:` entry `{id: search, type: function}` instead of `{id: WebPlugin.search, type: function}`.

Common situations: Authoring tool ids by function name only; importing a spec from a system that uses bare function names; copy-paste that dropped the plugin prefix.

Related errors

• Kernel instance is required for tool resolution.
• Missing or malformed 'vector_store_ids' in: {spec}
• Tool spec must include a 'type' field.
• Unsupported tool type: {spec.type}
• Missing 'type' field in agent definition.

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