A2A Hosting

The Agent Framework provides hosting packages that expose your AI agents via the Agent-to-Agent (A2A) protocol. Once hosted, any A2A-compliant client can discover and communicate with your agents, regardless of what framework or technology the client was built with.

NuGet Packages:

Getting started

Install the ASP.NET Core hosting package (it automatically installs the core hosting package and the A2A SDK packages):

dotnet add package Microsoft.Agents.AI.Hosting.A2A.AspNetCore --prerelease
dotnet add package Microsoft.Agents.AI.Foundry --prerelease

The following example shows a minimal ASP.NET Core application that hosts a single agent via A2A. It uses Microsoft Foundry as the AI provider - see Providers for other options.

using A2A;
using A2A.AspNetCore;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

string endpoint = builder.Configuration["FOUNDRY_PROJECT_ENDPOINT"]
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
string model = builder.Configuration["FOUNDRY_MODEL"] ?? "gpt-4o-mini";

// 1. Create and register the "weather-agent" agent in the DI container.
builder.Services.AddKeyedSingleton<AIAgent>("weather-agent", (sp, _) =>
{
    return new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
        .AsAIAgent(
            model: model,
            instructions: "You are a helpful weather assistant.",
            name: "weather-agent");
});

// 2. Register the A2A server for the "weather-agent" agent.
builder.AddA2AServer("weather-agent");

var app = builder.Build();

// 3. Map A2A protocol endpoints for the "weather-agent" agent.
app.MapA2AHttpJson("weather-agent", "/a2a/weather-agent");

// 4. Serve a minimal agent card for the "weather-agent" agent discovery.
app.MapWellKnownAgentCard(new AgentCard
{
    Name = "WeatherAgent",
    Description = "A helpful weather assistant.",
    SupportedInterfaces =
    [
        new AgentInterface
        {
            Url = "http://localhost:5000/a2a/weather-agent",
            ProtocolBinding = ProtocolBindingNames.HttpJson,
            ProtocolVersion = "1.0",
        }
    ]
});

app.Run();

The agent is now reachable at /a2a/weather-agent over the A2A HTTP+JSON protocol binding, and its agent card is discoverable at /.well-known/agent-card.json. Any A2A-compliant client can discover and communicate with this agent.

Protocol bindings

The A2A protocol defines two transport bindings. Both are supported:

Binding Method Description
HTTP+JSON MapA2AHttpJson Standard HTTP requests and Server-Sent Events for streaming.
JSON-RPC MapA2AJsonRpc JSON-RPC 2.0 over HTTP.

You can map both bindings simultaneously so that clients can choose their preferred transport. Different paths can be used if necessary:

app.MapA2AHttpJson("weather-agent", "/a2a/weather-agent");  // HTTP+JSON
app.MapA2AJsonRpc("weather-agent", "/a2a/weather-agent");   // JSON-RPC

Agent card

Agent cards describe your agent's metadata - name, description, version, and supported interfaces - so that clients can discover and understand its capabilities before sending requests. The Getting started section shows a minimal agent card. For production use, provide a fully populated card:

using A2A;
using A2A.AspNetCore;

app.MapWellKnownAgentCard(new AgentCard
{
    Name = "WeatherAgent",
    Description = "A helpful weather assistant.",
    Version = "1.0",
    DefaultInputModes = ["text"],
    DefaultOutputModes = ["text"],
    SupportedInterfaces =
    [
        new AgentInterface
        {
            Url = "http://localhost:5000/a2a/weather-agent",
            ProtocolBinding = ProtocolBindingNames.HttpJson,
            ProtocolVersion = "1.0",
        }
    ]
});

Note

MapWellKnownAgentCard is provided by the A2A SDK package (A2A.AspNetCore), not the Agent Framework hosting packages.

Tip

Only one agent card can be served per host, so only one agent is discoverable via the well-known path. Other agents can still be reached directly by URL. See Agent Discovery for more options.

How AddA2AServer works

The AddA2AServer method registers a keyed A2AServer singleton in the dependency injection container. When the server is constructed, it resolves or creates several internal components:

Component Default Purpose
IAgentHandler A2AAgentHandler Bridges incoming A2A requests to the AIAgent. Translates messages, runs the agent, and returns responses as A2A messages.
AgentSessionStore InMemoryAgentSessionStore Stores conversation sessions so the agent can maintain context across multiple requests with the same contextId.

Warning

The default InMemoryAgentSessionStore is intended for development only. State is lost on application restart and isn't shared across multiple instances. For production deployments, register a durable implementation.

Overriding defaults

You can replace any of these components by registering keyed services in the DI container before calling AddA2AServer. The server resolves keyed services using the agent name as the key.

Custom session store - for persistent conversation storage:

builder.Services.AddKeyedSingleton<AgentSessionStore>("weather-agent", new MyDurableSessionStore());

builder.AddA2AServer("weather-agent");

Custom agent handler - to take full control of request processing. When a keyed IAgentHandler is registered, it replaces the default A2AAgentHandler entirely:

builder.Services.AddKeyedSingleton<IAgentHandler>("weather-agent", new MyCustomHandler());

builder.AddA2AServer("weather-agent");

Multiple agents

You can host multiple agents in a single application. Each agent gets its own A2A server and endpoint:

// Register agents in DI.
builder.Services.AddKeyedSingleton<AIAgent>("weather-agent", (sp, _) =>
{
    return new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
        .AsAIAgent(model: model, instructions: "You are a helpful weather assistant.", name: "weather-agent");
});

builder.Services.AddKeyedSingleton<AIAgent>("scientist", (sp, _) =>
{
    return new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
        .AsAIAgent(model: model, instructions: "You are a scientist.", name: "scientist");
});

// Register A2A servers.
builder.AddA2AServer("weather-agent");
builder.AddA2AServer("scientist");

var app = builder.Build();

// Map endpoints.
app.MapA2AHttpJson("weather-agent", "/a2a/weather-agent");
app.MapA2AHttpJson("scientist", "/a2a/scientist");

app.Run();

In this example, neither agent has an agent card, so clients must know the endpoint URLs directly. You can add agent card discovery with MapWellKnownAgentCard, but only one agent can be advertised per host - see Agent card.

Task support

Note

The default agent handler doesn't return A2A tasks yet. The hosted agent always responds with an A2A message.

To return tasks, register a custom IAgentHandler as shown in Overriding defaults. It replaces the default handler, so your handler must run the agent and create, update, resume, and cancel tasks.

Next steps

See also