مخطط وكيل الإعداد

مهم

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

يحدد مخطط الوكيل هوية وكيلك وأذوناتك ومتطلبات البنية التحتية. أنشئ كل حالة وكيل من مخطط الوكيل هذا.

لمزيد من المعلومات حول هوية العميل 365، راجع العميل 365 هوية.

المتطلبات

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

1. Agent 365 CLI - انظر تركيب AGENT 365.

2. الأذونات المطلوبة:

   • مستخدم مستأجر صالح بأحد الأدوار التالية:
     • مسؤول عام
     • مسؤول معرف الوكيل
     • مطور معرف الوكيل
   • الوصول إلى اشتراك Azure مع أذونات لإنشاء موارد

3. ملف صالح a365.config.json في مجلد العمل الخاص بك، تم إعداده عبر هذه الخطوة: إعداد إعدادات العميل 365.

إنشاء مخطط وكيل

استخدم a365 setup الأمر لإنشاء موارد Azure وتسجيل مخطط الوكيل الخاص بك. يحدد المخطط هوية العامل والأذونات ومتطلبات البنية الأساسية. تؤسس هذه الخطوة الأساس لنشر عاملك وتشغيله في Azure.

إعداد التشغيل

شغل أمر الإعداد:

a365 setup -h

لدى القيادة خيارات متعددة. يمكنك إكمال الإعداد بالكامل في أمر واحد باستخدام a365 setup all أو اختيار خيارات أكثر تفصيلا.

تقوم عملية الإعداد بأكملها بتنفيذ هذه العمليات:

1. إنشاء بنية أساسية لـ Azure (إذا لم تكن موجودة بالفعل):

   • مجموعة الموارد
   • خطة خدمة التطبيقات مع SKU محدد
   • Azure Web App مع تمكين الهوية المُدارة

2. يسجل مخطط العامل:

   • إنشاء مخطط العامل في مستأجر Microsoft Entra
   • إنشاء تسجيلات تطبيق Microsoft Entra
   • تكوين هوية العامل بالأذونات المطلوبة

3. تكوين أذونات API:

   • إعداد نطاقات Microsoft Graph API
   • تكوين أذونات Messaging Bot API
   • تطبيق الأذونات القابلة للتوريث لمثيلات العامل

4. تحديث ملفات التكوين:

   • يحفظ المعرفات والنقاط النهائية المولدة لملف جديد في دليل العمل الخاص بك يسمى a365.generated.config.json
   • سجلات الهوية المُدارة ومعلومات الموارد

إشعار

أثناء الإعداد، يفتح الأمر نوافذ المتصفح لموافقة المسؤول. أكمل تدفقات الموافقة هذه للمتابعة. يستغرق الإعداد عادةً من 3 إلى 5 دقائق ويحفظ التكوين تلقائيًا في a365.generated.config.json.

التحقق من الإعداد

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

1. تحقق من التكوين المولد:

   a365 config display -g
   

   يشمل الناتج المتوقع هذه القيم الحرجة:

   {
   "managedIdentityPrincipalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintServicePrincipalObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "agentBlueprintClientSecret": "xxx~xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
   "agentBlueprintClientSecretProtected": true,
   "botId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "botMsaAppId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "botMessagingEndpoint": "https://your-app.azurewebsites.net/api/messages",
   "resourceConsents": [],
   "completed": true,
   "completedAt": "xxxx-xx-xxTxx:xx:xxZ",
   "cliVersion": "x.x.xx"
   }
   

   الحقول الرئيسية للتحقق منها:

   الحقل	قصد	ما الذي يجب التحقق منه
   managedIdentityPrincipalId	Azure managed identity authentication	يجب أن يكون GUID صالحا
   agentBlueprintId	معرف وكيلك الفريد	يستخدم في بوابة المطورين ومركز الإدارة
   agentBlueprintObjectId	معرف Microsoft Entra الخاص ب Blueprint
   botMessagingEndpoint	توجيه الرسائل	حيث يرسل Teams/Outlook رسائل إلى وكيلك
   agentBlueprintClientSecret	سر المصادقة	يجب أن توجد (القيمة مخفية)
   resourceConsents	أذونات واجهة برمجة التطبيقات	يجب أن تحتوي على موارد مثل Microsoft Graph، أدوات Agent 365، واجهة برمجة تطبيقات روبوت الرسائل، واجهة برمجة تطبيقات الملاحظة
   completed	حالة الإعداد	يجب أن يكون كذلك true

