إنشاء مثيلات العامل

بعد نشر العامل وإتاحته فِي مركز إدارة Microsoft، يمكنك إنشاء مثيلات للعامل ومستخدمي العامل. تستخدم هذه المثيلات والمستخدمون مخطط العامل ورمز العامل الذي أنشأته.

تقسم هذه المقالة العملية إلى ثلاث خطوات رئيسية:

1. تكوين العامل فِي مدخل مطوّري Teams
2. إنشاء مثيل عامل
3. اختبار العامل الذي تم نشره

إذا واجهت تحديات، راجع قسم استكشاف الأخطاء.

المتطلبات

• تم إعداد مخطط العامل بشكل صحيح كما هو موضح فِي خطوة إعداد مخطط العامل.
• تم نشر تطبيق عامل بشكل صحيح كما هو موضح فِي نشر عامل فِي مركز إدارة Microsoft.

1. تكوين العامل فِي مدخل مطوري Teams

بعد النشر، قم بتكوين مخطط عامل فِي بوابة مطوري Teams لربط عاملك بالبنية التحتية للرسائل فِي Microsoft 365. بدون هذا التكوين، لن يتلقى عاملُك رسائل مِنْ Teams أو البريد الإلكتروني أو خدمات Microsoft 365 الأخرى.

1. الحصول على معرّف مخطط العامل

   افتح a365.generated.config.json فِي مجلد العمل الخاص بك وانسخ قيمة agentBlueprintId.

2. الانتقال إلى مدخل المطوّرين

   افتح متصفحك واذهب إلى صفحة التكوين:

   https://dev.teams.microsoft.com/tools/agent-blueprint/<your-blueprint-id>/configuration
   

   استبدل <your-blueprint-id> بالقيمة agentBlueprintId التي نسختها.

   إشعار

   إذا لم يكن لديك حق الوصول إلى مدخل المطوّرين، فاتصل بمسؤول المستأجر لمنحك حق الوصول أو لإكمال هذا التكوين نيابةً عنك.

3. تكوين العامل

   في بوابة المطورين:

   1. عين نوع العامل الى API Based

   2. قم بتعيين عنوان URL للإشعارات إلى نقطة نهاية رسائل عاملِك. ابحث عن قيمة messagingEndpoint فِي a365.generated.config.json.

   3. حدد حفظ..

   

تحتاج إلى هذا التكوين قبل أن تتمكن مِنْ إنشاء مثيلات للعامل فِي Teams.

تعرّف على المزيد حول مخططات هوية العامل وتكوين مدخل المطوّرين..

2. إنشاء مثيل للعامل

الآن يمكنك طلب نسخة مِنْ مخطط عاملك مِنْ Teams. تعرّف على المزيد حول كيفية اكتشاف عامل وإنشائه وضمّه..

عند طلب مثيل للعامل، يرسل Teams الطلب إلى مسؤول المستأجر لديك للحصول على الموافقة. يمكن للمسؤولين مراجعة والموافقة على الطلبات مِنْ صفحة Microsoft admin center - العوامل المطلوبة.

بعد موافقة المسؤول على طلبك، ينشئ Teams مثيل العامل الخاص بك ويجعله متاحًا فِي Teams.

3. اختبار العامل الذي تم نشره

بعد إنشاء مثيل عامل، اختبره فِي Microsoft 365 للتأكد مِنْ أنه يعمل بشكل صحيح فِي بيئة الإنتاج.

بعد النشر، ومع تمكين إعلامات العامل فِي Agent 365 SDK، يتكامل العامل الخاص بك مع خدمات Microsoft 365. يعمل مع Teams للدردشات والقنوات والاجتماعات؛ ومع البريد الإلكتروني والتقويم للإرسال والاستلام والجدولة؛ ومع SharePoint وOneDrive للوصول إلى المستندات ومشاركة الملفات. كما يدعم أيضًا ميزات التعاون مثل الحضور التنظيمي ومهام Planner وتعليقات المستندات.

مهم

مثل المستخدمين العاديين تمامًا، يحتاج مستخدمو العاملين أيضًا إلى تراخيص Microsoft 365 المناسبة للوصول إلى الخدمات. تتضمن التراخيص الشائعة Microsoft 365 E5، وTeams Enterprise، وMicrosoft 365 Copilot.

