إنشاء عامل Agent 365 يتم نشره في Amazon Web Services ‏(AWS)

تعرّف على كيفية إنشاء واستضافة وتسجيل ونشر عامل Agent 365 يعمل على AWS Elastic Beanstalk باستخدام أداة سطر الأوامر Agent 365. توفر Microsoft Entra وGraph هوية عامل، الصلاحيات، والمخطط الأساسي، بينما توفر AWS Elastic Beanstalk بيئة التشغيل.

إذا كنت ترغب في توجيه عاملك إلى التعليمات البرمجية الخاصة بك الموجودة خلف نقطة نهاية AWS، فكل ما عليك فعله هو اتباع الخطوة التالية: تكوين الاستضافة غير التابعة لـ Azure. ثم اتبع جميع الخطوات الأخرى من الشروع في العمل باستخدام تطوير Agent 365.

الأهدَاف

تعرّف على كيفية استخدام Agent 365 وMicrosoft 365 كلوحة تحكم و:

• نشر وقت تشغيل عامل على AWS Elastic Beanstalk
• تكوين a365.config.json لاستضافة غير Azure
• إنشاء مخطط تفصيلي لعامل في Entra ID
• تكوين OAuth2 + الأذونات القابلة للتوريث
• سجل نقطة نهاية رسائل Bot Framework مشيرة إلى AWS
• إنشاء هوية عامل ومستخدم عامل
• (اختياري) نشر إلى واجهات تطبيقات Microsoft 365
• اختبر التفاعلات من طرف إلى طرف

المتطلبات

قبل البدء، تأكد من استيفاء المتطلبات الأساسية التالية لبيئة Azure / Microsoft 365 وAWS والبيئة المحلية.

متطلبات Azure / Microsoft 365 الأساسية

تأكد من امتلاكك وصولاً إلى مستأجر Microsoft Entra الخاص بك وقم بتثبيت الأدوات التالية لإنشاء الهويات والمخططات وتسجيل عاملِك.

• مستأجر Microsoft Entra يشمل:

  • الإذن أو الدور لإنشاء التطبيقات ومخططات العامل (مسؤول عام أو ما يعادله)
  • العضوية في برنامج الإصدار الأولي الرائد للحصول على وصول مبكر إلى Microsoft Agent 365.
  • يجب توفر ترخيص واحد على الأقل من Microsoft 365 لمستخدم عامل

• تم تثبيت Azure CLI وتسجيل الدخول.

• تثبيت واجهة سطر أوامر Agent 365

متطلبات Amazon Web Services ‏(AWS) الأساسية

تأكد من إعداد خدمات وأدوات AWS التالية لنشر وإدارة بيئة Elastic Beanstalk الخاصة بك.

• حساب AWS باستخدام الأذونات المناسبة
• تمكين الوصول إلى AWS Elastic Beanstalk
• تثبيت وتكوين واجهة سطر أوامر AWS
• تثبيت واجهة سطر أوامر Elastic Beanstalk

المتطلبات الأساسية لبيئة التطوير المحلية

قم بتثبيت وتكوين الأدوات التالية محلياً لبناء وتشغيل ونشر عامل.

• محرر الكود: استخدم تعليمة Visual Studio برمجية أو Visual Studio

• .NET SDK: استخدام .NET 8.0 SDK أو إصدار أحدث

• مجموعة أدوات AWS: ثبت هذا الملحق من Visual Studio أو تعليمة Visual Studio برمجية. سجل الدخول باستخدام بيانات اعتماد إدارة الهوية والوصول في AWS ‏(IAM).

• الوصول إلى واجهة برمجة تطبيقات LLM: اختر الخدمة المناسبة استنادا إلى تكوين وكيلك أو موفر النموذج المفضل لديك:

  • OpenAI API Key: احصل على مفتاح OpenAI API
  • Azure OpenAI: إنشاء مورد Azure OpenAI ونشره للحصول على مفتاح واجهة برمجة التطبيقات ونقطة النهاية

إنشاء ونشر عامل .NET

توضح التعليمات التالية كيفية إنشاء عامل بسيط يقوم بما يلي:

• يرد على GET /
• يقبل أنشطة Bot Framework عبر POST /api/messages

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

mkdir aws-a365-agent
cd aws-a365-agent

تهيئة مشروع .NET

لتبسيط تجربتك، تستخدم هذه المقالة نموذجًا مُعدًا مسبقًا. استنسخ مستودع عينات Agent 365 وانتقل إلى عينة dotnet\semantic-kernel\sample-agent.

يتضمن نموذج عامل النواة الدلالية - C#/.NET ما يلي:

• واجهة برمجة تطبيقات ويب ASP.NET Core بسيطة
• معالج رسائل Bot Framework عند /api/messages
• نقطة نهاية فحص السلامة عند /
• تكامل النواة الدلالية لقدرات الذكاء الاصطناعي

انتقل إلى dotnet\semantic-kernel\sample-agent وتحقق من نجاح بناء المشروع:

dotnet restore
dotnet build

