البدء السريع: نشر أول وكيل مستضاف لك

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

في هذه البداية السريعة، أنت:

• إعداد project عينة للوكلاء باستخدام أدوات Foundry
• اختبر الوكيل محليا
• النشر إلى خدمة وكلاء المسبك
• تفاعل مع وكيلك في ساحة اللعب
• تنظيف الموارد

المتطلبات المسبقه

قبل أن تبدأ، تحتاج إلى:

• اشتراك Azure - أنشئ واحدا مجانا
• (اختياري) أداة MCP، إذا كان لديك واحدة تريد استخدامها.
• بايثون 3.10 أو أحدث

• Azure مطور CLI الإصدار 1.23.0 أو أقدم
• تم تثبيت وتشغيل Docker Desktop

• Visual Studio Code
• إضافة مايكروسوفت فاوندري لكود فيجوال ستوديو

‏‫ملاحظة‬

الوكلاء المستضفون حاليا في مرحلة المعاينة.

الخطوة 1: إعداد نموذج project

قم بتهيئة project جديد باستخدام قالب Foundry starter وضبطه باستخدام عينة Agent-with-foundry-tools.

1. قم بتهيئة قالب البداية في مجلد فارغ:

   azd init -t https://github.com/Azure-Samples/azd-ai-starter-basic
   

   هذا الأمر التفاعلي يطلب منك اسم بيئة (على سبيل المثال، my-hosted-agent). اسم البيئة يحدد اسم مجموعة الموارد الخاصة بك (rg-my-hosted-agent).

   ‏‫ملاحظة‬

   إذا كانت هناك مجموعة موارد تحمل نفس الاسم موجودة بالفعل، azd provision تستخدم المجموعة الموجودة. لتجنب التعارضات، اختر اسم بيئة فريد أو احذف مجموعة الموارد الموجودة أولا.

2. تهيئة عينة الوكيل:

   azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/agent-with-foundry-tools/agent.yaml
   

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

   • Azure subscription - اختر اشتراك Azure الذي تريد إنشاء موارد Foundry فيه.
   • الموقع - اختر منطقة للموارد
   • نموذج SKU - اختر النسخة المتوفرة لمنطقتك واشتراكك
   • اسم النشر - أدخل اسما لنشر النموذج
   • ذاكرة الحاوية - أدخل قيمة لتخصيص الذاكرة للحاوية أو قبول الإعدادات الافتراضية
   • وحدة المعالجة المركزية الحاوية - أدخل قيمة لتخصيص وحدة المعالجة المركزية للحاوية أو قبول الإعدادات الافتراضية
   • الحد الأدنى للنسخ - أدخل قيمة للنسخ الدنيا من الحاوية
   • أقصى نسخ - أدخل قيمة لأكبر عدد من النسخ المقلدة للحاوية

   مهم

   إذا لم تكن تستخدم خادم MCP، أو قم بإزالة الأسطر التالية من agent.yaml الملف:

   - name: AZURE_AI_PROJECT_TOOL_CONNECTION_ID
     value: <CONNECTION_ID_PLACEHOLDER>
   

3. توفير الموارد المطلوبة ل Azure:

   ‏‫ملاحظة‬

   تحتاج إلى Contributor access على اشتراك Azure الخاص بك لتوفير الموارد.

   azd provision
   

   يستغرق هذا الأمر حوالي 5 دقائق وينشئ الموارد التالية:

   مورد	الغرض	التكلفة
   مجموعة الموارد	ينظم جميع الموارد ذات الصلة في نفس المنطقة	بلا تكلفة
   نشر النموذج	النموذج المستخدم من قبل الوكيل	انظر Foundry تسعير
   مشروع المسبك	يستضيف وكيلك ويوفر قدرات الذكاء الاصطناعي	يعتمد على الاستهلاك؛ انظر Foundry preciing
   Azure Container Registry	يخزن صور حاوية الوكيل الخاصة بك	المستوى الأساسي؛ انظر <تسعير ACR>
   مساحة عمل Log Analytics	إدارة جميع بيانات السجل في مكان واحد	لا تكلفة مباشرة. انظر Log Analytics Cost
   Application Insights	يراقب أداء الوكيل والسجلات	الدفع حسب الاستخدام؛ انظر Azure تسعير الشاشة
   الهوية المُدارة	توثيق وكيلك لصالح خدمات Azure	بلا تكلفة

   نصيحة

   شغل azd down عندما تنتهي من هذه البداية السريعة لحذف الموارد ومنع تحمل الرسوم.

