microsoft/semantic-kernel · error · AgentInitializationException

Function `{fqn}` must be in the form `pluginName.functionNam

Error message

Function `{fqn}` must be in the form `pluginName.functionName`.

What it means

Raised when a function tool's id (fully-qualified name) does not split into exactly two parts on '.'. The declarative builder expects the form pluginName.functionName and cannot resolve malformed names.

Source

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

def _code_interpreter(spec: ToolSpec) -> CodeInterpreterTool:
    file_ids = spec.options.get("file_ids")
    return CodeInterpreterTool(file_ids=file_ids) if file_ids else CodeInterpreterTool()


@_register_tool("file_search")
def _file_search(spec: ToolSpec) -> FileSearchTool:
    vector_store_ids = spec.options.get("vector_store_ids")
    if not vector_store_ids or not isinstance(vector_store_ids, list) or not vector_store_ids[0]:
        raise AgentInitializationException(f"Missing or malformed 'vector_store_ids' in: {spec}")
    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:

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Format the function tool id as pluginName.functionName with exactly one dot.
2. Confirm the plugin name and function name match those registered on the Kernel.
3. If the function lives at the top level, place it in a named plugin first.

Example fix

// before
tools:
  - type: function
    id: MyFunc
# or id: A-B-C

// after
tools:
  - type: function
    id: MyPlugin.MyFunc

def validate_function_id(tool_id: str) -> None:
    parts = tool_id.split(".")
    if len(parts) != 2:
        raise ValueError(f"id '{tool_id}' must be 'pluginName.functionName'")

def is_well_formed_fqn(tool_id: str) -> bool:
    parts = tool_id.split(".")
    return len(parts) == 2 and all(parts)

When it happens

Trigger: Setting a function tool id to 'functionName' (no plugin), 'a.b.c', or any value without exactly one dot separator.

Common situations: Developer uses the dash-separated format ('Plugin-Func') valid for filters but not here; forgets the plugin prefix; includes extra dotted segments.

Related errors

• Function ID is required for function tools.
• Function `{spec.id}` not found in kernel.
• Multiple definitions found for `{spec.id}`. Please remove du
• Missing or malformed 'tool_connections' in: {spec}
• Missing or malformed 'index_name' in: {spec}

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