بناء وكيل 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 + الأذونات القابلة للوراثة
• تعيين نقطة نهاية الرسائل في إطار عمل البوت تشير إلى AWS
• إنشاء هوية الوكيل + مستخدم الوكيل
• (اختياري) النشر إلى أسطح تطبيقات Microsoft 365
• تفاعلات الاختبار من طرف إلى طرف

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

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

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

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

• حساب Microsoft Entra مع:

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

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

• تم تثبيت واجهة الأوامر CLI لعامل 365

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

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

• حساب AWS مع الأذونات المناسبة
• تفعيل الوصول إلى AWS Elastic Beanstalk
• تم تثبيت وتكوين AWS CLI
• تم تثبيت وحدة CLI من Elastic Beanstalk

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

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

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

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

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

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

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

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

تصف التعليمات التالية كيفية إنشاء وكيل أدنى يقول:

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

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

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

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

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

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

• الحد الأدنى من واجهة برمجة تطبيقات الويب ASP.NET Core
• معالج رسائل إطار عمل الروبوت على /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 لإيقاف الخادم المحلي.

إنشاء ونشر

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

• Option A: إنشاء ونشر من Visual Studio
• الخيار ب: الإنشاء والنشر إلى AWS Elastic Beanstalk مع CLI

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

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

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

2. اختر النشر إلى AWS Elastic Beanstalk.

3. تابع معالج نشر Beanstalk:

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

4. حدد نشر.

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

الخيار ب: البناء والنشر على AWS Elastic Beanstalk باستخدام CLI

استخدم Elastic Beanstalk CLI لحزم ونشر عامل .NET إلى بيئة Amazon Linux 2 64 بت. تأكد من أن CLI لـ AWS و CLI لـ EB قد تم تكوينهما. يرتبط التطبيق بمتغير البيئة الذي PORT يحدده Beanstalk.

1. إنشاء تطبيق .NET ونشره:

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

   أنشئ ملف تجريبي يحتوي على المحتوى التالي.

   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 Dev Tools.

ملاحظة

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

تكوين الاستضافة خارج بيئة Azure

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

Important

بالنسبة إلى الاستضافة غير التابعة messagingEndpoint ل Azure، قم بتعيين القيمة إلى عنوان 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

وكيل Build 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

اعتمادا على بيئتك، يمكنك اختبار وكيل التأمين من أسطح مختلفة:

• ملعب الوكلاء
• الفرق (إذا نشرت)
• العميل شيل
• الأسطح الموحدة

يمكنك إرسال رسائل والتحقق من سجلات Elastic Beanstalk الخاصة بك. تعلم كيفية اختبار الوكلاء باستخدام Microsoft Agent 365 SDK والتحقق من وظائف وكيلك باستخدام أداة اختبار 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

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

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

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

Tip

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