PydanticAI

PydanticAI هو إطار عمل لوكلاء Python صممه الفريق الذي يقف خلف Pydantic، بقيادة Samuel Colvin، المهندس الذي ابتكر مكتبة التحقق Pydantic المُستخدمة في جميع أنحاء نظام Python البيئي. تم إصداره في 2 ديسمبر 2024، خلال أسبوع AWS re:Invent، ووصل إلى الإصدار المستقر 1.0 في 4 سبتمبر 2025، بعد 15 مليون عملية تنزيل. إطار العمل مرخص بموجب MIT ومجاني الاستخدام. وعده الأساسي: جلب نفس تجربة المطورين التي جعلت FastAPI إطار عمل الويب الافتراضي في Python إلى بناء وكلاء الذكاء الاصطناعي، واستبدال تحليل JSON العشوائي وهندسة التلقين الهشة بعقود كتابة صحيحة ومخرجات تم التحقق من صحتها.

يدعم PydanticAI كل من OpenAI و Anthropic و Google و xAI و Amazon Bedrock و Groq و Mistral و Ollama و Cohere و OpenRouter و Hugging Face و Cerebras بشكل افتراضي. تشمل الميزات الرئيسية التحقق من صحة المخرجات المهيكلة عبر نماذج Pydantic، ونظام حقن التبعيات باستخدام RunContext الذي يمرر اتصالات قاعدة البيانات وعملاء واجهة برمجة التطبيقات (API) بسلاسة إلى الأدوات، والبث مع التحقق في الوقت الفعلي، ودعم Model Context Protocol (MCP)، وموافقة الأدوات بمشاركة بشرية (human-in-the-loop)، وبنى الوكلاء المتعددين، والتنفيذ الدائم مع تكامل Temporal. يوفر التكامل الوثيق مع Pydantic Logfire إمكانية المراقبة المستندة إلى OpenTelemetry لتتبع عمليات تشغيل الوكيل، وتتبع تكاليف الرموز (tokens)، وتصحيح أخطاء استدعاءات الأدوات في بيئة الإنتاج. بحلول مايو 2026، حصد المستودع أكثر من 16,800 نجمة على GitHub، وأكثر من 241 إصداراً، ويُستخدم في بيئات الإنتاج من قبل الفرق التي تبني على Amazon Bedrock AgentCore.

ما يفعله PydanticAI فعلياً في مايو 2026

يتمحور PydanticAI حول فئة Agent واحدة تغلف نموذج لغة كبير (LLM)، ومجموعة من الأدوات، وتلقين النظام، ومخطط مخرجات مهيكل. عند تشغيل الوكيل، فإنه يتحقق من صحة مخرجات النموذج مقابل نموذج Pydantic في كل استدعاء، مع إعادة المحاولة تلقائياً بتقديم ملاحظات تصحيحية في حال فشل التحقق. يزيل هذا أكبر فئة من إخفاقات الإنتاج في أنظمة الوكلاء: وهي إرجاع نموذج اللغة الكبير (LLM) لبيانات مشوهة أو مفقودة أو ذات نوع خاطئ مما يؤدي إلى تعطل التعليمات البرمجية اللاحقة.

يُعد نظام حقن التبعيات هو الميزة التنافسية الرئيسية الثانية. فبدلاً من تمرير التكوين من خلال الحالة العامة أو متغيرات البيئة، تتلقى الأدوات كائن RunContext[Dependencies] مكتوباً في وقت التشغيل. من الناحية العملية، يعني هذا أنه يمكن حقن اتصال قاعدة بيانات، أو عميل API خارجي، أو سياق مستخدم بسلاسة في وقت استدعاء الوكيل، مما يجعل الأدوات قابلة لاختبار الوحدة دون الحاجة إلى استدعاءات LLM حية. هذا نمط تصميم مستعار من نظام تبعيات FastAPI وهو يحل نقطة ألم حقيقية تواجهها الفرق عند توسيع قواعد التعليمات البرمجية للوكلاء لتتجاوز ملفاً واحداً. لم تعد كتابة اختبار لأداة وكيل تتطلب استدعاء LLM حياً أو قاعدة بيانات حية: يمكنك تمرير كائن تبعية وهمي (mock) إلى RunContext والتحقق من النتيجة.