الخطوة 2: اختبر الوكيل محليا

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

1. إنشاء وتفعيل بيئة افتراضية بلغة بايثون:

   باش:

   python -m venv .venv
   source .venv/bin/activate
   

   باور شيل:

   python -m venv .venv
   .venv\Scripts\Activate.ps1
   

2. تثبيت التبعيات:

   pip install -r ./src/af-agent-with-foundry-tools/requirements.txt
   

3. انسخ المتغيرات البيئية المطلوبة المستخدمة في كود الوكيل إلى ملف .env محلي:

   باش:

   azd env get-values > .env
   

   باور شيل:

   azd env get-values > .env
   

4. أضف المتغير AZURE_OPENAI_CHAT_DEPLOYMENT_NAME إلى ملفك .env مع اسم نشر النموذج:

   AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="gpt-4.1"

5. شغل الوكيل محليا:

   python ./src/af-agent-with-foundry-tools/main.py
   

   إذا فشل الوكيل في التشغيل، تحقق من هذه المشاكل الشائعة:

   Error	حل
   AuthenticationError أو DefaultAzureCredential الفشل	قم بالعمل azd auth login مرة أخرى لتجديد جلستك.
   ResourceNotFound	تحقق من تطابق عناوين نقاط النهاية الخاصة بك مع القيم الموجودة في بوابة Foundry.
   DeploymentNotFound	تحقق من اسم النشر في قسم البناء>.
   Connection refused	تأكد من عدم استخدام أي عملية أخرى في المنفذ 8088.

