الانتقال إلى المحتوى الرئيسي
لم تُحدَّث ترجمة هذه الصفحة بعد، والنسخة الإنجليزية هي الأحدث والأصح، وقد يختلف المحتوى أدناه عنها. اقرأ النسخة الإنجليزية.
مع code mode يحصل الموديل على tool إضافية: run_code. بدلًا من أن يستدعي الـ tools واحدة تلو الأخرى، مع round trip للموديل بعد كل call، يكتب برنامج JavaScript قصيرًا يستدعي tools الـ agent كدوال async، ويُجري loop وfilter ويجمع نتائجها، ثم يُرجع قيمة واحدة. وهكذا تصبح عدة tool calls بـ round trip واحد للموديل، والنتائج الوسيطة الكبيرة لا تدخل الـ context أصلًا: فقط قيمة إرجاع البرنامج تدخل. يعمل البرنامج داخل QuickJS WebAssembly isolate داخل العملية نفسها، لا داخل Docker. وكل tool call يجريها يمر بالفحوص نفسها التي يمر بها call مباشر من الموديل: التحقق من الوسائط، hooks، قواعد الصلاحيات وأوضاعها، guardrails، وneedsApproval.

متى تستخدمه

  • الجواب يحتاج عدة calls تعتمد مدخلاتها على نتائج سابقة (ابحث عن ثلاثة أسعار، ثم حوّل مجموعها).
  • tool تُرجع أكثر بكثير مما يحتاجه الموديل (قائمة طويلة تحتاج filter، أو تقرير تحتاج إلى عدّه).
  • الـ call نفسها تتكرر على قائمة عناصر.
أما إذا كان call واحدًا، أو كانت كل خطوة تحتاج حكم الموديل، فالـ tool calls المباشرة أبسط، والموديل أفضل فيها.

شغّله

ثبّت الـ peer dependency الاختيارية quickjs-emscripten واضبط codeMode على createAgent(). بادئة vendor/ في اسم الموديل تحدد الـ provider؛ ومع OpenRouter استخدم openrouter/<vendor>/<model> (مثل openrouter/openai/gpt-4o-mini):
سكربت قد يكتبه الموديل لهذا السؤال:
run_code تُرجع { result, logs, toolCalls }: قيمة إرجاع السكربت، والأسطر التي سجّلها بـ console.log() (وconsole.error() / warn()، مسبوقة بمستواها)، وعدد الـ tool calls التي أجراها. بدون quickjs-emscripten مثبّتة، أول run لـ agent عليه codeMode يفشل بـ MissingPeerDependencyError يذكر اسم الحزمة وأمر التثبيت.

الخيارات

codeMode: true تعني الإعدادات الافتراضية. وإذا مرّرت object يمكنك ضبط أي خيار مما يلي: بدون tools، يستطيع السكربت استدعاء كل tools الـ run ما عدا run_code وask_question وtools الـ sub-agents (task وagent_status وagent_await وagent_cancel وdelegate_to_*) وtool_search وload_skill والأدوات التي يؤجّلها tool search. سمِّ tool في tools لتسمح بها رغم ذلك: الـ deferred tool المذكورة هناك تصبح قابلة للاستدعاء من السكربتات ويظهر توقيعها في وصف run_code (أي أنها لم تعد محجوبة عن الـ context في code mode)، لكنها تظل خارج قائمة tools الموديل نفسه إلى أن تحمّلها tool_search. يعرف الموديل ما يستطيع استدعاءه من وصف run_code: signature بأسلوب TypeScript لكل tool مسموحة، مبني من input schema الخاصة بها، ووصفها يظهر كتعليق:
ليس للنتائج نوع معلَن، فإذا فشل السكربت يسرد الخطأ أول خمس tool calls أجراها مع وسائطها ونتائجها (كل منها مقصوصة عند 200 حرف). ويستطيع الموديل قراءة الأشكال من هناك وإصلاح السكربت.

ما يستطيع السكربت فعله وما لا يستطيع

الكود هو جسم دالة async. يستطيع استخدام لغة JavaScript ودوالها المدمجة (JSON وMath وDate وPromise والمصفوفات والـ maps والتعابير النمطية)، واستدعاء tools، والتسجيل، وإرجاع قيمة.
  • await tools.<name>(args) تعود بنتيجة الـ tool، أو ترمي Error (name: 'ToolError') رسالته هي رسالة خطأ الـ tool نفسها. وtools فيها فقط الـ tools المسموحة ولا يمكن تغييرها.
  • الوسائط والنتائج تعبر الحدود نسخَ JSON: Date تصل كـ string، الدوال والحقول undefined تُحذف، وتغيير نتيجة داخل السكربت لا يغيّر شيئًا خارجها.
  • Promise.all تشغّل الـ calls في الوقت نفسه، بحد أقصى toolConcurrency (إعداد الـ agent) لكل سكربت.
  • يجب أن تكون قيمة الإرجاع JSON-serializable؛ وundefined تصبح null.
لا يوجد require ولا import ولا process ولا fetch ولا نظام ملفات ولا شبكة ولا setTimeout ولا أي مؤقّت آخر، ولا أي host object. ويصل السكربت إلى العالم الخارجي فقط عبر الـ tools المُعطاة له.

