ابنِ حواجز أمان الوكلاء الإنتاجية

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

كل نظام وكلاء إنتاجي في شركات مثل Anthropic وOpenAI وGoogle يحتوي على طبقات حواجز أمان كهذه. يتوقع المحاورون أن تفهمها بعمق وتصممها بشكل استباقي.

نظرة عامة على البنية

مدخل المستخدم
     ↓
┌─────────────────────┐
│  حواجز المدخلات      │ ← كشف الحقن، كشف PII، حدود الموضوع
└─────────┬───────────┘
          ↓
┌─────────────────────┐
│  متحكم التكلفة      │ ← ميزانية الرموز، حدود المعدل، توجيه تتابع النماذج
└─────────┬───────────┘
          ↓
┌─────────────────────┐
│  تنفيذ الوكيل       │ ← منطق وكيلك (استدعاءات الأدوات، الاستدلال)
└─────────┬───────────┘
          ↓
┌─────────────────────┐
│  حواجز الإجراءات    │ ← قائمة سماح الأدوات، حدود المعلمات، تأكيد العمليات المدمرة
└─────────┬───────────┘
          ↓
┌─────────────────────┐
│  حواجز المخرجات     │ ← تصفية المحتوى، فحص الدقة، التحقق من التنسيق
└─────────┬───────────┘
          ↓
┌─────────────────────┐
│  المراقبة            │ ← تسجيل منظم، تتبع، قواعد التنبيه
└─────────┬───────────┘
          ↓
الاستجابة للمستخدم

الخطوة 1: حواجز المدخلات (`input_guardrails.ts`)

ابنِ فئة InputGuardrailPipeline مع دوال حماية قابلة للتكوين:

كشف حقن الأوامر: تحقق من أنماط الحقن الشائعة (مثل "تجاهل التعليمات السابقة"، "system: أنت الآن"، تعليمات مشفرة). أعد GuardrailResult مع passed: boolean وreason: string وseverity: 'low' | 'medium' | 'high' | 'critical'.
كشف PII: امسح بحثاً عن عناوين البريد الإلكتروني وأرقام الهواتف وأنماط بطاقات الائتمان وأنماط SSN. أشر إلى PII المكتشف بالنوع والموقع.
فرض حدود الموضوع: تحقق مما إذا كان المدخل يبقى ضمن مجالات المواضيع المسموحة (قائمة قابلة للتكوين). ارفض الطلبات خارج الموضوع.
تنفيذ الأنبوب: شغّل جميع الحواجز بالتتابع. توقف فوراً عند شدة critical. أعد النتائج المجمعة.

الخطوة 2: حواجز المخرجات (`output_guardrails.ts`)

ابنِ OutputGuardrailPipeline:

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

الخطوة 3: حواجز الإجراءات (`action_guardrails.ts`)

ابنِ ActionGuardrailPipeline لأمان استدعاءات الأدوات:

قائمة سماح/حظر الأدوات: حافظ على قوائم قابلة للتكوين للأدوات المسموحة والمحظورة. احظر أي استدعاء أداة ليس في قائمة السماح.
فحص حدود المعلمات: لكل أداة، حدد نطاقات معلمات صالحة (مثل limit يجب أن يكون 1-100، email يجب أن يطابق نمطاً). ارفض المعلمات خارج الحدود.
تأكيد العمليات المدمرة: أشر إلى العمليات التي تعدل الحالة الخارجية (كتابة، حذف، إرسال). أعد نتيجة requires_confirmation: true بدلاً من الحظر.
تحديد معدل لكل أداة: تتبع عدد استدعاءات الأدوات ضمن نافذة زمنية. احظر الاستدعاءات المفرطة لنفس الأداة.

الخطوة 4: متحكم التكلفة (`cost_controller.ts`)

ابنِ CostController يدير إنفاق الوكيل:

ميزانية رموز لكل طلب: حدد عدد رموز أقصى لكل طلب. تتبع رموز الإدخال + الإخراج وارفض عند نفاد الميزانية.
حدود يومية لكل مستخدم: تتبع الاستخدام التراكمي لكل معرف مستخدم في اليوم. ارفض الطلبات عندما يتجاوز المستخدم حصته اليومية.
توجيه تتابع النماذج: بناءً على درجة تعقيد المهمة (بسيط/متوسط/معقد)، وجّه إلى مستوى النموذج المناسب (مثل نموذج صغير للتصنيف البسيط، نموذج كبير للاستدلال المعقد).
تقارير الاستخدام: أعد إحصائيات الاستخدام الحالية (الرموز المستخدمة، الميزانية المتبقية، النموذج المستخدم).

