ابنِ منسّق وكلاء متعددين

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

هذه هي البنية وراء أنظمة مثل مشرف LangGraph وOpenAI Swarm ومنصات دعم العملاء المؤسسية.

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

طلب المستخدم
     |
وكيل المشرف
     |
تفكيك المهام
     |
+---------+---------+
|         |         |
وكيل أ  وكيل ب  وكيل ج  (بالتوازي إذا مستقلة)
|         |         |
+---------+---------+
     |
تجميع النتائج
     |
الاستجابة النهائية

ملف 1: إطار تعريف الوكلاء

ابنِ واجهة AgentDefinition وفئة AgentRegistry. كل وكيل لديه:

• id فريد وname مقروء بشرياً
• systemPrompt يحدد سلوك الوكيل
• مصفوفة capabilities تصف المهام التي يمكنه التعامل معها (مثلاً ["billing", "refunds"])
• مصفوفة tools تسرد الأدوات التي يملك الوكيل وصولاً لها
• modelConfig مع اسم النموذج وإعدادات temperature
• maxTokenBudget يحدد عدد الرموز التي يمكن لهذا الوكيل استهلاكها لكل طلب

AgentRegistry يجب أن:

• يسجل ويلغي تسجيل الوكلاء
• يجد الوكلاء حسب القدرة (يعيد جميع الوكلاء الذين يسردون قدرة معينة)
• يتحقق أن معرفات الوكلاء فريدة عند التسجيل

ملف 2: وكيل المشرف

ابنِ فئة Supervisor تنسق سير عمل الوكلاء المتعددين:

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

ملف 3: بروتوكول تسليم الوكلاء

ابنِ HandoffManager يتعامل مع عمليات النقل بين الوكلاء:

• إنشاء HandoffRequest مع الوكيل المصدر والوكيل الهدف والسبب وسجل المحادثة وحالة المهمة
• التحقق أن الوكيل الهدف لديه القدرات المطلوبة قبل القبول
• نقل السياق (سجل المحادثة والنتائج المتراكمة) للوكيل المستقبل
• تتبع سلسلة التسليم لاكتشاف ومنع التسليمات الدائرية (أ -> ب -> أ)
• إعادة HandoffResult مع حالة النجاح/الفشل واستجابة الوكيل المستقبل

ملف 4: مدير الحالة المشتركة

ابنِ SharedStateManager يوفر حالة مشتركة آمنة للخيوط لجميع الوكلاء:

• get(key) وset(key, value) مع إصدار (كل كتابة تزيد رقم الإصدار)
• حل التعارضات مع استراتيجيتين:
  • last-write-wins: آخر كتابة تسري دائماً
  • merge: لقيم الكائنات، دمج عميق للقيمة الجديدة مع الموجودة
• getVersion(key) لاسترجاع رقم الإصدار الحالي لمفتاح
• getHistory(key) لاسترجاع سجل جميع الكتابات لمفتاح (القيمة + الإصدار + الطابع الزمني + معرف الوكيل)

ملف 5: المنفذ المتوازي

ابنِ ParallelExecutor يشغل المهام المستقلة بشكل متزامن:

• قبول رسم بياني للمهام حيث كل مهمة لديها id وdependencies (مصفوفة معرفات مهام) ودالة execute
• تحديد المهام التي يمكن تشغيلها بالتوازي (مهام مع جميع التبعيات مستوفاة)
• تنفيذ المهام الجاهزة بشكل متزامن باستخدام Promise.all
• الانتظار للتبعيات قبل بدء المهام التابعة
• اكتشاف التبعيات الدائرية ورمي خطأ
• إعادة جميع النتائج بعد تنفيذ الرسم البياني الكامل

ملف 6: قاطع الدائرة

ابنِ CircuitBreaker يحمي من فشل الوكلاء:

• ثلاث حالات: CLOSED (عادي)، OPEN (فاشل — رفض جميع الاستدعاءات)، HALF_OPEN (اختبار التعافي)
• تتبع عدد الأعطال لكل وكيل
• الانتقال من CLOSED إلى OPEN عندما يتجاوز عدد الأعطال عتبة قابلة للتكوين
• الانتقال من OPEN إلى HALF_OPEN بعد فترة تبريد قابلة للتكوين
• الانتقال من HALF_OPEN إلى CLOSED عند النجاح، أو العودة إلى OPEN عند الفشل
• عندما تكون دائرة الوكيل مفتوحة (OPEN)، التوجيه لوكيل بديل إذا تم تكوين واحد
• execute(agentId, fn) يغلف استدعاء الوكيل بمنطق قاطع الدائرة

ملف 7: تتبع التنفيذ

ابنِ ExecutionTracer يسجل كل إجراء في نظام الوكلاء المتعددين:

• تتبع كل استدعاء وكيل: معرف الوكيل، وقت البدء، وقت الانتهاء، استخدام الرموز، التكلفة
• تتبع التسليمات: المصدر، الهدف، السبب، النجاح/الفشل
• تتبع شجرة التنفيذ الكاملة (أي وكيل أنشأ أي مهام فرعية)
• حساب التكلفة الإجمالية عبر جميع الوكلاء (مجموع تكاليف الوكلاء الفردية)
• حساب المدة الإجمالية (وقت الساعة من أول حدث لآخر حدث)
• getSummary() يعيد كائناً مع التكلفة الإجمالية والمدة الإجمالية وعدد استدعاءات الوكلاء وتفصيل لكل وكيل

ماذا تقدّم

المحرر يحتوي على 7 أقسام ملفات مع تعليقات TODO. استبدل كل TODO بكود TypeScript الخاص بك. سيقوم المقيّم الذكي بتقييم كل قسم وفقاً لمعايير التقييم.

تلميحات

• للمنفذ المتوازي، استخدم الترتيب الطوبولوجي لتحديد ترتيب التنفيذ واكتشاف الدورات
• لقاطع الدائرة، خزّن وقت آخر فشل وقارنه مع Date.now() للتبريد
• لحل تعارضات الحالة المشتركة، استراتيجية الدمج يجب أن تستخدم دمج كائنات متكرر للكائنات المتداخلة
• لاكتشاف الحلقات في التسليمات، حافظ على Set<string> لمعرفات الوكلاء المزارة لكل محادثة
• استخدم Promise.all لتنفيذ المهام بالتوازي لكن كن حريصاً على التعامل مع فشل المهام الفردية بدون رفض الدفعة بالكامل