6. اختبر مع عميل REST. يعمل الوكيل على:localhost:8088

   باش:

   curl -X POST http://localhost:8088/responses \
       -H "Content-Type: application/json" \
       -d '{"input": "What is Microsoft Foundry?"}'
   

   باور شيل:

   Invoke-RestMethod -Method Post `
       -Uri "http://localhost:8088/responses" `
       -ContentType "application/json" `
       -Body '{"input":"What is Microsoft Foundry?"}'
   

   يجب أن ترى ردا بنتائج بحث ويب حول Microsoft Foundry.

7. أوقف الخادم المحلي باستخدام Ctrl+C.

الخطوة 3: النشر إلى خدمة وكلاء المسبك

أمر azd up يجمع بين ثلاث خطوات في خطوة واحدة: توفير البنية التحتية، تغليف تطبيقك، ونشره على Azure. وهذا يعادل تشغيل azd provision، azd package، و azd deploy بشكل منفصل.

قبل أن تبدأ، تحقق من أن Docker Desktop يعمل:

docker info

إذا فشل هذا الأمر، شغل Docker Desktop وانتظر حتى يتم تهيئته قبل المتابعة.

نشر عميلك:

azd up

النشر الأول سيستغرق وقتا أطول لأن Docker يحتاج لبناء الصورة.

تحذير

وكيلك المستضاف يتحمل رسوما أثناء النشر. بعد الانتهاء من الاختبار، أكمل موارد تنظيف لحذف الموارد وإيقاف الرسوم.

عند الانتهاء، سترى رابطا إلى ملعب الوكيل ونقطة النهاية للوكيل يمكن استخدامها لاستدعاء الوكيل برمجيا.

Deploying services (azd deploy)

  (✓) Done: Deploying service af-agent-with-foundry-tools
  - Agent playground (portal): https://ai.azure.com/nextgen/.../build/agents/af-agent-with-foundry-tools/build?version=1 
  - Agent endpoint: https://ai-account-<name>.services.ai.azure.com/api/projects/<project>/agents/af-agent-with-foundry-tools/versions/1

الخطوة 1: إنشاء مشروع مسبك

استخدم إضافة Microsoft Foundry في VS Code لإنشاء مورد جديد لمشروع Microsoft Foundry.

1. افتح لوحة الأوامر (Ctrl+Shift+P) واختر Microsoft Foundry: إنشاء مشروع.

2. حدد اشتراك Azure الخاص بك.

3. أنشئ مجموعة موارد جديدة أو اختر مجموعة موجودة.

4. أدخل اسما لمورد مشروع Foundry.

بمجرد اكتمال إنشاء المشروع، تابع إلى الخطوة التالية ونشر نموذج.

الخطوة 2: نشر نموذج

استخدم إضافة Microsoft Foundry في VS Code لنشر نموذج على Foundry.

1. افتح لوحة الأوامر (Ctrl+Shift+P) واختر Microsoft Foundry: Open Model Catalog.

2. تصفح كتالوج النماذج أو ابحث عن gpt-4.1 واختر زر النشر .

3. في صفحة نشر النماذج، اختر زر النشر إلى مايكروسوفت فاوندري .

بمجرد نشر النموذج بنجاح، انتقل إلى الخطوة التالية وأنشئ مشروع وكيل مستضاف

الخطوة 3: إنشاء مشروع وكيل مستضاف

استخدم إضافة Microsoft Foundry في VS Code لدعم مشروع وكيل مستضاف جديد.

1. افتح لوحة الأوامر (Ctrl+Shift+P) واختر Microsoft Foundry: إنشاء وكيل مستضاف جديد.

2. اختر إما قالب سير عمل الوكيل الواحد أو متعدد الوكلاء

3. اختر لغة برمجة، بايثون أو C#‎.

4. اختر نموذج gpt-4.1 الحالي الذي نشرته في الخطوة السابقة.

5. اختر المجلد الذي تريد حفظ ملفات مشروعك فيه.

6. أدخل اسم الوكيل المستضاف.

سيتم تشغيل نافذة VS Code جديدة مع مجلد مشروع الوكيل الجديد كمساحة عمل نشطة.

الخطوة 4: تثبيت التبعيات

يوصى باستخدام بيئة افتراضية لعزل تبعيات المشروع:

ماك أو إس/لينكس:

python -m venv .venv
source .venv/bin/activate

ويندوز (PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1

تثبيت التبعيات

تثبيت الاعتماديات المطلوبة على بايثون باستخدام pip:

pip install -r requirements.txt

الحزم المطلوبة هي:

• azure-ai-agentserver-agentframework - إطار عمل الوكلاء وحزمة تطوير AgentServer

الخطوة 5: اختبر الوكيل محليا

قم بتشغيل واختبار وكيلك قبل النشر.

الخيار 1: اضغط على F5 (موصى به)

اضغط F5 في VS Code لبدء التصحيح. بدلا من ذلك، يمكنك استخدام قائمة تصحيح أخطاء VS Code:

1. افتح عرض التشغيل والتصحيح (Ctrl+Shift+D / cmd+Shift+D)
2. اختر "تصحيح سير العمل المحلي HTTP Server" من القائمة المنسدلة
3. اضغط على زر بدء تصحيح الأخطاء الأخضر (أو اضغط F5)

سيؤدي ذلك إلى:

1. شغل خادم HTTP مع تفعيل التصحيح
2. افتح أداة AI Toolkit Agent Inspector للاختبار التفاعلي
3. تسمح لك بتعيين نقاط توقف وفحص سير العمل

الخيار الثاني: تشغيل المحطة

التشغيل كخادم HTTP (الافتراضي):

python main.py

سيبدأ هذا الوكيل المستضاف محليا على http://localhost:8088/.

PowerShell (ويندوز):

$body = @{
   input = "I need a hotel in Seattle from 2025-03-15 to 2025-03-18, budget under `$200 per night"
    stream = $false
} | ConvertTo-Json

