مخطط وكيل التثبيت

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

ملاحظة

يلزم إعداد مخطط عامل لتمكين إمكانات التسجيل وذكاء العمل وزملاء فريق الذكاء الاصطناعي. راجع بدء استخدام تطوير Agent 365 لفهم القدرات التي تنطبق على وكيلك.

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

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

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

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

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

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

    Tip

    لا يحتاج الوكلاء (وليس زملاء فريق الذكاء الاصطناعي) إلى ملف تكوين. استخدم a365 setup all --agent-name <name> وسيقوم CLI بتحديد تطبيق المستأجر والعميل تلقائيًا. يتطلب إعداد زميل الذكاء الاصطناعي إنشاء يدويا a365.config.json.

إنشاء نموذج وكيل

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

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

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

a365 setup -h

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

ملاحظة

a365 setup all يضبط تلقائياً إلى وضع blueprint agent. لإعداد عامل زميل في فريق الذكاء الاصطناعي بدلا من ذلك، مرر --aiteammate. بالنسبة لوكلاء M365 (Teams، Copilot)، مرر أيضا --m365 لتسجيل نقطة نهاية المراسلة تلقائيا.

إعداد العامل (افتراضي):

# With a config file
a365 setup all

# Config-free — no a365.config.json needed
a365 setup all --agent-name <your-agent-name>

إعداد عامل M365 (Teams/Copilot):

# Registers the messaging endpoint via MCP Platform
a365 setup all --m365

إعداد زميل الذكاء الاصطناعي في الفريق:

a365 setup all --aiteammate

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

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

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

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

    • إنشاء مُخطط الوكيل في مستأجر Microsoft Entra
    • إنشاء تسجيلات تطبيق Microsoft Entra
    • تكوين هوية العامل بالأذونات المطلوبة
    • تعيين managerApplications على المخطط الأساسي، وهو ضروري لإدارة النظام الأساسي

    Important

    لكي يتم قبول المخططات من قبل النظام الأساسي، يجب أن يكون managerApplications قد تم تعيينه. يقوم CLI بتعيين هذا تلقائيا. إذا كان لديك مخطط موجود تم إنشاؤه قبل تقديم هذا المطلب، فاحذفه وقم بتشغيل a365 setup all مرة أخرى، أو قم بتصحيحه يدويا عبر Graph API.

  3. تكوين أذونات واجهة برمجة التطبيقات:

    • إعداد نطاقات واجهة برمجة تطبيقات Microsoft Graph
    • يقوم بتكوين أذونات واجهة برمجة تطبيقات روبوت المراسلة
    • تطبيق الأذونات الموروثة لحالات الوكلاء

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

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

ملاحظة

يستغرق الإعداد عادة من 3 إلى 5 دقائق ويحفظ التكوين تلقائيا في a365.generated.config.json. إذا قمت بتشغيل كمسؤول عام، فقد يفتح CLI نافذة متصفح للحصول على موافقة المسؤول - أكمل تدفق الموافقة للمتابعة. إذا قمت بتشغيل كمطور معرف العامل، فلن تظهر أي نافذة مستعرض؛ ينشئ CLI عناوين URL للموافقة على المسؤول العام لإكمالها لاحقا.

الإعداد باستخدام مطور معرف العامل

إذا قمت بتشغيل كمطور معرف العامل (وليس المسؤول العام)، a365 setup all يكمل معظم الخطوات تلقائيا، ولكن منح إذن OAuth2 تتطلب خطوة مسؤول عام منفصلة.

ما الخطوات المكتملة تلقائيا:

  • البنية الأساسية ل Azure (مجموعة الموارد، خطة خدمة التطبيقات، تطبيق الويب)
  • تسجيل مخطط تصميم الوكيل
  • الأذونات القابلة للتوريث لمثيلات الوكيل

ما الخطوات التي تتطلب مسؤول عام:

  • منح الإذن المفوض OAuth2 (AllPrincipals الموافقة) ل Microsoft Graph وأدوات الوكيل 365 وواجهة برمجة تطبيقات روبوت المراسلة وواجهة برمجة تطبيقات إمكانية المراقبة وواجهة برمجة تطبيقات Power Platform

كيفية إكمال الإعداد باستخدام حساب غير مسؤول:

الخطوة من الإجراء
1 المطور قم بتشغيل a365 setup all. يكمل CLI جميع الخطوات التي يمكنه تنفيذها ويطبع إرشادات توضح ما يجب أن ينتهي منه المسؤول العام.
2 المطور شارك مجلد الإعدادات مع المسؤول العام العالمي. يحتوي المجلد على a365.config.json و a365.generated.config.json.
3 المسؤول العام قم بتشغيل a365 setup admin --config-dir "<path-to-config-folder>" لإكمال منح إذن OAuth2.