يتضمن دعم البث التحقق في الوقت الفعلي من المخرجات الجزئية المهيكلة، وليس فقط بث الرموز (tokens). هذا أمر بالغ الأهمية للوحات المعلومات وواجهات المستخدم الحية التي تعرض بيانات مهيكلة متزايدة بدلاً من النص الخام: يتحقق إطار العمل من صحة كل جزء من المخرجات الجزئية فور وصوله، لذلك لا يضطر التطبيق أبداً إلى التعامل مع خطأ في التحقق بعد اكتمال البث. تتيح مسارات العمل القائمة على الرسوم البيانية، المضافة عبر Graph API الخاص بـ PydanticAI، نمذجة تدفقات الوكلاء المعقدة كآلات حالة مكتوبة مع انتقالات بين الحالات تم التحقق منها بواسطة بيئة التطوير المتكاملة (IDE). يكتمل طقم الميزات باتصال الوكلاء المتعددين (التسليم من وكيل إلى وكيل)، ودعم خادم/عميل MCP، والتنفيذ الدائم (الوكلاء الذين يمكنهم التوقف مؤقتاً، والاحتفاظ بالحالة، والاستئناف بعد الانقطاع عبر Temporal). تتضمن خارطة الطريق اعتباراً من أوائل عام 2026 التخزين المؤقت للتلقين (prompt caching)، ودعم التضمينات (embeddings)، ومخرجات القواعد النحوية الخالية من السياق، ودعم موارد MCP الموسع.

أحد الأمثلة الملموسة على كيفية تطبيق ذلك عملياً: أبلغ نظام تصنيف المستندات القانونية المبني على PydanticAI عن دقة بلغت 94% مقارنة بـ 67% باستخدام مطابقة الكلمات الرئيسية. قام وكيل دعم عملاء التجارة الإلكترونية بحل 38% من التذاكر الواردة تلقائياً مع درجات رضا بلغت 96%. عالج تكامل نظام إدارة علاقات العملاء (CRM) العقاري 40-60 إشعاراً متزامناً في أقل من 8 ثوانٍ. هذه ليست ادعاءات تسويقية من PydanticAI؛ بل هي أرقام نشرها مطورون أفراد تحولوا إلى إطار العمل خصيصاً للهروب من إخفاقات التحقق في الأدوات السابقة.

"في المرة الرابعة التي اضطررت فيها إلى تصحيح أخطاء وكيل LangChain الذي أرجع بصمت ملف JSON مشوهاً وأدى إلى تعطل مسار معالجة طلبات العميل، قررت أنني انتهيت من ترقيع أخطاء الكتابة في منتصف الليل." - jahanzaibai، مجتمع DEV، 2025

موقع PydanticAI مقارنة بـ LangChain و smolagents

PydanticAI مقابل LangChain: يمتلك LangChain أكثر من 96 ألف نجمة على GitHub، ومكتبة تكامل ناضجة، وسنوات من عمليات النشر في بيئة الإنتاج. إنه لن يختفي. لكن إطار العمل يحمل تعقيداً متراكماً كبيراً: بصمة بحجم ~300 ميجابايت، وأنماط متعددة مهملة (AgentExecutor القديم مقابل LangGraph الأحدث)، وبنية تفصل ChatModel، وقوالب التلقين، و AgentExecutor، و RunnableWithMessageHistory إلى طبقات متميزة يجب ربطها معاً. بالنسبة للمخرجات المهيكلة، لا يمكن لـ LangChain الجمع بين with_structured_output() وأدوات إضافية في نفس الوكيل دون حل بديل مخصص مثل StructuredResponseTool. يتعامل PydanticAI مع هذا بشكل أصلي. بالنسبة لحقن التبعيات، يتطلب LangChain إنشاء فئة فرعية من BaseTool باستخدام أداة قائمة على الفئة؛ بينما يستخدم PydanticAI وظائف عادية مع RunContext. المقايضة هنا هي اتساع النظام البيئي: يمتلك LangChain موصلات لا يمتلكها PydanticAI ببساطة حتى الآن.

