Vercel AI SDK ومحوّل ACP: ما الذي تغيّر؟

ماذا أضافت Vercel AI SDK فعلياً؟

لنبدأ بالفصل بين الطبقات التي كثيراً ما تختلط على الناس.

ينتج النموذج الاستجابة التالية. أما بيئة الوكيل فتحوّل النموذج إلى عامل قادر على إنجاز المهام، إذ تدير الجلسات والأدوات والموافقات والبيئات المعزولة والتعليمات وضغط السياق وحلقة العمل. ويوفر ACP، وهو اختصار لـ Agent Client Protocol، لغة مشتركة للتواصل بين العميل وبيئة الوكيل.

كان HarnessAgent من Vercel يمنح التطبيقات بالفعل واجهة API واحدة للعمل مع بيئات الوكلاء. لكن حلقة الوصل كانت لا تزال مفقودة. قبل هذا الإصدار، احتاجت Vercel إلى محوّل منفصل لكل بيئة تشغيل، بما فيها Claude Code وCodex وPi وDeep Agents وOpenCode.

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

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

يدعم المحوّل حالياً ACP version 1، ولا يدعم سوى الإصدار 1. إنه توافق عند حدود البروتوكول، وليس ضماناً بأن تتصرف جميع بيئات الوكلاء بالطريقة نفسها بعد الاتصال.

توضح Vercel هذا الاختيار بلا لبس. استخدم @ai-sdk/harness-claude-code أو @ai-sdk/harness-codex مع هاتين البيئتين. واستخدم @ai-sdk/harness-acp عندما تملك بيئة الوكيل حزمة متوافقة ولا يتوفر لها محوّل مباشر.

لماذا يهم محوّل ACP؟

ما تغيّر فعلياً هو حجم عمل التكامل.

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

ويحمي ذلك أيضاً طبقة المنتج. تعيد الدالتان HarnessAgent.generate() وHarnessAgent.stream() نتائج متوافقة مع AI SDK. وإذا كان الفريق يستخدم useChat بالفعل، فيمكنه الإبقاء على تدفق الواجهة كما هو مع تبديل العامل الذي ينفذ المهام خلفها.

لكن هذا الإصدار لا يجعل بيئة الوكيل أسرع أو أقل تكلفة أو أكثر قدرة. ولا يجعل تطبيقات ACP متطابقة. كما أنه لا يلغي الحاجة إلى البيئة المعزولة؛ فما زالت كل بيئة وكيل تعمل عبر ACP تحتاج إلى بيئة شبكية معزولة تكشف منفذاً واحداً على الأقل.

أما من يستخدم Claude Code أو Codex أو أي وكيل برمجة آخر مباشرة، فلن يتأثر غالباً. هذه الميزة موجهة إلى من يبني المنتج المحيط بهؤلاء الوكلاء.

من يمكنه الاستفادة منه فوراً؟

مؤسس شركة أدوات تطوير يريد دعم AI SDK

لنفترض أن شركتك تقدم بيئة لوكيل برمجة وتنشر بالفعل حزمة NPM متوافقة مع ACP. يمكنك الآن إعداد ملف تعريف واحد باستخدام createACP، ومنح مستخدمي AI SDK مساراً مدعوماً إلى بيئة التشغيل لديك.

المكسب هنا هو التوزيع. يتولى فريقك صيانة ما يخص الحزمة من تثبيت ومصادقة وتعليمات وصلاحيات، بينما يعالج محوّل Vercel البنية المشتركة المحيطة بها.

مهندس منصات يدعم عدة بيئات تشغيل

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

هذا لا يمحو الفروق السلوكية، بل ينقلها إلى ملفات تعريف مسماة يسهل تدقيقها مقارنة بمكدسات تنسيق منفصلة.

فريق SaaS لديه واجهة قائمة مبنية على AI SDK

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

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

مهندس أمن يرسم حدود الصلاحيات

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

لا يعني ذلك أماناً تلقائياً، لكنه يوفر موضعاً واضحاً لصياغة قواعد الأمان واختبارها.

مسار الإعداد

مثال موثّق ومتكامل

ثبّت حزم بيئة الوكيل ومحوّل ACP وVercel Sandbox:

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

يستخدم أقصر مثال صادق ملف تعريف Codex ACP الكامل من Vercel، لأنه يعرض تثبيت الحزمة وبيانات الاعتماد المباشرة وإعداد AI Gateway والتعليمات والصلاحيات في موضع واحد. إنه مثال على التوصيل، لا توصية باختيار ACP عند استخدام Codex. ففي تكامل Codex فعلي، تفضّل Vercel المحوّل المباشر.

يعرض الكود التالي ملف التعريف ومسار الاستدعاء الموثقين حالياً. وفّر إما CODEX_API_KEY أو OPENAI_API_KEY للمصادقة المباشرة. وإذا توفر AI_GATEWAY_API_KEY أو VERCEL_OIDC_TOKEN، فسيختار المسار الافتراضي auth: 'auto' استخدام AI Gateway بدلاً من ذلك.

