Agenci hosta z usługą A2A

Protokół Agent-to-Agent (A2A) umożliwia ustandaryzowaną komunikację między agentami utworzonymi przy użyciu różnych struktur i technologii. Na tej stronie omówiono udostępnianie agentów programu Agent Framework jako serwerów A2A.

Aby odnaleźć i wywołać zdalnego agenta A2A, zobacz usługę agenta A2A.

Co to jest A2A?

A2A to standardowy protokół obsługujący:

  • Odnajdywanie agentów za pośrednictwem kart agentów
  • Komunikacja oparta na komunikatach między agentami
  • Długotrwałe procesy agentyczne poprzez zadania
  • Współdziałanie międzyplatformowe między różnymi frameworkami agentów

Aby uzyskać więcej informacji, zobacz specyfikację protokołu A2A.

Biblioteka Microsoft.Agents.AI.Hosting.A2A.AspNetCore zapewnia integrację ASP.NET Core na potrzeby uwidaczniania agentów za pośrednictwem protokołu A2A.

Pakiety NuGet:

Example

W tym minimalnym przykładzie pokazano, jak uwidocznić agenta za pośrednictwem usługi A2A. Przykład obejmuje zależności OpenAPI i Swagger w celu uproszczenia testowania.

1. Tworzenie projektu internetowego interfejsu API platformy ASP.NET Core

Utwórz nowy projekt internetowego interfejsu API platformy ASP.NET Core lub użyj istniejącego.

2. Zainstaluj wymagane zależności

Zainstaluj następujące pakiety:

Uruchom następujące polecenia w katalogu projektu, aby zainstalować wymagane pakiety NuGet:

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

# Libraries to connect to Microsoft Foundry
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI.Foundry --prerelease

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

3. Konfigurowanie połączenia microsoft Foundry

Aplikacja wymaga połączenia projektu Microsoft Foundry. Skonfiguruj punkt końcowy i nazwę wdrożenia przy użyciu dotnet user-secrets lub zmiennych środowiskowych. Można również po prostu edytować element appsettings.json, ale nie jest to zalecane dla aplikacji wdrożonych w środowisku produkcyjnym, ponieważ niektóre dane mogą być uważane za tajne.

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. Dodaj kod do Program.cs

Zastąp zawartość Program.cs pliku następującym kodem i uruchom aplikację:

using A2A.AspNetCore;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
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 AIProjectClient(
        new Uri(endpoint),
        new DefaultAzureCredential())
        .GetProjectOpenAIClient()
        .GetProjectResponsesClient()
        .AsIChatClient(deploymentName);

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

Warning

DefaultAzureCredential jest wygodne do programowania, ale wymaga starannego rozważenia w środowisku produkcyjnym. W środowisku produkcyjnym rozważ użycie określonego poświadczenia (np. ManagedIdentityCredential), aby uniknąć problemów z opóźnieniami, niezamierzonego sondowania poświadczeń i potencjalnych zagrożeń bezpieczeństwa wynikających z mechanizmów awaryjnych.

Testowanie agenta

Po uruchomieniu aplikacji możesz przetestować agenta A2A przy użyciu następującego .http pliku lub za pośrednictwem interfejsu użytkownika programu Swagger.

Format danych wejściowych jest zgodny ze specyfikacją A2A. Możesz podać wartości dla:

  • messageId - Unikatowy identyfikator dla tej konkretnej wiadomości. Możesz utworzyć własny identyfikator (np. identyfikator GUID) lub ustawić go tak, aby null umożliwić agentowi automatyczne wygenerowanie identyfikatora.
  • contextId - Identyfikator konwersacji. Podaj własny identyfikator, aby rozpocząć nową konwersację lub kontynuować istniejącą, ponownie używając poprzedniego contextIdelementu . Agent zachowa historię konwersacji dla tego samego contextIdelementu . Agent wygeneruje jeden dla ciebie również, jeśli żaden nie zostanie podany.
# 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"
  }
}

Uwaga: zastąp {{baseAddress}} punktem końcowym serwera.

To żądanie zwraca następującą odpowiedź 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"
}

Odpowiedź zawiera contextId (identyfikator konwersacji), messageId (identyfikator wiadomości) i faktyczną zawartość od agenta pirackiego.

Konfiguracja AgentCard

Zawiera AgentCard metadane dotyczące agenta na potrzeby odnajdywania i integracji:

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

Dostęp do karty agenta można uzyskać, wysyłając następujące żądanie:

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

Uwaga: zastąp {{baseAddress}} punktem końcowym serwera.

Właściwości karty agenta

  • Nazwa: Nazwa wyświetlana agenta
  • Opis: krótki opis agenta
  • Wersja: ciąg wersji agenta
  • Adres URL: adres URL punktu końcowego (automatycznie przypisany, jeśli nie zostanie określony)
  • Możliwości: metadane opcjonalne dotyczące przesyłania strumieniowego, powiadomień typu push i innych funkcji

Uwidacznianie wielu agentów

Możesz uwidocznić wielu agentów w jednej aplikacji, o ile ich punkty końcowe nie zderzają się. Oto przykład:

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

Pakiet agent-framework-a2a uwidacznia agenta programu Agent Framework za pośrednictwem protokołu A2A.

pip install agent-framework-a2a --pre

Testowanie zabezpieczonego punktu końcowego

Użyj elementu AuthInterceptor w kliencie testowym, aby zweryfikować zabezpieczony punkt końcowy A2A:

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

Uwidacznianie agenta platformy Agent za pośrednictwem usługi A2A

