Pydantic AI v2: القدرات وأداة التحكم (2026)

في سطر واحد: إصدار Pydantic AI v2، الذي صدر في 23 يونيو 2026، يدمج كل ما يحيط بالحلقة الأساسية للعميل (agent) — من تعليمات، وأدوات، وخطافات دورة الحياة (lifecycle hooks)، وإعدادات النموذج — في عنصر أساسي واحد قابل للتركيب يسمى "القدرة" (capability)، ويقدم نواة أخف بجانب حزمة Harness سريعة التطور، ويقلص نافذة التغييرات الجذرية (breaking-change window) إلى ثلاثة أشهر.

ملخص: صدر Pydantic AI v2 في 23 يونيو 2026، وهو أول إصدار رئيسي للإطار منذ v1 في سبتمبر الماضي.¹² العنوان الرئيسي هو عنصر أساسي جديد واحد — الـ capability — الذي يجمع تعليمات العميل، وأدواته، وخطافات دورة الحياة، وإعدادات النموذج في وحدة واحدة قابلة للتركيب.¹³ وبناءً على ذلك، قام الفريق بتقسيم المشروع إلى نواة صغيرة ومستقرة وحزمة رسمية سريعة التطور تسمى Harness، وقاموا بهدوء بتقليص النافذة التي يعدون بها بين التغييرات الجذرية من ستة أشهر إلى ثلاثة.¹⁴ إذا قمت بمعالجة تحذيرات الإلغاء (deprecation warnings) في v1 أولاً، فلن ينكسر أي شيء آخر تقريباً.⁵

ما ستتعلمه

• ما الذي تم إصداره في Pydantic AI v2، والتاريخ الدقيق الذي أصبح فيه مستقراً
• ما هي الـ "capability"، ولماذا تشكل الركيزة الأساسية لهذا الإصدار
• كيف يتم تقسيم المسؤوليات بين Harness والنواة الأكثر رشاقة
• ما الذي ينكسر فعلياً عند الترقية من v1 — وكيف خفف الفريق من ذلك
• لماذا انخفضت نافذة "عدم وجود تغييرات جذرية" من ستة أشهر إلى ثلاثة
• موقع v2 ضمن موجة إطلاق أطر عمل العملاء (agent-framework) الأوسع في عام 2026

ما الذي صدر في 23 يونيو

أصبح Pydantic AI v2 مستقراً في 23 يونيو 2026.¹ وهو أول إصدار رئيسي منذ وصول v1 في سبتمبر الماضي، ويحرص الفريق على الإشارة إلى أن الفجوة شملت أكثر من مائة إصدار "دون أن يتسبب ذلك في كسر الكود الخاص بك ولو لمرة واحدة".¹² Pydantic AI هو إطار عمل العملاء من الفريق الذي يقف وراء Pydantic — مكتبة التحقق من الأنواع المستخدمة في معظم أنظمة Python AI — لذا فإن الإصدار الرئيسي هنا هو إشارة تستحق القراءة وليس مجرد تغيير روتيني في الإصدارات.

الصياغة في الإعلان، الذي كتبه Douwe Maan من Pydantic، هي أن المشكلات المثيرة للاهتمام في بناء العملاء قد تغيرت.¹ ويجادل بأن "الحلقة الداخلية للعميل قد استقرت الآن: استدعاء النموذج، تشغيل أداة، ثم إعادة النتيجة"، وأن القوة الآن تكمن في الطبقة المحيطة بتلك الحلقة — التعليمات والأدوات التي تمنحها للعميل، وأيضاً الخطافات التي تعيد كتابة ما يراه النموذج أثناء التشغيل، وإدارة السياق، وتوجيه التشغيل أثناء التنفيذ، وتحميل الأدوات المناسبة في الوقت المناسب. أطروحة v2 بالكامل هي تحويل تلك الطبقة المحيطة إلى شيء واحد تقوم بتركيبه.¹

التثبيت يتم عبر أمر واحد لمستخدمي uv الحاليين:

uv add pydantic-ai

هذه هي القصة الكاملة لـ "الحصول على v2" إذا كنت تبدأ من الصفر.¹ السؤال الأكثر إثارة للاهتمام هو ما هذا العنصر الأساسي (primitive) في الواقع.

عنصر أساسي واحد: القدرة (capability)

القدرة (capability) في Pydantic AI هي وحدة واحدة قابلة للتركيب تجمع بين تعليمات العميل (agent)، وأدواته، وخطافات دورة الحياة (lifecycle hooks)، وإعدادات النموذج، بحيث يمكن لإضافة كاملة — مثل نظام ذاكرة، أو حاجز حماية (guardrail)، أو مجموعة أدوات برمجة — أن تصل إلى كل طبقة من طبقات العميل من خلال مفهوم واحد.¹³ وهي، بكلمات الفريق، "وحدة سلوك العميل التي تعيش داخل الحلقة". أنت تقوم بإرفاق القدرة بنفس الطريقة التي ترفق بها أي شيء آخر بالعميل:

from pydantic_ai import Agent
from pydantic_ai.capabilities import Capability, Thinking, ToolSearch, WebSearch
from pydantic_ai.mcp import MCPToolset
from pydantic_ai_harness import CodeMode

agent = Agent(
    'anthropic:claude-opus-4-7',
    instructions='Research thoroughly and cite your sources.',
    capabilities=[
        Thinking(effort='high'),  # extended thinking, unified across providers
        CodeMode(),               # one run_code call replaces N tool calls, sandboxed by Monty
        WebSearch(),              # native where the provider supports it, local fallback otherwise
        ToolSearch(),             # discover tools on demand instead of listing hundreds upfront
        Capability(
            id='github',
            description='Look up GitHub issues, pull requests, and code.',
            instructions='Use the GitHub tools when a question is about a repository.',
            toolset=MCPToolset('https://mcp.example.com/github'),
            defer_loading=True,  # stays out of the prompt until the model loads it on demand
        ),
    ],
)

بعض القدرات تكون بسيطة. Thinking(effort='high') هي في الحقيقة مجرد إعداد للنموذج — تفكير موسع، يتم تقديمه بطريقة متسقة عبر مختلف المزودين.¹ أما WebSearch() فهي تغلف أداة بحث ويب أصلية، وتُستخدم بشكل طبيعي حيثما يدعم المزود ذلك. أما القدرات القوية فتستخدم الخطافات (hooks) لقراءة وإعادة كتابة ما يراه النموذج في كل خطوة: أدواته، وتعليماته، وسجل الرسائل الخاص به.¹

هناك اثنتان من الأدوات في هذا المثال تستحق التوقف عندهما لأنهما ترتبطان مباشرة بمشكلات غطاها هذا الموقع. تتيح ToolSearch() للنموذج "اكتشاف الأدوات عند الطلب بدلاً من سرد المئات منها مسبقاً" — وهي نفس مشكلة الحمل الزائد التي تظهر عندما تحاول الإجابة على عدد الأدوات التي يمكن لعميل AI التعامل معها فعلياً قبل أن تتدهور الدقة.¹ وتأخذ الـ GitHub Capability في المثال هذا الأمر إلى أبعد من ذلك باستخدام defer_loading=True: حيث يرى النموذج وصفاً من سطر واحد فقط في كتالوج مضغوط، ثم يقوم بتحميل الحزمة كاملة — التعليمات والأدوات معاً — في خطوة واحدة عندما يقرر أنه بحاجة إليها.¹ وتقوم CodeMode() بدمج ما كان سيكون العديد من استدعاءات الأدوات المنفصلة في استدعاء run_code واحد، معزول (sandboxed) بواسطة Monty، وهي مجموعة Python الآمنة من Pydantic.¹⁶

بما أن القدرة (capability) قابلة للتسلسل (serializable)، يمكن تحميل العميل (agent) من ملف مواصفات (spec file)، كما أن السطح صغير بما يكفي بحيث يمكن لعميل برمجي موجه إلى وثائق القدرات أن يكتب معظمها نيابة عنك.¹³ نقطة التسلسل هذه هي أيضاً السبب في أن هذا العنصر الأساسي أصبح مغناطيساً لبقية الإطار العملي: ففي الإصدارات الأخيرة، قام الفريق بتحويل أدوات القياس (instrumentation)، واستدعاءات الأدوات المؤجلة التي يتم حلها في الحلقة (loop)، والضغط من جانب الخادم لـ OpenAI و Anthropic، والقدرات المبنية ديناميكياً لكل تشغيل، والتحميل عند الطلب، وطابور الرسائل المعلق لتوجيه التشغيل أثناء التنفيذ، كلها إلى "قدرات".¹ حتى التنفيذ المستدام (durable execution) — وهو القدرة على الحفاظ على تقدم العميل عبر الإخفاقات العابرة وإعادة التشغيل — يتم نقله إلى نفس طبقة القدرات، وهي عملية هجرة يصفها الفريق بأنها لا تزال جارية في وقت إصدار v2، مع نقطة توسيع لوقت التشغيل (runtime extension point) يتم تتبعها لما بعد v2.¹

The Harness ونواة أكثر رشاقة

