Deploy agent to Azure

هام

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

لقد بنيت وكيلك واختبرته محليا - الآن حان الوقت لإعادته إلى الحياة في السحابة. هذه الخطوة اختيارية ويمكن تخطيها إذا كنت قد نشرت وكيلك بالفعل على سحابة (لا تحتاج حتى أن تكون Azure).

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

هناك أيضا موارد متاحة لتوضيح كيفية تحديث نقطة نهاية الرسائل إذا كنت قد نشرت وكيلك بالفعل إلى مزودي خدمات سحابية آخرين مثل Amazon Web Services أو Google Cloud Platform، بدلا من Azure:

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

قبل أن تبدأ، تأكد من أن لديك الإعداد التالي:

الحسابات والأذونات المطلوبة

اشتراك Azure مع إمكانية الوصول إلى المساهم.
كود وكيل يعمل مع نقطة نهاية رسائل صالحة وقابلة للوصول. تأكد من أنك اختبرت وكيل الوكيل محليا وتم اختباره اختياريا باستخدام Microsoft 365 باستخدام أنفاق التطوير للتحقق من إمكانية بناء كود الوكيل وتشغيله كما هو متوقع.
أكمل خطوة مخطط وكيل الإعداد للحصول على مخطط وكيل صالح.
تأكد من تحديث ملفات a365.config.jsonالتكوين وملف a365.generated.config.json الإعدادات في الكود (مثل ملف .env).

الأَدَوَات المطلوبة

تثبيت Azure CLI ومصادقته (تثبيت Azure CLI)
A365 CLI تم التثبيت (Agent 365 CLI)

نشر في Azure

a365 deploy للأمر أمران فرعيان:

a365 deploy app - ينشر كود الوكيل الخاص بك على تطبيق الويب Azure الذي تم إنشاؤه أثناء الإعداد.
a365 deploy mcp - يحدث صلاحيات خادم MCP على مخطط الوكيل الخاص بك.

يركز هذا الدليل على نشر كود تطبيق الوكيل الخاص بك على Azure.

تطبيق وكيل النشر

شغل الأمرa365 deploy:

a365 deploy

خيارات النشر

يدعم أمر النشر عدة خيارات مفيدة:

خيار	Description	حالة الاستخدام
`--dry-run`	يوضح ما سيتم نشره بدون تنفيذ	معاينة خطوات النشر قبل التشغيل
`--inspect`	يتوقف قبل النشر لفحص مجلد النشر ومحتويات ZIP	مشاكل حزم نشر التصحيح
`--restart`	يتخطى البناء ويضغط مجلد النشر الحالي	تكرار سريع بعد التغييرات اليدوية
`-v`، `--verbose`	تمكين تسجيل التفاصيل	استكشاف مشاكل النشر
`-c`، `--config`	يحدد مسار ملف التهيئة المخصص	استخدام تكوين غير افتراضي

إشعار

استخدم a365 deploy --help لرؤية جميع الخيارات والأوامر الفرعية المتاحة.

مثال على النشر

# Preview what will be deployed
a365 deploy --dry-run

# Deploy with verbose logging for troubleshooting
a365 deploy --verbose

# Inspect the deployment package before uploading
a365 deploy --inspect

كيفية عمل التوزيع

النشر يعمل بشكل مختلف حسب لغة البرمجة التي تستخدمها.

أمر النشر لوكلاء .NET:

الكشف عن ملفات مشروع .NET (*.csprojأو *.fsprojأو *.vbproj)
استعادة حزم NuGet باستخدام dotnet restore
ينشر التطبيق باستخدام dotnet publish تكوين الإصدار
ينشئ بيان Oryx باستخدام أمر DLL نقطة الدخول (على سبيل المثال، dotnet YourApp.dll)
تكوين وقت تشغيل Azure استنادا إلى إصدار .NET المكتشف (الافتراضي: DOTNET|8.0)
يتم النشر عبر zip مع تقدم في الوقت الحقيقي

