Hébergement A2A

Agent Framework fournit des packages d’hébergement qui exposent vos agents IA via le protocole Agent-to-Agent (A2A). Une fois hébergé, tout client compatible A2A peut découvrir et communiquer avec vos agents, quelle que soit l’infrastructure ou la technologie avec laquelle le client a été créé.

Packages NuGet :

• Microsoft.Agents.AI.Hosting.A2A.AspNetCore - Mappage des points de terminaison pour ASP.NET Core avec les liaisons de protocoles A2A. Ce package inclut Microsoft.Agents.AI.Hosting.A2Ade manière transitive .
• Microsoft.Agents.AI.Hosting.A2A - Logique d’hébergement principale pour le pontage des agents IA au protocole A2A (inscription du serveur, gestion des demandes, gestion des sessions).

Premiers pas

Installez le package d’hébergement ASP.NET Core (il extrait automatiquement le package principal) :

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’exemple suivant montre une application minimale ASP.NET Core qui héberge un seul agent via A2A. Il utilise Microsoft Foundry en tant que fournisseur d’INTELLIGENCE artificielle : consultez Fournisseurs pour obtenir d’autres 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["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’agent est désormais accessible via /a2a/weather-agent la liaison de protocole HTTP+JSON A2A, et sa carte d’agent est détectable à l’adresse /.well-known/agent.json. Tout client compatible A2A peut découvrir et communiquer avec cet agent.

Liaisons de protocole

Le protocole A2A définit deux liaisons de transport. Les deux sont pris en charge :

Binding	Méthode	Description
HTTP+JSON	MapA2AHttpJson	Requêtes HTTP standard et événements Server-Sent pour la diffusion en continu.
JSON-RPC	MapA2AJsonRpc	JSON-RPC 2.0 sur HTTP.

Vous pouvez mapper les deux liaisons simultanément afin que les clients puissent choisir leur transport préféré. Différents chemins d’accès peuvent être utilisés si nécessaire :

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

Carte de l’agent

Les cartes d’agent décrivent les métadonnées de votre agent ( nom, description, version et interfaces prises en charge) afin que les clients puissent découvrir et comprendre ses fonctionnalités avant d’envoyer des requêtes. La section Prise en main affiche une carte d’agent simplifiée. Pour une utilisation en production, fournissez une carte entièrement remplie :

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 est fourni par le package sdk A2A (A2A.AspNetCore), et non par les packages d’hébergement Agent Framework.

Conseil / Astuce

Une seule carte d’agent peut être servie par hôte. Un seul agent est donc détectable via le chemin connu. D’autres agents peuvent toujours être atteints directement par URL. Pour plus d’options, consultez Découverte de l’agent .

Comment fonctionne AddA2AServer

La méthode AddA2AServer enregistre un singleton par clé A2AServer dans le conteneur d’injection de dépendances. Lorsque le serveur est construit, il résout ou crée plusieurs composants internes :

Composant	Default	Objectif
IAgentHandler	A2AAgentHandler	Acheminer les requêtes A2A entrantes vers le AIAgent. Traduit les messages, exécute l’agent et retourne des réponses sous forme de messages A2A.
AgentSessionStore	InMemoryAgentSessionStore	Stocke les sessions de conversation afin que l’agent puisse gérer le contexte entre plusieurs requêtes avec le même contextId.
ITaskStore	InMemoryTaskStore	Suit l'état des tâches pour les opérations A2A de longue durée.
AgentRunMode	DisallowBackground	Contrôle si l’agent peut retourner des réponses en arrière-plan (tâches A2A) au lieu de messages immédiats.

Avertissement

La valeur par défaut InMemoryAgentSessionStore et InMemoryTaskStore est destinée au développement uniquement. L’état est perdu lors du redémarrage de l’application et n’est pas partagé entre plusieurs instances. Pour les déploiements de production, inscrivez des implémentations durables.

Remplacement des paramètres par défaut

Vous pouvez remplacer l’un de ces composants en inscrivant des services avec clé dans le conteneur IoC avant d’appeler AddA2AServer. Le serveur résout les services clés à l’aide du nom de l’agent comme clé.

Magasin de sessions personnalisé : pour le stockage de conversation permanente :

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

builder.AddA2AServer("weather-agent");

Magasin de tâches personnalisé - pour le suivi des tâches durable :

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

builder.AddA2AServer("weather-agent");

Gestionnaire d’agent personnalisé : pour prendre le contrôle total du traitement des demandes. Lorsqu’un keyed IAgentHandler est inscrit, il remplace entièrement la valeur par défaut A2AAgentHandler :

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

builder.AddA2AServer("weather-agent");

Mode d’exécution de l’agent - configurer via A2AServerRegistrationOptions:

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

Plusieurs agents

Vous pouvez héberger plusieurs agents dans une seule application. Chaque agent obtient son propre serveur et point de terminaison 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();

Dans cet exemple, aucun agent n’a de carte d’agent. Les clients doivent donc connaître directement les URL de point de terminaison. Vous pouvez ajouter la découverte de cartes d’agent avec MapWellKnownAgentCard, mais un seul agent peut être annoncé par hôte : voir Carte Agent.

Réponses en arrière-fond

Note

Les réponses en arrière-plan ne sont pas encore prises en charge pour les agents hébergés par A2A. La valeur AgentRunMode par défaut est DisallowBackground, ce qui signifie que toutes les réponses sont renvoyées sous forme de messages A2A immédiats.

Étapes suivantes

Fournisseur A2A

Voir également

• Spécification du protocole A2A
• Intégration A2A
• Vue d’ensemble de l’hébergement
• Vue d’ensemble des agents