Machine Learning Mastery يستعرض كيفية بناء وكلاء ذكاء اصطناعي بلغة Python باستخدام Pydantic AI

نشر Machine Learning Mastery بتاريخ 29 أبريل 2026 تحليلًا مفصلًا لـ Pydantic AI، وهو إطار عمل بلغة Python لبناء وكلاء الذكاء الاصطناعي، يوفّر التنميط (typing) والتحقق من الصحة (validation) وأدوات مدمجة. ويوضح المقال كيف يمكن تحويل العمل مع LLM من مجموعة نصوص ومحلِّلات (parsers) هشة إلى عملية إنتاجية (production) أكثر قابلية للتنبؤ.

لماذا يهم هذا الأمر

الفكرة الرئيسية للمقال بسيطة: لا تزال معظم هياكل ربط الوكلاء أشبه بـ glue code. يُرجع النموذج سلسلة نصية، ويأمل المطوّر أن تحتوي JSON صحيحًا، ثم يحلّل الرد يدويًا، ويلتقط الأخطاء، ويضيف معالجة للاستثناءات في كل خطوة.

يقترح Pydantic AI مسارًا مختلفًا. فبدلًا من الردود غير المنظَّمة، يبني العمل حول نماذج Pydantic والمخططات (schemas) وفحص الأنواع وإعادة المحاولة تلقائيًا إذا لم يطابق خرج النموذج البنية المتوقعة. وبالنسبة لمطوّري Python، يعني ذلك سحرًا أقل وشيفرة أكثر قابلية للاختبار والقراءة والصيانة.

ويُبرز المقال ذلك بدءًا من أبسط مثال: يُنشأ الوكيل في بضعة أسطر فقط، ويُحدَّد النموذج بسلسلة بصيغة provider:model-name. يستخدم المؤلف openai:gpt-4o-mini، لكنه يؤكد بشكل منفصل أن القالب نفسه يعمل مع مزوّدين آخرين، منهم Anthropic وGemini. وتُحدَّد تعليمات الوكيل مرة واحدة، ثم يمكن تشغيله إما بسيناريو متزامن عبر run_sync أو بنسخة غير متزامنة بالواجهة البرمجية نفسها. وبذلك يبقى حاجز الدخول منخفضًا، ولا تنهار البنية عند أول تعقيد في المنطق.

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

أكثر أجزاء المقال فائدة هو شرح أربع آليات يقوم عليها سير عمل الوكيل العملي في Pydantic AI. لا يغرق المؤلف في التجريد، ولا يصف الإطار بلغة الوعود: كل عنصر مصحوب بمثال برمجي قصير وشرح لكيفية معالجته مشكلة محددة في تطوير بيئات الإنتاج، دون نظرية زائدة. ونتيجة لذلك يُقرأ المقال كخريطة للحد الأدنى من الحلول اللازمة لبناء أول وكيل عامل بلغة Python.

• يُلزم output_type النموذج بإرجاع البيانات في شكل كائن Python مُتحقَّق منه، بدلًا من نص حر.
• يحوّل @agent.tool_plain دالة Python عادية إلى أداة يستطيع الوكيل استدعاءها أثناء استدلاله.
• يوفّر deps_type وRunContext حقنًا للتبعيات دون حالة عامة (global state) ودون تبعيات خفية.
• تضيف capabilities قدرات إضافية مثل WebSearch وThinking دون إثقال المُنشئ (constructor).

ويعرض المؤلف بشكل منفصل كيف يبدو ذلك في مثال استخراج البيانات من إعلان وظيفة. يصف المطوّر نموذج JobPosting بحقول مثل المسمّى الوظيفي والشركة وقائمة المهارات ومستوى seniority وعلامة العمل عن بُعد (remote)، فيُرجع الوكيل كائنًا جاهزًا بدلًا من نص خام. وإذا فُقد حقل أو لم يتطابق النوع، يتحقق الإطار من الرد ويعيد المحاولة قبل أن يمرّ الخطأ إلى التطبيق. وهذا يعالج المشكلة المعتادة في كل الأنظمة التي يجب أن تنتج فيها LLM بيانات صالحة للاستخدام الفوري في الشيفرة.

كيف يقود ذلك إلى بيئة الإنتاج

يُخصَّص المثال الكبير الثاني في المقال لاستدعاء الأدوات (tool calling). يأخذ المؤلف قاعدة بيانات تغذية بسيطة ويسجّل دالة تُرجع، بحسب اسم المكوّن، السعرات الحرارية والبروتينات والكربوهيدرات والدهون لكل 100 غرام. بعد ذلك يتلقى الوكيل طلبًا مثل تحليل وجبة، فيستدعي الأداة بنفسه لكل مكوّن، ويجمع القيم، ويُسلّم النتيجة في شكل نموذج MealSummary. والناتج ليس ردّ دردشة حرًّا، بل ملخّص منظَّم يتضمن الأرقام الإجمالية وحكمًا على التركيب وتوصية.

وثمة تفصيل مهم: docstring الدالة هنا ليس تجميلًا، بل جزء من العقد الذي يفهم النموذج من خلاله متى ولماذا يستدعي الأداة.

والأهم من ذلك الجزء المتعلق بحقن التبعيات. فبدلًا من قاعدة بيانات مضمَّنة بشكل جامد على هيئة قاموس، يغلّف المؤلف مصدر البيانات في فئة خدمة (service class) باسم NutritionService، ثم يمرّرها إلى الوكيل عبر deps وRunContext المُنمَّط. وهذا يقرّب الشيفرة كثيرًا من ظروف التشغيل الفعلي: ففي موضع القاموس يمكن أن توجد قاعدة بيانات أو عميل API أو جلسة مستخدم أو أي تبعية أخرى وقت التشغيل (runtime). كما تتحقق قابلية الاختبار بشكل سليم. ففي المثال يمكن استبدال الخدمة بسهولة بكائن mock، ويواصل الوكيل عمله دون أي تغيير في منطقه الأساسي.

الطبقة الأخيرة هي القدرات المدمجة (capabilities). يتناول المقال اثنتين على الأقل: WebSearch للوصول إلى بيانات حديثة من الإنترنت، وThinking للاستدلال التدريجي الأعمق في المهام المعقدة. ويمكن الجمع بينهما في وكيل واحد، مثل مساعد بحثي يقرر بنفسه ما يبحث عنه، ثم يحصل على نتائج حديثة، وبعد ذلك فقط يصوغ الإجابة. وفي الختام يشير المؤلف بشكل منفصل إلى التكامل مع Logfire لأغراض المراقبة (observability): إذ يمكن رؤية استدعاءات النموذج وعمليات تشغيل الأدوات ومحاولات إعادة التحقق.

ماذا يعني ذلك

تكمن فائدة مادة Machine Learning Mastery في أنها تنقل الحديث عن وكلاء الذكاء الاصطناعي من وضع العروض التجريبية (demo) إلى وضع الممارسة الهندسية. فـ Pydantic AI لا يُقدَّم هنا بوصفه غلافًا آخر فوق LLM، بل كوسيلة لفرض الانضباط في الأنواع والتبعيات والأدوات. وبالنسبة لفرق Python، فهذه إشارة جيدة: يمكن بناء الوكلاء دون منسِّق (orchestrator) ثقيل، إذا استُند منذ البداية إلى مخططات قابلة للتحقق وعقود صريحة ومكوّنات تشغيل قابلة للاختبار.