Compartir a través de

Integración de A2A

El protocolo Agent-to-Agent (A2A) permite la comunicación estandarizada entre agentes, lo que permite a los agentes creados con diferentes marcos y tecnologías comunicarse sin problemas.

¿Qué es A2A?

A2A es un protocolo estandarizado que admite:

  • Detección de agentes mediante tarjetas de agente
  • Comunicación basada en mensajes entre agentes
  • Procesos agénticos de larga duración mediante tareas
  • Interoperabilidad multiplataforma entre diferentes marcos de agente

Para obtener más información, consulte la especificación del protocolo A2A.

La Microsoft.Agents.AI.Hosting.A2A.AspNetCore biblioteca proporciona integración de ASP.NET Core para exponer agentes a través del protocolo A2A.

Paquetes NuGet:

Example

En este ejemplo mínimo se muestra cómo exponer un agente a través de A2A. En el ejemplo se incluyen las dependencias de OpenAPI y Swagger para simplificar las pruebas.

1. Creación de un proyecto de API web de ASP.NET Core

Cree un nuevo proyecto de API web de ASP.NET Core o use uno existente.

2. Instalación de dependencias necesarias

Instale los siguientes paquetes:

Ejecute los siguientes comandos en el directorio del proyecto para instalar los paquetes NuGet necesarios:

# Hosting.A2A.AspNetCore for A2A protocol integration
dotnet add package Microsoft.Agents.AI.Hosting.A2A.AspNetCore --prerelease

# Libraries to connect to Azure OpenAI
dotnet add package Azure.AI.OpenAI --prerelease
dotnet add package Azure.Identity
dotnet add package Microsoft.Extensions.AI
dotnet add package Microsoft.Extensions.AI.OpenAI --prerelease

# Swagger to test app
dotnet add package Microsoft.AspNetCore.OpenApi
dotnet add package Swashbuckle.AspNetCore

3. Configuración de la conexión de Azure OpenAI

La aplicación requiere una conexión de Azure OpenAI. Configure el punto de conexión y el nombre de implementación mediante dotnet user-secrets o variables de entorno. También puede simplemente editar el appsettings.json, pero eso no se recomienda para las aplicaciones implementadas en producción, ya que algunos de los datos se pueden considerar confidenciales.

dotnet user-secrets set "AZURE_OPENAI_ENDPOINT" "https://<your-openai-resource>.openai.azure.com/"
dotnet user-secrets set "AZURE_OPENAI_DEPLOYMENT_NAME" "gpt-4o-mini"

4. Agregar el código a Program.cs

Reemplace el contenido de Program.cs por el código siguiente y ejecute la aplicación:

using A2A.AspNetCore;
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI.Hosting;
using Microsoft.Extensions.AI;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();
builder.Services.AddSwaggerGen();

string endpoint = builder.Configuration["AZURE_OPENAI_ENDPOINT"]
    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
string deploymentName = builder.Configuration["AZURE_OPENAI_DEPLOYMENT_NAME"]
    ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT_NAME is not set.");

// Register the chat client
IChatClient chatClient = new AzureOpenAIClient(
        new Uri(endpoint),
        new DefaultAzureCredential())
    .GetChatClient(deploymentName)
    .AsIChatClient();
builder.Services.AddSingleton(chatClient);

// Register an agent
var pirateAgent = builder.AddAIAgent("pirate", instructions: "You are a pirate. Speak like a pirate.");

var app = builder.Build();

app.MapOpenApi();
app.UseSwagger();
app.UseSwaggerUI();

// Expose the agent via A2A protocol. You can also customize the agentCard
app.MapA2A(pirateAgent, path: "/a2a/pirate", agentCard: new()
{
    Name = "Pirate Agent",
    Description = "An agent that speaks like a pirate.",
    Version = "1.0"
});

app.Run();

Probar el agente

Una vez que se ejecuta la aplicación, puede probar el agente de A2A mediante el siguiente .http archivo o a través de la interfaz de usuario de Swagger.

El formato de entrada cumple con la especificación A2A. Puede proporcionar valores para:

  • messageId : un identificador único para este mensaje específico. Puede crear su propio identificador (por ejemplo, un GUID) o establecerlo en null para permitir que el agente genere uno automáticamente.
  • contextId : identificador de conversación. Proporcione su propio identificador para iniciar una nueva conversación o continuar con una existente mediante la reutilización de un anterior contextId. El agente mantendrá el historial de conversaciones para el mismo contextId. El agente también generará uno para usted, si no se proporciona ninguno.
# Send A2A request to the pirate agent
POST {{baseAddress}}/a2a/pirate/v1/message:stream
Content-Type: application/json
{
  "message": {
    "kind": "message",
    "role": "user",
    "parts": [
      {
        "kind": "text",
        "text": "Hey pirate! Tell me where have you been",
        "metadata": {}
      }
    ],
	"messageId": null,
    "contextId": "foo"
  }
}