PydanticAI مقابل smolagents: يتخذ smolagents من Hugging Face رهاناً معمارياً معاكساً. يتكون جوهره بالكامل من حوالي 1,000 سطر من كود Python. يكتب الوكلاء وينفذون كود Python مباشرة (وكلاء الكود) بدلاً من استدعاء أدوات محددة مسبقاً عبر مخططات JSON. ينتج عن هذا مكاسب في الكفاءة: يدعي smolagents أنه يقلل من استدعاءات LLM بنسبة 30% تقريباً في المعايير المعقدة مقارنة باستخدام الأدوات بنمط JSON. التكلفة هي أن smolagents لا يحتوي على تحقق مدمج من صحة المخرجات المهيكلة، ولا دعم أصلي غير متزامن (async)، ومعالجة محدودة للذاكرة. يفرض PydanticAI اتساق البيانات عند كل حد؛ بينما يُحسّن smolagents سرعة التجريب والحد الأدنى من البصمة. إذا كنت تقوم بإنشاء نموذج أولي على نماذج مستضافة على Hugging Face وتريد تشغيل شيء ما في غضون ساعة، فإن smolagents يفوز. أما إذا كنت تبني نظام إنتاج حساساً للامتثال حيث يجب التحقق من صحة كل مخرج مقابل مخطط، فإن PydanticAI يفوز.

الجدير بالذكر: يشغل DSPy مساحة مجاورة مختلفة، حيث يقوم بتحسين برامج التلقين خوارزمياً بدلاً من توفير طبقة تنفيذ في وقت التشغيل. يُعد LangGraph (جزء من نظام LangChain البيئي) المنافس المباشر الأبرز لتنسيق الوكلاء المتعددين ذوي الحالة (stateful). يُعد LiteLLM مكملاً: فهو طبقة توجيه غير مرتبطة بمزود معين يمكن لـ PydanticAI الجلوس فوقها. يستهدف CrewAI أنظمة الوكلاء المتعددين القائمة على الأدوار بتجريد عالي المستوى يقايض التحكم بالبساطة.

كيف يبدو واقع حلقة الوكيل

يبدأ سير العمل النموذجي في PydanticAI بتحديد نموذج Pydantic للمخرجات المتوقعة، وإنشاء Agent مع تلقين النظام وخلفية النموذج، ثم تزيين (decorating) وظائف Python كأدوات. يُرجع تشغيل الوكيل كائن نتيجة مكتوباً، وليس سلسلة نصية. تعرف بيئة التطوير المتكاملة (IDE) شكل كل وسيطة أداة وكل حقل إخراج قبل تشغيل الكود.

بالنسبة للمراقبة، يؤدي استدعاء logfire.configure() و logfire.instrument_pydantic_ai() إلى تنشيط التتبع التلقائي لكل استدعاء LLM، وكل استدعاء أداة، وكل محاولة تحقق. يعني أساس OpenTelemetry أنه يمكن تصدير التتبعات إلى أي خلفية متوافقة، وليس فقط منصة Logfire التجارية. هذا تمييز ذو مغزى: تستخدم بعض الفرق Datadog أو Grafana بالفعل ولا تريد بائع مراقبة ثانٍ.

تُبلغ فرق الإنتاج عن نتائج قوية. وثّق أحد المطورين دقة بنسبة 94% في تصنيف المستندات القانونية (ارتفاعاً من 67% باستخدام مطابقة الكلمات الرئيسية)، وحل تلقائي بنسبة 38% لتذاكر دعم التجارة الإلكترونية مع درجات رضا بلغت 96%، ومعالجة 40-60 إشعاراً متزامناً لنظام إدارة علاقات العملاء (CRM) العقاري في أقل من 8 ثوانٍ. تأتي هذه الأرقام من الفرق التي تحولت خصيصاً إلى PydanticAI للتوقف عن مطاردة إخفاقات تحليل JSON في الساعة الثانية صباحاً.

"بعد قضاء الكثير من الوقت في تعقب أخطاء الوصول إلى السمات في سلاسل الوكلاء المكتوبة ديناميكياً، فإن هذا يهم أكثر من أي رقم معياري." - jahanzaibai، مجتمع DEV، 2025

لمن تم بناء PydanticAI

الإشارة الأوضح: إذا كنت قد استخدمت FastAPI وتعتبر نظام الكتابة في Python بمثابة بنية تحتية وليس مجرد توثيق، فستشعر بالألفة الفورية مع PydanticAI. يستهدف إطار العمل المهندسين الذين يرغبون في التعامل مع تطوير الوكلاء كعملية هندسة برمجيات عادية، مع اختبارات الوحدة، والعقود المكتوبة، ودعم بيئة التطوير المتكاملة (IDE)، بدلاً من صياغة التلقين المقترنة بالأمل.