import { createACP, type ACPPermissionModeMapping } from '@ai-sdk/harness-acp';
import { createCredentialRequestTransformation } from '@ai-sdk/harness/utils';
import { secureJsonParse } from '@ai-sdk/provider-utils';

export const codexACPHarness = createACP({
  harnessId: 'acp-codex',
  // Define the runtime's built-in tool names and input schemas to expose
  // provider-executed calls as typed HarnessAgent tools.
  // builtinTools: { ... },
  source: {
    type: 'npm-simple',
    packageName: '@agentclientprotocol/codex-acp',
    packageVersion: '1.1.4',
  },
  executable: 'codex-acp',
  forwardEnv: ['CODEX_CONFIG'],
  credentialEnv: ['CODEX_API_KEY', 'OPENAI_API_KEY'],
  credentialBrokering: ({ env }) => {
    const credential = env.CODEX_API_KEY ?? env.OPENAI_API_KEY;
    if (!credential) return [];
    const config =
      env.CODEX_CONFIG == null
        ? undefined
        : (secureJsonParse(env.CODEX_CONFIG) as {
            model_provider?: string;
            model_providers?: Record<string, { base_url?: string }>;
          });
    const baseUrl =
      config?.model_providers?.[config.model_provider ?? '']?.base_url ??
      'https://api.openai.com/v1';
    return [
      createCredentialRequestTransformation({
        baseUrl,
        headers: { Authorization: `Bearer ${credential}` },
      }),
    ];
  },
  instructionMapping: {
    type: 'launch-env-json',
    variable: 'CODEX_CONFIG',
    path: ['developer_instructions'],
  },
  permissionModeMapping: {
    'allow-reads': null,
    'allow-edits': null,
    'allow-all': { type: 'session-mode', modeId: 'agent-full-access' },
  } as const satisfies ACPPermissionModeMapping,
  authentication: {
    methodId: 'api-key',
  },
  providerAuthentication: {
    gateway: {
      env: {
        CODEX_API_KEY: { $source: 'gateway-api-key' },
        CODEX_CONFIG: {
          model: 'openai/gpt-5.6-sol',
          model_provider: 'ai_gateway',
          model_providers: {
            ai_gateway: {
              name: 'AI Gateway',
              base_url: {
                $source: 'gateway-base-url',
                ensureSuffix: '/v1',
              },
              env_key: 'CODEX_API_KEY',
              wire_api: 'responses',
              supports_websockets: false,
              http_headers: {
                'User-Agent': { $source: 'client-app' },
                'x-client-app': { $source: 'client-app' },
              },
            },
          },
          model_supports_reasoning_summaries: true,
          preferred_auth_method: 'apikey',
        },
      },
    },
  },
});

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

الصورة الكاملة بلا تجميل

حزم بيئات الوكلاء تجريبية، ومن المتوقع حدوث تغييرات كاسرة للتوافق بين الإصدارات؛ لذلك ليست هذه تبعية هادئة يمكن ترك إصدارها عائماً في بيئة الإنتاج من دون متابعة.

يتطلب تثبيت إصدار الحزمة قراراً صريحاً. يستطيع المصدر البسيط تثبيت إصدار محدد بدقة، كما يثبّت المثال @agentclientprotocol/codex-acp عند 1.1.4. وإذا حذفت الإصدار، فستثبّت البيئة المعزولة وسم latest للحزمة، ولن يدخل ذلك الإصدار في هوية بيئة الوكيل. وإذا كنت تحتاج إلى بناء قابل لإعادة الإنتاج، فاستخدم المصدر المقفل مع package.json وpnpm-lock.yaml؛ إذ تثبّته Vercel عبر pnpm install --frozen-lockfile.

يترك ACP version 1 أيضاً فجوات حقيقية:

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

لا تعرض صفحات Vercel الخاصة بهذا الإصدار سعراً منفصلاً لـ @ai-sdk/harness-acp. لكن لا ينبغي تحويل ذلك إلى استنتاج أن «الوكلاء مجانيون». فما زالت البنية تشمل مساراً لمصادقة النموذج وبيئة شبكية معزولة مطلوبة، ولذلك تظل تكاليف بيئة التشغيل وضوابطها الحالية سارية.

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

ما الخطوة التالية؟

قاعدتي بسيطة.

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

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

ابقَ على المحوّل المباشر إذا كنت تستخدم Claude Code أو Codex. لديك بالفعل المسار الذي توصي به Vercel، مع قدر أقل من السلوك الذي يُضغط ليمر عبر حدود البروتوكول.

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

إذا أردت مزيداً من الشروحات المبسطة للأدوات التي تغيّر طريقة إطلاق الفرق لمنتجاتها، فاشترك في النشرة البريدية.