microsoft/semantic-kernel · error · InvalidOperationException

Azure AI Search tool definition must have both 'index_connec

Error message

Azure AI Search tool definition must have both 'index_connection_id' and 'index_name' options set.

What it means

Thrown while building an AzureAISearchToolResource from an agent tool definition. The code treats both index_connection_id and index_name being empty as 'skip this tool' (returns null), but if exactly one of the two is set while the other is empty it throws InvalidOperationException. The library requires both fields together because Azure AI Search grounding needs both a connection reference and a target index.

Source

Thrown at dotnet/src/Agents/AzureAI/Extensions/AgentDefinitionExtensions.cs:233

        return null;
    }

    private static AzureAISearchToolResource? GetAzureAISearchResource(this AgentDefinition agentDefinition)
    {
        Verify.NotNull(agentDefinition);

        var azureAISearch = agentDefinition.GetFirstToolDefinition(AzureAISearchType);
        if (azureAISearch is not null)
        {
            string? indexConnectionId = azureAISearch.GetOption<string>("index_connection_id");
            string? indexName = azureAISearch.GetOption<string>("index_name");
            if (string.IsNullOrEmpty(indexConnectionId) && string.IsNullOrEmpty(indexName))
            {
                return null;
            }
            if (string.IsNullOrEmpty(indexConnectionId) || string.IsNullOrEmpty(indexName))
            {
                throw new InvalidOperationException("Azure AI Search tool definition must have both 'index_connection_id' and 'index_name' options set.");
            }
            int topK = azureAISearch.GetTopK() ?? 5;
            string filter = azureAISearch.GetFilter() ?? string.Empty;
            AzureAISearchQueryType? queryType = azureAISearch.GetAzureAISearchQueryType();

            return new AzureAISearchToolResource(indexConnectionId, indexName, topK, filter, queryType);
        }

        return null;
    }

    private static AzureAISearchToolDefinition CreateAzureAISearchToolDefinition(AgentToolDefinition tool)
    {
        Verify.NotNull(tool);

        return new AzureAISearchToolDefinition();
    }

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Provide both 'index_connection_id' and 'index_name' string options on the azure_ai_search tool definition.
2. If you intend to disable the tool, remove both options (or remove the tool block) so it returns null instead of throwing.
3. Validate the agent definition file against the expected schema before loading.

Example fix

// before
tools:
  - type: azure_ai_search
    options:
      index_connection_id: /subscriptions/.../connections/mySearch
      # index_name missing -> throws 161

// after
tools:
  - type: azure_ai_search
    options:
      index_connection_id: /subscriptions/.../connections/mySearch
      index_name: my-docs-index

var search = agentDefinition.GetFirstToolDefinition("azure_ai_search");
if (search is not null)
{
    string? conn = search.GetOption<string>("index_connection_id");
    string? name = search.GetOption<string>("index_name");
    if (string.IsNullOrEmpty(conn) ^ string.IsNullOrEmpty(name))
        throw new InvalidOperationException("azure_ai_search needs both index_connection_id and index_name.");
}

static bool IsAzureAISearchComplete(AgentToolDefinition t) =>
    !(string.IsNullOrEmpty(t.GetOption<string>("index_connection_id")) ^ string.IsNullOrEmpty(t.GetOption<string>("index_name")));

try { var resource = agentDefinition.GetAzureAISearchToolResource(); }
catch (InvalidOperationException ex) when (ex.Message.Contains("index_connection_id"))
{ /* fix the tool definition before retrying */ }

When it happens

Trigger: An agent definition includes an azure_ai_search tool whose options set index_connection_id but omit index_name (or vice versa). Passing GetOption<string>("index_connection_id") returns a value while GetOption<string>("index_name") returns null.

Common situations: YAML/JSON agent template has a typo in one key name. A template was partially edited. Copy-paste of a search tool config that dropped one field.

Related errors

• The option keys 'asset_identifiers' and 'asset_type' are req
• The option keys 'store_name' and 'data_sources' are required
• The option key '{bindingType}.storage_service_endpoint' is r
• The option key '{bindingType}.queue_name' is required.
• Invalid kernel selection. {selectedKernelName} is not a vali

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