أمر التوزيع لعوامل Python:

الكشف عن بنية مشروع Python (pyproject.tomlوالملفاتrequirements.txt)*.py
يبني الحزم باستخدام uv build إذا pyproject.toml كان موجودا
.env التحويل إلى إعدادات تطبيق Azure تلقائيا
يستخدم كشف بدء التشغيل الذكي للعثور على نقاط دخول Agent 365
يتم النشر عبر zip مع تقدم في الوقت الحقيقي

أمر التوزيع لوكلاء Node.js:

يكتشف Node.js بنية المشروع (package.json ملف)
يثبت التبعيات باستخدام npm ci (إذا npm install لزم الأمر)
تشغيل البرنامج النصي للبناء (npm run build) إذا تم تعريفه في package.json
نسخ ملفات التطبيق: الإخراج المضمن (dist/build) أو ملفات المصدر
نسخ للنشر على Azure
ينشئ تجسيد أوريكس مع أمر بدء من package.json (أو يكتشف نقطة الدخول)
تكوين وقت تشغيل Azure استنادا إلى إصدار العقدة المكتشفة (الافتراضي: NODE|18)
يتم النشر عبر zip مع تقدم في الوقت الحقيقي

Warning

إدارة الأسرار: عند النشر، قم بتخزين متغيرات البيئة (بما في ذلك مفاتيح API والأسرار) كإعدادات تطبيقات Azure. بينما تستخدم متغيرات البيئة عادة في الإعدادات، إلا أنها تخزن بنص عادي. لبيئات الإنتاج، استخدم Azure Key Vault للأسرار الحساسة. تعرف على المزيد حول التخزين الآمن لأسرار التطبيقات قيد التطوير في مزود تكوين ASP.NET Core وAzure Key Vault. لا تقم أبداً بإيداع .env الملفات ذات المعلومات الحساسة في نظام التحكم في المصدر.

التحقق من النشر

بعد انتهاء النشر، استخدم هذه القائمة والتعليمات أدناه للتحقق من النشر

✅ تم إكمال أمر النشر بدون أخطاء
✅ تطبيق ويب يعمل
✅ تظهر سجلات التطبيقات نجاح بدء التشغيل
✅ يتم تكوين متغيرات البيئة
✅ تستجيب نقطة نهاية الرسائل

تحقق من أمر النشر الذي اكتمل بدون أخطاء

عند تشغيل أمر النشر يجب أن ترى:

✓ Build completed successfully
✓ Deployment completed successfully

يجب أن ترى أيضا النجاح في سجلات النشر:

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

للاطلاع على تاريخ النشر التفصيلي:

Navigate to Azure Portal > Your Web App
النشر>مركز النشر
عرض سجلات أحدث نشر لك

إذا فشل البناء:

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

إذا تعطل التطبيق بعد النشر:

تحقق من السجلات بحثا عن رسائل خطأ محددة.
تحقق من أن جميع المتغيرات الضرورية في البيئة محددة.
انظر تعطل التطبيقات عند بدء التشغيل.

تحقق من تشغيل تطبيق الويب

استخدم الأمرaz webapp show للتحقق من تشغيل تطبيق الويب.

az webapp show --name <your-web-app> --resource-group <your-resource-group> --query state

الخرج المتوقع لهذا الأمر هو Running.

تحقق من أن سجلات التطبيقات تظهر نجاح بدء التشغيل

لعرض سجلات تطبيقات الويب في بوابة Azure:

ابحث عن تطبيق الويب بالاسم في بوابة Azure.
اذهب إلى مرور>السجلات>على تدفق السجلات.

بدلا من ذلك، يمكنك استخدام أمر PowerShell az webapp log tail لقراءة سجلات تطبيقات الويب:

az webapp log tail --name <your-web-app> --resource-group <your-resource-group>

إذا ظهرت رسائل تعطل أو أخطاء في السجلات، راجع تعطل التطبيقات عند بدء التشغيل.