عرض العامل المنشور في مركز الإدارة

بعد نشر العامل الخاص بك، يظهر فِي مركز إدارة Microsoft للتوظيف. قد يستغرق الأمر بعض الوقت حتى يتم نشره.

انتقل إلى ‏‫مركز إدارة Microsoft 365‬ - العوامل :

• عرض الوكيل المنشور
• إدارة إعدادات الوكيل
• مراقبة اِسْتِخْدَام العامل
• تكوين الأذونات

وكيل الاختبار في Teams

بعد نشر مخطط العامل وتكوينه وإنشاء مستخدم العامل، اختبر مستخدم العامل مباشرةً فِي Microsoft Teams:

بدء الاختبار

1. ابحث عن مستخدم العامل الجديد فِي Teams.

   إشعار

   تتم عملية إنشاء مستخدم عامل بشكل غير متزامن. قد يستغرق الأمر مِنْ بضع دقائق إلى ساعات حتى يصبح مستخدم العامل قابلاً للبحث بعد إنشائه.

2. ابدأ دردشة جديدة مع مثيل العامل الذي أنشأته حديثًا.

3. إرسال رسائل اختبار للتحقق مِنْ وظيفة العامل.

مثال على رسالة اختبار

إذا قمت بتكوين العامل بالبريد الإلكتروني، أرسل هذه الرسالة لاختبار وظيفة البريد الإلكتروني. قم بتحديث قيمة البريد الإلكتروني للمستلم recipient@contoso.com.

Send an email to <recipient@contoso.com> with subject "Hello from Teams" and message "This is a test message from my agent!"

يعالج العامل الطلب ويرسل البريد الإلكتروني دون الحاجة إلى مزيد مِنْ التأكيد.

قائمة التحقق

بعد إنشاء مثيل العامل، تحقق مِنْ أنه يعمل بشكل صحيح فِي Teams.

✅ تم حفظ تكوين مدخل المطوّرين
✅ يظهر العامل فِي بحث تطبيقات Teams
✅ يمكنك إنشاء مثيل عامل فِي Teams
✅ تم إنشاء مثيل العامل
✅ يظهر مستخدم العامل فِي المؤسسة
✅ يستجيب العامل للرسائل
✅ يمكن للعامل تنفيذ الإجراءات
✅ سجلات التطبيقات لا تظهر أي أخطاء
✅ المراقبة تعمل في مركز الإدارة

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

تحقق مِنْ حفظ تكوين مدخل المطوّرين.

الانتقال إلى: https://dev.teams.microsoft.com/tools/agent-blueprint/<your-blueprint-id>/configuration

✅ يُظهر حقل نوع العامل: API Based✅يتطابق عنوان URL للإعلامات ✅ مع نقطة نهاية المراسلة الخاصة بالعامل ✅ تظهر رسالة تم الحفظ بنجاح

تحقق مِنْ ظهور العامل فِي Teams

1. افتح تطبيق >Teams

2. ابحث عن اسم العامل الخاص بك.

   ✅ يظهر عامل فِي نتائج البحث. ✅ تظهر أيقونة عامل ووصفه.

التحقق من إمكانية إنشاء عامل مثيل للفرق

اختر عاملِك فِي تطبيقات Teams

✅ زر طلب مثيل/إنشاء مثيل مفعل.✅ يمكن طلب مثيل بدون أخطاء.

تحقق مِنْ إنشاء مثيل العامل.

بعد اختيار نسخة الطلب:

✅ تم إرسال الطلب بنجاح إلى المسؤول

تحقق مِنْ ظهور مستخدم العامل فِي المؤسسة.

في مركز إدارة Microsoft 365:

1. انتقل إلى: https://admin.cloud.microsoft/#/agents/all.
2. انتقل إلى تبويب طلبات جميع العوامل

✅ يتم إدراج طلب مثيل العامل الخاص بك مع الحالة "قيد المراجعة" ✅ يمكن للمسؤول الموافقة على مثيل العامل للاستخدام ✅ يمكن للمستخدم إنشاء مثيل مِنْ Teams وتعيين اسم له.

