الانتقال إلى المحتوى الرئيسي
لم تُحدَّث ترجمة هذه الصفحة بعد، والنسخة الإنجليزية هي الأحدث والأصح، وقد يختلف المحتوى أدناه عنها. اقرأ النسخة الإنجليزية.
أدوات تشغّل الـ agents بأمان: input و output guardrails تفحص ما يدخل أي run وما يخرج منه (ومعاملات الـ tool calls)، وpatch checks فحوص fail-closed على تغيير مقترح قبل أن تتصرّف بناءً عليه، وsandboxed tools تعمل داخل container معزولة بدلًا من عملية الـ host. للقرارات البشرية على كل call انظر Approvals؛ وللـ hooks التي تفحص كل tool call أو ترفضه انظر Hooks.

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).
الـ guardrail هو { 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 في الإنتاج:
أي guardrail تفعّل، دون النص. أي حظر (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 آخر.
إذا كنت تبني coding agent، فإن SandboxShell يضع أداة الـ shell الخاصة بالـ workspace خلف الـ adapter نفسه؛ انظر أدوات مساحة العمل.