Aspire agent awareness #2248

Aspire issue link

microsoft/aspire#17752

Overview

Migrated from microsoft/aspire#17752. The original implementation is microsoft/aspire#17757; this proposal moves that work into a CommunityToolkit.Aspire.Hosting.Agents integration.

Agents can use different protocols (OpenAI Responses, A2A, AG-UI, ACP, and others). Aspire currently understands Foundry prompt and hosted agents through integrations that also describe how those agents are deployed.

Add a generic API that identifies an endpoint-backed resource as an agent supporting a particular protocol, so developers can interact with that agent through custom commands in the Aspire dashboard. This should enrich the local development experience without dictating how the resource is deployed (Azure Container Apps, App Service, or other targets). It may also help scenarios discussed in microsoft/aspire#13851.

Protocol-specific behavior can include a dashboard URL for an A2A agent card and injecting the resource's own endpoint into A2A_AGENT_BASE_URL, allowing its agent card to advertise the actual URL rather than a hardcoded value. Consumers can receive an agent-card URL through explicit WithEnvironment calls and endpoint expressions, without changing core WithReference behavior.

Usage example

var weatherAgent = builder.AddUvicornApp("weatheragent", "./weather-agent-python", "weather_agent_python.main:app")
    .WithUv()
    .WithReference(deployment)
    .WaitFor(deployment)
    .AsAgent(AgentProtocol.A2A);

builder.AddProject<Projects.AgentClient>("agent-client")
    .WithEnvironment("WEATHERAGENT_AGENTCARD_URL",
        ReferenceExpression.Create($"{weatherAgent.GetEndpoint("http")}/.well-known/agent-card.json"))
    .WaitFor(weatherAgent);

The original proposal used a protocol-array overload of AsAgent; the implementation evolved to one call per protocol/path pair. The Toolkit integration should preserve the latest implementation's behavior and adapt its packaging and API surface to this repository's conventions.

Additional context

Original discussion: microsoft/aspire#17752

Original implementation and review: microsoft/aspire#17757

The implementation supports A2A (JSON-RPC and HTTP+JSON, including streaming), OpenAI Responses, AG-UI, and ACP message commands, plus explicit opt-in MCP tool commands through WithMcpToolCommands. Invocation belongs entirely in the integration package; no production changes to core Aspire.Hosting are required.

Commands and diagnostic URLs are run-mode developer tools, not deployed agent clients. They do not implement interactive sign-in, token acquisition or refresh, or forwarding the dashboard user's identity. Application-specific authentication should be handled by a driver application that Aspire can orchestrate and observe; endpoint authentication should not be disabled for these commands.

Help us help you

Yes, I'd like to be assigned to work on this item