Pakiet agent-framework-a2a udostępnia predefiniowane rozwiązanie A2AExecutor, które dostosowuje dowolnego agenta Agent Framework do serwerowego protokołu A2A. Uruchamia agenta, mapuje obsługiwaną treść wyjściową na zdarzenia A2A i artefakty oraz zarządza aktualizacjami statusu zadań za pośrednictwem oficjalnego a2a-sdk.

Aplikacja tworzy otaczający serwer zestawu A2A SDK: kartę agenta, DefaultRequestHandlermagazyn zadań, trasy lub konstruktora aplikacji, uwierzytelnianie i wdrażanie. Aby porównać adaptery aplikacji i samodzielne narzędzia pomocnicze do konwersji w agent-framework-hosting-a2a, zobacz Hostowanie agentów A2A we własnym zakresie.

import uvicorn
from a2a.server.request_handlers import DefaultRequestHandler
from a2a.server.routes import create_agent_card_routes, create_jsonrpc_routes
from a2a.server.tasks import InMemoryTaskStore
from a2a.types import AgentCapabilities, AgentCard, AgentInterface, AgentSkill
from agent_framework import Agent
from agent_framework.a2a import A2AExecutor
from agent_framework.openai import OpenAIChatClient
from starlette.applications import Starlette

flight_skill = AgentSkill(
    id="Flight_Booking",
    name="Flight Booking",
    description="Search and book flights across Europe.",
    tags=["flights", "travel", "europe"],
    examples=[],
)

public_agent_card = AgentCard(
    name="Europe Travel Agent",
    description="Helps users search and book flights and hotels across Europe.",
    version="1.0.0",
    default_input_modes=["text"],
    default_output_modes=["text"],
    capabilities=AgentCapabilities(streaming=True),
    supported_interfaces=[
        AgentInterface(url="http://localhost:9999/", protocol_binding="JSONRPC"),
    ],
    skills=[flight_skill],
)

agent = Agent(
    client=OpenAIChatClient(),
    name="Europe Travel Agent",
    instructions="You are a helpful Europe Travel Agent.",
)

request_handler = DefaultRequestHandler(
    agent_executor=A2AExecutor(agent, stream=True),
    task_store=InMemoryTaskStore(),
    agent_card=public_agent_card,
)

server = Starlette(
    routes=[
        *create_agent_card_routes(public_agent_card),
        *create_jsonrpc_routes(request_handler, "/"),
    ]
)

uvicorn.run(server, host="0.0.0.0", port=9999)

A2AExecutor przesyła strumieniowo aktualizacje agenta jako artefakty A2A, gdy agent bazowy obsługuje przesyłanie strumieniowe, i propaguje A2A context_id jako session_id sesji agenta. Można utworzyć klasę pochodną klasy A2AExecutor i przesłonić metodę handle_events, aby zaimplementować niestandardowe przekształcenia z formatu wyjściowego agenta na zdarzenia protokołu A2A.

Protokół A2A

Platforma Go Agent Framework obsługuje hostowanie agentów programu Agent Framework za pośrednictwem protokołu Agent-to-Agent (A2A) z pakietem provider/a2aprovider i oficjalnymi procedurami obsługi serwera A2A Go.

Zainstaluj pakiety Agent Framework i A2A w module Go:

go get github.com/microsoft/agent-framework-go
go get github.com/a2aproject/a2a-go/v2

Hostowanie agenta za pośrednictwem usługi A2A

Utwórz lub ponownie użyj agenta programu Agent Framework, opisz go za pomocą karty agenta A2A i uwidocznij go za pomocą jednego z powiązań transportu A2A. W tym przykładzie hostAgent jest dowolna struktura *agent.Agentagentów ; serwer hostuje punkt końcowy JSON-RPC w / i obsługuje kartę agenta w dobrze znanej ścieżce A2A.

import (
    "fmt"
    "net/http"

    "github.com/a2aproject/a2a-go/v2/a2a"
    "github.com/a2aproject/a2a-go/v2/a2asrv"
    "github.com/microsoft/agent-framework-go/provider/a2aprovider"
)

url := "http://localhost:5000"

card := &a2a.AgentCard{
    Name:               "InvoiceAgent",
    Description:        "Handles requests relating to invoices.",
    Version:            "1.0.0",
    DefaultInputModes:  []string{"text"},
    DefaultOutputModes: []string{"text"},
    Capabilities: a2a.AgentCapabilities{
        Streaming: false,
    },
    SupportedInterfaces: []*a2a.AgentInterface{
        a2a.NewAgentInterface(url, a2a.TransportProtocolJSONRPC),
    },
}

mux := http.NewServeMux()
requestHandler := a2asrv.NewHandler(
    a2aprovider.NewExecutor(hostAgent, a2aprovider.ExecutorConfig{}),
    a2asrv.WithExtendedAgentCard(card),
)
mux.Handle("/", a2asrv.NewJSONRPCHandler(requestHandler))
mux.Handle(a2asrv.WellKnownAgentCardPath, a2asrv.NewStaticAgentCardHandler(card))

if err := http.ListenAndServe(":5000", mux); err != nil {
    panic(fmt.Errorf("A2A server failed: %w", err))
}

Opakuj ten sam program obsługi żądań za pomocą a2asrv.NewRESTHandler, gdy chcesz udostępnić powiązanie transportowe HTTP+JSON. Ustaw wartość ExecutorConfig.AllowBackgroundResponses na true, jeśli hostowany agent powinien mieć możliwość zwracania zadań A2A dla długotrwałych operacji.

Zobacz także

Następne kroki

protokółAG-UI

  • Last updated on