وكلاء المضيف مع A2A

يتيح بروتوكول عامل إلى وكيل (A2A) اتصالا موحدا بين الوكلاء المبنيين بأطر وتقنيات مختلفة. تغطي هذه الصفحة الكشف عن عوامل إطار عمل العامل كخوادم A2A.

لاكتشاف واستدعاء عامل A2A بعيد، راجع خدمة عامل A2A.

ما هو A2A؟

A2A هو بروتوكول موحد يدعم:

  • اكتشاف العامل من خلال بطاقات الوكيل
  • الاتصال المستند إلى الرسائل بين الوكلاء
  • العمليات الوكيلة طويلة الأمد عبر المهام
  • إمكانية التشغيل التفاعلي عبر الأنظمة الأساسية بين أطر عمل الوكلاء المختلفة

لمزيد من المعلومات، راجع مواصفات بروتوكول A2A.

Microsoft.Agents.AI.Hosting.A2A.AspNetCore توفر المكتبة تكاملا ASP.NET Core لكشف وكلاءك عبر بروتوكول A2A.

حزم NuGet:

Example

يوضح هذا المثال الأدنى كيفية كشف عامل عبر A2A. تتضمن العينة تبعيات OpenAPI وSwagger لتبسيط الاختبار.

1. إنشاء مشروع واجهة برمجة تطبيقات ويب ASP.NET Core

إنشاء مشروع جديد ASP.NET Core Web API أو استخدام مشروع موجود.

2. تثبيت التبعيات المطلوبة

تثبيت الحزم التالية:

قم بتشغيل الأوامر التالية في دليل المشروع لتثبيت حزم 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. تكوين اتصال Microsoft Foundry

يتطلب التطبيق اتصال مشروع Microsoft Foundry. تكوين نقطة النهاية واسم النشر باستخدام dotnet user-secrets أو متغيرات البيئة. يمكنك أيضا ببساطة تحرير appsettings.json، ولكن هذا غير مستحسن للتطبيقات المنشورة في الإنتاج حيث يمكن اعتبار بعض البيانات سرية.

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. إضافة التعليمات البرمجية إلى Program.cs

استبدل محتويات بالتعليمات Program.cs البرمجية التالية وقم بتشغيل التطبيق:

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

تحذير

DefaultAzureCredential مناسب للتنمية ولكنه يتطلب دراسة متأنية في الإنتاج. في الإنتاج، ضع في اعتبارك استخدام بيانات اعتماد محددة (على سبيل المثال، ManagedIdentityCredential) لتجنب مشكلات زمن الانتقال، وبحث بيانات الاعتماد غير المقصودة، والمخاطر الأمنية المحتملة من الآليات الاحتياطية.

اختبار العامل

بمجرد تشغيل التطبيق، يمكنك اختبار عامل A2A باستخدام الملف التالي .http أو من خلال واجهة مستخدم Swagger.

يتوافق تنسيق الإدخال مع مواصفات A2A. يمكنك توفير قيم ل:

  • messageId - معرف فريد لهذه الرسالة المحددة. يمكنك إنشاء معرفك الخاص (على سبيل المثال، GUID) أو تعيينه للسماح null للعامل بإنشاء واحد تلقائيا.
  • contextId - معرف المحادثة. قم بتوفير المعرف الخاص بك لبدء محادثة جديدة أو متابعة محادثة موجودة عن طريق إعادة استخدام محادثة سابقة contextId. سيحتفظ العامل بمحفوظات المحادثات لنفس contextId. سيقوم العامل بإنشاء واحد لك أيضا، إذا لم يتم توفير أي منها.
# 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"
  }
}

ملاحظة: استبدل {{baseAddress}} بنقطة نهاية الخادم.

يقوم هذا الطلب بإرجاع استجابة 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"
}

تتضمن الاستجابة contextId (معرف المحادثة) messageId و(معرف الرسالة) والمحتوى الفعلي من عامل القراصنة.

تكوين بطاقة العامل

يوفر AgentCard بيانات تعريف حول وكيلك للاكتشاف والتكامل:

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

يمكنك الوصول إلى بطاقة العامل عن طريق إرسال هذا الطلب:

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

ملاحظة: استبدل {{baseAddress}} بنقطة نهاية الخادم.

خصائص بطاقة العامل

  • الاسم: الاسم المعروض للعامل
  • الوصف: وصف موجز للعامل
  • الإصدار: سلسلة الإصدار للعامل
  • Url: عنوان URL لنقطة النهاية (يتم تعيينه تلقائيا إذا لم يتم تحديده)
  • القدرات: بيانات تعريف اختيارية حول الدفق والإعلامات المؤقتة والميزات الأخرى

كشف عوامل متعددة

يمكنك عرض عوامل متعددة في تطبيق واحد، طالما أن نقاط النهاية الخاصة بهم لا تتصادم. إليك مثال:

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

agent-framework-a2a تعرض الحزمة عامل إطار عمل العامل عبر بروتوكول A2A.

pip install agent-framework-a2a --pre

اختبار نقطة نهاية آمنة

AuthInterceptor استخدم في عميل اختبار للتحقق من نقطة نهاية A2A آمنة:

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

agent-framework-a2a توفر الحزمة رأيا A2AExecutor يتكيف مع أي عامل إطار عمل عامل مع بروتوكول A2A من جانب الخادم. يقوم بتشغيل العامل، وتعيين محتوى الإخراج المدعوم لأحداث A2A والبيانات الاصطناعية، وإدارة تحديثات حالة المهمة من خلال المسؤول a2a-sdk.

يقوم تطبيقك بتجميع خادم A2A SDK المحيط: بطاقة العامل ومخزن DefaultRequestHandlerالمهام والمسارات أو منشئ التطبيق والمصادقة والنشر. للمقارنة مع المحولات المملوكة للتطبيق ومساعدي التحويل المستقلين في agent-framework-hosting-a2a، راجع عوامل 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 يبث تحديثات العامل كعناصر A2A عندما يدعم العامل الأساسي الدفق وينشر A2A context_id كجلسة session_idالعامل . يمكنك الفئة A2AExecutor الفرعية handle_events وتجاوز الأسلوب لتنفيذ تحويلات مخصصة من تنسيق إخراج العامل إلى أحداث بروتوكول A2A.

بروتوكول A2A

يدعم Go Agent Framework استضافة عوامل إطار عمل العامل من خلال بروتوكول عامل إلى وكيل (A2A) مع الحزمة provider/a2aprovider ومعالجات خادم A2A Go الرسمية.

تثبيت حزم إطار عمل العامل وA2A في الوحدة النمطية Go:

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

استضافة وكيل عبر A2A

إنشاء عامل إطار عمل عامل أو إعادة استخدامه، ووصفه باستخدام بطاقة عامل A2A، وعرضه من خلال أحد روابط النقل A2A. في هذا المثال، hostAgent هو أي إطار عمل *agent.Agentعامل ؛ يستضيف الخادم نقطة نهاية JSON-RPC في / ويخدم بطاقة العامل في مسار 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))
}

قم بتضمين معالج الطلب نفسه مع a2asrv.NewRESTHandler عندما تريد عرض ربط نقل HTTP+JSON. اضبط ExecutorConfig.AllowBackgroundResponses على true إذا كان يجب السماح للعامل المستضاف بإرجاع مهام A2A للعمل طويل الأمد.

انظر أيضاً

الخطوات التالية

بروتوكولAG-UI

  • Last updated on