microsoft/aspire · error · InvalidOperationException

Tool ' ' belongs to project ' ' but agent ' ' belongs to…

Error message

Tool '{tool.Name}' belongs to project '{tool.Project.Name}' but agent '{Name}' belongs to project '{Project.Name}'. All tools must belong to the same project as the agent.

What it means

A Foundry prompt agent can only use tools whose backing Foundry project matches the agent's own project. AddTool validates this at the resource-model level and throws when a tool is registered against a different Foundry project instance than the one the agent belongs to.

Solutions

Create the tool from the same Foundry project the agent uses, e.g. project.AddAISearchTool(...) instead of anotherProject.AddAISearchTool(...).
Check that the resource passed to WithTool was not built against a second AddAzureFoundry project.
Consolidate to a single Foundry project resource if both agent and tool should live together.

Example fix

// before
var tool = otherProject.AddBingGroundingTool("bing");
agent.WithTool(tool);
// after
var tool = project.AddBingGroundingTool("bing");
agent.WithTool(tool);

Defensive patterns

Strategy: validation

Validate before calling

if (!ReferenceEquals(tool.Project, agent.Project)) throw new InvalidOperationException($"Tool '{tool.Name}' must be added from the agent's Foundry project '{agent.Project.Name}'.");

Prevention

Always create tools from the same project builder instance used to create agents.
Avoid holding Foundry project resources in globals that can mix projects.
In multi-project apps, name project resources clearly and keep agent+tool wiring adjacent.

When it happens

Trigger: Calling WithTool (which routes to AddTool) on an agent built from project A, passing a tool (e.g. an Azure AI Search or Bing tool) whose Project is project B.

Common situations: Apps with multiple Foundry projects where tools and agents are wired across projects; reusing a tool definition from another AppHost section or another project builder.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Foundry/PromptAgent/AzurePromptAgentResource.cs:154

    public StaticValueProvider<string> Version { get; } = new();

    /// <summary>
    /// Gets the list of tool resources attached to this agent.
    /// </summary>
    [AspireExportIgnore(Reason = "IFoundryTool is a .NET extensibility point and is not ATS-compatible.")]
    public IReadOnlyList<IFoundryTool> Tools => _tools;

    /// <summary>
    /// Adds a tool resource to this prompt agent.
    /// </summary>
    /// <param name="tool">The tool resource to add.</param>
    internal void AddTool(FoundryToolResource tool)
    {
        ArgumentNullException.ThrowIfNull(tool);

        if (tool.Project != Project)
        {
            throw new InvalidOperationException(
                $"Tool '{tool.Name}' belongs to project '{tool.Project.Name}' but agent '{Name}' " +
                $"belongs to project '{Project.Name}'. All tools must belong to the same project as the agent.");
        }

        _tools.Add(tool);
    }

    /// <inheritdoc/>
    public ReferenceExpression ConnectionStringExpression =>
        ReferenceExpression.Create($"{Project.Endpoint}/agents/{Name}");

    IEnumerable<KeyValuePair<string, ReferenceExpression>> IResourceWithConnectionString.GetConnectionProperties()
    {
        yield return new("AgentName", ReferenceExpression.Create($"{Name}"));
        yield return new("ProjectEndpoint", ReferenceExpression.Create($"{Project.Endpoint}"));
        yield return new("ConnectionString", ConnectionStringExpression);
    }

View on GitHub (pinned to 25830f84bd)