microsoft/semantic-kernel · error · AgentInitializationException

OpenAPI tool '{spec.id}' is missing required 'specification'

Error message

OpenAPI tool '{spec.id}' is missing required 'specification' field.

What it means

Raised by the OpenAPI tool builder when a declarative spec declares a tool of type 'openapi' but its options map has no 'specification' entry (or it is empty). The Azure AI OpenApiTool cannot be constructed without the OpenAPI document, so agent initialization is aborted. It surfaces as an AgentInitializationException during AzureAIAgent restore/create from a YAML/JSON spec.

Source

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

            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,
        auth=auth,
        default_parameters=opts.get("default_parameters"),
    )


def _build_tool(spec: ToolSpec, kernel: "Kernel") -> ToolDefinition:

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Add an 'options.specification' field to the openapi tool entry containing the full OpenAPI document (a JSON string or a parsed object).
2. Verify the key is exactly 'specification' and is nested under 'options', not at the tool top level.
3. If loading from a file, read its contents and pass them as options.specification before building the agent.
4. Run the spec through AzureAIAgent.resolve_placeholders first to confirm the structure is intact.

Example fix

// before
tools:
  - type: openapi
    id: weather
    description: weather api
// after
tools:
  - type: openapi
    id: weather
    description: weather api
    options:
      specification: |
        {"openapi":"3.0.0","paths":{...}}

def validate_openapi_tool(spec_dict):
    for t in spec_dict.get('tools', []):
        if t.get('type') == 'openapi':
            opts = t.get('options') or {}
            if not opts.get('specification'):
                raise ValueError(f"openapi tool '{t.get('id')}' missing options.specification")
    return spec_dict
# call before AzureAIAgent restore/create

def has_openapi_spec(tool_entry: dict) -> bool:
    return (
        tool_entry.get('type') == 'openapi'
        and bool((tool_entry.get('options') or {}).get('specification'))
    )

try:
    agent = await AzureAIAgent._from_dict(data, kernel=kernel, client=client)
except AgentInitializationException as e:
    if 'specification' in str(e):
        log.error('OpenAPI tool missing specification; check options.specification')
    raise

When it happens

Trigger: Calling AzureAIAgent restore/creation with a declarative spec that lists a tool {"type":"openapi","id":"x"} but omits options.specification, or sets it to an empty string. Also triggered when the 'specification' key is misspelled (e.g. 'spec' or 'openapi_spec').

Common situations: Migrating from a hand-built OpenApiTool call to the declarative spec format and forgetting to inline the spec document; copying an example that loaded the spec from a file separately; YAML indentation that collapses the specification under the wrong key.

Related errors

• Tool spec must include a 'type' field.
• Missing required 'client' in AzureAIAgent._from_dict()
• model.id required when creating a new Azure AI agent
• OpenAPI tool requires a non-empty 'id' (used as name).
• OpenAPI tool '{spec.id}' requires a 'description'.

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