تشغيل الأوامر:

# Developer runs:
a365 setup all
# Setup completes all steps it can. The CLI prints the next steps
# for a Global Administrator directly in the output, including a
# direct link or consent URL they can open to complete the grants.

شارك الخطوات التالية المطبوعة بواسطة CLI مع المسؤول العام. يمكنهم فتح الارتباط المقدم أو عنوان URL للموافقة لإكمال منح OAuth2.

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

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

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

    افتح a365.generated.config.json في دليل العمل الخاص بك. أو استخدم PowerShell:

    Get-Content a365.generated.config.json | ConvertFrom-Json

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

    {
"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",
"messagingEndpoint": "https://your-app.azurewebsites.net/api/messages",
"resourceConsents": [],
"completed": true,
"completedAt": "xxxx-xx-xxTxx:xx:xxZ",
"cliVersion": "x.x.xx"
}

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

    الحقل الغرض ما الذي يجب التحقق منه
    managedIdentityPrincipalId مصادقة الهوية المدارة في Azure يجب أن يكون GUID صالحا
    agentBlueprintId معرف وكيلك الفريد يستخدم في بوابة المطورين ومركز الإدارة
    agentBlueprintObjectId مخطط Microsoft Entra ID
    messagingEndpoint توجيه الرسائل حيث يرسل Teams/Outlook رسائل إلى وكيلك
    agentBlueprintClientSecret سر المصادقة يجب أن توجد (القيمة مخفية)
    resourceConsents أذونات واجهة برمجة التطبيقات يجب أن تحتوي على موارد مثل Microsoft Graph وأدوات العامل 365 وواجهة برمجة تطبيقات روبوت المراسلة وواجهة برمجة تطبيقات إمكانية المراقبة
    completed حالة الإعداد يجب أن يكون كذلك true

    ملاحظة

    إذا قمت بتشغيل الإعداد كمسؤول معرف العامل أو مطور معرف العامل، resourceConsents فقد يكون فارغا وقد يكون completed فارغا false حتى يكمل مسؤول عمومي منح إذن OAuth2 باستخدام الخطوات التالية المطبوعة بواسطة CLI.

  2. التحقق من موارد Azure في مدخل Azure:

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

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

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

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

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

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

      • انتقل إلى App Services>App Service Plans
      • ابحث عن خطتك وتحقق من تطابق مستوى التسعير مع تكوين SKU

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

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

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

    انتقل إلى Azure Active Directory>App registrations>All applications:

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

    • افتح التطبيق وحدد أذونات واجهة برمجة التطبيقات

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

      • 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

    Important

    احفظ كلا الملفات 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:

    في مركز مسؤولي Microsoft Entra، ابحث عن agentBlueprintId أو ابحث بالاسم.

    تحقق مما يلي:

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

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

أذونات الوكيل

قبل أن تتمكن التطبيقات والوكلاء من قراءة بيانات Microsoft 365 أو كتابتها (المستخدمون والبريد والملفات وTeams والوكلاء وما إلى ذلك)، يجب منحهم أذونات Microsoft Graph بشكل صريح. أذونات Microsoft Graph هي نموذج التخويل الذي يتحكم في البيانات والإجراءات التي يمكن للتطبيق أو الخدمة الوصول إليها من خلال واجهات برمجة تطبيقات Microsoft Graph عبر Microsoft 365 ومعرف Microsoft Entra.

تعرف على المزيد: نظرة عامة على أذونات Microsoft Graph

لاستخدام أذونات Graph لمثيلات عامل العامل 365، يجب على المطور الإعلان عنها في مخطط العامل. عندما يقوم مسؤول بتنشيط المخطط في مركز إدارة Microsoft 365، يراجع المدخل أذونات الرسم البياني للمخطط ويطالب المسؤول بالموافقة عليها.

لفهم كيفية تمكين أذونات Graph لوكيلك والتحقق من صحتها، يمكنك:

تطبيق الأذونات على مخططك

استخدم a365 setup permissions custom لتطبيق أذونات واجهة برمجة التطبيقات المخصصة المضمنة في مخططك في Microsoft Entra.

a365 setup permissions custom `
  --resource-app-id 00000003-0000-0000-c000-000000000000 `
  --scopes Mail.Read,Mail.Send,Chat.Read,Chat.ReadWrite,Chat.Create,User.Read

للحصول على تفاصيل كاملة حول تكوين الأذونات المخصصة وإزالتها، راجع setup permissions custom.

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

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

Azure

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

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

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

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

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

Tip

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

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

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

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

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

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

الوصول إلى المساهم أو المالك في اشتراك Azure.

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

