إضافة برنامج وسيط

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

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

برنامج وسيط يحل هذا. يتيح لك البرنامج الوسيط تضمين مسار تنفيذ العامل مع سلوكيات قابلة لإعادة الاستخدام تعترض الطلبات والاستجابات وتفحصها وتعديلها في نقاط محددة جيدا. فكر في البرامج الوسيطة كسلسلة من الطبقات متحدة المركز حول العامل - تحصل كل طبقة على فرصة للعمل على الإدخال قبل أن تصل إلى العامل، وعلى الإخراج قبل أن تصل إلى المتصل.

متى يتم استخدام هذا

أضف برنامج وسيط إلى وكيلك عندما:

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

Tip

يتضمن إطار عمل العامل الأجهزة المضمنة للتتبع والمقاييس. راجع إمكانية المراقبة للحصول على التفاصيل.

كيفية عمل البنية الأساسية لبرنامج ربط العمليات التجارية للبرامج الوسيطة

عند استدعاء أسلوب تشغيل العامل الخاص بك، لا ينتقل الطلب مباشرة إلى النموذج. بدلا من ذلك، فإنه يتدفق عبر البنية الأساسية لبرنامج ربط العمليات التجارية من طبقات البرامج الوسيطة، كل منها يمكنه فحص الطلب أو تعديله، والتفويض إلى الطبقة التالية، ثم فحص الاستجابة أو تعديلها في طريق العودة.

┌─────────────────────────────────────────────────────────┐
│  Caller: agent.run("What's the weather?")               │
└──────────────┬──────────────────────────────────────────┘
               ▼
┌─────────────────────────────────────────────────────────┐
│  Middleware 1 (Logging)                                  │
│  • Logs the incoming request                            │
│  • Calls next middleware                                │
│  • Logs the outgoing response                           │
└──────────────┬──────────────────────────────────────────┘
               ▼
┌─────────────────────────────────────────────────────────┐
│  Middleware 2 (Guardrails)                               │
│  • Checks input against content policy                  │
│  • If blocked → returns early with rejection message    │
│  • If allowed → calls next middleware                   │
│  • Checks output against content policy                 │
└──────────────┬──────────────────────────────────────────┘
               ▼
┌─────────────────────────────────────────────────────────┐
│  Agent core (model invocation, tool calls, etc.)        │
└─────────────────────────────────────────────────────────┘

نقاط رئيسية:

1. يقرر كل برنامج وسيط ما إذا كان يجب المتابعة أم لا. يمكن للبرنامج الوسيط استدعاء الطبقة التالية في السلسلة للمتابعة بشكل طبيعي، أو يمكنه اختصار المسار عن طريق إرجاع استجابة مباشرة — على سبيل المثال، عندما تمنع حواجز الحماية طلبا.
2. يرى البرنامج الوسيط كلا الاتجاهين. يقوم البرنامج الوسيط بتشغيل التعليمات البرمجية قبل التفويض (لفحص الإدخال أو تعديله) وبعد عودة الاستجابة (لفحص الإخراج أو تعديله). هذا هو نمط "البصل" الكلاسيكي.
3. سلسلة برامج وسيطة متعددة معا. عند تسجيل العديد من مكونات البرامج الوسيطة، فإنها تتداخل: أول برنامج وسيط مسجل هو الطبقة الخارجية، وآخر طبقة مسجلة هي الطبقة الأقرب إلى العامل.

Tip

للحصول على عرض مفصل لكيفية احتواء البرنامج الوسيط في البنية الأساسية لبرنامج ربط العمليات التجارية لتنفيذ العامل الكامل - بما في ذلك موفري السياق وطبقات عميل الدردشة - راجع بنية مسار العامل.

ما الذي يمكن أن تفعله البرامج الوسيطة

يدعم إطار عمل العامل البرامج الوسيطة في ثلاث طبقات من البنية الأساسية لبرنامج ربط العمليات التجارية - تشغيل العامل، واستدعاء الوظيفة، وعميل الدردشة - مما يمنحك تحكما دقيقا في مكان اعتراض التنفيذ. تشمل الأنماط الشائعة ما يلي:

النمط	Example	Reference
حواجز الحماية والإنهاء	حظر المحتوى الضار، والحد من طول المحادثة	حواجز الإنهاء والحراسة
معالجة الاستثناءات	إعادة المحاولة على حالات الفشل العابرة، إرجاع الاستجابات الاحتياطية	معالجة الاستثناء
تجاوزات النتائج	تنقيح البيانات الحساسة أو إثراء إخراج العامل أو استبداله	تجاوزات النتائج
الحالة المشتركة	تمرير معرفات الطلب أو بيانات التوقيت بين البرامج الوسيطة	الحالة المشتركة
سياق وقت التشغيل	تغيير السلوك استنادا إلى تكوين جلسة العمل أو المستخدم أو كل تشغيل	سياق وقت التشغيل
مجال	تطبيق البرامج الوسيطة على جميع عمليات التشغيل أو تشغيل واحد فقط	نطاق العامل مقابل نطاق التشغيل

للحصول على معاينة كاملة لتعريف البرامج الوسيطة وتسجيلها، راجع تعريف البرامج الوسيطة. للحصول على نظرة عامة على البنية الكاملة، راجع نظرة عامة على البرنامج الوسيط.

الاعتبارات

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

الخطوات التالية

الآن بعد أن أصبح لدى وكيلك أدوات ومهارات وبرامج وسيطة، فإن الخطوة التالية هي موفري السياق - المكونات التي تدخل الذاكرة وملفات تعريف المستخدم والمعرفة الديناميكية في نافذة سياق العامل قبل كل تشغيل.

موفرو السياق

انتقل إلى أبعد من ذلك:

• نظرة عامة على البرامج الوسيطة — مرجع كامل لجميع أنواع البرامج الوسيطة
• بنية البنية الأساسية لبرنامج ربط العمليات التجارية للعامل - كيف يتناسب البرنامج الوسيط مع البنية الأساسية لبرنامج ربط العمليات التجارية للتنفيذ