2. Verify Azure resources in Azure Portal:

   أو استخدم az resource list أمر PowerShell.

   # List all resources in your resource group
   az resource list --resource-group <your-resource-group> --output table
   

   تحقق من إنشاء الموارد التالية:

   • مجموعة الموارد:

     • اذهب إلى مجموعات الموارد اختر> مجموعة الموارد الخاصة بك
     • تحقق من احتوائه على خطة App Service وتطبيق الويب

   • خطة خدمة تطبيق:

     • انتقل إلى خدمات التطبيق>خطط خدمة التطبيق
     • ابحث عن خطتك وتحقق من تطابق مستوى التسعير مع تكوين SKU

   • تطبيق الويب:

     • انتقل إلى خدمات التطبيق>تطبيقات الويب
     • ابحث عن تطبيق الويب الخاص بك، ثم انتقل إلى الإعدادات>الهوية>النظام المُعين
     • التحقق من أن الحالة قيد التشغيل
     • لاحظ تطابق معرف الكائن (الأساسي) managedIdentityPrincipalId

3. تحقق من تطبيقات Microsoft Entra في مدخل Microsoft Azure:

   انتقل إلى Azure Active Directory>تسجيلات التطبيق>جميع التطبيقات:

   • ابحث عن مخطط العامل الخاص بك بواسطة agentBlueprintId

   • افتح التطبيق وحدد أذونات API

   • تمنح صلاحيات التحقق باستخدام علامات تحقق خضراء:

     • Microsoft Graph (التفويض وأذونات التطبيق)
     • أذونات Messaging Bot API

   • جميع الأدوانات تظهر "تم المنح ل [مستأجرك]"

4. تحقق من إنشاء ملف التكوين المولد:

   يجب أن يكون هناك ملف مسمى a365.generated.config.json يحتوي على كل بيانات التكوين.

   يمكنك اختبار وجوده باستخدام أمر Test-Path PowerShell.

   # Check file exists
   Test-Path a365.generated.config.json
   # Should return: True
   

   مهم

   احفظ كلا الملفات a365.config.jsona365.generated.config.json . تحتاج إلى هذه القيم للنشر وحل المشكلات.

5. تحقق من أن تطبيق الويب مفعل الهوية المدارة:

   استخدم الأمرaz webapp identity show للتحقق مما إذا كانت هوية الإدارة مفعلة.

   az webapp identity show --name <your-web-app> --resource-group <your-resource-group>
   

   المتوقع:

   {
   "principalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "type": "SystemAssigned"
   }
   

6. تحقق من مخطط الوكيل المسجل في إنترا:

   في مركز إدارة Microsoft Entra، ابحث عن جهازك agentBlueprintId أو ابحث بالاسم.

   تحقق من ذلك:

   ✅ تسجيل التطبيقات وتطبيقات المؤسسات تظهر
   ✅ في مخطط تسجيل التطبيق، تظهر علامات تبويب صلاحيات API جميع الأذونات
   ✅ الحالة تظهر "تم المنح ل [مستأجرك]"

لمزيد من المساعدة، انظر:

• مشاكل التكوين
• مشاكل تطبيق العميل المخصص

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

نشر كود الوكيل الخاص بك على السحابة:

أسمانجوني

خدمات أمازون ويب (AWS)

منصة جوجل السحابية (GCP)

وكيل النشر إلى مركز إدارة مايكروسوفت

Troubleshooting

يصف هذا القسم المشاكل الشائعة عند إعداد مخططات الوكلاء.

Tip

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

تحدث هذه المشاكل أحيانا أثناء التسجيل:

• خطأ في الأذونات غير الكافية
• Missing Azure CLI authentication
• الموارد موجودة بالفعل
• موافقة الإدارة لم تكتمل
• ملفات التكوين مفقودة أو غير صالحة
• تم الإعداد لكن الموارد لم تنشئ
• مخطط الوكيل غير مسجل في إنترا
• أما صلاحيات API فلا تمنح
• الهوية المدارة غير مفعلة
• الإعداد يستغرق وقتا طويلا أو يتعطل

خطأ في الأذونات غير الكافية

عَرَض: خطأ في الأمور غير كافية أثناء a365 setup تنفيذ الأمر .

تحتاج إلى أحد الأدوار التالية في مستأجر Microsoft Entra الخاص بك:

• مسؤول عام
• مسؤول معرف الوكيل
• مطور معرف الوكيل

والوصول إلى مساهم أو مالك اشتراك أزور.

الحل: تحقق من وجود الأذونات المطلوبة في Entra.

• اذهب إلى: مركز >إدارة Microsoft Entra ملفك الشخصي > الأدوار المعينة
• تحقق من اشتراك Azure باستخدام az account show أمر PowerShell

Missing Azure CLI authentication

عَرَض: الإعداد يفشل بسبب أخطاء المصادقة.

الحل: تأكد من اتصالك ب Azure وتحقق من حسابك واشتراكك.

# Authenticate with Azure
az login

# Verify correct account and subscription
az account show

الموارد موجودة بالفعل

عَرَض: فشل الإعداد مع خطأ Resource already exists في مجموعة الموارد أو خطة خدمة التطبيقات أو تطبيق الويب.

الحلول: اختر أحد الحلول التالية

• استخدام الموارد الحالية

  إذا كانت هناك موارد وترغب في استخدامها، تأكد من أنها تتطابق مع إعدادك. استخدم az resource list أمر PowerShell.

  az resource list --resource-group <your-resource-group>
  

