Hospedagem A2A

A Estrutura do Agente fornece pacotes de hospedagem que expõem seus agentes de IA por meio do protocolo Agente para Agente (A2A). Uma vez hospedado, qualquer cliente em conformidade com A2A pode descobrir e se comunicar com seus agentes, independentemente de qual estrutura ou tecnologia foi utilizada na construção do cliente.

Pacotes NuGet:

• Microsoft.Agents.AI.Hosting.A2A.AspNetCore – mapeamento de ponto de extremidade do ASP.NET Core para associações de protocolo A2A. Esse pacote inclui transitivamente Microsoft.Agents.AI.Hosting.A2A.
• Microsoft.Agents.AI.Hosting.A2A – lógica de hospedagem principal para fazer a ponte de agentes de IA para o protocolo A2A (registro do servidor, tratamento de solicitações, gerenciamento de sessão).

Como começar

Instale o pacote de hospedagem do ASP.NET Core (ele puxa o pacote núcleo automaticamente):

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

O exemplo a seguir mostra um aplicativo ASP.NET Core mínimo que hospeda um único agente por meio do A2A. Ele usa o Microsoft Foundry como o provedor de IA - consulte Provedores para outras opções.

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

O agente agora pode ser acessado em /a2a/weather-agent pelo vínculo de protocolo HTTP+JSON A2A e seu cartão de agente pode ser descoberto em /.well-known/agent.json. Qualquer cliente compatível com A2A pode descobrir e se comunicar com esse agente.

Associações de protocolo

O protocolo A2A define duas associações de transporte. Ambos têm suporte:

Você pode mapear ambas as associações simultaneamente para que os clientes possam escolher seu transporte preferencial. Caminhos diferentes podem ser usados se necessário:

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

Cartão do agente

Os cartões de agente descrevem os metadados do agente - nome, descrição, versão e interfaces com suporte - para que os clientes possam descobrir e entender seus recursos antes de enviar solicitações. A seção Introdução mostra um cartão de agente básico. Para uso em produção, forneça um cartão totalmente preenchido:

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

Como AddA2AServer funciona

O método AddA2AServer registra um singleton com chave A2AServer no contêiner de injeção de dependência. Quando o servidor é construído, ele resolve ou cria vários componentes internos:

Substituindo padrões

Você pode substituir qualquer um desses componentes registrando serviços com chave no contêiner de DI antes de chamar AddA2AServer. O servidor resolve serviços com chave usando o nome do agente como a chave.

Repositório de sessão personalizado – para armazenamento de conversa persistente:

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

builder.AddA2AServer("weather-agent");

Repositório de tarefas personalizado – para acompanhamento de tarefas duráveis:

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

builder.AddA2AServer("weather-agent");

Manipulador de agente personalizado – para assumir o controle total do processamento de solicitações. Quando um keyed IAgentHandler é registrado, ele substitui o padrão A2AAgentHandler inteiramente:

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

builder.AddA2AServer("weather-agent");

Modo de execução do agente – configurar por meio de A2AServerRegistrationOptions:

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

Vários agentes

Você pode hospedar vários agentes em um único aplicativo. Cada agente obtém seu próprio servidor A2A e 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();

Neste exemplo, nenhum agente tem um cartão de agente, portanto, os clientes devem saber as URLs do ponto de extremidade diretamente. Você pode adicionar a descoberta de cartão de agente com MapWellKnownAgentCard, mas apenas um agente pode ser anunciado por host - consulte o cartão do Agente.

Respostas em segundo plano

Próximas Etapas 

Consulte também

• Especificação do protocolo A2A
• Integração A2A
• Visão geral da hospedagem
• Visão geral dos agentes