تحقق مِنْ أن العامل يستجيب للرسائل

في دردشة Teams مع عاملِك - أرسل رسالة اختبار: Hello!

✅ يظهر عامل مؤشر الكتابة ✅ يرد عامل خلال بضع ثوانٍ ✅ رد متماسك وذو صلة

تأكد مِنْ أن عامل يمكنه تنفيذ الإجراءات

إذا قمت بتكوين الأدوات، اختبر وظائف الأدوات. على سبيل المثال، إذا أضفت خادم Mail MCP، أرسل بريدا إلكترونيا اختباريا لنفسك.

على عامل أن يقوم بما يلي:

✅ تأكيد الطلب ✅ تنفيذ استدعاء الأداة ✅ تأكيد الإكمال بنجاح

تأكد مِنْ وصول البريد الإلكتروني إلى صندوق الوارد لديك.

تحقق من الوظائف

توفر قائمة التحقق التالية طريقة منهجية لاختبار عاملِك:

الوظائف الأساسية:

✅ يرد عامل على التحيات البسيطة. ✅ عامل يتعامل مع المحادثات متعددة الخطوات. ✅ يقدم العامل ردودًا ذات صلة.

وظائف الأداة:

يعتمد ذلك على تكوين خادم MCP

✅ يمكن إرسال البريد الإلكتروني. ✅ يمكن الوصول إلى التقويم. ✅ يمكن البحث فِي المستندات. ✅ يمكن تنفيذ الإجراءات المحددة.

معالجة الخطأ:

✅ يتعامل مع الطلبات غير الصحيحة بسلاسة. ✅ يوفر رسائل خطأ مفيدة. ✅ لا يتعطل عند إدخال بيانات غير متوقعة.

الأداء:

✅ يرد خلال ثوان قليلة ✅ لا توجد أخطاء تجاوز المهلة. ✅ أوقات استجابة ثابتة.

تحقق مِنْ سجلات التطبيقات

لمعرفة ما يفعله عاملك، تحقق مِنْ سجلات التطبيقات باستخدام أمر log tail مِنْ az webapp.

# Real-time logs from Azure
az webapp log tail --name <your-web-app> --resource-group <your-resource-group>

ما الذي يجب البحث عنه فِي السجلات:

✅ الطلبات الواردة مِنْ Teams ✅ المصادقة الناجحة ✅ تنفيذ استدعاءات الأدوات ✅ إرسال الاستجابات ❌ رسائل الخطأ أو الاستثناءات

تحقق مِنْ إمكانية المراقبة فِي مركز الإدارة.

بعد أن يبدأ عاملِك فِي التشغيل:

1. انتقل إلى: https://admin.cloud.microsoft/#/agents/all.

2. حدد عاملِك وافتح علامة تبويب النشاط.

   يجب أن تشاهد:

   ✅ الجلسات قيد الظهور. ✅ كل جلسة تعرض مشغلات والأفعال. ✅يتم تسجيل استدعاءات الأدوات مع الطوابع الزمنية.

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

أصبح عاملك الآن فِي السحابة وجاهزا للعمل جنبا إلى جنب مع فرقك فِي Microsoft 365. ما بدأ كرمز محلي أصبح الآن مساعدًا مسجلاً وجاهزًا للاستخدام المؤسسي، حيث يمكن للمستخدمين إنشاء نسخ مِنْ العامل فِي جميع أنحاء مؤسستك.

لقد اكتملت دورة تطوير عاملك، لكن تأثيره بدأ للتو. معظم ما قمت ببنائه فِي دورة حياة مطوري Agent 365 هو مفتوح المصدر ويرحب بمساهمات المجتمع. أبلغ عن الأخطاء، واطلب الميزات، وقدم طلبات السحب:

• عينات Agent 365:هل لديك بعض نماذج العوامل المثيرة للاهتمام والممتعة؟ شارك رمز العامل الخاص بك مع مجتمع المصادر المفتوحة هنا!
• Node.js SDKAgent 365 SDK فِي Node.js.
• Python SDK: Agent 365 SDK فِي Python.
• .NET SDK: Agent 365 SDK فِي C# (.NET).
• Agent 365 DevTools CLI: أداة CLI لمساعدتك خلال دورة حياة تطوير Agent 365 بالكامل.

