{"record":{"id":"78d9300cd75561f7","repo":"microsoft/aspire","slug":"foundry-hosted-agent-for-target-resource-targetresourcename","errorCode":null,"errorMessage":"Foundry hosted agent for target resource '{targetResourceName}' must declare at least one protocol version.","messagePattern":"Foundry hosted agent for target resource '(.+?)' must declare at least one protocol version\\.","errorType":"validation","errorClass":"DistributedApplicationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.Foundry/HostedAgent/HostedAgentConfiguration.cs","lineNumber":161,"sourceCode":"        {\n            def.EnvironmentVariables[envVar.Key] = envVar.Value;\n        }\n        var options = new ProjectsAgentVersionCreationOptions(def)\n        {\n            Description = Description,\n        };\n        foreach (var kvp in Metadata)\n        {\n            options.Metadata[kvp.Key] = kvp.Value;\n        }\n        return options;\n    }\n\n    private void ValidateProtocolVersions(string? targetResourceName)\n    {\n        if (ProtocolVersions.Count == 0)\n        {\n            throw new DistributedApplicationException($\"Foundry hosted agent for target resource '{targetResourceName}' must declare at least one protocol version.\");\n        }\n    }\n\n    private static void ValidateEnvironmentVariableNames(IEnumerable<string> environmentVariableNames, string? targetResourceName)\n    {\n        var invalidNames = environmentVariableNames\n            .Where(static name => !EnvironmentVariableNameRegex().IsMatch(name))\n            .Order(StringComparer.Ordinal)\n            .ToArray();\n\n        if (invalidNames.Length == 0)\n        {\n            return;\n        }\n\n        throw new DistributedApplicationException(\n            $\"Foundry hosted agent for target resource '{targetResourceName}' contains environment variable names that are not supported by Foundry Hosted Agents. \" +\n            $\"Environment variable names must contain only ASCII letters, digits, or underscores. \" +","sourceCodeStart":143,"sourceCodeEnd":179,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.Foundry/HostedAgent/HostedAgentConfiguration.cs#L143-L179","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"// before\nvar agent = foundry.AddHostedAgent(\"my-agent\", targetResource: project);\n\n// after\nvar agent = foundry.AddHostedAgent(\"my-agent\", targetResource: project)\n    .WithProtocolVersions([\"v1\"]);","handlingStrategy":"validation","validationCode":"if (agent.ProtocolVersions is not { Count: > 0 })\n    throw new InvalidOperationException(\"Hosted agent must declare at least one protocol version before creation.\");","typeGuard":null,"tryCatchPattern":"try { /* create agent version */ } catch (DistributedApplicationException ex) when (ex.Message.Contains(\"must declare at least one protocol version\")) { /* fix config or surface actionable message */ }","preventionTips":["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."],"tags":["azure-ai-foundry","aspire-hosting","validation","protocol-versions"],"backgroundTag":"empty-required-field","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T09:17:21.228Z"}