A2A Hosting

Struktura agentów udostępnia pakiety hostingowe, które uwidaczniają agentów sztucznej inteligencji za pośrednictwem protokołu Agent-to-Agent (A2A). Po uruchomieniu hostingu każdy klient zgodny ze standardem A2A może odnajdywać agentów i komunikować się z nimi niezależnie od frameworku lub technologii, z jaką został zbudowany klient.

Pakiety NuGet:

• Microsoft.Agents.AI.Hosting.A2A.AspNetCore — ASP.NET Core mapowanie punktów końcowych dla powiązań protokołu A2A. Ten pakiet transitwnie zawiera Microsoft.Agents.AI.Hosting.A2A.
• Microsoft.Agents.AI.Hosting.A2A — podstawowa logika hostingu dla mostkowania agentów sztucznej inteligencji do protokołu A2A (rejestracja serwera, obsługa żądań, zarządzanie sesjami).

Rozpoczęcie pracy

Zainstaluj pakiet hostingowy ASP.NET Core (automatycznie pobiera pakiet podstawowy):

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

W poniższym przykładzie przedstawiono minimalną aplikację ASP.NET Core, która hostuje jednego agenta za pośrednictwem usługi A2A. Używa Microsoft Foundry jako dostawcy sztucznej inteligencji — zobacz Dostawcy dla innych opcji.

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["AZURE_AI_PROJECT_ENDPOINT"]
    ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
string model = builder.Configuration["AZURE_AI_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();

Agent jest teraz osiągalny /a2a/weather-agent za pośrednictwem powiązania protokołu HTTP+JSON A2A, a jego karta agenta jest wykrywalna pod adresem /.well-known/agent.json. Każdy klient zgodny ze standardem A2A może odnajdywać i komunikować się z tym agentem.

Powiązania protokołu

Protokół A2A definiuje dwa powiązania transportu. Oba są obsługiwane:

Oba powiązania można mapować jednocześnie, aby klienci mogli wybrać preferowany transport. W razie potrzeby można używać różnych ścieżek:

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

Karta agenta

Karty agenta opisują metadane agenta — nazwę, opis, wersję i obsługiwane interfejsy — aby klienci mogli odnajdywać i rozumieć jego możliwości przed wysłaniem żądań. W sekcji Rozpoczęcie przedstawiono minimalną kartę agenta. W przypadku użycia produkcyjnego podaj w pełni wypełniona karta:

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",
        }
    ]
});

Jak działa AddA2AServer

Metoda AddA2AServer rejestruje singelton z kluczem A2AServer w kontenerze iniekcji zależności. Po utworzeniu serwera rozwiązuje problem lub tworzy kilka składników wewnętrznych:

Zastępowanie wartości domyślnych

Dowolny z tych składników można zastąpić, rejestrując usługi przypisane kluczom w kontenerze DI przed wywołaniem metody AddA2AServer. Serwer rozpoznaje kluczowe usługi przy użyciu nazwy agenta jako klucza.

Niestandardowy magazyn sesji — dla trwałego przechowywania konwersacji:

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

builder.AddA2AServer("weather-agent");

Niestandardowy magazyn zadań — na potrzeby trwałego śledzenia zadań:

builder.Services.AddKeyedSingleton<ITaskStore>("weather-agent", new MyDurableTaskStore());

builder.AddA2AServer("weather-agent");

Niestandardowy obsługiwacz agenta — pozwala na pełną kontrolę nad przetwarzaniem żądań. Gdy klucz IAgentHandler jest zarejestrowany, zastępuje wartość domyślną A2AAgentHandler w całości:

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

builder.AddA2AServer("weather-agent");

Tryb uruchamiania agenta — konfigurowanie za pomocą polecenia A2AServerRegistrationOptions:

builder.AddA2AServer("weather-agent", options =>
{
    options.AgentRunMode = AgentRunMode.DisallowBackground;
});

Wielu agentów

Możesz hostować wielu agentów w jednej aplikacji. Każdy agent otrzymuje własny serwer A2A i własny punkt końcowy.

// 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();

W tym przykładzie żaden z agentów nie ma karty agenta, więc klienci muszą bezpośrednio znać adresy URL punktów końcowych. Odkrywanie kart agenta można dodać za pomocą MapWellKnownAgentCard, ale można reklamować tylko jednego agenta na hosta — zobacz Kartę agenta.

Odpowiedzi w tle

Następne kroki

Zobacz także

• Specyfikacja protokołu A2A
• Integracja A2A
• Omówienie hostingu
• Omówienie agentów