Pydantic AI: بناء وكلاء Python مع التحقق من المخرجات

جرى التحقق من المعلومات بالرجوع إلى وثائق الجهة المطوّرة وترخيص المستودع في 17 أكتوبر 2026. يستند الاختيار هنا إلى التحقق من المخرجات، والوصول إلى خدمات التطبيق، ومسؤولية إدارة سير العمل والتعافي من الأعطال، وليس إلى ترتيب للأداء.

ما هو Pydantic AI؟

Pydantic AI هو حزمة تطوير وكلاء Python من فريق Pydantic. يجمع النموذج والتعليمات ودوال Python القابلة للاستدعاء ونوعًا اختياريًا للمخرجات داخل Agent، وهو الكائن الذي يشغّله تطبيقك. النموذج هو النظام الذي يولّد الردود، بينما تدير حزمة التطوير التفاعل المحيط به. ويعرض التعريف الحالي بالحزمة نطاقًا أوسع من الإمكانات، لكن هذا هو الأساس الذي تحتاجه لبناء ميزة في منتجك.

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

الوكيل في Pydantic AI: وحدة قابلة لإعادة الاستخدام

يحتفظ Agent بإعدادات مهمة معينة. أما التشغيل، فهو محاولة محددة لتنفيذ تلك المهمة باستخدام موجّه وتبعيات تُمرّر وقت التشغيل. يمكنك استدعاء run_sync() من برنامج متزامن، أو استخدام await agent.run() داخل كود تطبيق غير متزامن. وعند اكتمال التشغيل، تتاح القيمة النهائية عبر .output. توضح وثائق واجهات Agent هذه الواجهات.

لتحديد الأنواع وظيفتان منفصلتان. يساعد التحقق الساكن من الأنواع محرر الكود أو أداة فحص الأنواع على اكتشاف حالات عدم التطابق في كود Python. أما التحقق من المخرجات وقت التشغيل، فيفحص البيانات التي يعيدها النموذج وفق المخطط المعلن. ولا تجعل أيٌّ من الوظيفتين طلب دعم غامضًا واضحًا من تلقاء نفسها.

أدوات Pydantic AI: دوال تستفيد من سياق التطبيق

تتيح أدوات الدوال للنموذج طلب عملية يستطيع الكود تنفيذها، مثل الاستعلام عن اشتراك. سجّل الدالة التي تحتاج إلى سياق التشغيل باستخدام @agent.tool، أو استخدم @agent.tool_plain إن لم تكن بحاجة إليه. تصف تلميحات الأنواع الوسائط، وتساعد سلاسل التوثيق في شرح الأداة للنموذج. وتبيّن وثائق أدوات الدوال كيف تتحول هذه المعلومات إلى مخططات للأدوات.

حقن التبعيات يعني تمرير الخدمات التي يحتاجها تشغيل معيّن إلى ذلك التشغيل. تحدد deps_type=CustomerContext نوع Python المتوقع، بينما تمرر deps=customer_context الكائن الفعلي. تتلقى الأداة RunContext[CustomerContext] وتصل إلى تبعياته عبر ctx.deps. ويمكن لهذا السياق أن يحمل بيانات عميل تم التحقق من هويته، أو اتصالًا بقاعدة بيانات، أو عميلًا لواجهة API. ويذكر دليل التبعيات صراحةً أن deps_type يدعم فحص الأنواع، ولا يتحقق من صحة كائن التبعيات وقت التشغيل.

الفائدة واضحة لمن يبني منتج SaaS: يستطيع الخادم تحديد حساب العميل قبل أن يطلب النموذج الاستعلام عنه. أبقِ التحقق من الصلاحيات داخل كود الاستعلام. فتمرير عميل قاعدة بيانات عبر سياق محدد النوع لا يقيّد الصفوف التي يستطيع ذلك العميل قراءتها.

المخرجات المنظمة في Pydantic AI: ما الذي يجري التحقق منه؟

يحدد output_type النتيجة التي يتوقع تطبيقك استلامها. مرّر BaseModel من Pydantic، أي صنف Python ذا حقول محددة الأنواع، ليستخلص Pydantic AI المخطط ويتحقق من البيانات المولّدة وفقه. وتوضح وثائق المخرجات دعم أنواع أخرى أيضًا، منها أصناف البيانات والقوائم والأنواع الاتحادية.

تختلف أنماط المخرجات الثلاثة في الطريقة التي يُطلب بها من النموذج إنتاج البيانات:

هذه هي أنماط المخرجات الثلاثة الموثّقة في الحزمة، وليست ثلاثة مستويات للدقة. اختر الآلية التي يدعمها نموذجك، ثم قيّم النتيجة على المهمة التي تريد إنجازها.

