توصيل عامل متوفر عبر بروتوكول Agent2Agent (A2A)

بروتوكول Agent2Agent (A2A) هُوَ معيار مفتوح للاتصال والتعاون بين الوكلاء.

يمكنك توصيل العامل المخصص بعامل آخر يدعم بروتوكول A2A. يستخدم Copilot Studio بروتوكول A2A لإدارة العمليات مع هذا الوكيل استجابة لطلب المستخدم أو لتفعيل معين.

ما هو بروتوكول Agent2Agent (A2A)؟

يحدد بروتوكول Agent-to-Agent (A2A) عقدا قياسيا لاتصال العامل. وهو يمكن المنسق أو العامل من:

إرسال المهام إلى عوامل خارجية.
توفير بيانات تعريف غنية ومنظمة.
تلقي استجابات العامل بتنسيق يمكن التنبؤ به.

فيما يلي كيفية مقارنة بروتوكول A2A باتصال HTTP تقليدي للاتصال بين العوامل:

الميزة	بروتوكول A2A	موصل HTTP
مصمم لسير عمل العامل	✓	✗
يدعم التفاعلات متعددة المصطلحات	✓	✗
يوفر بيانات تعريف سياقية غنية	✓	محدود
متوافق عبر إطارات العمل	✓	يختلف

باستخدام A2A، يمكن Copilot Studio تفويض المهام إلى عامل آخر، وليس فقط استدعاء واجهات برمجة التطبيقات.

متى تستخدم اتصالات A2A

استخدم اتصال A2A عندما تريد دمج العوامل التي تنفذ بالفعل بروتوكول عامل إلى عامل. يعمل هذا النهج بشكل جيد مع الوكلاء الذين هم:

مبني على أطر عمل خارجية.
مستضاف خارج Copilot Studio.
مزودة بالاستدلال الخاص بمجال معين أو سير العمل الخاص بها.

استخدم أنماط التكامل البديلة عند الاقتضاء:

الحاجة إلى التكامل	النهج الموصى به
الاتصال بواجهات برمجة التطبيقات أو خدمات HTTP الأساسية	الموصلات المخصصة / أدوات HTTP
استخدام أدوات أو موارد MCP	خوادم MCP
دمج العوامل التي تم إنشاؤها مع Microsoft 365 Agents SDK	بروتوكول النشاط

يمكنك الجمع بين نماذج تكامل متعددة داخل نفس عامل Copilot Studio.

توصيل وكيلك بعامل آخر عبر بروتوكول A2A

انتقل إلى صفحة الوكلاء لوكيلك الرَّئِيسِيّ وحدد إضافة وكيل.
حدد الاتصال بعامل> خارجيAgent2Agent.
أدخل عنوان URL لنقطة النهاية لوكيل A2A. يجب أن يكون عنوان URL لنقطة النهاية نقطة النهاية للاتصال بٱلْعَامِلُ وليس عنوان URL لبطاقة ٱلْعَامِلُ.

بمجرد إدخال عنوان URL لنقطة النهاية، إذا كان لدى العامِل بطاقة عامل صالحة عَلَى عنوان URL القياسي .well-known ، فإن Copilot Studio يسحب تلقائيا الاسم والوصف للعامِل الخاص بك مِنْ البطاقة ويملأها فِي النموذج نيابة عنك.

إشعار

