microsoft/aspire · error · InvalidOperationException

Azure AI Search tool

Error message

Azure AI Search tool '{Name}' does not have a backing resource configured. Call .WithReference(searchResource) to link it to an Azure AI Search resource.

What it means

An Azure AI Search tool used by a Foundry prompt agent must be linked to a backing Azure AI Search resource through WithReference. ToAgentToolAsync throws when the tool's Connection is still null because the connection ID cannot be constructed without a backing resource.

Solutions

1. Call WithReference(searchResource) on the AI Search tool builder, where searchResource comes from builder.AddAzureSearch(...).
2. Verify the WithReference call happens before the agent is created/deployed.
3. Confirm tool.Resource.Connection is set at runtime before deploying.

Example fix

// before
var searchTool = project.AddAISearchTool("search-tool");
agent.WithTool(searchTool);
// after
var searchTool = project.AddAISearchTool("search-tool")
    .WithReference(search);
agent.WithTool(searchTool);

if (searchToolBuilder.Resource.Connection is null) throw new InvalidOperationException("Call WithReference(searchResource) before adding the tool to an agent.");

bool isLinked(AzureAISearchToolResource t) => t.Connection is not null;

When it happens

Trigger: Adding an AI Search tool via AddAISearchTool and passing it to agent.WithTool without ever calling WithReference(searchResource) on the tool builder.

Common situations: Skipping the WithReference step when copying minimal samples; conditional wiring that never executes; assuming the tool works standalone without a search resource.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• Azure AI Search tool
• Bing Grounding tool ' ' does not have a project connection…
• Bing Grounding tool ' ' already has a connection configured.
• Failed to resolve connection ID for Azure AI Search tool
• Failed to resolve connection ID for Azure AI Search tool

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/ee6404bb6e520c8d. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.Foundry/ToolResources/AzureAISearchToolResource.cs:59

    /// <summary>
    /// Gets or sets the optional search index name to query. If not set, the tool
    /// will use a default or prompt-specified index at runtime.
    /// </summary>
    public string? IndexName { get; set; }

    /// <summary>
    /// Gets or sets the Foundry project connection resource for this search tool.
    /// Set by <see cref="PromptAgentBuilderExtensions.WithReference(IResourceBuilder{AzureAISearchToolResource}, IResourceBuilder{AzureSearchResource})"/>.
    /// </summary>
    internal AzureCognitiveServicesProjectConnectionResource? Connection { get; set; }

    /// <inheritdoc/>
    public override async Task<ResponseTool> ToAgentToolAsync(CancellationToken cancellationToken = default)
    {
        if (Connection is null)
        {
            throw new InvalidOperationException(
                $"Azure AI Search tool '{Name}' does not have a backing resource configured. " +
                "Call .WithReference(searchResource) to link it to an Azure AI Search resource.");
        }

        // The connection ID output is resolved after infrastructure provisioning
        var connectionIdRef = new BicepOutputReference("id", Connection);
        var connectionId = await connectionIdRef.GetValueAsync(cancellationToken).ConfigureAwait(false);
        if (string.IsNullOrEmpty(connectionId))
        {
            throw new InvalidOperationException(
                $"Failed to resolve connection ID for Azure AI Search tool '{Name}'. " +
                "The Foundry project connection may not have been provisioned correctly.");
        }

        var index = new AzureAISearchToolIndex
        {
            ProjectConnectionId = connectionId,
            IndexName = IndexName

View on GitHub (pinned to 25830f84bd)