Agen host dengan A2A

Protokol Agent-to-Agent (A2A) memungkinkan komunikasi standar antara agen yang dibangun dengan kerangka kerja dan teknologi yang berbeda. Halaman ini mencakup mengekspos agen Agent Framework sebagai server A2A.

Untuk menemukan dan memanggil agen A2A jarak jauh, lihat layanan agen A2A.

Apa itu A2A?

A2A adalah protokol standar yang mendukung:

  • Identifikasi agen dengan kartu agen
  • Komunikasi berbasis pesan antar agen
  • Proses agenik yang berjalan lama melalui tugas
  • Interoperabilitas lintas platform antara kerangka kerja agen yang berbeda

Untuk informasi selengkapnya, lihat spesifikasi protokol A2A.

Library Microsoft.Agents.AI.Hosting.A2A.AspNetCore menyediakan integrasi ASP.NET Core untuk memperlihatkan agen Anda melalui protokol A2A.

Paket NuGet:

Example

Contoh minimal ini menunjukkan cara mengekspos agen melalui A2A. Sampel termasuk dependensi OpenAPI dan Swagger untuk menyederhanakan pengujian.

1. Buat proyek ASP.NET Core Web API

Buat proyek ASP.NET Core Web API baru atau gunakan yang sudah ada.

2. Pasang dependensi yang diperlukan

Instal paket berikut:

Jalankan perintah berikut di direktori proyek Anda untuk menginstal paket NuGet yang diperlukan:

# 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. Mengatur koneksi Microsoft Foundry

Aplikasi ini memerlukan koneksi proyek Microsoft Foundry. Konfigurasikan titik akhir dan nama penyebaran menggunakan dotnet user-secrets atau variabel lingkungan. Anda juga dapat mengedit appsettings.json, tetapi hal ini tidak disarankan untuk aplikasi yang disebarkan dalam lingkungan produksi karena beberapa data dapat dianggap rahasia.

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. Tambahkan kode ke Program.cs

Ganti konten Program.cs dengan kode berikut dan jalankan aplikasi:

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 nyaman untuk pengembangan tetapi membutuhkan pertimbangan yang cermat dalam produksi. Dalam produksi, pertimbangkan untuk menggunakan kredensial tertentu (misalnya, ManagedIdentityCredential) untuk menghindari masalah latensi, pemeriksaan kredensial yang tidak diinginkan, dan potensi risiko keamanan dari mekanisme fallback.

Menguji Agen

Setelah aplikasi berjalan, Anda dapat menguji agen A2A menggunakan file berikut .http atau melalui antarmuka pengguna Swagger.

Format input mematuhi spesifikasi A2A. Anda dapat memberikan nilai untuk:

  • messageId - Pengidentifikasi unik untuk pesan spesifik ini. Anda dapat membuat ID Anda sendiri (misalnya GUID) atau mengaturnya ke null untuk membiarkan agen membuatnya secara otomatis.
  • contextId - Pengidentifikasi percakapan. Berikan ID Anda sendiri untuk memulai percakapan baru atau melanjutkan percakapan yang sudah ada dengan menggunakan kembali contextId sebelumnya. Agen akan mempertahankan riwayat percakapan untuk hal yang sama contextId. Agen juga akan menghasilkan satu untuk Anda, jika tidak ada yang disediakan.
# 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"
  }
}

Catatan: Ganti {{baseAddress}} dengan titik akhir server Anda.

Permintaan ini mengembalikan respons JSON berikut:

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

Respons mencakup contextId (pengidentifikasi percakapan), messageId (pengidentifikasi pesan), dan konten aktual dari agen bajak laut.

Konfigurasi AgentCard

AgentCard menyediakan metadata tentang agen Anda untuk penemuan dan integrasi:

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

Anda dapat mengakses kartu agen dengan mengirim permintaan ini:

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

Catatan: Ganti {{baseAddress}} dengan titik akhir server Anda.

Properti AgentCard

  • Nama: Nama yang ditampilkan dari agen
  • Deskripsi: Deskripsi singkat agen
  • Versi: String versi untuk agen
  • Url: URL Titik Akhir (ditetapkan secara otomatis jika tidak ditentukan)
  • Kemampuan: Metadata opsional tentang streaming, pemberitahuan push, dan fitur lainnya

Mengekspos Beberapa Agen

Anda dapat mengekspos beberapa agen dalam satu aplikasi, selama titik akhir mereka tidak bertabrakan. Berikut adalah sebuah contoh:

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

Paket mengekspos agent-framework-a2a agen Agent Framework melalui protokol A2A.

pip install agent-framework-a2a --pre

Menguji titik akhir yang aman

AuthInterceptor Gunakan di klien pengujian untuk memverifikasi titik akhir A2A yang aman:

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

Menyediakan akses ke agen Agent Framework melalui A2A

Paket agent-framework-a2a menyediakan A2AExecutor dengan konvensi tertentu yang menyesuaikan agen Agent Framework apa pun ke protokol sisi server A2A. Menjalankan agen, memetakan konten keluaran yang didukung ke event dan artefak A2A, serta mengelola pembaruan status tugas melalui a2a-sdk resmi.

Aplikasi Anda merakit komponen server A2A SDK di sekitarnya: kartu agen, DefaultRequestHandler, penyimpanan tugas, rute atau pembuat aplikasi, autentikasi, dan penyebaran. Untuk perbandingan dengan adapter yang dimiliki aplikasi dan alat bantu konversi mandiri di agent-framework-hosting-a2a, lihat Meng-host sendiri agen A2A.

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 mengirimkan pembaruan agen secara streaming sebagai artefak A2A ketika agen yang mendasarinya mendukung streaming dan meneruskan A2A context_id sebagai session_id sesi agen. Anda dapat membuat subclass dari A2AExecutor dan meng-override metode handle_events untuk mengimplementasikan transformasi kustom dari format output agen Anda ke event protokol A2A.

Protokol A2A

Go Agent Framework mendukung hosting agen Agent Framework melalui protokol Agent-to-Agent (A2A) dengan provider/a2aprovider paket dan penangan server A2A Go resmi.

Instal paket Agent Framework dan A2A di modul Go Anda:

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

Meng-host agen melalui A2A

Buat atau gunakan kembali agen Agent Framework, jelaskan dengan kartu agen A2A, dan ekspos melalui salah satu pengikatan transportasi A2A. Dalam contoh ini, hostAgent dapat berupa Agent Framework *agent.Agent apa pun; server menyediakan endpoint JSON-RPC di / dan menyajikan kartu agen di jalur well-known 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))
}

Bungkus handler permintaan yang sama dengan a2asrv.NewRESTHandler ketika Anda ingin mengekspos pengikatan transportasi HTTP+JSON. Atur ExecutorConfig.AllowBackgroundResponses ke true jika agen yang dihosting harus diizinkan untuk mengembalikan tugas A2A untuk pekerjaan jangka panjang.

Lihat Juga

Langkah berikutnya

Protokol AG-UI

  • Last updated on