{"record":{"id":"6113dfa01b542232","repo":"microsoft/autogen","slug":"semantic-config-name-is-required-when-query-type-i","errorCode":null,"errorMessage":"semantic_config_name is required when query_type is 'semantic'","messagePattern":"semantic_config_name is required when query_type is 'semantic'","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/packages/autogen-ext/src/autogen_ext/tools/azure/_ai_search.py","lineNumber":854,"sourceCode":"                # Semantic search with re-ranking\n                # Note: Make sure your index has semantic configuration enabled\n                semantic_tool = AzureAISearchTool.create_full_text_search(\n                    name=\"semantic-search\",\n                    endpoint=\"https://your-search.search.windows.net\",\n                    index_name=\"<your-index>\",\n                    credential=AzureKeyCredential(\"<your-key>\"),\n                    query_type=\"semantic\",  # Enable semantic ranking\n                    semantic_config_name=\"<your-semantic-config>\",  # Required for semantic search\n                    search_fields=[\"content\", \"title\"],  # Required: fields to search within\n                    select_fields=[\"content\", \"title\", \"url\"],  # Optional: fields to return\n                    top=5,\n                )\n\n                # The search tool can be used with an Agent\n                # assistant = Agent(\"assistant\", tools=[semantic_tool])\n        \"\"\"\n        if query_type == \"semantic\" and not semantic_config_name:\n            raise ValueError(\"semantic_config_name is required when query_type is 'semantic'\")\n\n        config_dict = {\n            \"name\": name,\n            \"endpoint\": endpoint,\n            \"index_name\": index_name,\n            \"credential\": credential,\n            \"description\": description,\n            \"api_version\": api_version or DEFAULT_API_VERSION,\n            \"query_type\": query_type,\n            \"search_fields\": search_fields,\n            \"select_fields\": select_fields,\n            \"top\": top,\n            \"filter\": filter,\n            \"semantic_config_name\": semantic_config_name,\n            \"enable_caching\": enable_caching,\n            \"cache_ttl_seconds\": cache_ttl_seconds,\n        }\n","sourceCodeStart":836,"sourceCodeEnd":872,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/python/packages/autogen-ext/src/autogen_ext/tools/azure/_ai_search.py#L836-L872","documentation":"The full-text AzureAISearchTool constructor rejects query_type='semantic' unless semantic_config_name is given: semantic ranking on Azure AI Search requires the index to have a semantic configuration, and the tool must send its name with every query. This is a fail-fast duplicate of the config model's rule (error 938).","triggerScenarios":"AzureAISearchTool(..., query_type='semantic') with semantic_config_name omitted, None, or empty string.","commonSituations":"Switching query_type from 'simple' to 'semantic' for better relevance without first creating a semantic configuration on the index; passing the configuration name in the wrong kwarg (e.g. semantic_configuration).","solutions":["Create a semantic configuration on the index (Portal: Indexes → Semantics, or CLI/REST), then pass its name: semantic_config_name='my-semantic-config'.","Verify the exact name — it is case-sensitive and must match the configuration defined on the index.","If you do not need ranking, keep query_type='simple' or 'full'."],"exampleFix":"# before\nAzureAISearchTool(name='s', endpoint=ep, index_name='idx', credential=cred, query_type='semantic')\n# after\nAzureAISearchTool(name='s', endpoint=ep, index_name='idx', credential=cred, query_type='semantic', semantic_config_name='my-semantic-config')","handlingStrategy":"validation","validationCode":"def semantic_kwargs_valid(query_type: str, semantic_config_name) -> bool:\n    if query_type == 'semantic':\n        return isinstance(semantic_config_name, str) and bool(semantic_config_name.strip())\n    return True","typeGuard":"def semantic_ready(query_type: str, semantic_config_name) -> bool:\n    return query_type != 'semantic' or bool(semantic_config_name)","tryCatchPattern":"try:\n    tool = AzureAISearchTool(..., query_type='semantic')\nexcept ValueError as e:\n    if 'semantic_config_name is required' in str(e):\n        tool = AzureAISearchTool(..., query_type='semantic', semantic_config_name='default')\n    else:\n        raise","preventionTips":["Create the semantic configuration on the index before enabling query_type='semantic'.","Store semantic_config_name in env/config alongside query_type so they change together.","Remember semantic search requires a supported service tier."],"tags":["azure","azure-ai-search","semantic-search","configuration","validation"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}