إن Pydantic AI Harness عبارة عن حزمة منفصلة من الطرف الأول، pydantic-ai-harness، توفر "البطاريات" (المكونات الجاهزة) للعميل: الذاكرة، والضوابط (guardrails)، وإدارة السياق، والوصول إلى نظام الملفات، ووضع البرمجة (code mode)، وغيرها.¹⁴ هذا هو المكان الذي قضى فيه الفريق شهر يونيو، إلى جانب عميل برمجي بدون واجهة (headless coding agent) مبني على Pydantic AI يقولون إنهم يختبرونه داخلياً (dogfooding) عبر مستودعات Pydantic الخاصة.¹ يقوم مؤلفو المجتمع أيضاً بتوفير قدرات — حيث يشير الإعلان إلى VStorm من بين آخرين — مع مصفوفة قدرات في مستودع Harness تربط القدرات التي يوصي بها الفريق.¹

الفصل بين النواة (core) و Harness هو أمر متعمد، وهو النصف الهيكلي من قصة v2. تظل النواة صغيرة ومستقرة: فهي توفر الحلقة (loop)، والمزودين (providers)، والقدرات والخطافات (hooks) API، وفقط القدرات التي تحتاج إما إلى دعم عميق من المزود أو التي تعد أساسية لكل عميل.¹ كل شيء آخر يعيش في Harness، حيث يمكنه التحرك بسرعة، ويمكن لأي قدرة أن تنتقل إلى النواة بمجرد أن يثبت أنها ضرورية على نطاق واسع. يظهر نفس النهج في التغليف: uv add pydantic-ai لا يزال يتضمن OpenAI و Anthropic و Google افتراضياً، ولكن القائمة الطويلة من المزودين — bedrock و groq و mistral وأصدقاؤهم — أصبحت الآن اختيارية، لذا تقوم بتثبيت ما تستخدمه فقط.¹

هذا النمط — نواة مستقرة بالإضافة إلى حزمة "بطاريات" سريعة التطور — هو نمط بدأت أدوات الذاكرة والسياق في التقارب نحوه عبر النظام البيئي، وهو يتشابه مع الفصل بين نافذة السياق الخام للنموذج والآلية التي تديرها، وهو موضوع تم استكشافه في هذا الشرح لـ أداة الذاكرة وتحرير السياق في Claude. نسخة Pydantic تضع اسماً وحدود حزمة لهذا المفهوم.

ما الذي سيتعطل عند الترقية من v1

تم تصميم الترقية من Pydantic AI v1 إلى v2 لتكون عملية شبه تلقائية — إذا انتقلت أولاً إلى أحدث إصدار من v1 وقمت بمعالجة كل تحذير من تحذيرات الإيقاف التدريجي (deprecation warning).¹⁵ النصيحة المباشرة في الإعلان هي توجيه وكيل برمجي (coding agent) لمعالجة هذه التحذيرات؛ القيام بذلك يغطي معظم عملية الانتقال. أما ما لا يمكن لتحذير الإيقاف التدريجي رصده فهو قائمة قصيرة، ومن الجدير بمعرفتها قبل تحديث الإصدار:

• openai: أسماء النماذج الآن تستخدم الـ Responses API بشكل افتراضي. استخدم البادئة openai-chat: للبقاء على Chat Completions.¹
• WebSearch و WebFetch أصبحا أصليين (native) بشكل افتراضي، و MCP(url=...) يعمل محلياً بشكل افتراضي.¹
• أصبحت أدوات القياس (Instrumentation) الآن تعتمد بشكل افتراضي على الإصدار 5، مع سمات مجمعة لاستخدام الـ tokens.¹
• أدوات الدوال (Function tools) المطلوبة جنباً إلى جنب مع أداة مخرجات ناجحة يتم تشغيلها الآن بدلاً من تخطيها — وهو سلوك end_strategy='graceful'.¹

القائمة الكاملة موجودة في دليل الترقية (Upgrade Guide).⁵ هدف التصميم واضح: أحدث إصدار من v1 يحذر بالفعل من معظم ما يغيره v2، لذا يجب أن يبدو الإصدار نفسه غير مفاجئ إذا كنت مواكباً للتحديثات. هذه قصة انتقال غير مبهرة عمداً، وبالنسبة للفرق التي تشغل وكلاء في بيئة الإنتاج، فإن هذا هو الجزء الأكثر طمأنينة في الإصدار.

من ستة أشهر إلى ثلاثة: قراءة سياسة الإصدارات

التغيير الوحيد في v2 الذي لا علاقة له بالكود هو وعد. الفترة التي تضمنها Pydantic AI بين التغييرات الجذرية (breaking changes) ضمن سياسة الدعم الخاصة بها انتقلت من ستة أشهر إلى ثلاثة.¹ الفريق صريح في أن هذا ليس تقليلاً من الالتزام بالاستقرار: فلا توجد تغييرات جذرية ضمن إصدار رئيسي واحد، وعمليات الإيقاف التدريجي تسبق دائماً عمليات الإزالة، وكلاهما يظل كما كان تماماً. الشيء الوحيد الذي تقلص هو المدى الزمني الذي يرغب المشروع في الالتزام به لقرارات التصميم الحالية.

