تم كتابة الدليل السريع لخدمة Microsoft Foundry Agent Service بلغة Python. وهي تخفي تعقيدات Azure التقنية داخل هياكل برمجية كثيفة لدرجة أنه يمكنك إنهاء البرنامج التعليمي دون معرفة الموارد التي تم إنشاؤها بالفعل. إذا كنت تبني باستخدام .NET، فستبدأ بعائق: العينات تشير إلى الاتجاه الخاطئ، وتتغير أسماء الحزم دون سابق إنذار، كما أن إعادة العلامة التجارية الأخيرة من Azure AI Foundry إلى Microsoft Foundry تركت مجموعتين من الوثائق تتنافسان في نتائج البحث.

لقد قمت مؤخراً ببناء أول عميل (agent) لي باستخدام C#. تعمل الخدمة بشكل جيد بمجرد إزالة الضجيج وفصل الخطوات الأساسية عن ارتباك إصدارات المعاينة (preview). إليك خارطة الطريق التي تمنيت لو كانت لدي في اليوم الأول.

الموارد الأربعة التي تحتاجها فعلياً

لا تحتاج إلى عشرات خدمات Azure لتشغيل Prompt Agent أساسي. أنت بحاجة إلى أربعة أشياء بالضبط، وتجعل واجهة CLI هذه الموارد مرئية بطريقة لا توفرها دفاتر ملاحظات Python.

أولاً، مورد Foundry بنوع AIServices. يعمل هذا كمساحة السعة الأم للموديلات التي ستستدعيها. ثانياً، project داخل هذا المورد. المشروع هو النطاق الذي توجد فيه تعريفات العميل الخاص بك، وخيوط المحادثة (conversation threads)، وإعدادات النشر. ثالثاً، deployed model. بدون نشر نشط، لن يكون لدى العميل نقطة نهاية (endpoint) لاستدعائها. رابعاً، role assignment لهويتك الخاصة حتى يتمكن SDK من المصادقة مقابل المشروع.

هذا كل شيء. لا حاجة لعنقود Kubernetes، ولا حوسبة مخصصة، ولا ذاكرة تخزين مؤقت Redis مدارة يدوياً لسجل المحادثات.

Prompt Agents مقابل Hosted Agents

تمنحك Foundry طريقتين لتشغيل العملاء. لا تذهب تلقائياً إلى الخيار الأكثر تعقيداً.

Prompt Agents هي المسار الأبسط. تختار الموديل، وتكتب تعليمات النظام، وتقوم Foundry بتشغيل العميل نيابة عنك. أنت لا تدير الحوسبة، أو الحاويات (containers)، أو منطق التوجيه (routing logic). هذا الخيار يناسب الأدوات الداخلية، وروبوتات المساعدة، والإجابة المباشرة على الأسئلة بناءً على المستندات.

Hosted Agents تتطلب منك كتابة كود التطبيق، وتغليفه كحاوية، وربطه بـ Foundry. اختر هذا المسار فقط عندما تحتاج إلى منطق أعمال مخصص لا تستطيع Foundry التعبير عنه من خلال الأوامر (prompts) والأدوات المدمجة، مثل استدعاء API داخلي باستخدام مصادقة غير قياسية.

يركز هذا الدليل على Prompt Agents لأنها أسرع طريقة للتحقق من صحة إعداد .NET الخاص بك قبل الاستثمار في ملفات Docker وعمليات التنسيق (orchestration).

الإعداد عبر سطر الأوامر

استخدام CLI يجبرك على رؤية كل مورد، وهو بالضبط ما يخفيه الدليل السريع الخاص بـ Python. قم بإنشاء مجموعة موارد في East US 2. اختيار المنطقة أمر مهم هنا؛ حيث تقوم Foundry بإطلاق دعم الأدوات بشكل غير متساوٍ، وتضم منطقة East US 2 حالياً أوسع مجموعة من الأدوات. إذا اخترت منطقة تفتقر إلى مفسر الأكواد (code interpreter) أو أدوات البحث في الملفات، فستفشل عملية إنشاء العميل مع خطأ غامض حول قدرات غير مدعومة.

قم بإنشاء مورد Foundry باستخدام العلم --allow-project-management. بدون هذا العلم، سيبقى المورد نقطة نهاية لخدمات معرفية مستقلة ولن يقبل عمليات النشر المرتبطة بالمشروع والتي يتطلبها العملاء. بعد ذلك، قم بإنشاء المشروع، وانشر الموديل الخاص بك، وقم بتعيين دور Foundry User لنفسك.

استخدم GUID المستقر للدور بدلاً من الاسم المعروض:

53ca6127-db72-4b80-b1b0-d745d6d5456d

تنتشر أسماء الأدوار عبر Azure Active Directory بسرعات مختلفة اعتماداً على المستأجر (tenant). قد ترى إحدى المؤسسات دور Foundry User في البوابة اليوم، بينما لن تراه مؤسسة أخرى إلا بعد أيام. يشير GUID مباشرة إلى التعريف ولن يفشل أثناء عملية النشر. هذا التفصيل الصغير يمكن أن يوفر عليك ساعة من تصحيح أخطاء "رفض الإذن" (permission-denied) التي تبدو وكأنها مشاكل في السياسات ولكنها في الواقع مشاكل في حل التسميات (label-resolution).

تجنب حزمة NuGet الخاطئة

هنا يقع مطورو .NET في الخطأ غالباً. سترى إشارات إلى Azure.AI.Projects.OpenAI في مقتطفات برمجية قديمة. هذه الحزمة مخصصة للمعاينة فقط، وتتداخل مع Azure.AI.Extensions.OpenAI. كلاهما يحدد طرق التوسيع (extension methods) والأنواع في مساحات أسماء (namespaces) متشابهة. إذا قمت بتثبيتهما جنباً إلى جنب، فسيتعطل البناء (build) مع أخطاء مراجع غامضة (ambiguous reference errors) التي