يمكن إعادة خطأ التحقق إلى النموذج ليحاول مجددًا. لكن عدد محاولات الإعادة محدود، وقد يؤدي استنفاد محاولات المخرجات إلى رفع UnexpectedModelBehavior. لذلك يحتاج تطبيقك إلى مسار واضح عند الفشل، كطلب المعلومات الناقصة أو إحالة الطلب إلى شخص. راجع آلية إعادة المحاولة.

شرح Pydantic AI عمليًا: قرار دعم بمخرجات يجري التحقق منها

ابدأ بكائن قرار للقراءة فقط، قبل منح الوكيل صلاحية تغيير أي شيء. يكيّف هذا المثال الأنماط الموثّقة لاستخدام Agent وRunContext وoutput_type مع مهمة صغيرة لفرز طلبات الدعم.

يشترط دليل التثبيت الحالي استخدام Python 3.11 أو أحدث. ثبّت المكتبة داخل بيئة افتراضية:

python -m pip install pydantic-ai

اضبط OPENAI_API_KEY في بيئتك لحساب لديه صلاحية الوصول إلى النموذج. احفظ الكود التالي باسم triage.py وشغّله بالأمر python triage.py. يتبع معرّف النموذج وثائق Agent الحالية، ويمكنك استبداله بنموذج مدعوم متاح لحسابك.

from dataclasses import dataclass
from typing import Literal

from pydantic import BaseModel
from pydantic_ai import Agent, RunContext

@dataclass
class Customer:
    plan: str

class Triage(BaseModel):
    category: Literal['billing', 'technical']
    priority: Literal['normal', 'urgent']
    summary: str

agent = Agent(
    'openai:gpt-6.1-sol',
    deps_type=Customer,
    output_type=Triage,
    instructions=(
        'Triage the support message. Use customer_plan for context. '
        'Summarize the issue without inventing account facts.'
    ),
)

@agent.tool
def customer_plan(ctx: RunContext[Customer]) -> str:
    """Return the authenticated customer's plan."""
    return ctx.deps.plan

if __name__ == '__main__':
    result = agent.run_sync(
        'I was charged twice for my subscription.',
        deps=Customer(plan='business'),
    )
    print(result.output.model_dump())

عند نجاح التشغيل، يكون result.output كائنًا من النوع Triage. ويجب أن تتوافق قيمتا التصنيف والأولوية فيه مع الخيارات المعلنة، بينما يحوّل model_dump() الكائن إلى قاموس. جرى التحقق دون اتصال من أداة السياق في المثال، ومن نوع النتيجة ورفض التصنيف غير الصالح، باستخدام TestModel. أما الصياغة التي يولّدها النموذج ودقة الفرز، فتحتاجان إلى تقييم على حالاتك الفعلية.

سياق العميل هنا للتوضيح. في المنتج الفعلي، أنشئه من الطلب بعد التحقق من هوية صاحبه، ومن سجلات الحسابات لديك. وحدد أيضًا متى تُعد الحالة عاجلة؛ فالمخطط يعدد التسميات المقبولة، لكنه لا يتضمن سياسة لتحديد الاستعجال. سدّ هذه الفجوة في قواعد العمل أهم من إضافة وكيل آخر.

النماذج في Pydantic AI: تبديل المزوّد لا يعني تطابق السلوك

يقلل Pydantic AI كود الربط الخاص بكل مزوّد، لكن تغيير النموذج يظل مؤثرًا في السلوك. تستخدم خيارات كثيرة معرّفًا بالشكل <provider>:<model>. ويتطلب بعضها تحديد نموذج أو عميل صراحةً، إلى جانب بيانات الاعتماد المناسبة وحزم التثبيت الإضافية. ويعتمد دعم الميزات على النموذج وواجهة API المختارين، كما يوضح دليل المزوّدين.

يشمل الدليل OpenAI وAnthropic وGoogle/Gemini وAWS Bedrock وGroq وMistral وxAI وOllama. ويغطي أيضًا خيارات الوصول الموثّقة التالية:

• خدمات النماذج والاستدلال: Alibaba Cloud/Qwen وCerebras وCohere وCrusoe وDeepSeek وFireworks AI وHeroku AI وHugging Face وMeta وMoonshot AI/Kimi وNebius AI Studio وOVHcloud AI Endpoints وSambaNova وSnowflake Cortex وTogether AI وZ.AI.
• خيارات السحابة والبوابات والاستضافة الذاتية: Google Cloud/Vertex AI وMicrosoft Azure/Foundry وPydantic AI Gateway وLiteLLM وOpenRouter وVercel AI Gateway وvLLM.
• خيارات إضافية للوصول ونماذج اتخاذ القرار: GitHub Copilot وOpenAI Codex وOpenAI Decisions API وSystem One API وTypeSafe (Jev).

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