• حذف الموارد المتضاربة

  احذف مجموعة الموارد أو أعد تسمية مواردك وأعد a365.config.json تشغيل الإعداد.

  يمكنك استخدام az group delete أمر Powershell لحذف مجموعة الموارد.

  # WARNING: This command deletes all resources in it
  az group delete --name <your-resource-group>
  

• استخدم أمر التنظيف للبدء من جديد

  استخدم الأمرcleanup لإزالة جميع موارد العميل 365، ثم أمرa365 setup all إعادة تشغيل الإعداد.

  Warning

  الجري a365 cleanup مدمر

  a365 cleanup
  a365 setup all
  

موافقة الإدارة لم تكتمل

عَرَض: نوافذ المتصفح تفتح أثناء الإعداد لكنك أغلقتها دون الحصول على موافقة كاملة.

الحل: شغل a365 setup all الأمر. إعادة طلب طلب موافقة المسؤول:

أكمل جميع تدفقات الموافقة في نوافذ المتصفح التي تظهر.

ملفات التكوين مفقودة أو غير صالحة

عَرَض: يفشل الإعداد مع وجود أخطاء "عدم العثور على الإعدادات" أو أخطاء التحقق.

الحل:

1. تحقق من a365.config.json وجود الملف.
2. عرض التكوين الحالي باستخدام أمر عرض الإعدادات a365.
3. إذا كان الشيء مفقودا أو غير صحيح، أعد التهيئة باستخدام أمر config init a365.

# Verify a365.config.json exists
Test-Path a365.config.json

# Display current configuration
a365 config display

# If missing or invalid, re-initialize
a365 config init

تم الإعداد لكن الموارد لم تنشئ

عَرَض: أمر الإعداد ينجح لكن موارد Azure غير موجودة.

الحل:

1. تحقق من الموارد التي تم إنشاؤها a365 config display -g باستخدام الأمر.
2. تحقق من وجود موارد Azure باستخدام az resource list الأمر.
3. إذا كانت الموارد مفقودة، تحقق من وجود أخطاء في إخراج الإعداد وأعد تشغيلها باستخدام a365 setup all الأمر.

# Check created resources
a365 config display -g

# Verify Azure resources exist
az resource list --resource-group <your-resource-group> --output table

# If resources missing, check for errors in setup output and re-run
a365 setup all

مخطط الوكيل غير مسجل في إنترا

عَرَض: تم الإعداد لكن لم أتمكن من العثور على مخطط الوكيل في مركز إدارة Microsoft Entra.

الحل:

1. احصل على معرف البلوبرينت من الإعدادات المولدة باستخدام أمر a365 display-g.

   a365 config display -g
   # Look for: agentBlueprintId
   

2. البحث في مركز إدارة Microsoft Entra:

   1. اذهب إلى: مركز إدارة Microsoft Entra.
   2. انتقل إلى تسجيلات التطبيقات جميع>التطبيقات
   3. ابحث عن agentBlueprintId

3. إذا لم يتم العثور عليهa365 setup all، أعد تشغيل الإعداد باستخدام الأمر.

   a365 setup all
   

أما صلاحيات API فلا تمنح

عَرَض: اكتمل الإعداد لكن الأصوات تظهر ك "غير ممنوح" في Entra.

الحل:

1. Open Microsoft Entra admin center

2. ابحث عن تسجيل تطبيق مخطط وكيلك

3. اذهب إلى صلاحيات API

4. امنح موافقة المسؤول:

   1. اختر منح موافقة الإدارة ل [مستأجرك]
   2. أكد الفعل

5. تحقق من جميع الأصوات تظهر علامات تحقق خضراء

الهوية المدارة غير مفعلة

عَرَض: تطبيق ويب موجود لكن الهوية المدارة غير مفعلة.

الحل:

1. تحقق من az webapp identity showحالة الهوية المدارة باستخدام الأمر.
2. إذا لم يكن مفعلا، قم بتفعيله يدويا باستخدام az webapp identity assign الأمر.
3. تحقق من تفعيله باستخدام az webapp identity show الأمر.

# Check managed identity status
az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

# If not enabled, enable it manually
az webapp identity assign --name <your-web-app> --resource-group <your-resource-group>

# Verify it's enabled
az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

الإعداد يستغرق وقتا طويلا أو يتعطل

عَرَض: أمر الإعداد يعمل لأكثر من 10 دقائق دون إكماله.

الحل:

1. تحقق مما إذا كانت نوافذ المتصفح تنتظر الموافقة - أكمل جميع تدفقات الموافقة.

2. إذا تم تعليقك فعلا، ألغ (Ctrl+C) وتحقق مما تم إنشاؤه:

   # Check generated config
   a365 config display -g
   
   # Check Azure resources
   az resource list --resource-group <your-resource-group>
   

3. تنظيف وإعادة المحاولة:

   a365 cleanup
   a365 setup all