Delen via

A2A-integratie

Het A2A-protocol (Agent-to-Agent) maakt gestandaardiseerde communicatie tussen agents mogelijk, zodat agents die zijn gebouwd met verschillende frameworks en technologieën naadloos kunnen communiceren.

Wat is A2A?

A2A is een gestandaardiseerd protocol dat ondersteuning biedt voor:

  • Agentdetectie via agentkaarten
  • Communicatie op basis van berichten tussen agents
  • Langlopende agent-gebaseerde processen via taken
  • Platformoverschrijdende interoperabiliteit tussen verschillende agentframeworks

Zie de A2A-protocolspecificatie voor meer informatie.

De Microsoft.Agents.AI.Hosting.A2A.AspNetCore bibliotheek biedt ASP.NET Core-integratie voor het beschikbaar maken van uw agents via het A2A-protocol.

NuGet-pakketten:

Example

In dit minimale voorbeeld ziet u hoe u een agent blootstelt via A2A. Het voorbeeld bevat OpenAPI- en Swagger-afhankelijkheden om het testen te vereenvoudigen.

1. Een ASP.NET Core Web API-project maken

Maak een nieuw ASP.NET Core Web API-project of gebruik een bestaand web-API-project.

2. Vereiste afhankelijkheden installeren

Installeer de volgende pakketten:

Voer de volgende opdrachten uit in uw projectmap om de vereiste NuGet-pakketten te installeren:

# 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. Azure OpenAI-verbinding configureren

Voor de toepassing is een Azure OpenAI-verbinding vereist. Configureer de eindpunt- en implementatienaam met behulp van dotnet user-secrets of omgevingsvariabelen. U kunt ook gewoon de appsettings.json bewerken, maar dat wordt niet aanbevolen voor de apps die in productie zijn, aangezien sommige gegevens als vertrouwelijk worden beschouwd.

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. Voeg de code toe aan Program.cs

Vervang de inhoud van Program.cs door de volgende code en voer de toepassing uit.

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

Het testen van de agent

Zodra de toepassing wordt uitgevoerd, kunt u de A2A-agent testen met behulp van het volgende .http bestand of via de Swagger-gebruikersinterface.

De invoerindeling voldoet aan de A2A-specificatie. U kunt waarden opgeven voor:

  • messageId - Een unieke id voor dit specifieke bericht. U kunt uw eigen id (bijvoorbeeld een GUID) maken of deze zo instellen null dat de agent er automatisch een kan genereren.
  • contextId - De gespreks-id. Geef uw eigen id op om een nieuw gesprek te starten of door te gaan met een bestaand gesprek door een vorige contextIdopnieuw te gebruiken. De agent zal de gespreksgeschiedenis bijhouden voor hetzelfde contextId. Agent genereert er ook een voor u, als er geen is opgegeven.
# 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"
  }
}

Opmerking: Vervang {{baseAddress}} door uw servereindpunt.

Deze aanvraag retourneert het volgende JSON-antwoord:

{
	"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"
}

Het antwoord bevat de contextId (gespreks-id), messageId (bericht-id) en de werkelijke inhoud van de piratenagent.

AgentCard-configuratie

De AgentCard bevat metagegevens over uw agent voor detectie en integratie:

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

U kunt toegang krijgen tot de agentkaart door deze aanvraag te verzenden:

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

Opmerking: Vervang {{baseAddress}} door uw servereindpunt.

Eigenschappen van AgentCard

  • Naam: Weergavenaam van de agent
  • Beschrijving: Korte beschrijving van de agent
  • Versie: Versiestring voor de agent
  • URL: Eindpunt-URL (automatisch toegewezen indien niet opgegeven)
  • Mogelijkheden: optionele metagegevens over streaming, pushmeldingen en andere functies

Meerdere agents exposeren

U kunt meerdere agents in één toepassing beschikbaar maken, zolang hun eindpunten niet botsen. Hier is een voorbeeld:

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

Met het agent-framework-a2a pakket kunt u verbinding maken met en communiceren met externe A2A-compatibele agents.

pip install agent-framework-a2a --pre

Verbinding maken met een A2A-agent

Gebruik A2AAgent dit om een extern A2A-eindpunt te verpakken. De agent lost de mogelijkheden van de externe agent op via de AgentCard en verwerkt alle protocolgegevens.

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

Streamingreacties

A2A biedt natuurlijk ondersteuning voor streaming via Server-Sent Gebeurtenissen: updates komen in realtime binnen wanneer de externe agent werkt:

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))")

Langdurige taken

Standaard wacht A2AAgent totdat de externe agent klaar is voordat het wordt geretourneerd. Voor langlopende taken stelt u background=True in om een vervolgtoken op te halen dat u kunt gebruiken om later opnieuw te peilen of opnieuw in te schrijven.

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)

Authenticatie

Gebruik een AuthInterceptor voor beveiligde A2A-eindpunten:

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!")

Zie ook

Volgende stappen

AG-UI Protocol

  • Last updated on