Bagikan melalui

Integrasi A2A

Protokol Agent-to-Agent (A2A) memungkinkan komunikasi standar antar agen, memungkinkan agen yang dibangun dengan kerangka kerja dan teknologi yang berbeda untuk berkomunikasi dengan mulus.

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:

Contoh

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 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. Mengonfigurasi koneksi Azure OpenAI

Aplikasi ini memerlukan koneksi Azure OpenAI. 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.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();

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 ini agent-framework-a2a memungkinkan Anda terhubung dan berkomunikasi dengan agen eksternal yang mematuhi A2A.

pip install agent-framework-a2a --pre

Menyambungkan ke Agen A2A

Gunakan A2AAgent untuk membungkus titik akhir A2A jarak jauh apa pun. Agen menyelesaikan kemampuan agen jarak jauh melalui AgentCard-nya dan menangani semua detail protokol.

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

Respons yang Mengalir

A2A secara alami mendukung streaming melalui Server-Sent Events — pembaruan tiba secara real time saat agen jarak jauh bekerja:

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

Tugas Berjalan Lama

Secara default, A2AAgent menunggu agen jarak jauh selesai sebelum kembali. Untuk tugas yang berjalan lama, atur background=True untuk mendapatkan token kelanjutan yang dapat Anda gunakan untuk melakukan polling atau berlangganan ulang nanti:

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)

Authentication

Gunakan sebuah AuthInterceptor untuk 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!")

Lihat Juga

Langkah selanjutnya

Protokol AG-UI

  • Last updated on