Invoke-RestMethod -Uri http://localhost:8088/responses -Method Post -Body $body -ContentType "application/json"

باش/كيرل (لينكس/ماك أو إس):

curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/responses \
   -d '{"input": "Find me hotels in Seattle for March 20-23, 2025 under $200 per night","stream":false}'

سيستخدم الوكيل الأداة get_available_hotels للبحث عن فنادق متاحة تتوافق مع معاييرك.

الخطوة 6: النشر إلى خدمة وكلاء المسبك

قم بنشر وكيلك مباشرة من VS Code.

1. افتح لوحة الأوامر (Ctrl+Shift+P) واختر Microsoft Foundry: نشر الوكيل المستضاف.

2. اختر تكوين وحدة المعالجة المركزية والذاكرة لحاوية الوكيل المستضاف.

3. في مربع الحوار الذي يظهر، اختر زر التأكيد والنشر.

انتقل إلى مستكشف مايكروسوفت فاوندري باختيار الأيقونة على اليسار. يظهر الوكيل في شريط جانبي عرض شجرة الوكلاء المستضافين (المعاينة) بعد اكتمال النشر.

تحقق من وكيلك واختبر

بعد انتهاء النشر، تحقق من أن وكيلك يعمل.

تحقق من حالة الوكيل

تحقق من حالة وكيلك للتأكد من أنه يعمل.

1. اختر وكيل الاستضافة الخاص بك من عرض شجرة الوكلاء المستضافين (المعاينة).

2. اختر نسخة (v1) لفتح صفحة التفاصيل.

تظهر صفحة التفاصيل الحالة تحت قسم تفاصيل الحاويات.

اختبار في ساحة اللعب باستخدام كود VS

تتضمن Microsoft Foundry ل VS Code ملعب مدمج للدردشة والتفاعل مع وكيلك.

1. اختر وكيل الاستضافة الخاص بك من عرض شجرة الوكلاء المستضافين (المعاينة).

2. اختر نسخة (v1) لفتح صفحة التفاصيل.

3. اختر خيار Playground واكتب رسالة وأرسل لاختبار وكيلك.

اختبار في ملعب المصنع

انتقل إلى الوكيل في بوابة المصنع:

1. افتح بوابة Foundry وسجل الدخول بحسابك Azure.

2. اختر project من قائمة المشاريع الأخيرة، أو اختر All projects للعثور عليه.

3. في التنقل الأيسر، اختر البناء لتوسيع القائمة، ثم اختر الوكلاء.

4. في قائمة الوكلاء، ابحث عن وكيل النشر (يتطابق مع اسم الوكيل من النشر).

5. اختر اسم الوكيل لفتح صفحة تفاصيله، ثم اختر فتح في ساحة الألعاب في شريط الأدوات العلوي.

6. في واجهة الدردشة، اكتب رسالة اختبار مثل "ما هو Microsoft Foundry؟" واضغط Enter.

7. تحقق من أن الوكيل يرد بمعلومات من نتائج البحث على الويب. قد يستغرق الرد بضع ثوان بينما يستفسر الوكيل عن مصادر خارجية.

نصيحة

إذا لم يتم تحميل الملعب أو لم يرد الوكيل، تحقق من حالة Started الوكيل باستخدام صفحة تفاصيل الحاوية الموضحة أعلاه.

تنظيف الموارد

لتجنب الرسوم، احذف الموارد عندما تنتهي.

تحذير

يقوم هذا الأمر بحذف جميع موارد Azure التي تم إنشاؤها في هذه البداية السريعة بشكل دائم، بما في ذلك Foundry project، وسجل الحاويات، وApplication Insights، ووكيل الاستضافة الخاص بك. لا يمكن التراجع عن هذا الإجراء.

لمعاينة ما سيتم حذفه قبل التأكيد:

azd down --preview

