شرح محول fx AI SDK harness من Vercel وكيفية تشغيله عملياً

أضافت Vercel أداة fx إلى طبقة AI SDK harness في August 31, 2026. يمكنك الآن تشغيل وكيل البرمجة خفيف الوزن هذا عبر واجهة HarnessAgent الموحدة والمستخدمة مع بيئات البرمجة الأخرى، إلا أن الفائدة العملية الحقيقية تكمن في خفض مجهود التكامل البرمجي، وليس في الحصول على وكيل يمكن استبداله بسحر دون فروق تشغيلية.

ما هو محول fx AI SDK harness في الواقع؟

أداة fx هي بيئة تشغيل لوكلاء البرمجة (coding-agent harness) وأداة سطر أوامر في آن واحد. بيئة التشغيل (harness) هي النظام المحيط باستدعاءات النموذج: فهي تدير مساحة العمل، والأدوات، والمهارات، والجلسات، والصلاحيات، وضغط السياق، والوكلاء الفرعيين الذين يمكّنون النموذج من إنجاز عمل برمجي حقيقي.

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

يعمل المحول الجديد @ai-sdk/harness-fx adapter كحلقة وصل بين HarnessAgent و fx. وفي الخلفية، يعتمد على Agent Client Protocol أو ما يُعرف بـ ACP كلغة مشتركة لبدء الجلسات، وإرسال التعليمات، وبث مجريات التقدم، والتعامل مع الأدوات، وإجراء عمليات التنظيف بعد الانتهاء.

أصبح المسار الآن كالتالي: يتواصل تطبيقك مع HarnessAgent، ثم يترجم محول fx هذا الطلب إلى بروتوكول ACP، ويعمل fx داخل بيئة معزولة شبكياً (network sandbox)، بينما تمر طلبات النموذج الخاصة به عبر Vercel AI Gateway.

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

لماذا يعد هذا التحديث مهماً، وما الذي لا يثبته؟

المكسب الفعلي هنا هو تقليص تكلفة التكامل التقني. فإذا كان منتجك يستخدم بالفعل HarnessAgent، فإن إضافة fx لم تعد تتطلب بناء نظام مستقل لإدارة الجلسات، أو معالج للتدفقات، أو جسر للصلاحيات، أو مسار مخصص للتنظيف.

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

يشير الموقع الرسمي لأداة fx حالياً إلى أن الوكيل في الإصدار v0.0.7، وهو تجريبي ومُرخص تحت Apache-2.0. كذلك تُعد حزم AI SDK harness تجريبية أيضاً؛ لذا فهذا المسار مناسب لاختبارات الاستكشاف الهندسي المعزولة، لكنه ليس اعتمادية هادئة يمكنك افتراض استقرارها دون متابعة.

لا توجد أرقام منشورة لمقارنات قبل وبعد الإطلاق توضح وقت الإعداد، أو زمن الاستجابة، أو جودة الكود البرمجي، أو التوفير المالي؛ فلا تحول مجرد وجود "واجهة برمجية موحدة" إلى ادعاءات أداء غير مستندة لأدلة. المحول يقلل العمل البرمجي الروتيني، لكن تقييم مدى كفاءة fx في حل مهام مستودعك البرمجي يظل مسؤوليتك.

المطورون الذين يستخدمون fx مباشرة عبر الطرفية (terminal) لن يتأثروا تقريباً، وينطبق الأمر نفسه على التطبيقات التي تقتصر على استدعاء النماذج عبر دوال التوليد العادية في AI SDK دون تشغيل بيئات وكلاء. تنحصر أهمية هذا التغيير إذا كنت تدمج coding agents مباشرة في منتج برمجي أو منصة داخلية.

الفئات المستفيدة من هذا التكامل غداً

المؤسس الفردي الذي يضيف إصلاح المستودعات إلى نظام SaaS

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

فرق منصات الوكلاء التي تجري تقييمات للبيئات البرمجية