استكشاف الأخطاء وإصلاحها

يحتوي هذا القسم على المشكلات الشائعة عند إنشاء مثيلات العامل واختبارها.

تلميح

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

لا يظهر عامل في Teams

العرض: يظهر عامل فِي مركز الإدارة لكن لا يمكنك العثور عليه فِي تطبيقات Teams.

السبب الجذري: غياب تكوين بوابة المطورين.

الحل:

1. احصل على معرف المخطط مِنْ a365.generated.config.json — ابحث عن agentBlueprintId.

2. قم بالتكوين فِي بوابة المطورين:

   1. انتقل إلى: https://dev.teams.microsoft.com/tools/agent-blueprint/<your-blueprint-id>/configuration.

   2. عين نوع العامل الى API Based

   3. قم بتعيين عنوان URL للإشعارات إلى نقطة نهاية رسائل عاملِك. ابحث عن قيمة messagingEndpoint فِي a365.generated.config.json.

   4. حدد حفظ..

3. انتظر مِنْ 5 إلى 10 دقائق حتى يكتمل النشر.

التحقق:

• افتح تطبيقات Teams > وابحث > عن عاملك.
• يظهر عامل وهو متاح للإضافة.

لا يمكن إنشاء نسخة عامل في Teams

العَرَض: يظهر عامل فِي Teams ولكن لا يمكنك إضافة أو إنشاء مثيل؛ زر طلب المثيل لا يعمل.

السبب الجذري: Microsoft Agent 365 Frontier غير مفعل للمستأجر.

الحل: تواصل مع مسؤول المستأجر الخاص بك للتحقق مِنْ تفعيل Microsoft Agent 365 Frontier للمستأجر.

تعرّف على المزيد حول Frontier..

التحقق:

تظهر ميزات Frontier داخل تطبيقات Microsoft 365 Copilot وMicrosoft 365 بمجرد أن تسمح إعدادات الترخيص والمسؤول بذلك.

عدم استجابة العامل للرسائل

العَرَض: تقوم بإنشاء مثيل عامل لكنه لا يستجيب للرسائل. لا توجد سجلات فِي التطبيق.

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

استكشاف الأخطاء وإصلاحها

1. تأكد مِنْ أن تطبيق الويب يعمل:

   az webapp show --name <your-app-name> --resource-group <your-resource-group> --query state
   # Should be: "Running"
   

2. تأكد مِنْ نقطة نهاية المراسلة:

   • يجب أن يكون: https://<your-app-root-url>/api/messages
   • تحقق مِنْ ذلك فِي a365.config.json و a365.generated.config.json

3. اختبر نقطة النهاية مباشرة:

   curl https://<your-app-root-url>/api/messages
   # Should not return 404
   

4. تحقق مِنْ سجلات التقديم:

   az webapp log tail --name <your-app-name> --resource-group <your-resource-group>
   # Look for incoming requests and errors
   

التشخيصات المتقدمة

1. تحقق من المصادقة:

   • تحقق مِنْ انتهاء صلاحية الرموز جددها إذا لزم الأمر.
   • تحقق مِنْ بيانات الاعتماد فِي إعدادات تطبيق الويب.

2. تحقق مِنْ تكوين الأداة/خادم MCP.:

   • تحقق مِنْ تكوين خوادم MCP.
   • تحقق مِنْ منح الصلاحيات

3. اختبر محلياً:

   • شغل العامل محليًا بنفس التكوين.
   • اختبر باستخدام Agents Playground.
   • إذا كان يعمل محليًا ولكن يواجه مشكلة في > التوزيع السحابي.

الحلول الشائعة

• نقطة نهاية المراسلة غير صحيحة: قم بتحديثها فِي بوابة Azure وبوابة المطورين.
• توقف تطبيق الويب: ابدأه باستخدام Azure portal أو CLI.
• رمز مميز منتهي الصلاحية: حدّث الرموز المميزة فِي متغيرات بيئة تطبيق الويب.
• متغيرات البيئة المفقودة: تحقق مِنْ إعدادات التطبيق فِي بوابة Azure.
• مشاكل خادم MCP: تحقق مِنْ كيان الخدمة والأذونات.
• أخطاء التعليمة البرمجية: تحقق مِنْ سجلات التطبيقات بحثًا عن استثناءات.