تكوين النموذج

اتبع التعليمات في الخطوة 2: تكوين النموذج اللغوي لتكوين المشروع باستخدام مفتاح API المفتوح الخاص بك.

الاختبار المحلي (اختياري)

1. قبل النشر على AWS، اختبر عاملك محليًا:

   # Run the application
   dotnet run
   

2. اختبر نقاط النهاية في طرفية أخرى:

   # Test agent endpoint locally
   curl http://localhost:3978
   

3. اضغط Ctrl+C لإيقاف الخادم المحلي.

إنشاء ونشر

اختر الخيار الذي تفضله لبناء ونشر هذا التطبيق النموذجي:

• الخيار أ: الإنشاء والنشر من Visual Studio
• الخيار ب: الإنشاء والنشر على AWS Elastic Beanstalk باستخدام واجهة سطر الأوامر (CLI)

الخيار أ: الإنشاء والنشر من Visual Studio

استخدم أداة AWS Toolkit لـ Visual Studio لنشر التطبيق على Elastic Beanstalk عبر معالج إرشادي.

1. في مستكشف الحلول، انقر بزر الماوس الأيمن فوق مشروعك.

2. حدد النشر إلى AWS Elastic Beanstalk.

3. تابع معالج توزيع Beanstalk:

   • اختر ملف تعريف بيانات اعتماد AWS الخاص بك.
   • حدد المنطقة (على سبيل المثال، us-east-1).
   • حدد النظام الأساسي (.NET Core on Linux).
   • قم بتكوين إعدادات البيئة.

4. حَدِّد توزيع.

يقوم المعالج بإنشاء وتغليف ونشر تطبيقك على AWS.

الخيار ب: الإنشاء والنشر على AWS Elastic Beanstalk باستخدام واجهة سطر الأوامر (CLI)

استخدم واجهة سطر أوامر Elastic Beanstalk لتغليف ونشر عامل .NET في بيئة Amazon Linux 2 ذات 64 بت. تأكد من تكوين كل من AWS CLI وEB CLI. يرتبط التطبيق بمتغير البيئة PORT المعيَّن بواسطة Beanstalk.

1. إنشاء ونشر تطبيق .NET الخاص بك:

   # Publish for Linux runtime (AWS Elastic Beanstalk uses Amazon Linux)
   dotnet publish -c Release -o ./publish --runtime linux-x64
   

   أنشئ ملف Procfile يحتوي على المحتوى التالي.

   web: dotnet ./SemanticKernelSampleAgent.dll
   

2. قم بتهيئة Elastic Beanstalk لـ .NET. سيُطلب منك اختيار المنطقة والنظام الأساسي:

   eb init
   

3. حدد:

   • النظام الأساسي: 64bit-amazon-linux-2023-v3.7.0-running-.net-8
   • المنطقة: منطقتك المفضلة في AWS (على سبيل المثال: us-east-1)

4. أنشئ حزمة نشر وقم بنشرها:

   cd publish
   zip -r ../deploy.zip .
   cd ..
   eb create aws-a365-agent-env
   eb deploy
   

   هذا الأمر:

   • ينشئ تطبيق Elastic Beanstalk.
   • ينشئ بيئة مع موازن تحميل.
   • ينشر تطبيقك.
   • يقوم بتوفير موارد AWS اللازمة.

5. عند الانتهاء، احصل على نقطة نهاية Elastic Beanstalk الخاصة بك:

   eb status
   

   لاحظ نقطة النهاية الخاصة بك. ينبغي أن يبدو الأمر كالتالي:

   http://aws-a365-agent-env.us-east-1.elasticbeanstalk.com
   

   نقطة النهاية هذه عبارة عن messagingEndpoint المستخدم بواسطة واجهة سطر أوامر أدوات تطوير Agent 365.

إشعار

بالنسبة لبيئات الإنتاج، قم بتكوين HTTPS عن طريق إضافة شهادة SSL/TLS في Elastic Beanstalk. يتطلب Bot Framework استخدام HTTPS لنقاط النهاية الإنتاجية.

التكوين للاستضافة على غير Azure

أنشئ a365.config.json يدويًا في مجلد مشروع Elastic Beanstalk الخاص بك:

مهم

بالنسبة للاستضافة غير Azure، قم بتعيين قيمة messagingEndpoint إلى عنوان URL الخاص بـ Elastic Beanstalk مع مسار /api/messages.

يجب أن يبدو ملف a365.config.json شيئًا مثل هذا:

{
  "tenantId": "YOUR_TENANT_ID",
  "environment": "prod",

  "messagingEndpoint": "http://aws-a365-agent-env.us-east-1.elasticbeanstalk.com/api/messages",

  "agentIdentityDisplayName": "MyAwsAgent Identity",
  "agentBlueprintDisplayName": "MyAwsAgent Blueprint",
  "agentUserDisplayName": "MyAwsAgent User",
  "agentUserPrincipalName": "myawsagent@testTenant.onmicrosoft.com",
  "agentUserUsageLocation": "US",
  "managerEmail": "myManager@testTenant.onmicrosoft.com",

  "deploymentProjectPath": ".",
  "agentDescription": "AWS-hosted Agent 365 Agent"
}