تمنح قابلية الانتقال بين المزوّدين مؤسسَ المنتج مخرجًا من الاعتماد على مزوّد بعينه، ومساحة للتجربة. أما المطوّر الذي ينفذ التبديل، فيبقى اختبار القبول لديه ثابتًا: هل يختار البديل الأدوات الصحيحة، ويلتزم بمخطط المخرجات، ويصدر قرارات مقبولة في الحالات نفسها؟ احتفظ بنتائج تثبت ذلك قبل تغيير النموذج الافتراضي في بيئة الإنتاج.

MCP والتنفيذ القابل للاستئناف: ربط الأدوات وحفظ التقدم

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

يوحّد Model Context Protocol، أو MCP، الطريقة التي تعرض بها التطبيقات الأدوات والسياق لعملاء الذكاء الاصطناعي. وتقبل إمكانات MCP في Pydantic AI عناوين URL للخوادم ومدخلات من نوع العميل أو مجموعة الأدوات، مع خيارات MCP الأصلية لدى المزوّد حيثما تكون مدعومة. ويتيح ذلك إعادة استخدام خادم أدوات بدل كتابة تكامل جديد لكل وكيل. لكنه لا يحدد أيّ العملاء يحق له استخدام عمليات ذلك الخادم.

يعني التنفيذ القابل للاستئناف حفظ التقدم، بحيث يمكن مواصلة العمل بعد فشل أو إعادة تشغيل أو انتظار طويل. وتذكر وثائق استمرارية التنفيذ الحالية 9 حلول:

• حلول تُصان بالتعاون مع فرق المزوّدين: Temporal وDBOS وPrefect وRestate وAWS Lambda.
• تكاملات خارجية لحزم التطوير: Kitaru وApache Airflow وAbsurd وpgtask.

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

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

التقييم في Pydantic AI: اختبر القرار وراء الكائن

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

لمثال فرز طلبات الدعم، أنشئ حالات تتناول تكرار الفوترة، وفشل تسجيل الدخول، وغياب سياق الحساب، ورسالة تطلب من المساعد تجاهل تعليماته. افحص التصنيف وقرار التصعيد وما إذا كان الاستعلام المطلوب عن الحساب قد نُفّذ. وأدرج حالات تكون فيها الإجابة المقبولة هي طرح سؤال.

بالنسبة إلى مسؤول التشغيل، يشرح التتبّع تشغيلًا واحدًا، بينما يقيس التقييم السلوك عبر حالات متعددة. يستخدم Pydantic AI معيار OpenTelemetry لبيانات مراقبة التطبيقات، ويدعم أنظمة خلفية أخرى للرصد عبر أدوات القياس والتتبّع. افحص الطلب المرسل إلى النموذج واستدعاءات الأدوات عند فشل حالة، ثم احتفظ بتلك الحالة ضمن مجموعة التقييم.

توفّر خدمة Pydantic Logfire الاختيارية تتبّع الوكلاء والنماذج والأدوات. خطتها Personal مجانية، وتبدأ خطة Team من $49 شهريًا، مع فوترة الاستخدام الإضافي ومقاعد المستخدمين على نحو منفصل، وفق صفحة الأسعار.

متى تختار Pydantic AI بدلًا من إطار آخر؟

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

مقارنة Pydantic AI مع LangGraph

يشكّل LangGraph نقطة بداية أقوى إذا أردت تصميم سير العمل المحيط بالوكيل بصورة صريحة. تتمحور وثائقه حول الوكلاء الذين يحتفظون بالحالة ويعملون لفترات طويلة، والتنفيذ القابل للاستئناف، والتدخل البشري. تخيّل تطبيقًا بمراحل إلزامية: جمع الأدلة، والحصول على الموافقة، وتنفيذ إجراء مصرح به، ثم التحقق من النتيجة وتسويتها.

يبرز Pydantic AI عندما يكون الوكيل محدد الأنواع مكوّنًا داخل عملية يديرها تطبيقك أصلًا. ويمكنه المشاركة في مسارات عمل تحفظ التقدم أيضًا، لذا لا يكفي الاحتفاظ بالحالة وحده لحسم الاختيار. السؤال الحاسم هو: هل تريد نمذجة إجراءات العمل حول الوكيل، أم أن حاجتك الأساسية هي ضبط سلوك الوكيل نفسه؟ التحدي في LangGraph هو مسؤوليتك عن تصميم سير العمل وإدارة حالته؛ أما حدود Pydantic AI، فتظهر حين تتوقع أن يصمم عقد الوكيل المريح العملية بأكملها نيابة عنك.