الخطوة 5: أداة التقييم (`evaluation_harness.ts`)

ابنِ EvaluationHarness لاختبار سلوك الوكيل:

تعريف حالات الاختبار: حدد حالات اختبار مع: input، expected_behavior (استدعاءات الأدوات، أنماط المخرجات، القيود)، وtags (للتجميع).
منفذ الاختبار: نفّذ كل حالة اختبار عبر أنبوب الحواجز والوكيل. قارن السلوك الفعلي مع التوقعات.
التأكيدات: ادعم التأكيدات على: محتوى المخرجات (يحتوي/لا يحتوي)، استدعاءات الأدوات (الأدوات المتوقعة مع المعلمات المتوقعة)، تفعيل الحواجز (الحواجز المتوقع تفعيلها)، والتكلفة (ضمن الميزانية).
تقارير النتائج: اجمع أعداد النجاح/الفشل، وأنشئ ملخصاً مع تفاصيل الفشل.

الخطوة 6: مجموعة الاختبارات العدائية (`adversarial_tests.ts`)

ابنِ مكتبة من أنماط الاختبار العدائية:

أنماط حقن الأوامر: 5 محاولات حقن على الأقل (تجاوز التعليمات، اختطاف الدور، حمولات مشفرة، هجمات الفواصل، حقن غير مباشر عبر نتائج الأدوات).
أنماط كسر القيود: 3 محاولات كسر قيود على الأقل (تبديل الشخصية، التأطير الافتراضي، التلاعب متعدد الأدوار).
حالات حدية: مدخل فارغ، مدخل طويل جداً، تلاعب بـ Unicode، JSON متداخل في المدخل.
مولد الاختبارات: دالة تنشئ حالات اختبار EvaluationHarness من هذه الأنماط، مع سلوك متوقع = يجب أن تلتقطها الحواجز جميعاً.

الخطوة 7: المراقبة (`observability.ts`)

ابنِ طبقة مراقبة منظمة:

مسجل القرارات: سجّل كل قرار وكيل (اختيار الأداة، اختيار المعلمات، توليد الاستجابة) كـ JSON منظم مع طوابع زمنية.
بانِي التتبع: ابنِ تتبعاً يمتد عبر الطلب بأكمله: مدخل → فحوصات الحواجز → خطوات الوكيل → استدعاءات الأدوات → حواجز المخرجات → الاستجابة. كل نطاق له معرف فريد ومعرف أب.
جامع المقاييس: تتبع الأعداد والمدد لـ: نجاح/فشل الحواجز، استدعاءات الأدوات حسب النوع، استخدام الرموز، الكمون لكل خطوة.
واجهة التصدير: وفّر طريقة لتصدير التتبعات والمقاييس بتنسيق متوافق مع أدوات المراقبة (JSON منظم).

الخطوة 8: قواعد التنبيه (`alert_rules.ts`)

ابنِ نظام تنبيه قابل للتكوين:

تعريف القواعد: حدد قواعد تنبيه مع: name، condition (دالة تقيّم المقاييس)، severity، وaction (دالة رد اتصال).
قواعد مدمجة: نفّذ 3 قواعد افتراضية على الأقل:
- ارتفاع التكلفة: تنبيه عندما تتجاوز تكلفة الطلب ضعف المتوسط المتحرك
- معدل انتهاكات الأمان: تنبيه عندما يتجاوز معدل فشل الحواجز حداً قابلاً للتكوين
- تدهور الكمون: تنبيه عندما يتجاوز الكمون p95 اتفاقية مستوى الخدمة المحددة
مقيّم القواعد: بالنظر إلى المقاييس الحالية، قيّم جميع القواعد وأعد التنبيهات المفعّلة.
سجل التنبيهات: تتبع التنبيهات الأخيرة مع طوابع زمنية وإزالة التكرار (لا تعد التنبيه لنفس القاعدة ضمن فترة تهدئة).

اختبار تنفيذك

للتحقق من أن تنفيذك يعمل:

أنشئ تكوينات حواجز نموذجية وشغّل المدخلات عبر الأنبوب
استخدم مجموعة الاختبارات العدائية للتحقق من كشف الحقن
اختبر متحكم التكلفة بمحاكاة استخدام الرموز
شغّل أداة التقييم مع حالات اختبار يجب أن تنجح وتفشل
تحقق من أن تتبعات المراقبة تلتقط دورة حياة الطلب الكاملة
فعّل قواعد التنبيه بمقاييس وهمية تتجاوز الحدود

التعليمات