استضافة A2A

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

حزم NuGet:

Microsoft. Agents.AI.Hosting.A2A.AspNetCore - ASP.NET Core تعيين نقطة النهاية لروابط بروتوكول A2A. تتضمن Microsoft.Agents.AI.Hosting.A2Aهذه الحزمة بشكل عابر .
Microsoft. Agents.AI.Hosting.A2A - منطق الاستضافة الأساسية لربط وكلاء الذكاء الاصطناعي ببروتوكول A2A (تسجيل الخادم، معالجة الطلب، إدارة الجلسة).

الشروع في العمل

تثبيت حزمة استضافة ASP.NET Core (تسحب في الحزمة الأساسية تلقائيا):

dotnet add package Microsoft.Agents.AI.Hosting.A2A.AspNetCore --prerelease
dotnet add package A2A.AspNetCore --prerelease
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI.Foundry --prerelease

يوضح المثال التالي تطبيق ASP.NET Core الحد الأدنى الذي يستضيف وكيلا واحدا عبر A2A. ويستخدم Microsoft Foundry كموفر الذكاء الاصطناعي - راجع موفري الخدمات للحصول على خيارات أخرى.

using A2A;
using A2A.AspNetCore;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

string endpoint = builder.Configuration["AZURE_AI_PROJECT_ENDPOINT"]
    ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
string model = builder.Configuration["AZURE_AI_MODEL"] ?? "gpt-4o-mini";

// 1. Create and register the "weather-agent" agent in the DI container.
builder.Services.AddKeyedSingleton<AIAgent>("weather-agent", (sp, _) =>
{
    return new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
        .AsAIAgent(
            model: model,
            instructions: "You are a helpful weather assistant.",
            name: "weather-agent");
});

// 2. Register the A2A server for the "weather-agent" agent.
builder.AddA2AServer("weather-agent");

var app = builder.Build();

// 3. Map A2A protocol endpoints for the "weather-agent" agent.
app.MapA2AHttpJson("weather-agent", "/a2a/weather-agent");

// 4. Serve a minimal agent card for the "weather-agent" agent discovery.
app.MapWellKnownAgentCard(new AgentCard
{
    Name = "WeatherAgent",
    Description = "A helpful weather assistant.",
    SupportedInterfaces =
    [
        new AgentInterface
        {
            Url = "http://localhost:5000/a2a/weather-agent",
            ProtocolBinding = ProtocolBindingNames.HttpJson,
            ProtocolVersion = "1.0",
        }
    ]
});

app.Run();

يمكن الوصول إلى العامل الآن عبر /a2a/weather-agent ربط بروتوكول A2A HTTP+JSON، ويمكن اكتشاف بطاقة العامل الخاصة به في /.well-known/agent.json. يمكن لأي عميل متوافق مع A2A اكتشاف هذا العامل والتواصل معه.

روابط البروتوكول

يحدد بروتوكول A2A ربطي نقل. كلاهما مدعوم:

Binding	الاسلوب	Description
HTTP+JSON	`MapA2AHttpJson`	طلبات HTTP القياسية وأحداث Server-Sent للبث.
JSON-RPC	`MapA2AJsonRpc`	JSON-RPC 2.0 عبر HTTP.

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

app.MapA2AHttpJson("weather-agent", "/a2a/weather-agent");  // HTTP+JSON
app.MapA2AJsonRpc("weather-agent", "/a2a/weather-agent");   // JSON-RPC

بطاقة العامل

تصف بطاقات العامل بيانات تعريف الوكيل - الاسم والوصف والإصدار والواجهات المدعومة - حتى يتمكن العملاء من اكتشاف قدراته وفهمها قبل إرسال الطلبات. يعرض قسم بدء الاستخدام الحد الأدنى من بطاقة العامل. لاستخدام الإنتاج، قم بتوفير بطاقة مملوءة بالكامل:

using A2A;
using A2A.AspNetCore;

app.MapWellKnownAgentCard(new AgentCard
{
    Name = "WeatherAgent",
    Description = "A helpful weather assistant.",
    Version = "1.0",
    DefaultInputModes = ["text"],
    DefaultOutputModes = ["text"],
    SupportedInterfaces =
    [
        new AgentInterface
        {
            Url = "http://localhost:5000/a2a/weather-agent",
            ProtocolBinding = ProtocolBindingNames.HttpJson,
            ProtocolVersion = "1.0",
        }
    ]
});

Note

MapWellKnownAgentCard يتم توفيرها بواسطة حزمة A2A SDK (A2A.AspNetCore)، وليس حزم استضافة إطار عمل العامل.

Tip

يمكن تقديم بطاقة عامل واحدة فقط لكل مضيف، لذلك يمكن اكتشاف عامل واحد فقط عبر المسار المعروف. لا يزال من الممكن الوصول إلى الوكلاء الآخرين مباشرة عن طريق عنوان URL. راجع اكتشاف العامل لمزيد من الخيارات.

