microsoft/semantic-kernel · error · AgentInitializationException

'top_k' must be an integer in: {spec}

Error message

'top_k' must be an integer in: {spec}

What it means

Raised when an azure_ai_search tool spec's top_k option is present but not a Python int (e.g. a string or float from JSON). top_k controls how many search results the tool returns.

Source

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

    index_name = opts.get("index_name")
    if not index_name or not isinstance(index_name, str):
        raise AgentInitializationException(f"Missing or malformed 'index_name' in: {spec}")

    raw_query_type = opts.get("query_type", AzureAISearchQueryType.SIMPLE)
    if type(raw_query_type) is str:
        try:
            query_type = AzureAISearchQueryType(raw_query_type.lower())
        except ValueError:
            raise AgentInitializationException(f"Invalid query_type '{raw_query_type}' in: {spec}")
    else:
        query_type = raw_query_type

    filter_expr = opts.get("filter", "")

    top_k = opts.get("top_k", 5)
    if not isinstance(top_k, int):
        raise AgentInitializationException(f"'top_k' must be an integer in: {spec}")

    return AzureAISearchTool(
        index_connection_id=conn_id,
        index_name=index_name,
        query_type=query_type,
        filter=filter_expr,
        top_k=top_k,
    )


@_register_tool("azure_function")
def _azure_function(spec: ToolSpec) -> ToolDefinition:
    # TODO(evmattso): Implement Azure Function tool support
    raise NotImplementedError("Azure Function tools are not yet supported with the Azure AI Agent Declarative Spec.")


@_register_tool("bing_grounding")
def _bing_grounding(spec: ToolSpec) -> BingGroundingTool:

View on GitHub (pinned to c028a0c7dc)

Solutions

  1. Provide top_k as an integer literal in the spec.
  2. If loading from external config, coerce to int explicitly: int(opts['top_k']) before constructing the agent.
  3. Omit top_k to accept the default of 5.

Example fix

// before
options:
  top_k: "5"

// after
options:
  top_k: 5
Defensive patterns

Strategy: validation

Validate before calling

def coerce_top_k(opts: dict):
    k = opts.get("top_k", 5)
    if not isinstance(k, int):
        raise TypeError("top_k must be int")
    return k

Type guard

def top_k_is_int(opts: dict) -> bool:
    k = opts.get("top_k", 5)
    return isinstance(k, int)

Prevention

When it happens

Trigger: Declarative spec specifies top_k as a string (e.g. "5") or float (5.0) because the spec was loaded from JSON/YAML without type coercion.

Common situations: YAML auto-parses some numeric-like values as strings; config templating injects numbers as strings; copy-paste from a JSON sample.

Related errors

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