Nota: Reemplace por {{baseAddress}} el punto de conexión del servidor.

Esta solicitud devuelve la siguiente respuesta JSON:

{
	"kind": "message",
	"role": "agent",
	"parts": [
		{
			"kind": "text",
			"text": "Arrr, ye scallywag! Ye’ll have to tell me what yer after, or be I walkin’ the plank? 🏴‍☠️"
		}
	],
	"messageId": "chatcmpl-CXtJbisgIJCg36Z44U16etngjAKRk",
	"contextId": "foo"
}

La respuesta incluye ( contextId identificador de conversación), messageId (identificador de mensaje) y el contenido real del agente pirata.

Configuración de AgentCard

AgentCard proporciona metadatos sobre el agente para la detección e integración:

app.MapA2A(agent, "/a2a/my-agent", agentCard: new()
{
    Name = "My Agent",
    Description = "A helpful agent that assists with tasks.",
    Version = "1.0",
});

Para acceder a la tarjeta del agente, envíe esta solicitud:

# Send A2A request to the pirate agent
GET {{baseAddress}}/a2a/pirate/v1/card

Nota: Reemplace por {{baseAddress}} el punto de conexión del servidor.

Propiedades de AgentCard

  • Nombre para mostrar del agente
  • Descripción: breve descripción del agente
  • Versión: cadena de versión para el agente
  • Dirección URL: dirección URL del punto de conexión (asignada automáticamente si no se especifica)
  • Funcionalidades: metadatos opcionales sobre streaming, notificaciones push y otras características

Exposición de varios agentes

Puede exponer varios agentes en una sola aplicación, siempre y cuando sus puntos de conexión no entren en conflicto. Este es un ejemplo:

var mathAgent = builder.AddAIAgent("math", instructions: "You are a math expert.");
var scienceAgent = builder.AddAIAgent("science", instructions: "You are a science expert.");

app.MapA2A(mathAgent, "/a2a/math");
app.MapA2A(scienceAgent, "/a2a/science");

El agent-framework-a2a paquete le permite conectarse y comunicarse con agentes externos compatibles con A2A.

pip install agent-framework-a2a --pre

Conexión a un agente de A2A

Use A2AAgent para ajustar cualquier punto de conexión A2A remoto. El agente resuelve las funcionalidades del agente remoto a través de su AgentCard y controla todos los detalles del protocolo.

import asyncio
import httpx
from a2a.client import A2ACardResolver
from agent_framework.a2a import A2AAgent

async def main():
    a2a_host = "https://your-a2a-agent.example.com"

    # 1. Discover the remote agent's capabilities
    async with httpx.AsyncClient(timeout=60.0) as http_client:
        resolver = A2ACardResolver(httpx_client=http_client, base_url=a2a_host)
        agent_card = await resolver.get_agent_card()
        print(f"Found agent: {agent_card.name}")

    # 2. Create an A2AAgent and send a message
    async with A2AAgent(
        name=agent_card.name,
        agent_card=agent_card,
        url=a2a_host,
    ) as agent:
        response = await agent.run("What are your capabilities?")
        for message in response.messages:
            print(message.text)

asyncio.run(main())

Respuestas de streaming

A2A admite naturalmente el streaming a través de eventos de Server-Sent: las actualizaciones llegan en tiempo real a medida que funciona el agente remoto:

async with A2AAgent(name="remote", url="https://a2a-agent.example.com") as agent:
    async with agent.run("Tell me about yourself", stream=True) as stream:
        async for update in stream:
            for content in update.contents:
                if content.text:
                    print(content.text, end="", flush=True)

        final = await stream.get_final_response()
        print(f"\n({len(final.messages)} message(s))")

Tareas de larga duración

De forma predeterminada, A2AAgent espera a que el agente remoto finalice antes de volver. En el caso de las tareas de larga duración, establezca background=True para obtener un token de continuación que puede usar para sondear o volver a enviar más adelante:

async with A2AAgent(name="worker", url="https://a2a-agent.example.com") as agent:
    # Start a long-running task
    response = await agent.run("Process this large dataset", background=True)

    if response.continuation_token:
        # Poll for completion later
        result = await agent.poll_task(response.continuation_token)
        print(result)

Autenticación

Use un AuthInterceptor para puntos de conexión A2A protegidos:

from a2a.client.auth.interceptor import AuthInterceptor

class BearerAuth(AuthInterceptor):
    def __init__(self, token: str):
        self.token = token

    async def intercept(self, request):
        request.headers["Authorization"] = f"Bearer {self.token}"
        return request

async with A2AAgent(
    name="secure-agent",
    url="https://secure-a2a-agent.example.com",
    auth_interceptor=BearerAuth("your-token"),
) as agent:
    response = await agent.run("Hello!")

Véase también

Pasos siguientes

El Protocolo AG-UI

  • Last updated on