Hostování agentů s A2A

Protokol Agent-to-Agent (A2A) umožňuje standardizovanou komunikaci mezi agenty sestavenými s různými architekturami a technologiemi. Tato stránka popisuje zveřejnění agentů Agent Framework jako serverů A2A.

Pokud chcete zjistit a vyvolat vzdáleného agenta A2A, podívejte se na službu agenta A2A.

Co je A2A?

A2A je standardizovaný protokol, který podporuje:

  • Zjišťování agentů prostřednictvím karet agenta
  • Komunikace založená na zprávách mezi agenty
  • Dlouhotrvající agentické procesy prostřednictvím úkolů
  • Interoperabilita mezi platformami mezi různými architekturami agentů

Další informace najdete ve specifikaci protokolu A2A.

Knihovna Microsoft.Agents.AI.Hosting.A2A.AspNetCore poskytuje integraci ASP.NET Core pro expozici vašich agentů prostřednictvím protokolu A2A.

Balíčky NuGet:

Example

Tento minimální příklad ukazuje, jak vystavit agenta prostřednictvím A2A. Ukázka zahrnuje závislosti OpenAPI a Swagger, které zjednodušují testování.

1. Vytvoření projektu webového rozhraní API ASP.NET Core

Vytvořte nový projekt webového rozhraní API ASP.NET Core nebo použijte existující projekt.

2. Instalace požadovaných závislostí

Nainstalujte následující balíčky:

Spuštěním následujících příkazů v adresáři projektu nainstalujte požadované balíčky 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. Konfigurace připojení Microsoft Foundry

Aplikace vyžaduje připojení projektu Microsoft Foundry. Nakonfigurujte koncový bod a název nasazení pomocí dotnet user-secrets nebo proměnných prostředí. Můžete také jednoduše upravit appsettings.json, ale to se nedoporučuje pro aplikace nasazené v produkčním prostředí, protože některá data se dají považovat za tajná.

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. Přidejte kód do Program.cs

Nahraďte obsah Program.cs následujícím kódem a spusťte aplikaci:

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 je vhodný pro vývoj, ale vyžaduje pečlivé zvážení v produkčním prostředí. V produkčním prostředí zvažte použití konkrétních přihlašovacích údajů (např ManagedIdentityCredential. ) k zabránění problémům s latencí, neúmyslnému testování přihlašovacích údajů a potenciálním bezpečnostním rizikům z náhradních mechanismů.

Testování agenta

Po spuštění aplikace můžete agenta A2A otestovat pomocí následujícího .http souboru nebo pomocí uživatelského rozhraní Swagger.

Vstupní formát odpovídá specifikaci A2A. Můžete zadat hodnoty pro:

  • messageId – Jedinečný identifikátor pro tuto konkrétní zprávu. Můžete vytvořit vlastní ID (např. GUID) nebo ho nastavit na null, aby ho agent vygeneroval automaticky.
  • contextId - Identifikátor konverzace. Zadejte vlastní ID, abyste mohli zahájit novou konverzaci nebo pokračovat v existující konverzaci opětovným použitím předchozího contextId. Agent bude spravovat historii konverzací pro tentýž contextId. Agent pro vás vygeneruje také jeden, pokud není k dispozici.
# 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"
  }
}

Poznámka: Nahraďte {{baseAddress}} koncovým bodem serveru.

Tento požadavek vrátí následující odpověď 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"
}

Odpověď obsahuje contextId (identifikátor konverzace), messageId (identifikátor zprávy) a skutečný obsah od pirátských agentů.

Konfigurace AgentCard

Tento AgentCard poskytuje metadata o vašem agentovi pro objevování a integraci.

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

K kartě agenta se dostanete odesláním tohoto požadavku:

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

Poznámka: Nahraďte {{baseAddress}} koncovým bodem serveru.

Vlastnosti AgentCard

  • Název: Zobrazovaný název agenta
  • Popis: Stručný popis agenta
  • Verze: Řetězec verze pro agenta
  • Adresa URL: Adresa URL koncového bodu (automaticky přiřazená, pokud není zadána)
  • Možnosti: Volitelná metadata o streamování, nabízených oznámeních a dalších funkcích

Zpřístupnění více agentů

V jedné aplikaci můžete vystavit více agentů, pokud jejich koncové body nekolidují. Tady je příklad:

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

Balíček agent-framework-a2a zveřejňuje agenta Agent Framework přes protokol A2A.

pip install agent-framework-a2a --pre

Testování zabezpečeného koncového bodu

AuthInterceptor Ověření zabezpečeného koncového bodu A2A pomocí testovacího klienta:

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

Zpřístupnění agenta frameworku Agent Framework přes A2A

Balíček agent-framework-a2a poskytuje předdefinovaný A2AExecutor, který přizpůsobí libovolného agenta Agent Framework protokolu A2A na straně serveru. Spouští agenta, mapuje podporovaný výstupní obsah na události a artefakty A2A a spravuje aktualizace stavu úloh prostřednictvím oficiálního a2a-sdk.

Vaše aplikace sdružuje server A2A SDK a jeho okolní součásti: kartu agenta, DefaultRequestHandler, úložiště úloh, trasy nebo konstruktor aplikace, ověřování a nasazení. Porovnání s adaptéry vlastněnými aplikací a pomocnými rutinami pro samostatné převody naleznete v agent-framework-hosting-a2atématu Agenti A2A v místním hostiteli.

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 Streamuje aktualizace agenta jako artefakty A2A, když podkladový agent podporuje streamování a šíří A2A context_id jako relace agenta session_id. Můžete odvodit podtřídu z A2AExecutor a přepsat metodu handle_events, abyste implementovali vlastní transformace z výstupního formátu svého agenta na události protokolu A2A.

Protokol A2A

Rozhraní Go Agent Framework podporuje hostování agentů Agent Framework prostřednictvím protokolu Agent-to-Agent (A2A) s balíčkem provider/a2aprovider a oficiálními obslužnými rutinami serveru A2A Go.

Nainstalujte balíčky Agent Framework a A2A v modulu Go:

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

Hostování agenta prostřednictvím A2A

Vytvořte nebo znovu použijte agenta Agent Framework, popište ho pomocí karty agenta A2A a zpřístupňte ho prostřednictvím jedné z transportních vazeb A2A. V tomto příkladu je hostAgent libovolný framework pro agenty *agent.Agent; server hostuje koncový bod JSON-RPC na adrese / a zpřístupňuje kartu agenta na známé cestě 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))
}

Stejnou obslužnou rutinu požadavku zabalte pomocí a2asrv.NewRESTHandler, pokud chcete zpřístupnit transportní vazbu HTTP+JSON. Nastavte ExecutorConfig.AllowBackgroundResponses na true, pokud má hostovaný agent vracet úlohy A2A pro dlouhotrvající práci.

Viz taky

Další kroky

Protokol AG-UI

  • Last updated on