What causes "OpenAPI tool requires a non-empty 'id' (used as name)." in microsoft/semantic-kernel?

Add a non-empty, unique id to the openapi tool entry; it becomes the tool name.

microsoft/semantic-kernel · error · AgentInitializationException

OpenAPI tool requires a non-empty 'id' (used as name).

Error message

OpenAPI tool requires a non-empty 'id' (used as name).

What it means

Raised when an openapi tool spec has no id. The id is used as the tool's name when registering the OpenAPI spec with the Azure AI agent, so it must be a non-empty string.

Source

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

        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:
        raise AgentInitializationException(f"Invalid JSON in OpenAPI 'specification' field: {e}") from e

    auth = opts.get("auth", OpenApiAnonymousAuthDetails())

    return OpenApiTool(
        name=spec.id,
        description=spec.description,
        spec=parsed_spec,

View on GitHub (pinned to c028a0c7dc)

Solutions

Add a non-empty, unique id to the openapi tool entry; it becomes the tool name.
Ensure the id does not collide with other tool ids in the same spec.

Example fix

// before
tools:
  - type: openapi
    description: Weather API
    options:
      specification: '{...}'

// after
tools:
  - type: openapi
    id: weatherApi
    description: Weather API
    options:
      specification: '{...}'

Defensive patterns

Strategy: validation

Validate before calling

def ensure_openapi_id(tool_spec: dict) -> None:
    if not tool_spec.get("id"):
        raise ValueError("openapi tool requires non-empty 'id'")

Type guard

def has_openapi_id(tool_spec: dict) -> bool:
    return bool(tool_spec.get("id"))

Prevention

Require id in your spec schema for every openapi tool.
Use a unique, descriptive id since it becomes the tool name.

When it happens

Trigger: Declarative spec includes an openapi tool entry without an id field or with an empty id string.

Common situations: Developer assumes the id is derived from the OpenAPI spec's title; spec template leaves id blank; id templated from an unset variable.

Related errors

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