يلخص الجدول التالي حقول التكوين المهمة وغرضها.

الحقل	المعنى
messagingEndpoint	رابط Elastic Beanstalk الخاص بك + /api/messages
deploymentProjectPath	الموقع الذي يتم فيه ختم .env

إنشاء عامل Agent 365

بعد تشغيل رمز العامل الخاص بك على نقطة نهاية AWS، اتبع الخطوات المتبقية من الشروع في العمل باستخدام تطوير Agent 365 لإعداد عامل Agent 365 الخاص بك.

تحقق من العامل من البداية إلى النهاية

استخدم هذه الفحوصات للتأكد من إمكانية الوصول إلى العامل المستضاف على AWS، واستقباله لأنشطة Bot Framework، واستجابته بشكل صحيح عبر واجهات Agent 365.

تحقق من اتصال Elastic Beanstalk

أرسل طلب GET إلى نقطة نهاية Elastic Beanstalk.

curl http://aws-a365-agent-env.us-east-1.elasticbeanstalk.com/

يجب أن تظهر هذه الرسالة عند إرسال الطلب:

AWS Agent is running.

تحقق من سجلات Elastic Beanstalk للرسائل الواردة من Bot Framework

استخدم سجلات Elastic Beanstalk للتحقق من أن العامل يستقبل أنشطة Bot Framework ويستجيب بشكل صحيح.

eb logs

أو بث السجلات في الوقت الحقيقي:

eb logs --stream

بعد وصول رسالة إلى عاملك، تظهر لك:

POST 200 /api/messages
Received activity: { ... }

اختبر عامل من واجهات Agent 365

اعتمادًا على بيئتك، يمكنك اختبار عامل من واجهات مختلفة:

• ملعب العاملين
• Teams (إذا نُشرت)
• العامل Shell
• الواجهات الاتحادية

يمكنك إرسال الرسائل والتحقق من سجلات Elastic Beanstalk الخاصة بك. تعرّف على كيفية اختبار العاملين باستخدام حزمة تطوير البرامج (SDK) الخاصة بـ Microsoft Agent 365 والتحقق من صحة وظائف عاملك باستخدام أداة اختبار Agents Playground..

سير عمل المطور

بمجرد اكتمال الإعداد، اتبع سير العمل هذا للتطوير التكراري:

التطوير والاختبار محليًا

استخدم وضع المراقبة للتطوير السريع مع إعادة التحميل التلقائي:

# Automatically rebuild and restart on file changes
dotnet watch run

قم بإجراء تغييراتك على الكود، واحفظ التغييرات، واختبر محليًا قبل النشر.

قم بإنشاء التطبيق وأعد نشره إلى AWS Elastic Beanstalk

عندما تكون جاهزًا لنشر التغييرات:

# Clean previous builds (optional but recommended)
dotnet clean

# Publish optimized release build
dotnet publish -c Release -o ./publish --runtime linux-x64

# Create deployment package
cd publish
zip -r ../deploy.zip .
cd ..

# Deploy to AWS
eb deploy

الاختبار والمراقبة

قم بالاختبار باستخدام واجهات Agent 365 وراقب سجلات Elastic Beanstalk:

# Stream logs in real-time
eb logs --stream

لا تحتاج إلى إعادة إنشاء هويتك أو Blueprint أو نقطة نهاية روبوت أو الأذونات.

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

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

تلميح

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

نقطة نهاية المراسلة لا تستقبل الطلبات

افحص التفاصيل التالية:

• تأكد أن نقطة النهاية الخاصة بك هي بالضبط:
  http://<your-app>.elasticbeanstalk.com/api/messages
• بيئة Elastic Beanstalk لديك سليمة. استخدم الفحص باستخدام eb health.
• مجموعة الأمان الخاصة بك تسمح بحركة مرور HTTP أو HTTPS الواردة.
• لا توجد قواعد لجدار الحماية أو قيود VPC.

مشكلات سلامة التطبيق

تحقق من سلامة البيئة:

eb health --refresh

اعرض السجلات المفصلة‬:

eb logs

مشكلات ربط المنافذ

تأكد من أن تطبيقك يستمع إلى المنفذ الذي يحدده متغير بيئة PORT. يقوم Elastic Beanstalk بضبط هذه القيمة تلقائيًا.

مشكلات في إنشاء أو تشغيل .NET

تحقق من أخطاء الإنشاء باستخدام هذه الأوامر:

# Clean and rebuild
dotnet clean
dotnet build --verbosity detailed

تحقق من إصدار .NET:

dotnet --version
dotnet --list-sdks

تحقق من وجود مشكلات في الحزمة:

# List installed packages
dotnet list package

# Update packages
dotnet restore --force

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

عيّن ترخيص Microsoft 365 صالح يدويًا أو استخدم مسار مستخدم بدون ترخيص إذا كان ذلك مدعومًا.