microsoft/aspire · error · DistributedApplicationException

Foundry hosted agent for target resource

Error message

Foundry hosted agent for target resource '{targetResourceName}' must declare at least one protocol version.

What it means

A Foundry hosted agent resource must advertise which A2A/MCP protocol versions it supports. HostedAgentConfiguration.ValidateProtocolVersions throws this DistributedApplicationException during agent-version creation when the agent's ProtocolVersions collection is empty, because Foundry Hosted Agents require at least one declared protocol version to provision the agent.

Solutions

Call the protocol-versions configuration API (e.g. .WithProtocolVersions(...)) on the hosted agent resource before the app model is evaluated, passing at least one supported protocol version.
Verify ProtocolVersions is populated by inspecting the agent builder configuration; add a unit test asserting Count > 0.
Check the Aspire.Hosting.Foundry README/sample for the current required protocol-version declarations.

Example fix

// before
var agent = foundry.AddHostedAgent("my-agent", targetResource: project);

// after
var agent = foundry.AddHostedAgent("my-agent", targetResource: project)
    .WithProtocolVersions(["v1"]);

Defensive patterns

Strategy: validation

Validate before calling

if (agent.ProtocolVersions is not { Count: > 0 })
    throw new InvalidOperationException("Hosted agent must declare at least one protocol version before creation.");

Try / catch

try { /* create agent version */ } catch (DistributedApplicationException ex) when (ex.Message.Contains("must declare at least one protocol version")) { /* fix config or surface actionable message */ }

Prevention

Always chain WithProtocolVersions right after creating the hosted agent resource.
Write a unit test asserting ProtocolVersions.Count > 0 for every hosted agent in the app model.
Wrap hosted-agent creation in a helper that enforces protocol versions by default.

When it happens

Trigger: Calling ToProjectsAgentVersionCreationOptions on a hosted agent configuration whose ProtocolVersions collection was never populated (Count == 0). This happens when the user adds a hosted agent targeting a resource without calling the API that declares protocol versions (e.g. WithProtocolVersions).

Common situations: Declaring a hosted agent with only a target resource and project but forgetting the protocol-version call; copying sample code that omits protocol versions; upgrading from an older package version where the versions call was optional.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Foundry/HostedAgent/HostedAgentConfiguration.cs:161

        {
            def.EnvironmentVariables[envVar.Key] = envVar.Value;
        }
        var options = new ProjectsAgentVersionCreationOptions(def)
        {
            Description = Description,
        };
        foreach (var kvp in Metadata)
        {
            options.Metadata[kvp.Key] = kvp.Value;
        }
        return options;
    }

    private void ValidateProtocolVersions(string? targetResourceName)
    {
        if (ProtocolVersions.Count == 0)
        {
            throw new DistributedApplicationException($"Foundry hosted agent for target resource '{targetResourceName}' must declare at least one protocol version.");
        }
    }

    private static void ValidateEnvironmentVariableNames(IEnumerable<string> environmentVariableNames, string? targetResourceName)
    {
        var invalidNames = environmentVariableNames
            .Where(static name => !EnvironmentVariableNameRegex().IsMatch(name))
            .Order(StringComparer.Ordinal)
            .ToArray();

        if (invalidNames.Length == 0)
        {
            return;
        }

        throw new DistributedApplicationException(
            $"Foundry hosted agent for target resource '{targetResourceName}' contains environment variable names that are not supported by Foundry Hosted Agents. " +
            $"Environment variable names must contain only ASCII letters, digits, or underscores. " +

View on GitHub (pinned to 25830f84bd)