مشاركة عبر

بناء وكيل Agent 365 يتم نشره في Amazon Web Services (AWS)

هام

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

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

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

الاهداف

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

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

Prerequisites

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

Azure / Microsoft 365 prerequisites

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

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

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

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

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

إنشاء ونشر وكيل .NET

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

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

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

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

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

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

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

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

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

dotnet restore
dotnet build

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

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

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

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

    # Run the application
dotnet run

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

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

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

إنشاء ونشر

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

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

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

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

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

  3. تابع ساحر نشر Beanstalk:

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

  4. حدد Deploy.

يقوم المعالج ببناء وتغليف ونشر تطبيقك على 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

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

    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.

Note

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

Configure for non-Azure hosting

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

هام

بالنسبة للاستضافة غير Azure، قم بتعيين هذه القيم:

  • messagingEndpoint: رابط Elastic Beanstalk الخاص بك مع المسار /api/messages
  • needDeployment false

يجب أن يبدو الملف a365.config.json كالتالي:

{
  "tenantId": "YOUR_TENANT_ID",
  "subscriptionId": "YOUR_AZURE_SUBSCRIPTION_ID",
  "resourceGroup": "a365-aws-demo",
  "location": "westus",
  "environment": "prod",

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

  "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"
}

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

Field معني
messagingEndpoint رابط Elastic Beanstalk الخاص بك + /api/messages
"needDeployment": false يقول لي "أنا أستضيف خادمي الخاص؛ لا تنشر إلى أزور'
deploymentProjectPath أين .env يحدث الختم

وكيل Build Agent 365

بعد أن يعمل كود الوكيل على نقطة نهاية AWS، اتبع الخطوات المتبقية من دورة حياة تطوير الوكيل 365 لإعداد وكيل Agent 365 الخاص بك.

تحقق من الوكيل من البداية إلى الطرف

استخدم هذه الفحوصات للتأكد من أن وكيلك المستضاف من AWS قابل للوصول، ويستقبل أنشطة إطار عمل البوت، ويستجيب بشكل صحيح عبر أسطح 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: { ... }

وكيل الاختبار من أسطح العامل 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

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

Troubleshooting

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

  • Last updated on