عندما تكون مستعدا للحذف، قم بتشغيل:

azd down

تستغرق عملية التنظيف حوالي 2-5 دقائق.

تحذير

حذف الموارد يزيل بشكل دائم جميع موارد Azure التي تم إنشاؤها في هذه البداية السريعة، بما في ذلك مشروع Foundry، سجل الحاويات، Application Insights، ووكيل الاستضافة الخاص بك. لا يمكن التراجع عن هذا الإجراء.

لحذف مواردك، افتح بوابة Azure، انتقل إلى مجموعة الموارد الخاصة بك، واحذفها مع جميع الموارد المحتواة.

للتحقق من حذف الموارد، افتح بوابة Azure، واذهب إلى مجموعة الموارد الخاصة بك، وتأكد من أن الموارد لم تعد تظهر. إذا كانت مجموعة الموارد فارغة، يمكنك حذفها أيضا.

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

إذا واجهت مشاكل، جرب هذه الحلول للمشاكل الشائعة:

مشكلة	حل
أخطاء بناء دوكر	تأكد من تشغيل Docker Desktop. ركض docker info للتحقق.
خطأ SubscriptionNotRegistered	مزودو التسجيل: az provider register --namespace Microsoft.CognitiveServices
AuthorizationFailed أثناء التموين	اطلب دور المساهم في اشتراكك أو مجموعة الموارد الخاصة بك.
الوكيل لا يبدأ محليا	تحقق من تعيين متغيرات البيئة وتشغيلها az login لتحديث بيانات الاعتماد.
خطأ AcrPullUnauthorized	منح دور AcrPull لهوية project المدارة في سجل الحاويات.

مشكلة	حل
azd init الفشل	شغل azd version اللعبة للتحقق من الإصدار 1.23.0+. قم بالتحديث باستخدام winget upgrade Microsoft.Azd (ويندوز) أو brew upgrade azd (macOS).
نموذج غير موجود في الكتالوج	قم بتقسيم نموذج agent.yaml وغير نشر النموذج إلى نموذج متاح في اشتراكك مثل gpt-4.1. ثم قم بإزالة قيمة AZURE_LOCATION من ملف .azure/<environment name>/.env. أعد تشغيل azd ai agent init الأمر مع ملفك المجمع agent.yaml .

عرض سجلات الحاويات الخاصة بوكيلك

يمكنك التحقق من سجلات الجهاز والنظام في الحاوية لاستكشاف المشاكل.

1. اختر وكيل الاستضافة الخاص بك من عرض شجرة الوكلاء المستضافين (المعاينة).

2. اختر نسخة (v1) لفتح صفحة التفاصيل.

3. اختر زر السجلات على اليمين لفتح عارض السجلات.

مشكلة	حل
لم يتم العثور على امتداد	قم بتثبيت إضافة Microsoft Foundry for VS Code من سوق VS Code.

ما تعلمته

في هذه البداية السريعة، قمت بـ:

• قم بإعداد عينة وكيل مستضاف باستخدام أدوات Foundry (البحث على الويب وMCP)
• اختبرت الوكيل محليا
• تم نشره في خدمة وكلاء المسبك
• تحقق من وكيلك في ساحة اللعب في Foundry

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

الآن بعد أن نشرت أول وكيل مستضاف لك، تعلم كيف:

إدارة دورة حياة الوكيل المستضاف

خصص وكيلك بقدرات إضافية:

• Connect أدوات MCP لتوسيع وظائف الوكيل
• استخدم استدعاء الدوال لتكامل المنطق المخصص
• أضف البحث عن الملفات للبحث في مستنداتك
• تمكين مفسر الكود لتشغيل كود بايثون

يمكنك رؤية القائمة الكاملة للأدوات المتاحة في مقال كتالوج الأدوات .

المحتوى ذو الصلة

• ما هي الوكلاء المستضافون؟
• نشر وكيل مستضاف
• دورة حياة تطوير الوكيل
• بايثون استضاف عينات الوكلاء