التحقق من الصحة

أرسل رسالة إلى العامل الخاص بك فِي Teams وتحقق مِنْ سجلات التطبيق للطلبات الواردة.

يمكنك أيضًا تجربة:

• استكشاف الأخطاء وإصلاحها المتعلقة بنشر عامل إلى خدمات ويب Amazon
• استكشاف الأخطاء المتعلقة بنشر عامل على Google Cloud Platform

فشل استدعاءات الأدوات

العرض: عامل يرد على الرسائل، لكن استدعاءات الأدوات لا تعمل. ترى أخطاء رفض الإذن أو انتهاء الوقت.

السبب الجذري: صلاحيات خادم MCP مفقودة، أو مبدأ الخدمة غير مكون، أو مشاكل فِي الاتصال بالشبكة، أو تكوين أداة غير صحيح.

الحلول

جرب الحلول التالية عند فشل استدعاءات الأدوات:

• تحقق مِنْ الأذونات فِي مركز الإدارة

  مراجعة وموافقة على صلاحيات خادم MCP المطلوبة:

  • انتقل إلى: https://admin.cloud.microsoft/#/agents/all.
  • حدد عاملِك > الأذونات
  • تأكد مِنْ أن القائمة تتضمن وتوافق على خوادم MCP المطلوبة

• التحقق من أساس الخدمة

  شغّل برنامج الإعداد النصي لمرة واحدة إذا لم تكن قد شغّلته مِنْ قبل:

  # Download and run:
  # https://github.com/microsoft/Agent365-devTools/blob/main/scripts/cli/Auth/New-Agent365ToolsServicePrincipalProdPublic.ps1
  

• تحقق مِنْ تكوين نقطة نهاية MCP.

  تأكد مِنْ أنك تستخدم نقطة نهاية MCP الإنتاجية:

  # Should be production endpoint, not mock
  MCP_PLATFORM_ENDPOINT=https://agent365.svc.cloud.microsoft
  

• تحقق مِنْ الهوية المُدارة

  تحقق مِنْ تمكين الهوية المُدارة فِي تطبيق الويب الخاص بك:

  # Verify managed identity is enabled
  az webapp identity show --name <your-app-name> --resource-group <your-resource-group>
  

التحقق من الصحة

اختبر استدعاءات الأدوات عبر Teams وتحقق مِنْ السجلات للتأكد مِنْ نجاح التنفيذ.

يمكنك أيضًا اتباع هذه الخطوات:

• أدوات استكشاف الأخطاء وإصلاحها
• خادم أدوات المحاكاة

فشل تعيين الترخيص

العرض: لا يمكنك تعيين ترخيص لمستخدم عامل. تظهر أخطاء الترخيص فِي مركز الإدارة.

السبب الجذري: عدم توفر عدد كافٍ مِنْ التراخيص، أو نوع ترخيص غير صحيح، أو مشكلة فِي الأذونات.

الحلول

جرّب الحلول التالية عندما يفشل تعيين الترخيص:

1. تحقق مِنْ توفر التراخيص:

   • تحقق مِنْ مركز إدارة Microsoft 365 >الفوترة>التراخيص.
   • تأكد مِنْ تفعيل Microsoft Agent 365 Frontier للمستأجر.

2. تعيين الترخيص يدويًا:

   • انتقل إلى مركز إدارة Microsoft 365. >المستخدمين.
   • ابحث عن مستخدم العامل.
   • قم بتعيين الترخيص المناسب.

3. التراخيص المطلوبة لكامل الوظائف:

   • Microsoft 365 E5 (أو ما يعادله).
   • Teams Enterprise.
   • Microsoft 365 Copilot (للحصول على ميزات Copilot).

التحقق من الصحة

تحقق مِنْ أن ملف تعريف المستخدم فِي مركز الإدارة يعرض التراخيص المعينة.