تحقق من تكوين متغيرات البيئة

In Azure portal:

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

إذا لم تكن متغيرات البيئة محددة:

أعد تشغيل النشر للمزامنة من .env الملف.
أو يتم ضبطه يدويا في Azure Portal.
انظر متغيرات البيئة غير محددة أو غير صحيحة.

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

اختبر أن نقطة النهاية التي تجدها في صفحة نظرة عامة على تطبيق الويب موجودة عبر Powershell أو أي وسيلة أخرى. بخلاف ذلك، راجع 404 في نقطة نهاية المراسلة.

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

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

انشر وكيلك

وكيلك الآن موجود في السحابة وجاهز للرد على طلبات الوكلاء. بينما يتعامل وكيلك مع الطلبات الواقعية، فكر في الخطوات التالية لكودك:

مراقبة الأداء: استخدم ميزات الملاحظة لتتبع سلوك الوكلاء وتحسين الاستجابات.
أضف المزيد من الأدوات: استكشف كتالوج الأدوات لتوسيع قدرات وكيلك.
قم بالتكرار والتحسين: قم بتحديث كود الوكيل، وأعد النشر، وأعد النشر (تذكر زيادة رقم الإصدار!).
توسع عبر منظمتك: شارك قصص نجاح وكيلك لتحفيز التبني.

Troubleshooting

يصف هذا القسم المشاكل الشائعة عند نشر الوكلاء إلى Azure.

Tip

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

فشل أمر النشر

عَرَض: خطأ أثناء a365 deploy تنفيذ الأمر.

الأسباب والحلول الشائعة:

أخطاء البناء

أعد بناء المشروع محليا لرؤية أخطاء التجميع التفصيلية:
```
# .NET
dotnet clean
dotnet build --verbosity detailed

# Python
uv build

# Node.js
npm install
npm run build
```

التكوين المفقود

تأكد من وجود كلا ملفي التكوين وصحتهما:

# Verify configuration files exist
Test-Path a365.config.json
Test-Path a365.generated.config.json

# Display configuration file contents
a365 config display

# Display generated configuration file contents
a365 config display -g

Azure authentication expired

سجل الدخول مرة أخرى إلى Azure:
```
az login
az account show  # Verify correct subscription
```

تطبيق ويب لم يتم إنشاؤه

اذكر تطبيقات الويب للتأكد من وجود الهدف:

# List Web Apps in resource group
az webapp list --resource-group <your-resource-group> --output table

إذا لم يكن هناك تطبيق ويب موجود، قم بتشغيل الإعدادات مرة أخرى:

# Verify setup was completed
a365 config display -g
# Check for: webAppName

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

تحقق من سجلات النشر

استخدم الأمرaz webapp log tail لعرض سجلات النشر التفصيلية:
```
az webapp log tail --name <your-app-name> --resource-group <your-resource-group>
```

التحقق:

# Web App should be running
az webapp show --name <your-app-name> --resource-group <your-resource-group> --query state
# Expected: "Running"

تم إيقاف تطبيق الويب

عَرَض: النشر ناجح لكن تطبيق الويب لا يعمل.

الحل: استخدم az webapp start وقم az webapp show بتشغيل تطبيق الويب وتحقق من تشغيله.

# Start the Web App
az webapp start --name <your-app> --resource-group <your-resource-group>

# Verify it's running
az webapp show --name <your-app> --resource-group <your-resource-group> --query state

تعطل التطبيق عند بدء التشغيل

عَرَض: يبدأ تطبيق الويب لكنه يتعطل فورا؛ السجلات تظهر أخطاء.

الأسباب الشائعة:

التبعيات المفقودة - تحقق من مخرجات البناء شملت جميع الحزم المطلوبة
متغيرات البيئة المفقودة - تحقق من تكوين جميع الإعدادات المطلوبة
عدم تطابق إصدار وقت التشغيل - تأكد من تطابق وقت تشغيل Azure مع بيئة التطوير الخاصة بك
أخطاء الشيفرة - تحقق من سجلات التطبيقات للاستثناءات المحددة