إنه يتناسب جيداً مع الفرق التي تستخدم Pydantic بالفعل (وهي في هذه المرحلة معظم فرق Python التي تعمل مع نماذج LLM، نظراً لأن OpenAI SDK و Google ADK و LangChain نفسها تعتمد جميعها على Pydantic للتحقق من الصحة). يُعد اعتماد PydanticAI إضافة وليس إعادة كتابة كاملة. كما أنه يناسب المجالات الحساسة للامتثال: التمويل، والرعاية الصحية، والقانون، حيث يجب أن يكون كل مخرج للذكاء الاصطناعي قابلاً للتدقيق ومهيكلاً. نقلته Thoughtworks إلى مرحلة "التجربة" (Trial) في نوفمبر 2025، وهي إشارتهم إلى أنه ينبغي للمؤسسات استخدامه في مشروع حقيقي لبناء فهم لهذه الفئة.

إنه خيار معقول للفرق التي تستخدم Amazon Bedrock AgentCore، حيث يُعد PydanticAI إطار عمل مدعوماً من الطرف الأول. وهو يتكامل بشكل طبيعي إلى جانب LiteLLM للفرق التي تقوم بالتوجيه عبر مزودين متعددين.

ما لا يمثله PydanticAI

لا يُعد PydanticAI سكين جيش سويسري للوكلاء متعدد الأغراض لكل حزمة تقنية. إليك بعض القيود الصريحة:

إنه مخصص لـ Python فقط. لا توجد حزمة تطوير برمجيات (SDK) لـ JavaScript أو TypeScript أو أي لغة أخرى. إذا كانت الواجهة الخلفية لديك هي Go أو Java أو Node.js، فأنت بحاجة إلى إطار عمل مختلف.

المدخلات متعددة الوسائط (الصور، الصوت، الفيديو) غير مدعومة في نواة الوكيل اعتباراً من منتصف عام 2026. يعالج إطار العمل النصوص والبيانات المهيكلة؛ ويتطلب تمرير صورة إلى أداة معالجة يدوية خارج طبقة التحقق الخاصة بإطار العمل.

بالنسبة لتنسيق الوكلاء المتعددين على نطاق واسع مع رسوم بيانية معقدة للحالة، يمتلك LangGraph أدوات أكثر نضجاً. يُعد Graph API الخاص بـ PydanticAI فعالاً ولكنه أحدث، ويُبلغ المطورون أن بيئة العمل (ergonomics) لأنظمة الوكلاء المتعددين المترامية الأطراف لا تزال قيد التطوير.

يستحق القلق بشأن الاعتماد على Logfire الإشارة إليه. تكامل المراقبة ممتاز ومفيد حقاً، لكن فريق Pydantic لديه حوافز تجارية لتوجيه المستخدمين نحو المستويات المدفوعة من Logfire. يُصدر إطار العمل بيانات OpenTelemetry، لذا فأنت لست مقيداً بشكل صارم، ولكن يجب على الفرق التي تمتلك بالفعل حزمة مراقبة (Datadog، Honeycomb، Grafana) التحقق من مسار التصدير قبل الالتزام.

هناك أيضاً مشكلات معروفة تستحق الانتباه: قدم الإصدار v1.30.0 عن طريق الخطأ تبعية صارمة لـ openai v2.8.0 مما أدى إلى تعطل المشاريع الحالية (مشكلة GitHub رقم 3707)، ومنطق إعادة المحاولة لا يحل دائماً إخفاقات التحقق كما هو متوقع (مشكلة رقم 739)، ودعم نموذج DeepSeek واجه أخطاء في التعيين (mapping bugs). وجود فريق تطوير نشط مع 364 مشكلة مفتوحة يعني أن إطار العمل سريع الاستجابة ولكنه لا يزال يحتوي على بعض الجوانب غير المكتملة.

تجاوز PydanticAI إذا: كنت تريد تشغيل شيء ما في فترة ما بعد الظهر دون أي معرفة بـ Pydantic، أو إذا كانت حزمتك التقنية ليست Python، أو إذا كنت بحاجة إلى أدوات وكلاء متعددة الوسائط ناضجة، أو إذا كنت بحاجة إلى اتساع تكاملات LangChain التي تزيد عن 300 تكامل.