يستطيع فريق المنصة إرسال نفس نص أمر الإصلاح عبر fx وبيئة تشغيل مدعومة أخرى، والتقاط التدفق نفسه على مستوى التطبيق، ومن ثم مقارنة معدلات إتمام المهام. تضم طبقة البيئات المدعومة أيضاً كلاً من Claude Code و Cline و Codex و Cursor و Deep Agents و Grok Build و OpenCode و Pi.

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

وكالات تطوير البرمجيات التي تعزل أعمال العملاء

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

فرق أدوات المطورين الداخلية لإصلاح المشاكل البسيطة

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

خطوات التنفيذ العملية

توفر current fx harness documentation دليلاً برمجياً متكاملاً بلغة TypeScript؛ استخدمه داخل مشروع AI SDK يدعم تشغيل TypeScript.

1. 1

   تثبيت الحزم الثلاث المطلوبة

   أضف الحزمة الأساسية لبيئات التشغيل، ومحول fx، ومحول Vercel Sandbox:

   pnpm add @ai-sdk/harness @ai-sdk/harness-fx @ai-sdk/sandbox-vercel

2. 2

   تزويد بيئة التشغيل ببيانات اعتماد Gateway

   قم بتعيين إما VERCEL_OIDC_TOKEN أو AI_GATEWAY_API_KEY في بيئة التشغيل التي تبدأ الوكيل؛ وعند توفر القيمتين، يفضل المحول استخدام VERCEL_OIDC_TOKEN.

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

3. 3

   إنشاء الجلسة، وبث المخرجات، وحذفها

   هذا هو المثال الأساسي الموثق، متضمناً معالجة التنظيف في حالتي النجاح والفشل:

   import { HarnessAgent } from '@ai-sdk/harness/agent';
   import { fx } from '@ai-sdk/harness-fx';
   import { createVercelSandbox } from '@ai-sdk/sandbox-vercel';
   
   const agent = new HarnessAgent({
     harness: fx,
     model: 'openai/gpt-5.6-luna',
     sandbox: createVercelSandbox({
       runtime: 'node24',
       ports: [4000],
     }),
   });
   
   const session = await agent.createSession();
   
   let exitCode = 0;
   try {
     const result = await agent.stream({
       session,
       prompt: 'Check the test failures and fix the production code.',
     });
   
     for await (const part of result.stream) {
       if (part.type === 'text-delta') {
         process.stdout.write(part.text);
       }
     }
   } catch (err) {
     exitCode = 1;
     console.error(err);
   } finally {
     await session.destroy();
     process.exit(exitCode);
   }

4. 4

   اختبار الصلاحيات والأحداث قبل المهام الحقيقية

   ابدأ بتشغيل مهمة مستودع آمنة لا ضرر منها؛ تأكد من استقبال تطبيقك للتدفق النصي، ومن وصول طلبات الإذن إلى المشغل، ومن تنفيذ session.destroy() عند فشل المهمة.

   التفصيلة التي يتجاهلها الكثيرون هي المنفذ المكشوف؛ إذ يتواصل fx عبر جسر ACP، مما يفرض على البيئة المعزولة فتح منفذ واحد على الأقل، ويستخدم هذا المثال المنفذ 4000.

إذا كنت بحاجة إلى بناء محول لوكيل مخصص آخر متوافق مع ACP، فإن الدليل ذو الصلة AI SDK ACP harness adapter explainer يشرح تلك الطبقة الأدنى بالتفصيل.

ما هي تكاليف التشغيل؟

أداة fx نفسها مفتوحة المصدر تحت رخصة Apache-2.0، إلا أن تشغيلها بشكل مدمج يولد تكاليف لرموز النماذج (tokens) واستهلاك Sandbox.

تفرض AI Gateway نسبة $0 كهامش ربح و $0 كرسوم منصة على الرموز. يحصل كل فريق في Vercel على رصيد شهري مجاني قدره $5 لمجموعة محددة من النماذج مع حدود معدل استهلاك أقل لكل نموذج. شراء أرصدة Gateway ينقل الفريق إلى الفئة المدفوعة وينهي ذلك الرصيد المجاني الشهري.

