Laravel AI SDK v1.0: ما الجديد، وما الذي سيتغير في تطبيقك عند الترقية

في 23 سبتمبر 2026 أعلن فريق Laravel، في مقال كتبه Pushpak Chhajed، عن الإصدار المستقر الأول (v1.0) من Laravel AI SDK، وهي واجهة واحدة بأسلوب Laravel للتعامل مع مزودي الذكاء الاصطناعي. بحسب الفريق، أُغلقت مئات الأخطاء منذ المرحلة التجريبية وأُضيفت ميزات كبيرة. لكن هذا الإصدار يحمل أيضًا تغييرات كاسرة، فالمقال يستحق قراءة متأنية قبل أن تضغط على الترقية.

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

1) التصنيف: نوع جديد من النماذج

بعض أعمال الذكاء الاصطناعي ليست كتابة: توجيه تذكرة، أو وسم تعليق، أو اختيار فرع في سير عمل. هذه قرارات تصنيف تحتاج سرعة وكلفة منخفضة. يقول المقال إن شركة TypeSafe (صانعة نموذج Jev) تسمي هذه النماذج «System One»، وإن الـ SDK صار فيه التصنيف قدرةً مستقلة إلى جانب النصوص والصور والصوت والتضمينات (embeddings). ويعد المقال بأن Jev يجيب أسئلة التصنيف في أجزاء من الثانية وبجزء من كلفة النماذج اللغوية التقليدية.

وللحالات الأبسط، دالة جديدة على الكلاس Str اسمها decide (macro): تسأل سؤالًا واحدًا بنعم أو لا وتعيد قيمة منطقية (boolean)، ويتحكم الوسيط threshold في مقدار اليقين المطلوب من النموذج.

التصنيف يعمل اليوم عبر TypeSafe وOpenRouter، ووعد الفريق بإضافة مزودين آخرين خلف الواجهة نفسها عندما تصدر نماذج مماثلة.

2) تحدّث بلغة واجهتك: Vercel Chat وAG-UI

الـ SDK صار يقرأ الطلبات ويبث الاستجابات بمعيارين شائعين للواجهات:

  • Vercel Chat: تمرّر الطلب إلى Vercel::chat ثم تمرر النتيجة إلى الـ agent. يقول المقال إن هذا المسار الواحد يتولى استقبال الرسالة الجديدة، وتحديث سجل المحادثة في قاعدة بياناتك، وفحص قرارات الموافقة على الأدوات التي أرسلها المستخدم.
  • AG-UI (Agent User Interaction): المعيار الذي تستخدمه عملاء مثل CopilotKit. ويمكن أيضًا تحويل الرسائل المخزنة إلى الشكل الذي يتوقعه العميل لإعادة بناء شاشة المحادثة بعد إعادة تحميل الصفحة.

3) الـ Middleware يخصص حلقة الـ agent

سابقًا كان middleware الـ agent يعمل مرة واحدة لكل prompt. الآن يغلّف كل خطوة توليد: agent ينادي ثلاث أدوات قبل أن يجيب يشغّل الـ middleware ثلاث مرات. كل خطوة تصل ككائن PendingStep تستطيع فحصه ونسخه مع تعديلات، وتتوفر دوال: withModel وwithInstructions وwithMessages وwithTools وonlyTools وwithToolChoice وwithMaxTokens وwithProviderOptions.

تطبيقات هذا، بحسب المقال: سحب أداة مكلفة من الـ agent بعد استخدامها مرة، أو تبديل النموذج كله في منتصف الـ prompt، أو تلخيص سجل رسائل طويل، أو إرجاع إجابة مخزنة مؤقتًا دون استدعاء المزود أصلًا. أي أن الـ middleware صار مكانًا قويًا للتحكم في الكلفة والسياق.

4) أدوات تتطلب موافقة بشرية: Approvable

بعض الأدوات لا يجوز أن تعمل دون موافقة صريحة (حذف بيانات، إرسال أموال...). الآن تنفذ الأداة العقد Approvable وتستخدم الـ trait InteractsWithApprovals. عندما يصل الـ agent إلى أداة كهذه يتوقف ليطلب الموافقة بدل تنفيذها. تخبرك الاستجابة بما ينتظر الموافقة، بما في ذلك الوسائط التي اختارها النموذج.