كيف `AddA2AServer` يعمل

يسجل AddA2AServer الأسلوب قاعدة بيانات أحادية ذات A2AServer مفتاح في حاوية حقن التبعية. عند إنشاء الخادم، فإنه يحل أو ينشئ عدة مكونات داخلية:

المكون	Default	الغرض
`IAgentHandler`	`A2AAgentHandler`	الجسور الواردة طلبات A2A إلى `AIAgent`. يترجم الرسائل، ويشغل العامل، ويعيد الاستجابات كرسائل A2A.
`AgentSessionStore`	`InMemoryAgentSessionStore`	يخزن جلسات المحادثة حتى يتمكن العامل من الحفاظ على السياق عبر طلبات متعددة بنفس `contextId`.
`ITaskStore`	`InMemoryTaskStore`	يتعقب حالة المهمة لعمليات A2A طويلة الأمد.
`AgentRunMode`	`DisallowBackground`	يتحكم في ما إذا كان يمكن للعامل إرجاع استجابات الخلفية (مهام A2A) بدلا من الرسائل الفورية.

تحذير

الإعداد الافتراضي InMemoryAgentSessionStore و InMemoryTaskStore مخصص للتطوير فقط. يتم فقدان الحالة عند إعادة تشغيل التطبيق ولا تتم مشاركتها عبر مثيلات متعددة. بالنسبة إلى عمليات نشر الإنتاج، قم بتسجيل عمليات التنفيذ الدائمة.

تجاوز الإعدادات الافتراضية

يمكنك استبدال أي من هذه المكونات عن طريق تسجيل الخدمات الرئيسية في حاوية DI قبل استدعاء AddA2AServer. يحل الخادم الخدمات الرئيسية باستخدام اسم العامل كمفتاح.

مخزن جلسة عمل مخصص - لتخزين المحادثات المستمرة:

builder.Services.AddKeyedSingleton<AgentSessionStore>("weather-agent", new MyDurableSessionStore());

builder.AddA2AServer("weather-agent");

مخزن مهام مخصص - لتعقب المهام الدائمة:

builder.Services.AddKeyedSingleton<ITaskStore>("weather-agent", new MyDurableTaskStore());

builder.AddA2AServer("weather-agent");

معالج عامل مخصص - للتحكم الكامل في معالجة الطلب. عند تسجيل مفتاح IAgentHandler ، فإنه يحل محل الافتراضي A2AAgentHandler بالكامل:

builder.Services.AddKeyedSingleton<IAgentHandler>("weather-agent", new MyCustomHandler());

builder.AddA2AServer("weather-agent");

وضع تشغيل العامل - تكوين عبر A2AServerRegistrationOptions:

builder.AddA2AServer("weather-agent", options =>
{
    options.AgentRunMode = AgentRunMode.DisallowBackground;
});

عوامل متعددة

يمكنك استضافة عوامل متعددة في تطبيق واحد. يحصل كل عامل على خادم A2A الخاص به ونقطة النهاية الخاصة به:

// Register agents in DI.
builder.Services.AddKeyedSingleton<AIAgent>("weather-agent", (sp, _) =>
{
    return new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
        .AsAIAgent(model: model, instructions: "You are a helpful weather assistant.", name: "weather-agent");
});

builder.Services.AddKeyedSingleton<AIAgent>("scientist", (sp, _) =>
{
    return new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
        .AsAIAgent(model: model, instructions: "You are a scientist.", name: "scientist");
});

// Register A2A servers.
builder.AddA2AServer("weather-agent");
builder.AddA2AServer("scientist");

var app = builder.Build();

// Map endpoints.
app.MapA2AHttpJson("weather-agent", "/a2a/weather-agent");
app.MapA2AHttpJson("scientist", "/a2a/scientist");

app.Run();

في هذا المثال، لا يملك أي عامل بطاقة عامل، لذلك يجب أن يعرف العملاء عناوين URL لنقطة النهاية مباشرة. يمكنك إضافة اكتشاف بطاقة العامل باستخدام MapWellKnownAgentCard، ولكن يمكن الإعلان عن وكيل واحد فقط لكل مضيف - راجع بطاقة العامل.

استجابات الخلفية

Note

استجابات الخلفية غير مدعومة حتى الآن للوكلاء المستضافين على A2A. AgentRunMode الإعدادات الافتراضية ل DisallowBackground، ما يعني أنه يتم إرجاع جميع الاستجابات كرسائل A2A فورية.

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

خدمة عامل A2A

(راجع أيضًا)

الملاحظات

هل كانت هذه الصفحة مفيدة؟

Last updated on 2026-08-25