إنشاء مثيلات وكيل

هام

يجب أن تكون جزءًا من برنامج الإصدار الأولي Frontier للحصول على وصول مبكر إلى Microsoft Agent 365. Frontier تربطك مباشرة بأحدث ابتكارات الذكاء الاصطناعي من Microsoft. تخضع المعاينات الحدودية لشروط المعاينة الحالية لاتفاقيات العملاء. نظرًا لأن هذه الميزات لا تزال قيد التطوير، فقد يتغير توفرها وقدراتها بمرور الوقت.

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

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

1. تهيئة الوكيل في بوابة مطوري Teams
2. إنشاء نسخة وكيل
3. اختبر وكيل النشر الخاص بك

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

المتطلبات الأساسية

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

1. تكوين الوكيل في بوابة مطوري Teams

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

1. احصل على معرف المخطط الخاص بك

   شغل أمر عرض الإعدادات a365 -g لعرض إعدادك:

   a365 config display -g
   

   انسخ agentBlueprintId القيمة من المخرج.

2. الانتقال إلى بوابة المطورين

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

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

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

   إشعار

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

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

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

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

   2. قم بتعيين عنوان URL للإعلام إلى نقطة نهاية الرسائل الخاصة بوكيلك. قم بتشغيل الأمر التالي للحصول على القيمة:

      a365 config display -g --field messagingEndpoint
      

   3. حَدِّد حِفظ.

   

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

تعرف أكثر على مخططات هوية الوكلاء وتكوين بوابة المطورين.

2. إنشاء نسخة وكيل

الآن يمكنك طلب نسخة من مخطط وكيلك من Teams. تعرف أكثر على كيفية اكتشاف الوكيل وإنشائه ودمجه.

عند طلب مثيل وكيل، يقوم Teams بإرسال الطلب إلى مسؤول المستأجر الخاص بك للموافقة. يمكن للمسؤولين مراجعة والموافقة على الطلبات من صفحة الوكلاء المطلوبين في مركز إدارة مايكروسوفت .

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

3. اختبر عميلك المنشور

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

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

هام

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

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

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

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

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

عامل الاختبار في Teams

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

إشعار

الحدود المطلوبة: تأكد من تمكين Microsoft Agent 365 Frontier للمستأجر الخاص بك ومنحك المسؤول حق الوصول. أنت بحاجة إلى هذا الْوصول لإنشاء مثيلات الْوكلاء والْتفاعل مَعَ الْوكلاء فِي Microsoft Teams أثناء كون Agent 365 فِي مرحلة الْمعاينة. تعرف أكثر على فرونتير تواصل مع مدير المستأجر إذا لم يكن لديك صلاحية.

ابدأ الاختبار

1. ابحث عن مستخدم وكيلك الجديد في تيمز.

   إشعار

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

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
✅ يمكنك إنشاء وكيل مثيل للفرق
✅ تم إنشاء مثيل الوكيل
✅ يظهر مستخدم الوكيل في المؤسسة
✅ الوكيل يستجيب للرسائل
✅ يمكن للوكيل تنفيذ الإجراءات
✅ سجلات التطبيقات لا تظهر أي أخطاء
✅ قابلية الملاحظة تعمل في مركز الإدارة

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

تحقق من حفظ إعدادات بوابة المطورين

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

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

يظهر وكيل التحقق في Teams

1. > افتح التطبيقات الخاصة بـ Teams

2. ابحث عن اسم وكيلك

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

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

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

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

تحقق من إنشاء مثيل الوكيل

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

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

التحقق من ظهور مستخدم الوكيل في المنظمة

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

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

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

وكيل التحقق يستجيب للرسائل

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

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

يمكن للوكيل التحقق من قدرته على أداء الإجراءات

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

يجب على الوكيل:

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

يجب عليك التأكد من وصول البريد الإلكتروني إلى بريدك الإلكتروني.

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

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

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

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

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

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

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

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

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

الأداء:

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

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

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

# 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. ما بدأ ككود محلي أصبح الآن مساعدا قابلا للاكتشاف وجاهز للمؤسسات حيث يمكن للمستخدمين إنشاء نسخ وكلاء عبر مؤسستك.

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

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

Troubleshooting

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

Tip

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

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

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

السبب الجذري: إعداد بوابة المطورين مفقود.

الحل:

1. احصل على معرف المخطط الخاص بك:

   a365 config display -g
   # Copy the agentBlueprintId value
   

2. تهيئة في بوابة المطورين:

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

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

   3. قم بتعيين عنوان URL للإشعار على نقطة النهاية الخاصة بالرسائل لوكيلك. قم بتشغيل الأمر التالي للحصول على القيمة:

      a365 config display -g --field messagingEndpoint
      

   4. حَدِّد حِفظ.

3. انتظر من 5 إلى 10 دقائق حتى التكاثر.

التحقق:

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

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

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

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

حل: اتصل بمسؤول المستأجر للتحقق من تمكين Microsoft Agent 365 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".
   • إذا كان يعمل محليًا ولكن يواجه مشكلة في التوزيع السحابي >.

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

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

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

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

قد ترغب أيضا في تجربة:

• استكشاف الْأخطاء وإصلاحها الْمتعلقة بنشر عامل إلى خدمات أمازون ويب
• استكشاف أخطاء نشر عامل إلى 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).

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

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