إذا لم يتم ملء الاسم والوصف تلقائيا لعامِلك، فمن المحتمل أن عامِلك ليس لديه بطاقة عامِل، أو أن البطاقة موجودة عَلَى عنوان URL مختلف عن العنوان المتوقع، أو أن هناك مشكلة فِي الاتصال بالبطاقة. أولا، تحقق مِنْ صحة نقطة نهاية عامِلك. إذا كان الأمر كذلك، يمكنك إدخال اسم ووصف مناسبين لعامل SDK يدويا. يجب أن يصف الوصف الغرض مِنْ العامِل الخاص بك، بحيث يمكن للعامِل الرئيسي فهم متى يجب استخدام ٱلْعَامِلُ الثاني. تعرف على المزيد حول كتابة بيانات تعريف فعالة. يمكنك أيضا محاولة الانتقال إلى بطاقة الوكيل في المستعرض (الموجودة في نقطة نهاية الوكيل + /.well-known/agent.json).
حدد أسلوب المصادقة المناسب، اعتمادا على كيفية تكوين عامل SDK الخاص بك، من القائمة المنسدلة Authentication . الخيارات هي:
- بلا: حدد هذا الخيار إذا كان العامل الخاص بك لا يتطلب مصادقة أو إذا كنت تستخدم نموذج العامل المتوفر في هذه الوثائق، والذي لم يتم تمكين المصادقة عليه.
- مفتاح واجهة برمجة التطبيقات: حدد هذا الخيار إذا كان العامل يتطلب مفتاح API للمصادقة. تحتاج إلى توفير اسم العنوان حيث يجب تضمين مفتاح API أو معلمة الاستعلام.
- OAuth 2.0: حدد هذا الخيار إذا كان وكيلك يستخدم OAuth 2.0 للمصادقة. تحتاج إلى توفير معرف العميل وسر العميل وعنوان URL للتخويل وعنوان URL للرمز المميز وعنوان URL للتحديث.
إذا قُمْت بتحديد نوع مصادقة آخر غير None، يجب عليك أيضا إكمال تفاصيل المصادقة الأخرى.
حدد إنشاء.
حدد الاتصال المطلوب مِنْ قائمة الاتصالات المتوفرة أو أنشئ اتصالا جديدا بين عامِل A2A وعامل Copilot Studio الخاص بك.
حدد إضافة وتكوين.

إشعار

أنت مسؤول عن مراجعة الوكلاء المتصلين واختبارهم بعناية في سياق حالات الاستخدام المحددة، واتخاذ جميع القرارات والتخصيصات المناسبة. عندما تتصل بوكلاء خارج Copilot Studio، فأنت مسؤول عن استخدام هؤلاء الوكلاء. وتشمل الاعتبارات ضمان ما يلي:

تدفقات البيانات ومعالجة البيانات ومشاركة البيانات بين الوكلاء مناسبة لحالة الاستخدام الخاصة بك وتلبي المتطلبات والقوانين ذات الصلة
يلبي الوكلاء معايير الجودة والموثوقية والأمان والثقة المناسبة
يتم توفير الأذونات والحدود والموافقات المناسبة، إذا كانت حكيمة لحالة الاستخدام الخاصة بك
إمكانية المراقبة والهوية والتتبع المناسبة ووظائف الرقابة البشرية متبعة

عينة اتصال A2A

في هذا التشغيل السريع، تقوم بتكوين وكيل مُمَكَّن لـ A2A وتوصله إلى وكيل Copilot Studio. عند إكمال الخطوات، يمكنك

قم بتشغيل وكيل A2A ممكّن محلياً أو استخدم وكيل A2A الموجود لديك بالفعل.
تعريض الوكيل بأمان عبر HTTPS باستخدام Dev Tunnels أو خيار استضافة آخر.
قم بتوصيل العامل الخارجي بعامل Copilot Studio من خلال اتصال A2A.
تحقق من صحة الاتصال عن طريق استدعاء الوكيل من Copilot Studio بمهمة لغة طبيعية مثل: "أي نبات يحتاج إلى مزيد من الضوء - نبات الطماطم أم نبات الفراولة؟"

بعد تكوين الاتصال، سترى:

اتصال A2A ناجح تم إنشاؤه من Copilot Studio.
سجلات النشاط من العامل الخارجي تؤكد استلامه للمهمة المفوضة ومعالجتها.
حمولة A2A الكاملة، بما في ذلك بيانات التعريف الأخرى التي ترسلها Copilot Studio مع كل طلب.

المتطلبات المسبقه

لاتباع السيناريو النموذجي، تحتاج إلى:

