A2A ile konak aracıları

Aracıdan Aracıya (A2A) protokolü, farklı çerçeveler ve teknolojilerle oluşturulmuş aracılar arasında standartlaştırılmış iletişim sağlar. Bu sayfa, Aracı Çerçevesi aracılarını A2A sunucuları olarak ifşa etme konularını kapsar.

Uzak bir A2A aracısını bulmak ve çağırmak için bkz. A2A aracı hizmeti.

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

Uygulama bir Microsoft Foundry proje 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.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 geliştirme için uygundur ancak üretimde dikkatli bir şekilde dikkate alınması gerekir. Üretimde gecikme sorunları, istenmeyen kimlik bilgisi yoklama ve geri dönüş mekanizmalarından kaynaklanan olası güvenlik risklerini önlemek için belirli bir kimlik bilgisi (ör ManagedIdentityCredential. ) kullanmayı göz önünde bulundurun.

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 A2A protokolü üzerinden bir Agent Framework aracısını kullanıma sunar.

pip install agent-framework-a2a --pre

Güvenli uç noktayı test edin

Güvenli bir AuthInterceptor A2A uç noktasını doğrulamak için bir test istemcisinde 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!")

A2A üzerinden bir Agent Framework aracısını sunma

agent-framework-a2a paketi, herhangi bir Agent Framework aracısını A2A sunucu tarafı protokolüne uyarlayan, belirli tercihleri dayatan bir A2AExecutor sağlar. Aracıyı çalıştırır, desteklenen çıktı içeriğini A2A olaylarına ve artefaktlara eşler ve görev durumu güncelleştirmelerini resmî a2a-sdk aracılığıyla yönetir.

Uygulamanız çevresindeki A2A SDK sunucusunu bir araya getirmektedir: aracı kartı, DefaultRequestHandler, görev deposu, yollar veya uygulama oluşturucu, kimlik doğrulaması ve dağıtım. agent-framework-hosting-a2a içindeki uygulamaya ait adaptörler ve bağımsız dönüştürme yardımcılarıyla ilgili bir karşılaştırma için bkz. A2A aracılarını kendi ortamınızda barındırma.

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, temeldeki aracı akışı desteklediğinde aracı güncellemelerini A2A artefaktları olarak akış halinde iletir ve A2A context_id öğesini aracı oturumunun session_id öğesi olarak yayar. Aracınızın çıktı biçiminden A2A protokol olaylarına özel dönüşümler uygulamak için A2AExecutor sınıfından türetebilir ve handle_events yöntemini geçersiz kılabilirsiniz.

A2A Protokolü

Go Agent Framework, Agent Framework aracılarını Aracıdan Aracıya (A2A) protokolü aracılığıyla paket ve resmi A2A Go sunucu işleyicileri ile provider/a2aprovider barındırmayı destekler.

Go modülünüze Agent Framework ve A2A paketlerini yükleyin:

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

A2A aracılığıyla aracı barındırma

Bir Agent Framework agent’ı oluşturun veya yeniden kullanın, onu bir A2A agent kartı ile tanımlayın ve A2A taşıma bağlamalarından biri üzerinden kullanıma sunun. Bu örnekte, hostAgent herhangi bir Ajan Çerçevesi *agent.Agent olabilir; sunucu, / adresinde bir JSON-RPC uç noktası barındırır ve ajan kartını well-known A2A yolunda sunar.

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

HTTP+JSON taşıma bağlamasını kullanıma sunmak istediğinizde aynı istek işleyicisini a2asrv.NewRESTHandler ile sarın. Barındırılan aracının uzun süreli işler için A2A görevlerini döndürmesine izin verilecekse ExecutorConfig.AllowBackgroundResponses değerini true olarak ayarlayın.

Ayrıca Bkz

Sonraki Adımlar

AG-UI Protokolü

  • Last updated on