وضع الشيفرة

​

متى تستخدمه

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

​

تفعيله

npm install quickjs-emscripten@^0.32.0

import { createAgent, defineTool } from '@lousho/build-ai-agent';
import { z } from 'zod';

const prices: Record<string, number> = { apple: 1.2, pear: 0.8, plum: 2 };

const getPrice = defineTool({
  name: 'get_price',
  description: 'The price of one fruit in USD',
  input: z.object({ item: z.string() }),
  execute: async ({ item }) => ({ item, usd: prices[item] ?? null }),
});

const convert = defineTool({
  name: 'convert',
  description: 'Converts an amount in USD to another currency',
  input: z.object({ amount: z.number(), to: z.enum(['EUR', 'GBP']) }),
  execute: async ({ amount, to }) => ({ amount: amount * (to === 'EUR' ? 0.9 : 0.8), currency: to }),
});

const agent = createAgent({
  model: 'openai/gpt-4o-mini',
  tools: [getPrice, convert],
  codeMode: { exclusive: true },
});

const { text } = await agent.send('What do an apple, a pear and a plum cost together in EUR?');

let usd = 0;
for (const item of ['apple', 'pear', 'plum']) {
  usd += (await tools.get_price({ item })).usd;
}
const eur = await tools.convert({ amount: usd, to: 'EUR' });
return { usd, eur: eur.amount };

​

الخيارات

// The price of one fruit in USD
tools.get_price(args: { item: string }): Promise<unknown>

​

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

• await tools.<name>(args) تنتهي بنتيجة الأداة، أو ترمي Error (name: 'ToolError') رسالته هي رسالة خطأ الأداة. ولا يحتوي tools إلا على الأدوات المسموحة ولا يمكن تعديله.
• تعبر الوسائط والنتائج الحدّ نسخًا بصيغة JSON: فـ Date تصل نصًّا، وتُحذف الدوال والحقول undefined، وتعديل نتيجة داخل البرنامج لا يغيّر شيئًا خارجه.
• Promise.all تشغّل الاستدعاءات في وقت واحد، بحد أقصى toolConcurrency منها (إعداد الوكيل) في البرنامج الواحد.
• يجب أن تكون القيمة المعادة قابلة للتحويل إلى JSON؛ وundefined تصبح null.

​

نموذج الأمان

• العزل. يحصل كل برنامج على بيئة تشغيل وسياق QuickJS جديدين في WebAssembly، بلا شيء من المضيف فيهما سوى دالتين (استدعاء أداة، وسطر سجل) تسحبهما شيفرة الإعداد الخاصة بـ SDK من الكائن العام قبل أن يعمل البرنامج. ولا يُستخدم node:vm: فهو ليس حدًّا أمنيًا.
• الحدود. يفرض العزل حدّ الذاكرة وحدّ المكدّس البالغ 512 KiB. ويفحص معالج مقاطعة الموعد النهائي أثناء حساب البرنامج، فتُوقَف الحلقة التي لا تنتهي عند timeoutMs (ولا يستطيع try / catch اعتراض هذا الإيقاف)، ويفحصه مؤقّت أثناء انتظاره أداة. وكثرة استدعاءات الأدوات توقف البرنامج أيضًا، حتى لو التقط الخطأ.
• البوابة لكل استدعاء. كل tools.x(args) استدعاء أداة داخلي في التشغيل: يُتحقَّق منه مقابل مخطط الأداة، ثم تأتي خطّافات ما قبل الأداة وقواعد الصلاحيات ووضع الصلاحيات وحواجز حماية الأدوات وneedsApproval، ثم تعمل الأداة (عبر البيئة المعزولة للتشغيل إن كانت requiresSandbox) بمُنفِّذ (principal) التشغيل، ثم خطّافات ما بعد الأداة. والاستدعاء المرفوض يرمي خطأً في البرنامج مع سبب الرفض. وحاجز الحماية الذي يمنع استدعاءً داخليًا يوقف التشغيل كله، كما يفعل مع استدعاء مباشر.
• وضع التخطيط. run_code معلَّمة للقراءة فقط: فهي لا تغيّر شيئًا بنفسها. وفي وضع التخطيط يُفحص كل استدعاء داخلي على حدة، فيستطيع البرنامج استدعاء أدوات القراءة فقط، أما استدعاء أي أداة أخرى فيرمي denied by plan mode.
• الأخطاء. يصل خطأ الأداة إلى البرنامج رسالةً فقط، لا أثر مكدّس للمضيف أبدًا. والرموز التي حصلت عليها الأداة من ctx.getToken() تُحجب من نتيجتها، كما في الاستدعاء المباشر.

​

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

​

الأحداث والتتبّع

​

القيود والمتانة

• لا تقدّم جزئي. حالة البرنامج تعيش في العزل فقط. وبعد تعطل، يستدعي التشغيل المستأنف run_code من جديد فيعمل البرنامج كله مرة أخرى، بما فيه استدعاءات الأدوات التي كان قد أجراها. اجعل الأدوات التي يستدعيها البرنامج متساوية الأثر (idempotent) (قيمة ctx.toolCallId لكل استدعاء داخلي هي نفسها عند إعادة التشغيل: استخدمها مفتاحًا لتساوي الأثر)، أو استدعِ الأدوات ذات الآثار الجانبية مباشرة.
• JavaScript فقط. يكتب النموذج JavaScript؛ ولا يُحوَّل TypeScript.
• أين يعمل. تشغيلات وكيل createAgent(): send() وstream() والجلسات والاستئناف والموافقات، على Node. أما الهدف cloudflare-worker في lousho build فلا يضمّ QuickJS: وتشغيل مفعَّل فيه codeMode يفشل هناك عند بدايته. والوكيل الذي يبدأ وكيلًا فرعيًا (أداة task أو أداة التفويض) يعمل بلا وضع الشيفرة، وcodeMode الخاص بالوكيل الرئيسي لا يصل إلى أدوات الوكيل الفرعي.
• الأخطاء نتائج. خطأ في البرنامج، أو انتهاء المهلة، أو بلوغ حدّ الذاكرة، أو كثرة استدعاءات الأدوات، أو قيمة معادة تتجاوز maxOutputChars، هو خطأ أداة في run_code يسمّي السبب؛ يحصل عليه النموذج ويتابع التشغيل.