ملاحظة

إذا كان لديك دور مسؤول معرف العامل أو دور مطور معرف العامل (وليس المسؤول العام)، a365 setup all فلا يزال ينجح ولكنه يتخطى منح إذن OAuth2. بعد اكتمال الإعداد، يقوم CLI بطباعة الخطوات التالية لمسؤول عام لإكمال المنح المتبقية. يتوقع سير العمل هذا للمؤسسات التي يكون فيها مطور الوكيل والمسؤول العام أشخاصا مختلفين.

المصادقة الخاصة بـ Azure CLI مفقودة

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

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

# Authenticate with Azure
az login

# Verify correct account and subscription
az account show

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

عَرَض: فشل الإعداد مع Resource already exists حدوث خطأ لمجموعة الموارد أو خطة App Service أو Web App.

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

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

    إذا كانت هناك موارد وترغب في استخدامها، تأكد من أنها تتطابق مع إعدادك. استخدم 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 الأمر لإعادة تشغيل الإعداد.

    تحذير

    تشغيل a365 cleanup يتسبب في دمار.

    a365 cleanup
a365 setup all

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

حل: اختر استنادا إلى دورك:

  • المسؤول العام: قم بتشغيل a365 setup all مرة أخرى. يطالب CLI بموافقة المسؤول. أكمل تدفق الموافقة في نافذة المستعرض التي تظهر.

  • مسؤول معرف العامل أو المطور: لا يمكنك إكمال منح OAuth2 مباشرة. تشغيل a365 setup all - يقوم ملخص الإعداد بطباعة الخطوات التالية للمسؤول العالمي، بما في ذلك رابط مباشر أو URL للموافقة لإكمال المنح. شارك هذه التفاصيل مع المسؤول العام.

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

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

الحل:

  1. تحقق من وجود ملف a365.config.json.
  2. إذا كان مفقودا أو غير صالح، قم بإنشائه يدويا أو استخدامه a365 setup all --agent-name <name> (العوامل فقط).
# Verify a365.config.json exists
Test-Path a365.config.json

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

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

الحل:

  1. تحقق من الموارد التي تم إنشاؤها عن طريق فتح a365.generated.config.json في دليل العمل الخاص بك.
  2. تحقق من وجود موارد Azure باستخدام الأمر az resource list.
  3. إذا كانت الموارد مفقودة، فتحقق من وجود أخطاء في إخراج الإعداد وأعد تشغيل الإعداد باستخدام a365 setup all الأمر .
# Check created resources
Get-Content a365.generated.config.json | ConvertFrom-Json

# 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

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

الحل:

  1. احصل على معرف المخطط من a365.generated.config.json.

    Get-Content a365.generated.config.json | ConvertFrom-Json | Select-Object agentBlueprintId

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

    1. انتقل إلى: مركز مسؤولي Microsoft Entra.
    2. انتقل إلى App registrations>All applications.
    3. ابحث عن agentBlueprintId.

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

    a365 setup all

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

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

الحل:

  1. افتح مركز مسؤولي Microsoft Entra.

  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
Get-Content a365.generated.config.json | ConvertFrom-Json

# Check Azure resources
az resource list --resource-group <your-resource-group>

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

    a365 cleanup
a365 setup all

تنظيف عامل خال من التكوين

عَرَض: لقد قمت بتوفير وكيل مع a365 setup all --agent-name <name> وتريد الآن إزالته، ولكن ليس لديك a365.config.json ملف.

حل: استخدم a365 cleanup --agent-name لإزالة العامل بدون ملف تكوين. يقرأ واجهة سطر الأوامر معرفات الموارد من ملف التكوين العام الذي تم إنشاؤه وكتابته أثناء عملية إعداد بوتستراب.

a365 cleanup --agent-name <your-agent-name>

Tip

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

إذا لم يعد لديك التكوين العمومي الذي تم إنشاؤه (على سبيل المثال، بعد إعادة تثبيت CLI)، فاستخدم a365 cleanup مع الحد الأدنى من a365.config.json الذي تم إنشاؤه يدويا، أو قم بإزالة الموارد مباشرة عبر مدخل Azureمركز مسؤولي Microsoft Entra.

تعذر إرسال الرسالة الأولى في Teams

عَرَض: بعد توفير مثيل عامل، لا يمكنه إرسال رسالة إلى مدير العامل كرسالة ترحيب.

حل: مطلوب إذن [Chat.Create][perm-chatcreate] لإنشاء كائن دردشة جديد. إذا كانت هناك دردشة واحدة موجودة بالفعل، فترجع هذه العملية الدردشة الموجودة ولا تنشئ دردشة جديدة.

  • Last updated on