A2A Hosting

Agent Framework fornisce pacchetti di hosting che espongono gli agenti di intelligenza artificiale tramite il protocollo da agente a agente (A2A). Una volta ospitato, qualsiasi client conforme a A2A può individuare e comunicare con gli agenti, indipendentemente dal framework o dalla tecnologia con cui è stato compilato il client.

Pacchetti NuGet:

Microsoft.Agents.AI.Hosting.A2A.AspNetCore - mapping degli endpoint di ASP.NET Core per le associazioni del protocollo A2A. Questo pacchetto include Microsoft.Agents.AI.Hosting.A2Ain modo transitivo .
Microsoft.Agents.AI.Hosting.A2A : logica di hosting principale per gli agenti di intelligenza artificiale tramite bridging al protocollo A2A (registrazione del server, gestione delle richieste, gestione delle sessioni).

Come iniziare

Installare il pacchetto di hosting ASP.NET Core (include automaticamente il pacchetto principale):

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

L'esempio seguente illustra un'applicazione core minima di ASP.NET che ospita un singolo agente tramite A2A. Usa Microsoft Foundry come provider di intelligenza artificiale. Per altre opzioni, vedere Provider .

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

L'agente è ora raggiungibile all'indirizzo /a2a/weather-agent tramite il binding del protocollo HTTP+JSON A2A, e la scheda dell'agente è rintracciabile a /.well-known/agent.json. Qualsiasi client conforme a A2A può individuare e comunicare con questo agente.

Associazioni di protocollo

Il protocollo A2A definisce due associazioni di trasporto. Entrambi sono supportati:

Binding	Metodo	Descrizione
HTTP+JSON	`MapA2AHttpJson`	Richieste standard HTTP ed eventi inviati dal server per lo streaming.
JSON-RPC	`MapA2AJsonRpc`	JSON-RPC 2.0 su HTTP.

È possibile eseguire il mapping simultaneo di entrambe le associazioni in modo che i client possano scegliere il trasporto preferito. Se necessario, è possibile usare percorsi diversi:

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

Scheda agente

Le schede agente descrivono i metadati dell'agente, ovvero nome, descrizione, versione e interfacce supportate, in modo che i client possano individuare e comprendere le relative funzionalità prima di inviare richieste. La sezione Per iniziare mostra una carta agente minima. Per l'uso in produzione, fornire una scheda completamente popolata:

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 viene fornito dal pacchetto A2A SDK (A2A.AspNetCore), non dai pacchetti di hosting di Agent Framework.

Suggerimento

È possibile gestire una sola scheda agente per host, quindi solo un agente può essere individuabile tramite il percorso noto. È comunque possibile raggiungere altri agenti direttamente tramite URL. Per altre opzioni, vedere Individuazione Agenti.

Funzionamento di `AddA2AServer`

Il metodo AddA2AServer registra un singleton chiave A2AServer nel contenitore di iniezione delle dipendenze. Quando il server viene costruito, risolve o crea diversi componenti interni:

Componente	Impostazione predefinita	Scopo
`IAgentHandler`	`A2AAgentHandler`	Collega le richieste A2A in ingresso a `AIAgent`. Traduce i messaggi, esegue l'agente e restituisce le risposte come messaggi A2A.
`AgentSessionStore`	`InMemoryAgentSessionStore`	Archivia le sessioni di conversazione in modo che l'agente possa mantenere il contesto tra più richieste con lo stesso `contextId`.
`ITaskStore`	`InMemoryTaskStore`	Tiene traccia dello stato delle attività per le operazioni A2A a lungo termine.
`AgentRunMode`	`DisallowBackground`	Controlla se l'agente può restituire risposte in background (attività A2A) anziché messaggi immediati.

Avviso

Il valore predefinito InMemoryAgentSessionStore e InMemoryTaskStore sono destinati solo allo sviluppo. Lo stato viene perso al riavvio dell'applicazione e non viene condiviso tra più istanze. Per le distribuzioni di produzione, registrare implementazioni permanenti.

Sovrascrittura delle impostazioni predefinite

È possibile sostituire uno di questi componenti registrando servizi identificati da chiave nel contenitore DI prima di chiamare AddA2AServer. Il server risolve i servizi con chiave usando il nome dell'agente come chiave.

Archivio sessioni personalizzato : per l'archiviazione di conversazioni persistenti:

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

builder.AddA2AServer("weather-agent");

Archivio attività personalizzato : per il rilevamento di attività durevoli:

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

builder.AddA2AServer("weather-agent");

Gestore dell'agente personalizzato : per assumere il controllo completo dell'elaborazione delle richieste. Quando viene registrata una chiave IAgentHandler , sostituisce completamente il valore predefinito A2AAgentHandler :

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

builder.AddA2AServer("weather-agent");

Modalità di esecuzione dell'agente : configurare tramite A2AServerRegistrationOptions:

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

Più agenti

È possibile ospitare più agenti in una singola applicazione. Ogni agente ottiene il proprio server e endpoint A2A.

// 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 questo esempio, nessun agente dispone di una scheda agente, quindi i client devono conoscere direttamente gli URL dell'endpoint. È possibile aggiungere l'individuazione delle schede agente con MapWellKnownAgentCard, ma è possibile annunciare un solo agente per host. Vedere Scheda agente.

Risposte in secondo piano

Note

Le risposte in background non sono ancora supportate per gli agenti ospitati su A2A. Il AgentRunMode valore predefinito è DisallowBackground, ovvero tutte le risposte vengono restituite come messaggi A2A immediati.

Passaggi successivi

A2A Provider

Vedere anche

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-04-24