مورد Azure OpenAI يتضمن:
- عنوان URL لنقطة النهاية
- اسم التوزيع
- مفتاح واجهة برمجة التطبيقات
.NET 10 SDK أو أعلى
بيئة Copilot Studio مع أذونات ل:
- تحرير الوكلاء
- تكوين الاتصالات
طريقة لكشف العامل المحلي بشكل عام:
- أنفاق التطوير (مستحسن للتطوير)
- أو بيئة مستضافة مثل Azure App Service أو حاوية

إذا كان لديك بالفعل وكيل مُفعل لخاصية A2A، فانتقل إلى إقامة اتصال A2A في Copilot Studio.

الخطوة 1: استنساخ وتكوين نموذج عامل A2A

استنساخ نموذج مستودع عامل A2A:

git clone https://github.com/microsoft/CopilotStudioSamples.git
cd CopilotStudioSamples/extensibility/a2a/Simple-A2A-Sample

تعيين إعدادات Azure OpenAI المطلوبة:

AZURE_OPENAI_ENDPOINT: عنوان URL الخاص بنقطة نهاية Azure OpenAI
AZURE_OPENAI_DEPLOYMENT_NAME: اسم نشر Azure OpenAI
AZURE_OPENAI_API_KEY: مفتاح Azure OpenAI API

يمكنك تكوين هذه الإعدادات إما كمتغيرات بيئة أو عن طريق حفظها في appsettings.json أو appsettings.Development.json.

الخيار أ: تكوين كمتغيرات البيئة

$env:AZURE_OPENAI_ENDPOINT="https://YOUR-RESOURCE.openai.azure.com"
$env:AZURE_OPENAI_DEPLOYMENT_NAME="YOUR-DEPLOYMENT"
$env:AZURE_OPENAI_API_KEY="YOUR-KEY"

الخيار ب: التكوين في ملف appsettings.json

{  
    "AzureOpenAI": {    
        "Endpoint": "https://YOUR-RESOURCE.openai.azure.com",
        "DeploymentName": "YOUR-DEPLOYMENT",
        "ApiKey": "YOUR-KEY"  
    }
}

الخطوة 2: إنشاء العامل وتشغيله وكشفه

استعادة التبعيات وبنائها:

dotnet restore
dotnet build

تشغيل العميل:

dotnet run

تعرض وحدة التحكم عنوان URL المحلي لنقطة نهاية A2A.

كشف نقطة النهاية

إشعار

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

إذا كنت تستخدم Visual Studio Code وتخطط لعرض نقطة النهاية باستخدام Dev Tunnels، فكشف منفذ نفق تطوير جديد. اختر منفذ A2A المعروض في وحدة التحكم. انقر بزر الماوس الأيمن واجعل المنفذ عاما؛ وإلا، فلن يكون مرئيا عبر الإنترنت.

تمنحك أنفاق التطوير عنوان URL عاما، مثل: https://xyz123-9000.dev.tunnels.ms/. لاحظ عنوان URL هذا كنقطة نهاية أساسية حتى تتمكن من استخدامه عند تكوين اتصال A2A في Copilot Studio.

الخطوة 3: إنشاء اتصال A2A في Copilot Studio

بعد الوصول إلى عامل A2A بشكل عام، قم بإنشاء اتصال A2A داخل Copilot Studio.

افتح Copilot Studio وحدد الوكيل الأساسي.
حدد Agents.
حدد Add agent، ثم اختر A2A agent.
أدخل قيم التكوين المطلوبة:
- الاسم: اسم وصفي، مثل عامل نباتي.
- عنوان URL لنقطة النهاية: استخدم عنوان URL العام لنفق التطوير متبوعا بنقطة نهاية رسالة A2A، على سبيل المثال: https://xyz123-5073.dev.tunnels.ms/a2a/botanical/v1/message:stream
- المصادقة: حدد بلا إذا كنت تستخدم نموذج العامل (لم يتم فرض أي مصادقة).
حدد حفظ للتحقق من صحة الاتصال وإنشاءه.

