microsoft/semantic-kernel · error · AgentInitializationException

Multiple definitions found for `{spec.id}`. Please remove du

Error message

Multiple definitions found for `{spec.id}`. Please remove duplicates.

What it means

Raised when the declarative function-tool builder resolves more than one function for a single pluginName.functionName id. The lookup must be unambiguous to map one tool to one kernel function.

Source

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

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:
    opts = spec.options or {}

    if not spec.id:
        raise AgentInitializationException("OpenAPI tool requires a non-empty 'id' (used as name).")
    if not spec.description:
        raise AgentInitializationException(f"OpenAPI tool '{spec.id}' requires a 'description'.")

    raw_spec = opts.get("specification")
    if not raw_spec:
        raise AgentInitializationException(f"OpenAPI tool '{spec.id}' is missing required 'specification' field.")

    try:
        parsed_spec = json.loads(raw_spec) if isinstance(raw_spec, str) else raw_spec
    except json.JSONDecodeError as e:

View on GitHub (pinned to c028a0c7dc)

Solutions

  1. Remove the duplicate registration so only one function matches the id.
  2. Rename one of the conflicting plugins or functions to disambiguate.
  3. Audit kernel.get_list_of_function_metadata_filters({}) output for repeated fully_qualified_name values.

Example fix

// before
kernel.add_plugin(PluginA(), "Shared")
kernel.add_plugin(PluginB(), "Shared")  # both define Func
# spec id: Shared.Func -> 2 matches

// after
kernel.add_plugin(PluginA(), "Shared")
kernel.add_plugin(PluginB(), "SharedB")
# spec id: Shared.Func or SharedB.Func
Defensive patterns

Strategy: validation

Validate before calling

def assert_unique_fqns(kernel) -> None:
    fqns = [f.fully_qualified_name for f in kernel.get_list_of_function_metadata_filters({})}
    dupes = {f for f in fqns if fqns.count(f) > 1}
    if dupes:
        raise ValueError(f"Duplicate fully_qualified_name(s): {sorted(dupes)}")

Type guard

def no_duplicate_fqns(kernel) -> bool:
    fqns = [f.fully_qualified_name for f in kernel.get_list_of_function_metadata_filters({})]
    return len(fqns) == len(set(fqns))

Prevention

When it happens

Trigger: Two plugins or two functions share the same fully-qualified name, so get_list_of_function_metadata_filters returns >1 entry.

Common situations: Same plugin registered twice under the same name; method overloaded with duplicate @kernel_function names; copy-paste plugin definitions; merging specs that both register 'MyPlugin.MyFunc'.

Related errors

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