السبب المذكور هو المؤشر: "المجال يتحرك بسرعة كافية بحيث أن الالتزام لفترة أطول يعني الالتزام بقرارات تناسب اليوم وليس العالم بعد ثلاثة أشهر من الآن".¹ إذا قرأت هذا كإشارة للصناعة بدلاً من مجرد ملاحظة إصدار، فهذا يعني أن مطور الإطار البرمجي يقول إن الأرض تحت تصميم الوكلاء لا تزال تتحرك بسرعة تجعل الوعد المعماري لمدة ستة أشهر عبئاً. الدليل موجود في الإصدار نفسه — فالمبدأ الأساسي للقدرات (capability primitive) لم يكن موجوداً بهذا الشكل قبل عام، ويتم الآن نقل التنفيذ المستدام (durable execution) إليه حتى في هذه اللحظة.¹ أفق الثلاثة أشهر هو رهان الفريق على أن إعادة التشكيل القادمة ستكون أقرب من السابقة.

أين يقع v2 في سباق أطر العمل لعام 2026

يأتي Pydantic AI v2 في منتصف واحدة من أكثر الفترات ازدحاماً التي شهدها نظام agent-framework. فخلال عام 2026، قامت جميع الأطر القائمة على الرسوم البيانية (graph-based) والفرق (crew-based) — ومن بينها LangGraph و CrewAI و OpenAI Agents SDK — بإصدارات مكثفة، وحافظ Pydantic AI نفسه على وتيرة إصدارات سريعة منذ v2.⁷ الأمر المثير للاهتمام ليس من الذي يفوز، بل ما الذي يبنيه الجميع: ضغط السياق (context compaction)، والتنفيذ المستدام (durable execution)، والبحث عن الأدوات والتحميل المؤجل، والذاكرة، والضوابط (guardrails). هذه اهتمامات تتعلق بالإنتاج الفعلي وليس مجرد عروض تجريبية، وظهورها عبر أطر عمل مختلفة هو أوضح إشارة على أن أدوات الـ agent قد انتقلت من كونها مجرد ابتكار جديد إلى بنية تحتية.

الرهان المميز لـ Pydantic AI داخل هذا التقارب هو الدمج. فبينما توفر أطر العمل الأخرى واجهات منفصلة للأدوات والذاكرة والبرمجيات الوسيطة (middleware) والإعدادات، يرى v2 أن كل ذلك له نفس الشكل — وهو "القدرة" (capability) — وأن دمجها في وحدة واحدة قابلة للتركيب والتسلسل هو ما يجعل الـ agents أسهل في البناء والفحص وتسليمها لبرنامج آخر لتجميعها.¹³ مجموعة أدوات MCP في المثال هي تلميح لكيفية اتصال هذا بالعالم الأوسع لأدوات الـ agent: يمكن للقدرات أن تغلف خادم MCP بالطريقة التي تهدف إليها مواصفات MCP stateless الناشئة، بحيث تنطبق نفس قصة الحوكمة والتفويض سواء كانت الأداة محلية أو بعيدة. وبما أن القياس (instrumentation) أصبح الآن "قدرة"، فإن الآثار التي يصدرها الـ agent بالفعل تغلق حلقة يشعر الفريق بحماس شديد تجاهها: الـ agent الذي يمكنه قراءة تشغيلاته الخاصة يمكنه، من الناحية النظرية، رصد مجموعة من التعليمات المتناقضة أو أداة لا يتطابق وصفها مع ما تفعله، واقتراح الإصلاح.¹

لا يجعل هذا Pydantic AI الإطار الوحيد الذي يفكر بهذه الطريقة، والمنشور لا يحتاج أن يكون كذلك. ما يقدمه v2 هو إجابة متماسكة على سؤال يطرحه المجال بأكمله الآن علانية: بمجرد أن تصبح حلقة الـ agent أمراً بديهياً، ما هي الوحدة الصحيحة لبناء كل شيء آخر من خلالها؟

الخلاصة

Pydantic AI v2 هو رهان على التوحيد: عنصر أساسي واحد لتركيب كل ما يحيط بحلقة الوكيل (agent's loop)، ونواة صغيرة تظل مستقرة، و Harness يمكنه التحرك بسرعة تطور المجال.¹ السطر الأكثر كشفاً في هذا الإصدار لا يتعلق بالقدرات على الإطلاق — بل هو قرار الوعد بالاستقرار لمدة ثلاثة أشهر فقط بدلاً من ستة.¹ هذا يخبرك المسؤول عن الصيانة، بلغة سياسة الإصدارات، أن شكل أطر عمل الوكلاء لا يزال قيد التحديد. v2 هو إجابة قوية واحدة، لكنه لن يكون الإجابة الأخيرة هذا العام.