نموذج الأمان

  • العزل. كل سكربت يحصل على QuickJS runtime وcontext جديدين في WebAssembly، ولا يوجد فيهما شيء من الـ host غير دالتين (واحدة لـ tool call وواحدة لسطر log) ينزعهما كود الإعداد الخاص بالـ SDK من الـ global object قبل أن يعمل السكربت. وnode:vm لا يُستخدم هنا، لأنه ليس حدًّا أمنيًا.
  • الحدود. الـ isolate يفرض حد الذاكرة وحد الـ stack البالغ 512 KiB. والموعد النهائي يفحصه interrupt handler بينما السكربت يحسب، فأي loop لا نهائية تُوقَف عند timeoutMs — try / catch لا يستطيع التقاط هذا الإيقاف — ويفحصه مؤقّت بينما السكربت ينتظر tool. وكثرة الـ tool calls توقّف السكربت أيضًا، حتى لو التقط الخطأ.
  • البوابة لكل call. كل tools.x(args) هو inner tool call داخل الـ run: يُتحقق منه مقابل schema الـ tool، ثم pre-tool hooks وقواعد الصلاحيات ووضع الصلاحيات وtool guardrails وneedsApproval، ثم تعمل الـ tool (عبر sandbox الـ run إذا كانت requiresSandbox) بـ principal الـ run، ثم post-tool hooks. والـ call المرفوضة ترمي خطأ داخل السكربت مع سبب الرفض. والـ guardrail التي تمنع inner call توقّف الـ run كله، كما تفعل مع call مباشرة.
  • Plan mode. run_code معلَّمة read-only: لا تغيّر شيئًا بنفسها. وفي plan mode يُفحص كل inner call على حدة، فيستطيع السكربت استدعاء tools القراءة فقط، وأي call لـ tool أخرى ترمي denied by plan mode.
  • الأخطاء. خطأ الـ tool يصل إلى السكربت كرسالة فقط، ولا يصل معه stack trace من الـ host أبدًا. والـ tokens التي أخذتها الـ tool من ctx.getToken() تُحجب من نتيجتها، كما في call مباشرة.
السكربت الذي يحسب دون انتظار يعمل على thread عمليتك: يحجب الـ event loop إلى أن ينتهي أو يوقفه timeoutMs. وعلى سيرفر يعالج طلبات أخرى، أبقِ timeoutMs منخفضًا.

الموافقات وتسجيل الدخول والتوقفات الأخرى

السكربت لا يستطيع التوقف. الـ QuickJS isolate لا يمكن حفظه واستئنافه لاحقًا، فأي inner call كان سيوقّف الـ run يرمي خطأ داخل السكربت بدلًا من ذلك، والـ run لا يتوقف: يستطيع الموديل بعد ذلك استدعاء تلك الـ tool مباشرة، فيتوقف الـ run كالمعتاد. وrun_code نفسها قد تحتاج approval (مثلًا مع permissions: [ask('*')]): يتوقف الـ run قبل أن يعمل السكربت، ويعمل السكربت بعد قرار الموافقة، مع فحص كل inner call.

الأحداث والـ tracing

الـ inner calls تصدّر أحداث tool.start وtool.partial وtool.done وtool.error المعتادة، مع parentToolCallId مضبوط على معرّف call الـ run_code. معرّفاتها <run_code call id>:<n>، مرقّمة بترتيب الـ calls التي أجراها السكربت. وtool.done أو tool.error لكل inner call يصل قبل الخاص بـ run_code نفسها: فإذا انتهى السكربت (أو أُوقف) وما زالت calls بدأها شغّالة، يُلغى abortSignal الخاص بها وتنتظر run_code حتى تستقر. والـ inner calls تنتج أيضًا أحداث permission.decision، والـ hooks تراها تحت معرّفاتها الخاصة. النتائج الداخلية تذهب للأحداث وللسكربت فقط. أما الـ transcript والـ session والموديل فيحصلون فقط على نتيجة run_code وحدها. مع tracing، لكل inner call الـ span execute_tool الخاصة بها، ابنة لـ span الـ run_code، ومعها السمة lousho.tool.parent_call_id.

القيود والـ durability

  • لا تقدّم جزئي. حالة السكربت تعيش فقط داخل الـ isolate. بعد crash، يستدعي الـ run المستأنف run_code من جديد ويعمل السكربت كله مرة أخرى، بما فيه الـ tool calls التي كان أجراها. اجعل الـ tools التي يستدعيها السكربت idempotent — ctx.toolCallId لكل inner call هو نفسه عند إعادة التشغيل، فاستخدمه كـ idempotency key — أو نادِ الـ tools التي لها side effects مباشرة.
  • JavaScript فقط. الموديل يكتب JavaScript؛ وTypeScript لا يمر بـ transpile.
  • أين يعمل. كل runs وكيل createAgent(): send() وstream() والـ sessions والاستئناف والموافقات، على Node. وهدف cloudflare-worker في lousho build لا يضمّ QuickJS، فالـ run المفعَّل فيه codeMode يفشل هناك من بدايته. والـ agent الذي يُشغَّل كـ sub-agent (عبر أداة task أو delegate tool) يعمل دون code mode، وcodeMode الخاص بالـ lead لا يصل إلى tools الـ sub-agent.
  • الأخطاء نتائج. خطأ في السكربت، timeout، بلوغ حد الذاكرة، كثرة tool calls، أو قيمة إرجاع تتجاوز maxOutputChars — كلها تصبح tool error في run_code يسمّي السبب؛ يستلمه الموديل والـ run يكمل.