microsoft/autogen · error · ValueError

semantic_config_name is required when query_type is 'semanti

Error message

semantic_config_name is required when query_type is 'semantic'

What it means

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).

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/tools/azure/_ai_search.py:854

                # Semantic search with re-ranking
                # Note: Make sure your index has semantic configuration enabled
                semantic_tool = AzureAISearchTool.create_full_text_search(
                    name="semantic-search",
                    endpoint="https://your-search.search.windows.net",
                    index_name="<your-index>",
                    credential=AzureKeyCredential("<your-key>"),
                    query_type="semantic",  # Enable semantic ranking
                    semantic_config_name="<your-semantic-config>",  # Required for semantic search
                    search_fields=["content", "title"],  # Required: fields to search within
                    select_fields=["content", "title", "url"],  # Optional: fields to return
                    top=5,
                )

                # The search tool can be used with an Agent
                # assistant = Agent("assistant", tools=[semantic_tool])
        """
        if query_type == "semantic" and not semantic_config_name:
            raise ValueError("semantic_config_name is required when query_type is 'semantic'")

        config_dict = {
            "name": name,
            "endpoint": endpoint,
            "index_name": index_name,
            "credential": credential,
            "description": description,
            "api_version": api_version or DEFAULT_API_VERSION,
            "query_type": query_type,
            "search_fields": search_fields,
            "select_fields": select_fields,
            "top": top,
            "filter": filter,
            "semantic_config_name": semantic_config_name,
            "enable_caching": enable_caching,
            "cache_ttl_seconds": cache_ttl_seconds,
        }

View on GitHub (pinned to 027ecf0a37)

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'.

Example fix

# before
AzureAISearchTool(name='s', endpoint=ep, index_name='idx', credential=cred, query_type='semantic')
# after
AzureAISearchTool(name='s', endpoint=ep, index_name='idx', credential=cred, query_type='semantic', semantic_config_name='my-semantic-config')

Defensive patterns

Strategy: validation

Validate before calling

def semantic_kwargs_valid(query_type: str, semantic_config_name) -> bool:
    if query_type == 'semantic':
        return isinstance(semantic_config_name, str) and bool(semantic_config_name.strip())
    return True

Type guard

def semantic_ready(query_type: str, semantic_config_name) -> bool:
    return query_type != 'semantic' or bool(semantic_config_name)

Try / catch

try:
    tool = AzureAISearchTool(..., query_type='semantic')
except ValueError as e:
    if 'semantic_config_name is required' in str(e):
        tool = AzureAISearchTool(..., query_type='semantic', semantic_config_name='default')
    else:
        raise

Prevention

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.

When it happens

Trigger: AzureAISearchTool(..., query_type='semantic') with semantic_config_name omitted, None, or empty string.

Common situations: 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).

Related errors

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/6113dfa01b542232. Report an issue: GitHub.