Aracılığıyla paylaş

A2A Tümleştirmesi

Aracıdan Aracıya (A2A) protokolü aracılar arasında standartlaştırılmış iletişime olanak tanıyarak farklı çerçeveler ve teknolojilerle oluşturulmuş aracıların sorunsuz bir şekilde iletişim kurmasına olanak tanır.

A2A nedir?

A2A, şu desteği sağlayan standartlaştırılmış bir protokoldür:

  • Aracı kartları aracılığıyla aracı bulma
  • Aracılar arasında ileti tabanlı iletişim
  • Görevler aracılığıyla uzun süreli etken süreçler
  • Farklı ajan çerçeveleri arasında platformlar arası birlikte çalışabilirlik

Daha fazla bilgi için bkz. A2A protokol belirtimi.

Kitaplık, Microsoft.Agents.AI.Hosting.A2A.AspNetCore A2A protokolü aracılığıyla aracılarınızı kullanıma sunmak için ASP.NET Core tümleştirmesi sağlar.

NuGet Paketleri:

Example

Bu basit örnek, A2A aracılığıyla bir aracıyı nasıl kullanıma sunacağınızı gösterir. Örnek, testi basitleştirmek için OpenAPI ve Swagger bağımlılıklarını içerir.

1. ASP.NET Core Web API projesi oluşturma

Yeni bir ASP.NET Core Web API projesi oluşturun veya var olan bir projeyi kullanın.

2. Gerekli bağımlılıkları yükleme

Aşağıdaki paketleri yükleyin:

Gerekli NuGet paketlerini yüklemek için proje dizininizde aşağıdaki komutları çalıştırın:

# 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 bağlantısını yapılandırma

Uygulama bir Azure OpenAI bağlantısı gerektirir. veya ortam değişkenlerini kullanarak dotnet user-secrets uç nokta ve dağıtım adını yapılandırın. Ayrıca, yalnızca öğesini düzenleyebilirsiniz appsettings.json, ancak verilerin bir kısmı gizli olarak değerlendirilebileceği için üretimde dağıtılan uygulamalar için bu önerilmez.

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. Kodu Program.cs'ye ekleyin

öğesinin içeriğini Program.cs aşağıdaki kodla değiştirin ve uygulamayı çalıştırın:

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

Aracıyı Test Etme

Uygulama çalıştırıldıktan sonra aşağıdaki .http dosyayı kullanarak veya Swagger kullanıcı arabirimi aracılığıyla A2A aracısını test edebilirsiniz.

Giriş biçimi A2A belirtimiyle uyumlu. Aşağıdakiler için değerler sağlayabilirsiniz:

  • messageId - Bu özel ileti için benzersiz bir tanımlayıcı. Kendi kimliğinizi (örneğin, GUID) oluşturabilir veya null ayarlayarak aracının otomatik olarak bir kimlik oluşturmasına izin verebilirsiniz.
  • contextId - Konuşma tanımlayıcısı. Yeni bir konuşma başlatmak için kendi kimliğinizi belirtin veya önceki contextIdbir öğesini yeniden kullanarak var olan bir konuşmaya devam edin. Aracı, aynı contextId için konuşma geçmişini korur. Ajan, sağlanmadıysa sizin için de bir tane oluşturur.
# 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"
  }
}

Not: {{baseAddress}} ile sunucu uç noktanızı değiştirin.

Bu istek aşağıdaki JSON yanıtını döndürür:

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

Yanıtta contextId (konuşma tanımlayıcısı), messageId (ileti tanımlayıcısı) ve korsan ajanının gerçek içeriği yer alır.

AgentCard Yapılandırması

aracınız AgentCard hakkında bulma ve tümleştirme için meta veriler sağlar:

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

Aracı kartına şu isteği göndererek erişebilirsiniz:

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

Not: {{baseAddress}} ile sunucu uç noktanızı değiştirin.

AgentCard Özellikleri

  • Ad: Aracının görünen adı
  • Açıklama: Temsilcinin kısa açıklaması
  • Sürüm: Ajan için sürüm dizesi
  • Url: Uç nokta URL'si (belirtilmezse otomatik olarak atanır)
  • Özellikler: Akış, anında iletme bildirimleri ve diğer özellikler hakkında isteğe bağlı meta veriler

Birden Çok Aracıyı Açığa Çıkarma

Birbirleriyle çakışmadıkları sürece, tek bir uygulamada birden fazla aracı kullanıma sunabilirsiniz. Bir örnek aşağıda verilmiştir:

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, agent-framework-a2a harici A2A uyumlu aracılara bağlanmanızı ve onlarla iletişim kurmanızı sağlar.

pip install agent-framework-a2a --pre

A2A Aracısı'na bağlanma

Uzak A2A uç noktalarını sarmak için A2AAgent'yi kullanın. Aracı, uzak aracının özelliklerini AgentCard aracılığıyla çözer ve tüm protokol ayrıntılarını işler.

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

Akış Yanıtları

A2A doğal olarak Sunucu-Gönderimli Olaylar aracılığıyla akış desteği sunar. Uzak aracı çalıştığında güncellemeler gerçek zamanlı olarak gelir.

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

Uzun Süreli Görevler

Varsayılan olarak A2AAgent, geri dönmeden önce uzak aracı bitene kadar bekler. Uzun süreli görevler için, daha sonra yoklama yapabilmek veya yeniden abone olabilmek amacıyla kullanabileceğiniz bir devam belirtecini almak için background=True ile ayarlayın:

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

Güvenli A2A uç noktaları için bir AuthInterceptor kullanın:

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

Ayrıca Bkz.

Sonraki Adımlar

AG-UI Protokolü

  • Last updated on