الحل: استخدم أوامر az webapp log tail، az webapp config appsettings list، و az webapp config appsettings set لعرض السجلات، والتحقق من متغيرات البيئة، وتعيين المتغيرات المفقودة.

# View application logs
az webapp log tail --name <your-app> --resource-group <your-resource-group>

# Check environment variables
az webapp config appsettings list --name <your-app> --resource-group <your-resource-group>

# Manually set a missing variable
az webapp config appsettings set --name <your-app> --resource-group <your-resource-group> --settings KEY=VALUE

404 على نقطة نهاية المراسلة

عَرَض: تطبيق ويب يعمل لكن /api/messages نقطة النهاية تعيد 404.

الحل:

تحقق من تكوين المسار في رمز الوكيل الخاص بك.
تحقق من أن معالج نقطة النهاية مسجل بشكل صحيح.
تأكد من تحديد نقطة الدخول الصحيحة أثناء النشر.

اختبر نقطة النهاية بإرسال GET طلب إلى الرابط. استخدم az webapp config show الأمر للتحقق من إعدادات تطبيقات الويب.

curl https://<your-app-name>.azurewebsites.net/api/messages
az webapp config show --name <your-app> --resource-group <your-resource-group>

متغيرات البيئة غير محددة أو غير صحيحة

عَرَض: النشر ينجح لكن الوكيل لا يعمل؛ أخطاء التكوين المفقودة في السجلات.

الحل: تحقق من متغيرات البيئة وحدثها. استخدم أوامر az webapp config appsettings list، و az webapp config appsettings set للتحقق من متغيرات البيئة، وتعيين المتغيرات المفقودة. ثم أعد النشر.

# List all app settings
az webapp config appsettings list --name <your-app> --resource-group <your-resource-group>

# Set a specific variable
az webapp config appsettings set --name <your-app> --resource-group <your-resource-group> --settings API_KEY=your-value

# Re-run deployment (it will update app settings from .env)
a365 deploy

مشاكل حزمة النشر

عَرَض: يتم رفع النشر لكن التطبيق لا يبدأ بشكل صحيح.

الحل: استخدم العلم a365 deploy --inspect لفحص حزمة النشر:

# Inspect what will be deployed
a365 deploy --inspect

هذا العلم يتوقف قبل الرفع، مما يسمح لك ب:

تحقق من محتويات مجلد النشر
تحقق من محتويات ZIP
تأكد من تضمين جميع الملفات

المشاكل الشائعة التي يجب التحقق منها:

مفقود node_modules (Node.js)
ملفات DLL المترجمة المفقودة (.NET)
حزم بايثون المفقودة

البناء ينجح محليا لكنه يفشل في Azure

عَرَض: الكود يبني بشكل جيد على جهازك لكنه يفشل أثناء نشر Azure.

الحلول‏‎:

تحقق من وجود تبعيات خاصة بالمنصة
- بعض الحزم تحتوي على بناءات خاصة بالمنصة.
- تأكد من دعم التبعيات لينكس (تطبيقات الويب Azure تعمل على لينكس بشكل افتراضي).
تحقق من تطابق إصدارات وقت التشغيل

شغَّل هذه الأوامر:
```
# Check your local version
dotnet --version  # .NET
node --version    # Node.js
python --version  # Python
```
قارن مع وقت تشغيل Azure في Portal: الإعدادات>الإعدادات>الإعدادات العامة>إعدادات المكدس.
اختبار باستخدام تسجيل مطول
```
a365 deploy --verbose
```

لمزيد من المساعدة، انظر: استكشاف أخطاء نقطة النهاية عبر المراسلة

الملاحظات

هل كانت هذه الصفحة مفيدة؟

Last updated on 2026-01-30