مقارنة Pydantic AI مع LangChain

يكون LangChain خيارًا مناسبًا إذا كانت تكاملاته الحالية مع النماذج والأدوات وبنيته للوكلاء تلائم تطبيقك بالفعل. يُبنى وكلاء LangChain على LangGraph، وفق التعريف بـLangChain، ولذلك لا يعني اختيار واجهته الأعلى مستوى للوكلاء التخلي عن أساس بيئة التشغيل هذا.

اختر Pydantic AI لخدمة Python إذا كانت عقوده للتبعيات والمخرجات تنسجم مع أسلوبك الحالي في كتابة الكود. وأبقِ ميزة LangChain التي تعمل جيدًا، ما لم تستطع تحديد مصدر تعقيد ملموس سيزيله الانتقال. ستظل بحاجة إلى فهم تجريدات LangChain عندما يمتد السلوك بين طبقتي الوكيل وسير العمل؛ فتغيير المكتبات ينقل هذا الجهد إلى موضع آخر فحسب. وللتعمق في العلاقة بينهما، راجع مقارنة LangChain مع LangGraph.

متى تستخدم OpenAI Agents SDK أو استدعاءات API المباشرة؟

تلائم OpenAI Agents SDK حلقة تشغيل وكيل يديرها تطبيقك، مع الأدوات وتحويل المهام بين الوكلاء والتتبّع. تعمل الحزمة داخل تطبيقك وتدعم المخرجات المنظمة، كما تتيح واجهات المزوّدين استخدام نماذج من خارج OpenAI. لذلك لا يصح اعتبار المخرجات محددة الأنواع أو حرية اختيار المزوّد ميزتين حصريتين لـPydantic AI.

اختر تلك الحزمة إذا كان نموذجها للوكلاء وتحويل المهام ينسجم مع تكامل OpenAI المحيط الذي تنوي صيانته. واختر Pydantic AI إذا كان نموذجه لتبعيات Python وإعداد المزوّدين أنسب لتطبيقك. وفي الحالتين، تبقى مسؤولية النشر وصلاحيات الأدوات وصحة عمل التطبيق لديك.

استخدم استدعاءات API المباشرة حين تقتصر المهمة على طلب إلى نموذج يحيط به قدر قليل من الكود الحتمي. فواجهات API المباشرة تستطيع بالفعل إعادة مخرجات مقيّدة بمخطط. لا يحتاج مستخرج بيانات الإيصالات إلى إطار وكلاء لمجرد أن النتيجة كائن Pydantic. وتظهر حدود هذا الخيار عندما تضطر مرارًا إلى إعادة بناء حلقات الأدوات ومحاولات التحقق وأدوات القياس والتتبّع عبر ميزات متعددة.

للاطلاع على نطاق أوسع من الخيارات، راجع دليل أطر وكلاء الذكاء الاصطناعي. وإذا بقي سؤالك حول التحكم الصريح في سير العمل مقابل توزيع الأدوار على وكلاء متخصصين، فانتقل إلى مقارنة LangGraph مع CrewAI.

أين تبدأ المبالغة في مزايا الوكلاء محددي الأنواع؟

تبدأ المبالغة عند افتراض أن الوكيل محدد الأنواع يصبح تلقائيًا نظامًا صحيح الأداء وجاهزًا للإنتاج. فهناك حدود لا تستطيع المكتبة إلغاءها:

• سلامة الأنواع لا تعني صحة المعلومات. قد تكون الإجابة سليمة البنية وتسيء فهم طلب المستخدم. حدد ما ينبغي التحقق منه بالرجوع إلى السجلات المعتمدة.
• قابلية الانتقال بين النماذج لا تعني تساوي الجودة. يحتاج إعداد مزوّد جديد إلى تقييم المهمة نفسه الذي يحتاجه موجّه جديد.
• استمرارية التنفيذ لا تعني النشر التلقائي. اختر وشغّل المحرك والتخزين ومسار التعافي التي تحتاجها ميزتك.
• إعادة المحاولة عمل إضافي. يضيف طلب آخر إلى النموذج وقت استجابة واستهلاكًا. حدد نتيجة واضحة في التطبيق عند استنفاد المحاولات.

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

أسئلة شائعة عن Pydantic AI

ما الذي يمكنك إطلاقه الأسبوع المقبل؟

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

للحصول على ملاحظات عملية حول بناء ميزات الذكاء الاصطناعي، اشترك في النشرة البريدية.