{"record":{"id":"01e84fa939301e8e","repo":"microsoft/semantic-kernel","slug":"top-k-must-be-an-integer-in-spec","errorCode":null,"errorMessage":"'top_k' must be an integer in: {spec}","messagePattern":"'top_k' must be an integer in: (.+?)","errorType":"validation","errorClass":"AgentInitializationException","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/azure_ai/azure_ai_agent.py","lineNumber":125,"sourceCode":"\n    index_name = opts.get(\"index_name\")\n    if not index_name or not isinstance(index_name, str):\n        raise AgentInitializationException(f\"Missing or malformed 'index_name' in: {spec}\")\n\n    raw_query_type = opts.get(\"query_type\", AzureAISearchQueryType.SIMPLE)\n    if type(raw_query_type) is str:\n        try:\n            query_type = AzureAISearchQueryType(raw_query_type.lower())\n        except ValueError:\n            raise AgentInitializationException(f\"Invalid query_type '{raw_query_type}' in: {spec}\")\n    else:\n        query_type = raw_query_type\n\n    filter_expr = opts.get(\"filter\", \"\")\n\n    top_k = opts.get(\"top_k\", 5)\n    if not isinstance(top_k, int):\n        raise AgentInitializationException(f\"'top_k' must be an integer in: {spec}\")\n\n    return AzureAISearchTool(\n        index_connection_id=conn_id,\n        index_name=index_name,\n        query_type=query_type,\n        filter=filter_expr,\n        top_k=top_k,\n    )\n\n\n@_register_tool(\"azure_function\")\ndef _azure_function(spec: ToolSpec) -> ToolDefinition:\n    # TODO(evmattso): Implement Azure Function tool support\n    raise NotImplementedError(\"Azure Function tools are not yet supported with the Azure AI Agent Declarative Spec.\")\n\n\n@_register_tool(\"bing_grounding\")\ndef _bing_grounding(spec: ToolSpec) -> BingGroundingTool:","sourceCodeStart":107,"sourceCodeEnd":143,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/azure_ai/azure_ai_agent.py#L107-L143","documentation":"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.","triggerScenarios":"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.","commonSituations":"YAML auto-parses some numeric-like values as strings; config templating injects numbers as strings; copy-paste from a JSON sample.","solutions":["Provide top_k as an integer literal in the spec.","If loading from external config, coerce to int explicitly: int(opts['top_k']) before constructing the agent.","Omit top_k to accept the default of 5."],"exampleFix":"// before\noptions:\n  top_k: \"5\"\n\n// after\noptions:\n  top_k: 5","handlingStrategy":"validation","validationCode":"def coerce_top_k(opts: dict):\n    k = opts.get(\"top_k\", 5)\n    if not isinstance(k, int):\n        raise TypeError(\"top_k must be int\")\n    return k","typeGuard":"def top_k_is_int(opts: dict) -> bool:\n    k = opts.get(\"top_k\", 5)\n    return isinstance(k, int)","tryCatchPattern":null,"preventionTips":["When loading specs from JSON/YAML, coerce numeric options to int explicitly.","Define the spec with a typed schema that rejects non-int top_k."],"tags":["azure-ai-agent","declarative-spec","azure-ai-search","type-validation"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}