مخطط إعداد العامل

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

إشعار

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

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

المتطلبات

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

  1. Agent 365 CLI - راجع تثبيت Agent 365 CLI

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

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

    تلميح

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

إنشاء مخطط العامل

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

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

قم بتشغيل أمر الإعداد:

a365 setup -h

يتضمن الأمر خيارات متعددة. يمكنك إكمال الإعداد بالكامل باستخدام a365 setup all أو اختيار المزيد من الخيارات التفصيلية.

إشعار

a365 setup all الإعدادات الافتراضية لوضع عامل المخطط. لإعداد عامل زميل الذكاء الاصطناعي بدلاً من ذلك، مرر --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 Web App مع تمكين الهوية المُدارة
  2. يسجل مخطط العامل:

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

    مهم

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

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

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

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

إشعار

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

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

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

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

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

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

  • يمنح إذن OAuth2 المفوض (موافقة AllPrincipals) لـ Microsoft Graph وAgent 365 Tools وMessaging Bot API وObservability API وPower Platform API

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

الخطوة من الإجرَاء
1 المطور قم بتشغيل a365 setup all. يكمل CLI جميع الخطوات التي يستطيع تنفيذها ويعرض الخطوات التالية، بما في ذلك رابط الموافقة الذي يجب أن يفتحه مسؤول عام.
2 المطور شارك رابط الموافقة من ناتج CLI مع المسؤول العام لديك.
3 المسؤول العمومي افتح عنوان URL الموافقة في متصفح مسجل الدخول كمسؤول عمومي وامنح الأذونات المطلوبة.

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

# 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 مع المسؤول العمومي الخاص بك. يمكنهم فتح الرابط المقدم أو رابط الموافقة لإتمام منح صلاحيات 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، وAgent 365 Tools، وMessaging Bot API، وObservability API.
    completed حالة الإعداد يجب أن يكون true

    إشعار

    إذا قمت بتشغيل الإعداد كـ Agent ID Administrator أو Agent ID Developer، فقد يكون 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 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.json و a365.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 ID.

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

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

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

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

استخدم a365 setup permissions custom لتطبيق أذونات API مخصصة ضمن مخططك في 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.

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

نشر كود عامل على السحابة:

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

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

تلميح

دليل استكشاف أخطاء Agent 365 يتضمن توصيات عالية المستوى لاستكشاف الأخطاء وحلها، وأفضل الممارسات، وروابط لمحتوى استكشاف الأخطاء لكل جزء من دورة تطوير Agent 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 وأعد تشغيل الإعداد.

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

    # WARNING: This command deletes all resources in it
    az group delete --name <your-resource-group>
    
  • استخدم أمر التنظيف للبدء من جديد

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

    تحذير

    تشغيل a365 cleanup مدمر.

    a365 cleanup
    a365 setup all
    

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

الحل: اختر وفقاً لدورك:

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

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

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

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

الحل:

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

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

الأعراض: أمر الإعداد ناجح لكن موارد 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. انتقل إلى تسجيلات التطبيقات> ثم جميع التطبيقات.
    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 لإزالة عامل بدون ملف تكوين. يقرأ CLI ومعرفات الموارد من الإعدادات المولدة عالميا التي كتبت أثناء إعداد bootstrap.

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

تلميح

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

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

غير قادر على إرسال الرسالة الأولى في Teams

المشكلة: بعد تهيئة مثيل لعامل، لا يمكنه إرسال رسالة إلى مدير العامل كرسالة ترحيب.

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

  • لتنفيذ ذلك، قم بتكوين أذونات المخطط القابلة للتوريث لتشمل Chat.Createالنطاق.
  • قم بتكوين رسالة دردشة على Teams ليتم إرسالها بمجرد توفير مثيل عامل.
  • أنشئ مثيل عامل جديد استنادًا إلى المخطط واختبر رسالة التشغيل الأولية.