عندما يكون التكوين صالحا، Copilot Studio يؤكد اتصال عامل A2A بنجاح.

نصيحة

نظرا لأن اتصالات A2A تستخدم البنية الأساسية للموصل المخصص، يمكنك أيضا استخدامها للاتصال بعوامل A2A التي تعمل محليا أو داخل شبكة ظاهرية.

الخطوة 4: إرسال مهمة من Copilot Studio إلى عامل A2A

بعد إنشاء الاتصال، تحقق من التكامل عن طريق إرسال مهمة.

افتح الوكيل الرئيسي في Copilot Studio وانتقل إلى لوحة Test.
أدخل نص توجيهي يجب تفويضه إلى وكيل A2A. على سبيل المثال: "ما هو النبات الذي يحتاج إلى مزيد من الضوء — نبات الطماطم أو نبات الفراولة؟"
يقوم منسق العامل بتقييم إدخال المستخدم وتفويض المهمة إلى عامل A2A.
يعالج العامل الخارجي الطلب ويعيد استجابة، والتي تظهر في دردشة الاختبار.

في سجلات العامل الخارجي، ترى:

تم تلقي مهمة A2A.
موجه اللغة الطبيعية
تم إرجاع الاستجابة التي تم إنشاؤها إلى Copilot Studio.

الخطوة 5: فحص الحمولة وبيانات التعريف A2A

تتضمن رسائل A2A بيانات تعريف منظمة توفر سياقا إضافيا. يمكن أن تساعد بيانات التعريف هذه العامل على تكييف الاستجابات أو إدارة التوجيه أو الحفاظ على الاستمرارية عبر عمليات تشغيل المستخدم.

تتضمن حمولة رسالة A2A النموذجية ما يلي:

فريد contextId
معرفات الرسائل
معلومات الإعدادات المحلية
محفوظات الدردشة الكاملة، وليس فقط أحدث تعبير للمستخدم
أجزاء محتوى الرسالة (نص أو مكالمات أداة أو بيانات تعريف أخرى)

مثال على مقتطف الحمولة:

{
"method": "message/send",
"params": {
 "message": {
   "contextId": "ee1e68ee-75fc-42bb-83d7-25fd26e559c3",
   "metadata": {
     "copilotstudio.microsoft.com/a2a/chathistory": [
       {
         "From": "agent",
         "Locale": "en-US",
         "Text": "Hello, I'm A2A Agent Demo...",
         "Timestamp": "2025-11-26T23:19:28.764Z"
       },
       {
         "From": "user",
         "Locale": "en-US",
         "Text": "Which plant needs more sunlight...",
         "Timestamp": "2025-11-26T23:20:21.484Z"
       }
     ]
   }
 }
}
}

يمكنك استخدام بيانات التعريف هذه لأي منطق تسلسلي ينفذه وكيل A2A.

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

بعد إنشاء اتصال A2A الأساسي، يمكنك:

أضف مهارات جديدة أو معرفة بالمجال إلى وكيل A2A الخاص بك.
استخدم بيانات التعريف من حمولة A2A لتنفيذ منطق التوجيه والتخصيص.
أضف المصادقة لتأمين نقطة نهاية A2A وتحديث إعدادات Copilot Studio وفقا لذلك.
قم بتوصيل العوامل الأخرى التي تدعم A2A باستخدام نفس نهج التكوين.

النقاط الموجزة الأساسية

يمكن Copilot Studio تنسيق العوامل الخارجية باستخدام بروتوكول A2A.
تمكن A2A من سير عمل متعددة الوكلاء مع بيانات تعريف سياقية غنية.
يوضح وكيل العينة الرحلة ذهابا وإيابا بالكامل: Copilot Studio -> وكيل A2A -> Copilot Studio.
تتضمن رسائل A2A بيانات تعريف مفصلة تدعم سلوك العامل المدرك للسياق.

الملاحظات

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

Last updated on 2026-04-22