ما هو PydanticAI؟ دليل إطار عمل وكيل بايثون الآمن بالأنواع

إذا كنت قد أطلقت ميزة LLM وشاهدتها تُرجع JSON مشوهًا في الإنتاج، فإن PydanticAI مصمم لك. إنه إطار عمل وكيل بايثون من الفريق الذي يقف وراء Pydantic، ويضع المخرجات الآمنة من حيث النوع والمتحقق منها في صميم تطوير الوكلاء. يشرح هذا الدليل ماهية PydanticAI، ولماذا تعتبر سلامة النوع مهمة للوكلاء، والمفاهيم الأساسية التي ستستخدمها بالفعل، وكيف يقارن بأطر عمل بايثون الأخرى مثل LangGraph.

ما هو PydanticAI

PydanticAI هو إطار عمل وكيل مفتوح المصدر ومستقل عن المزود لبايثون. يتم صيانته من قبل نفس الفريق الذي يبني Pydantic Validation و Pydantic Logfire، لذلك فهو يرث أساسًا قويًا للتحقق وهدف تصميم واضح: جلب "شعور FastAPI" إلى بناء الوكلاء.

ببساطة، أنت تصف ما يجب أن يفعله وكيلك، وما هي الأدوات التي يمكنه استدعاؤها، وما هو الشكل الذي يجب أن تتخذه مخرجاته. يتولى PydanticAI استدعاءات النموذج، ويتحقق من كل شيء مقابل نماذج Pydantic الخاصة بك، ويعيد المحاولة عندما يُرجع النموذج شيئًا لا يتناسب.

وصل المشروع إلى إصدار مستقر v2.0.0 في 23 يونيو 2026، بعد سلسلة من الإصدارات التجريبية. يركز الإصدار الثاني على تصميم "harness-first" حيث تتكون أدوات الوكيل وخطافاته وتعليماته وإعدادات النموذج كوحدات قابلة لإعادة الاستخدام. يمكنك تثبيته باستخدام pip install pydantic-ai أو uv add pydantic-ai.

لماذا تعتبر سلامة النوع مهمة للوكلاء

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

معظم أخطاء الوكلاء تأتي من هذه الفجوة. النموذج "يعيد في الغالب" JSON صالحًا، يعمل المحلل اللغوي الخاص بك في الاختبار، ثم يترك رد الإنتاج حقلًا أو يلف الإجابة بنثر وتنهار مسار عملك. ينتهي بك الأمر بكتابة تحليل دفاعي، وتنظيف بالتعابير النمطية (regex)، وحلقات إعادة المحاولة يدويًا.

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

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

المفاهيم الأساسية

يحافظ PydanticAI على مساحته السطحية صغيرة. تغطي خمس أفكار معظم ما ستبنيه.

الوكلاء (Agents)

فئة Agent هي نقطة الدخول الرئيسية. يمكنك إنشاء واحدة باستخدام معرف نموذج وتعليمات اختيارية. الفئة عامة على معلمتي نوع: نوع التبعيات ونوع الإخراج، وهذا ما يمنح المحرر ومدقق النوع رؤية حقيقية لوكيلك.

from pydantic_ai import Agent

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    instructions='Be concise, reply with one sentence.',
)

result = agent.run_sync('Where does "hello world" come from?')
print(result.output)

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

المخرجات المكتوبة (Typed outputs)

مرر نموذج Pydantic كـ output_type وسيتم التحقق من نتيجة الوكيل مقابله. تحصل على كائن مكتوب مرة أخرى، ويعرف IDE الخاص بك كل حقل. إليك رسم تخطيطي للمخرجات المهيكلة:

from pydantic import BaseModel
from pydantic_ai import Agent

class SupportTicket(BaseModel):
    category: str
    priority: int
    summary: str

agent = Agent('openai:gpt-4o', output_type=SupportTicket)
result = agent.run_sync('My payment failed three times today.')
print(result.output.priority)  # an int, validated, not a guess

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

الأدوات (Tools)

تتيح الأدوات للنموذج الوصول إلى ما هو خارج نطاقه: استعلام قاعدة بيانات، استدعاء REST API، إجراء حساب. تسجل أداة باستخدام مزين @agent.tool. يقرأ PydanticAI تلميحات نوع الدالة ووثائقها (docstring) لبناء المخطط الذي يراه النموذج، ثم يتحقق من كل استدعاء مقابله.

from pydantic_ai import Agent, RunContext

agent = Agent('openai:gpt-4o', deps_type=str)

@agent.tool
async def get_user_balance(ctx: RunContext[str], account_id: str) -> float:
    """Return the current balance for an account."""
    # ctx.deps holds your injected dependency
    return await lookup_balance(ctx.deps, account_id)

يقرر النموذج متى يستدعي الأداة. لا تُشغل دالتك إلا بوسيطات اجتازت التحقق بالفعل.

التبعيات (Dependencies)

تحتاج الوكلاء الحقيقيون إلى سياق: اتصال قاعدة بيانات، عميل HTTP، المستخدم الحالي، مفتاح API. يتعامل PydanticAI مع هذا عن طريق حقن التبعية. تعلن عن deps_type على الوكيل، ثم تقرأها من خلال RunContext داخل الأدوات والتعليمات الديناميكية. تظل السلسلة بأكملها آمنة من حيث النوع، ويصبح الاختبار أسهل لأنه يمكنك استبدال التبعيات الحقيقية بوهمية.

المزودون المستقلون عن النموذج والبث (Model-agnostic providers and streaming)