ثم تستأنف المحادثة بقرار لكل استدعاء معلّق، ويمكن أن يكون القرار: موافقة، أو رفض مع سبب يُعطى للنموذج، أو تعديل الوسائط قبل تشغيل الأداة. وتعمل الموافقات مع prompt وstream وqueue وطرق البث (broadcast).

5) المحادثات تخزّن كل خطوة

هذا أهم تغيير كاسر. الجدول conversations كان يخزّن استدعاءات الأدوات ونتائجها كقائمتين مسطحتين، مع حالة إعادة التشغيل في العمود meta. وهذا ضيّع معرفة أي جولة (round-trip) أنتجت استدعاءً معينًا، فكانت إعادة بناء السجل لمزود ما تعتمد على التخمين، وبعض المزودين كان يرفض النتيجة. وجعل استدعاءً لم يُنفَّذ يبدو كأنه ينتظر موافقة.

الآن تحمل الرسائل عمودًا واحدًا من نوع JSON اسمه steps فيه عنصر لكل جولة، وكل نتيجة مخزنة مع الاستدعاء الذي أنتجها. وما زالت المحادثات صفًا لكل دور (turn)، فيستمر عمل الترقيم (pagination) والخاصيتين toolCalls وtoolResults كما كانا.

ما الذي يتأثر؟

  • أي SQL خام يقرأ tool_calls أو tool_results يجب أن ينتقل إلى steps.
  • دليل الترقية يتضمن مهاجرة ملء (backfill) يجب تشغيلها مرة واحدة قبل النشر في الإنتاج.

6) لا ترسل كل الأدوات مع كل طلب: ToolSearch

agent عنده 30 أداة يصف الأدوات الثلاثين كلها مع كل طلب، وهذا يستهلك توكنات ويجعل اختيار النموذج أقل دقة كلما طالت القائمة. الآن تلف الأدوات النادرة الاستخدام داخل ToolSearch فيحمّلها المزود فقط عندما يحتاجها الـ prompt. الأدوات الملفوفة لا تحتاج تعديلًا. وهذا مدعوم مع OpenAI وAnthropic.

7) دع الـ agents ينفذون كودًا: CodeExecution

أداة المزود الجديدة CodeExecution تشغّل الكود في بيئة معزولة (sandbox) لدى المزود نفسه، لنتائج أدق في تحليل البيانات والحسابات. مدعومة مع Anthropic وOpenAI وAzure وGemini وxAI.

8) تقارير استهلاك موحدة (كاسر أيضًا)

صار تقرير الاستهلاك متسقًا عبر كل المزودين. الخاصيتان promptTokens وcompletionTokens أصبحتا inputTokens و**outputTokens**، وتشملان الأعداد الكاملة للمزود، أما التوكنات المخزنة مؤقتًا (cached) والمكتوبة في الكاش (cache-written) وتوكنات الاستدلال (reasoning) فهي الآن مجموعات جزئية من هذه الإجماليات. إذا كنت تجمع هذه الأرقام بنفسك فراجع الحسابات حتى لا تعد توكنات مرتين.

كيف أرقّي بأمان؟

يصنف فريق Laravel التغييرات الكاسرة في أربعة مجالات: تخزين المحادثات، وmiddleware الـ agent، واستهلاك التوكنات، وبروتوكولات البث. وفي دليل الترقية كل تغيير بكود قبل/بعد ودرجة احتمال التأثر، لتعمل على ما ينطبق عليك فقط.

ويوصي الفريق بترك مساعد ذكاء اصطناعي ينجز معظم العمل: Laravel Boost (خادم MCP الرسمي من Laravel) يأتي بأوامر ترقية موجهة لهذا الـ SDK. بعد تثبيته كاعتماد تطويري وتثبيت خادمه وإرشاداته، شغّل الأمر /upgrade-ai-sdk-v1 في Claude Code أو Cursor أو OpenCode أو Gemini أو VS Code، وسيمر Boost بمساعدك على الدليل تغييرًا بتغيير.

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

الخلاصة

  • v1.0 يضيف التصنيف السريع، ودعم بروتوكولات الواجهات، وتحكمًا أدق في حلقة الـ agent، وموافقة بشرية على الأدوات، وتقليلًا لاستهلاك التوكنات.
  • الثمن: تغييرات كاسرة في تخزين المحادثات وتقارير الاستهلاك، وتتطلب مهاجرة ملء قبل النشر.
  • لا تُرقِّ قبل قراءة دليل الترقية.

المصادر