بالنسبة للبيئة المعزولة، فإن نموذج Vercel الخاص بمنطقة iad1 يسعر مهمة التحقق البرمجي بالذكاء الاصطناعي لمدة 5 دقائق بمواصفات 2 vCPUs و 4 GB من الذاكرة بنحو $0.03 بافتراض استخدام كامل للمعالج بنسبة 100% CPU. ووفقاً لهذا المثال، فإن تكلفة 1,000 مهمة تبلغ نحو $30 من قدرة معالجة Sandbox قبل احتساب تكلفة رموز النموذج؛ وقد تكون تكلفة المعالج النشط الفعلية أقل أثناء انتظار الوكيل لاستجابات النموذج أو عمليات إدخال وإخراج الشبكة.

يُخصم استهلاك Pro Sandbox أولاً من رصيد الخطة البالغ $20 شهرياً. المهلة الافتراضية للجلسة في Sandbox هي 5 دقائق، لذا حدد مهلة المهمة بعناية واحرص على إنهاء الجلسات المكتملة فوراً بدلاً من تركها مفتوحة.

خمسة قيود تقنية حاسمة قبل النشر للإنتاج

1. كلتا الطبقتين لا تزالان في المرحلة التجريبية

يحمل منتج fx وحزم AI SDK harness علامات تشير إلى أنها تجريبية. تحذر وثائق البيئة صراحة من إمكانية حدوث تغييرات جذرية معطلة (breaking changes) بين التحديثات.

2. المحول يعتمد تلقائياً على أحدث إصدار من fx

تُشغل الجلسة الأولى أداة التثبيت القياسية لأداة fx، والتي تجلب أحدث إصدار متاح تلقائياً. يحدد المحول مصدر التثبيت، والملف التنفيذي، وأمر التشغيل، وإصدار ACP مسبقاً، لذا لا تتيح لك دالة createFx() تثبيت تلك التفاصيل على إصدار محدد (pinning)، وهو ما يمثل عائقاً أمام موثوقية التكرار إذا كانت بيئة الإنتاج تتطلب استخدام إصدارات ثنائية معتمدة ومحددة بدقة.

3. عدم تطابق أوضاع الصلاحيات بدقة

يتم تحويل كل من allow-reads و allow-edits إلى وضع ask في fx، بينما يتحول allow-all إلى وضع code. لا تتيح fx وضعاً يسمح بتعديل الملفات مع اشتراط الموافقة على أوامر الطرفية، لذا لا يمكنك الافتراض بأن مسميات الصلاحيات على مستوى تطبيقك ستحافظ على دلالتها المحددة.

4. فجوات المراقبة والتتبع في ACP v1

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

5. غياب قابلية النقل لعدة خصائص تحكم

لا يوفر هذا المسار آليات نقل جاهزة لضغط السياق يدوياً، أو التوجيه أثناء الدور (mid-turn steering)، أو تصفية الأدوات المدمجة، كما لا تتوفر مخرجات مهيكلة مقيدة بمخطط (schema). يمكن لمحول ACP أن يكشف إمكانيات أقل مقارنة بالمحول المباشر، ولهذا السبب توصي Vercel باستخدام المحولات المباشرة مع Claude Code و Codex عند توفرها.

ما الخطوات التي يجب اتخاذها الآن؟

يمكنك تجربة المحول هذا الأسبوع إذا كان لديك بالفعل تطبيق يعمل عبر HarnessAgent، وكنت ترغب في تقييم fx على مهمة مستودع محددة، ولديك الجاهزية للتعامل مع اعتمادية برمجية تجريبية. ابدأ بنمط مهام مفرد وسجل معدلات الإنجاز، وطلبات الإذن، والتنظيف، والإنفاق على النماذج، وتكاليف Sandbox.

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

لن تتأثر بأي من هذا إذا كنت تشغل fx فقط كأداة سطر أوامر محلية، أو إذا كان تطبيقك يكتفي باستدعاءات النماذج البسيطة؛ فلا يوجد ما يدعو لإضافة طبقة بيئات تشغيل لمجرد توفر محول جديد.

للمزيد من التحليلات المعمقة والمبسطة حول الأدوات التي يعتمد عليها المطورون في الإنتاج الفعلي، انضم إلى newsletter.