يدعم PydanticAI قائمة طويلة من المزودين: OpenAI، Anthropic، Gemini، DeepSeek، Grok، Cohere، Mistral، Perplexity، بالإضافة إلى خيارات سحابية مثل Azure AI Foundry و Amazon Bedrock والنماذج المستضافة ذاتيًا. عادةً ما يكون التبديل تغييرًا في سطر واحد في سلسلة النموذج.

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

كيف يقارن PydanticAI بأطر عمل وكلاء بايثون الأخرى

لا يوجد إطار عمل "أفضل" واحد. إنها تحسن أشياء مختلفة. إليك قراءة صادقة لمكان PydanticAI.

ميزة PydanticAI هي طبقة التحقق. إذا كان وكيلك يغذي بيانات مكتوبة في أنظمة أخرى، فإن ضمان تطابق المخرجات مع نموذج Pydantic يزيل فئة كاملة من أخطاء وقت التشغيل. يمنحك LangGraph تحكمًا أدق في آلات الحالة والتدفقات المعقدة. يعد OpenAI Agents SDK مناسبًا طبيعيًا إذا كنت ملتزمًا بالفعل بـ OpenAI وترغب في ميزات مثل تسليم الوكيل و دعم خادم MCP.

يمكنك أيضًا دمجها. يعمل PydanticAI بشكل جيد كطبقة مخرجات مكتوبة داخل تنسيق أكبر.

متى تستخدم PydanticAI

استخدم PydanticAI عندما:

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

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

اختبار ومحاكاة واجهات برمجة التطبيقات (APIs) وراء وكيلك

وكيل PydanticAI لا يكون موثوقًا إلا بقدر موثوقية واجهات برمجة التطبيقات التي يعتمد عليها. كل تشغيل يستدعي مزود LLM، ومعظم الوكلاء المفيدين يستدعون أيضًا نقاط نهاية REST الخاصة بك أو أدوات الطرف الثالث. هذه الاستدعاءات هي المكان الذي تتسلل فيه السلوكيات المتقلبة والتكاليف المفاجئة وعدم تطابق الأشكال. يتحقق PydanticAI من مخرجات النموذج، لكنه لا يستطيع التحقق من أن واجهة برمجة تطبيقات الأداة التي تستدعيها تُرجع ما تتوقعه.

هنا يأتي دور Apidog، وهي وظيفة مختلفة عن إطار العمل. Apidog هي منصة API حيث تقوم باختبار ومحاكاة واجهات برمجة التطبيقات الأساسية التي يتفاعل معها وكيلك.

بعض الاستخدامات الملموسة:

• محاكاة LLM أو نقطة نهاية الأداة. أثناء التطوير، وجه أداة إلى واجهة برمجة تطبيقات وهمية تُرجع استجابات حتمية. تتوقف عن حرق الرموز في كل تشغيل اختبار وتتجنب حدود معدل المزود أثناء التكرار.
• تأكيد أشكال الاستجابة. قبل توصيل نقطة نهاية REST بدالة @agent.tool، استخدم تأكيدات API لتأكيد تطابق الاستجابة الحقيقية مع الهيكل الذي تتوقعه أداتك. اكتشف حقلًا مفقودًا على مستوى API، وليس بعمق داخل تشغيل الوكيل.
• إدارة المفاتيح لكل بيئة. احتفظ بمفاتيح المزود وعناوين URL الأساسية في بيئات Apidog منفصلة بحيث تصل عمليات التشغيل المحلية والمرحلية و CI إلى الأهداف الصحيحة دون تغييرات في الكود.
• التحقق من نقطة نهاية LLM مباشرة. إذا كنت تستدعي مزودًا عبر HTTP، يمكنك اختبار ChatGPT API باستخدام Apidog لتأكيد التوثيق والبث وتنسيقات استدعاء الأدوات قبل أن يعتمد وكيلك عليها.

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

الأسئلة الشائعة

هل PydanticAI مجاني ومفتوح المصدر؟

نعم. PydanticAI مفتوح المصدر ويمكنك تثبيته من PyPI باستخدام pip install pydantic-ai أو uv add pydantic-ai. ستظل تدفع مقابل أي مزود LLM تستخدمه، حيث يقوم إطار العمل باستدعاء واجهات برمجة التطبيقات هذه نيابة عنك. للحفاظ على تكاليف المزود منخفضة أثناء البناء، يمكنك محاكاة استجابات API أثناء الاختبار بدلاً من الوصول إلى النموذج المباشر في كل تشغيل.

ما هي النماذج التي يعمل بها PydanticAI؟

إنه مستقل عن المزود. تسرد الوثائق OpenAI، Anthropic، Gemini، DeepSeek، Grok، Cohere، Mistral، و Perplexity، بالإضافة إلى خيارات سحابية مثل Azure AI Foundry و Amazon Bedrock والنماذج المستضافة ذاتيًا. تحدد نموذجًا بتمرير سلسلة مثل 'anthropic:claude-sonnet-4-6' أو 'openai:gpt-4o' إلى مُنشئ Agent، وعادة ما يكون التبديل تغييرًا في سطر واحد.

كيف يختلف PydanticAI عن LangChain أو LangGraph؟

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

هل أحتاج إلى معرفة Pydantic لاستخدامه؟

يساعد ذلك، لكن الأساسيات سريعة التعلم. تحدد أشكال البيانات كفئات ترث من BaseModel، ويستخدمها PydanticAI للمخرجات ومخططات الأدوات. إذا كنت قد استخدمت بايثون لاختبار API أو عملت مع FastAPI، فسيبدو النموذج الذهني مألوفًا.

الخاتمة

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

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