Input و output guardrails
createAgent({ guardrails }) (أو ExecuteOptions.guardrails) يفحص الـ run في ثلاث نقاط، وكل قائمة تعمل بالترتيب:
الـ input guardrails المتوازية. فحص input بطيء (فحص يستدعي model، مثل
moderationGuardrail({ model })) يضيف زمن الاستجابة الخاص به كاملًا قبل أن يبدأ الـ agent بالرد. علّمه بـ runInParallel: true (على IoGuardrail الخاص بك، أو كخيار في promptInjectionGuardrail وmoderationGuardrail) فيعمل بينما أول model call قيد التشغيل: الـ input guardrails الحاجبة (الوضع الافتراضي) تعمل أولًا، بما فيها الـ rewrites، ثم تبدأ الفحوص المتوازية معًا على الـ input نفسه ويبدأ الـ model call فورًا. إلى أن تجتاز كل الفحوص المتوازية، لا يخرج أي شيء أنتجه الـ call: أحداث text.delta وreasoning.* وأحداث الـ tools التي ينفّذها الـ provider تُحتجز بالترتيب (step.start لا يُحتجز)، ولا تُنفَّذ الـ tool calls؛ والرد الذي يصل مبكرًا ينتظر الفحوص. إذا اجتازت، تخرج الأحداث المحتجزة ويستمر الـ run تمامًا كما في وضع الـ guardrails الحاجبة. وإذا حجب أحدها، يُلغى الـ model call، وتُرمى الأحداث المحتجزة، ولا يصل شيء من الـ call إلى سجل المحادثة أو checkpoint أو onLLMResponse، وينتهي الـ run بـ finishReason: 'guardrail' وguardrail.tripped (أو GuardrailError مع onTripped: 'throw') مثل أي حظر عادي. الفحص المتوازي لا يستطيع إجراء rewrite، لأن الـ input وصل إلى الـ model بالفعل: نتيجة rewrite تحجب، ويبدأ السبب بـ runInParallel guardrails cannot rewrite: . الثمن هو التكلفة: قد يكون الـ call المحجوب قد استهلك tokens قبل الحظر. تُحسب في result.usage إذا أبلغ عنها الـ provider (call انتهى قبل الـ trip)؛ أما الـ stream الملغى فلا يُبلغ عنها عادةً، ولا نقدّرها بأنفسنا. أول model call في الـ run فقط هو الذي يتسابق، والـ run الذي يُستأنف بعد approval (موافقة) لا يعيد فحص الـ input. وفي guardrails من نوع output وtools، يُتجاهَل runInParallel. نص model في الـ guardrail هو spec بصيغة provider/model: بادئة vendor/ تختار الـ provider؛ ومع OpenRouter استخدم openrouter/<vendor>/<model> (مثال openrouter/openai/gpt-4o-mini).
{ name, check(ctx) }. في ctx: kind ('input' أو 'output' أو 'tool')، وtext، وmessages الخاصة بالـ run، وtoolName وargs عندما يكون tool call، وsignal الخاصة بالـ run. تعيد check (مباشرة أو عبر promise) { ok: true } أو { ok: false, reason, action?, replacement?, info? }:
action: 'block'(الافتراضي) ينهي الـ run بـfinishReason: 'guardrail'وresult.guardrail({ name, kind, reason, toolName?, info? }). تكونresult.textهي''ولا يُضاف الرد المحجوب إلى سجل المحادثة؛ ولا يُنفَّذ الـ tool call المحجوب (ولا الذي يليه في الدورة نفسها) ويأخذ نتيجة “cancelled”، لكي يبقى سجل المحادثة صالحًا.stream()يطلقguardrail.trippedقبلrun.done.action: 'rewrite'يضعreplacementمكان النص (وفي معاملات tool call:replacementهي المعاملات الجديدة بصيغة JSON)، ويرى الـ guardrail التالي النص الجديد، وstream()يطلقguardrail.rewrote.
onTripped: 'throw' يُرفض الحظر بـ GuardrailError (LOUSHO_GUARDRAIL_TRIPPED، ومعه الـ guardrail نفسه) بدلًا من أن ينتهي بشكل عادي. وإذا رمت check خطأً، يفشل الـ run. الـ sub-agents تشغّل guardrails الأب أولًا، ثم guardrails الخاصة بها. ملفات spec الخاصة بالـ agent تسمّي الـ guardrails المدمجة في policy.guardrails (انظر الإعداد).
الأربعة الأخيرة starter set للفحوص التي تحتاجها أغلب الـ agents في الإنتاج:
result.guardrail، guardrail.tripped، guardrail.rewrote، GuardrailError.guardrail) يحمل info — GuardrailTripInfo إذا وفّره الـ guardrail، والـ starter set توفّره دائمًا: { category: 'pii', matches: [{ type, start, end }] } أو { category: 'secret', matches: [{ label, start, end }] } أو { category: 'prompt-injection', source: 'heuristic' | 'model', signals } أو { category: 'moderation', categories }. تشير الإزاحات إلى مواضع في النص المفحوص (ctx.text). لا يحتوي info النص المطابق أبدًا، ولا reason في فحصَي PII والأسرار (أنواع وتسميات فقط)، فلا تنسخ الأحداث والـ traces والـ logs البيانات الشخصية ولا السر. ويستطيع الـ guardrail الخاص بك أن يعيد info: { category: 'custom', ...anything }.
الحدود. فحوص PII والأسرار وprompt injection فحوص أنماط heuristic: تلتقط الصيغ الشائعة المذكورة أعلاه وتفوّت غيرها (بيانات شخصية بصيغ أو لغات أخرى، سر ببادئة غير معروفة، injection أُعيدت صياغته أو تُرجم أو رُمّز)، وتعلّم أيضًا بعض النصوص البريئة (رقم طلب يشبه رقم هاتف، نسخة تشبه IP address، مستخدم يسأل عن “system prompts”). عاملها كـ filter أول، لا كحد أمني؛ وأبقِ صلاحيات الـ tools والـ approvals مفعّلة لأي شيء يهمك. الفحوص التي تعتمد على model موثوقيتها بقدر موثوقية الـ model، وتكلّف call واحدًا لكل نص مفحوص، وتفشل fail-closed: الرد الذي لا يأتي بأي من الصيغتين يُحجب، مع سبب يذكر أن الرد لم يُقرأ. نتائج الـ tools (مثل صفحة ويب مجلوبة فيها injection غير مباشر) لا يفحصها أي guardrail حتى الآن.
Patch checks
runPatchChecks(patch, checks) يشغّل كل الفحوص بالتوازي على patch مقترح ويجمع النتائج في verdict واحد. مثال ops-pipeline يستخدمه كبوابة على patch من agent إصلاح قبل أن يُفتح pull request:
Fail-closed. الفحص الذي يرمي خطأً، أو يُرفض، أو لا ينتهي خلال مهلة الـ timeout (30 ثانية افتراضيًا)، أو يعيد أي شيء غير
pass: true يُحسب فاشلًا: runPatchCheckSafely(check, patch) تغلّف كل واحد منها. فحص الأمر يقتل العملية عندما تنقضي المهلة (على Windows، شجرة العمليات كلها). اكتب فحصك بالشكل { name, check(patch) } الذي يعيد { pass, reason? }.
Sandboxed tools
الـ tool تشترك بـrequiresSandbox: true ودالة sandboxExecute(args, sandbox). بعد ذلك يستدعي الـ executor sandboxExecute مع SandboxAdapter الخاص بالـ run بدلًا من أن يستدعي execute. createAgent() لا تأخذ sandbox حتى الآن، لذا يمر ذلك عبر الـ executor.
متقدم: الـ executor API
NoopSandbox(الافتراضي) يعمل على الـ host. مجرد بديل شكلي، لا عزل فيه.SubprocessSandboxينفّذ كل أمر في Docker container جديدة، معزولة عن الشبكة وتُحذف تلقائيًا، ولا يُوصَل بها أي مجلد من الـ host إلاcwdالذي تمرّره. يحتاج Docker daemon قيد التشغيل والـ peer dependency الاختياريةdockerode(npm install dockerode@^5.0.1؛ تُحمَّل عند أول استخدام). وإذا أُلغي الـ run (أُلغيت الـsignalالخاصة به) أو انتهت مهلة الأمر، تُقتل الـ container وتُحذف. كل container تعمل بمستخدم غير root (user، الافتراضي'1000:1000'؛ وعلى host لينكس يجب أن يستطيع الكتابة في الـcwdالموصول)، مع إسقاط كل Linux capabilities، وno-new-privileges، وlimitsافتراضيًا 512 MiB ذاكرة و256 عملية و1 CPU.writeFile(path)يكتب على الـ host فقط تحتroot(الافتراضي: مجلد العمل الحالي)؛ وأي مسار خارجه، حتى لو كان عبر symlink، يُرفض بـLOUSHO_SANDBOX_PATH_DENIED.- نفّذ
SandboxAdapter(name،run(cmd, args, opts)،writeFile(path, content)) لـ backend آخر.
SandboxShell يضع أداة الـ shell الخاصة بالـ workspace خلف الـ adapter نفسه؛ انظر أدوات مساحة العمل.