ابنِ إطار وكيل استدعاء أدوات

في هذا المختبر، ستبني أساس كل نظام وكلاء: وكيل استدعاء أدوات بلغة Python. وكيلك سيحتفظ بسجل أدوات، ويستخدم LLM لتحديد الأدوات التي يجب استدعاؤها، والتحقق من المعاملات، وتنفيذ الأدوات بأمان، والتعامل مع الأخطاء بسلاسة.

هذا هو النمط المستخدم في كل إطار وكلاء رئيسي (LangGraph، CrewAI، OpenAI Agents SDK). ببنائه من الصفر، ستفهم بالضبط كيف يعمل استدعاء الأدوات تحت الغطاء.

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

رسالة المستخدم
     ↓
حلقة الوكيل ←──────────────────┐
     ↓                           │
LLM (يقرر: الرد أو              │
     استدعاء أداة)               │
     ↓                           │
[إذا استدعاء أداة]              │
     ↓                           │
التحقق من المعاملات             │
     ↓                           │
تنفيذ الأداة (مع مهلة زمنية)    │
     ↓                           │
حقن النتيجة → العودة لـ LLM ────┘
     ↓
[إذا استجابة نهائية]
     ↓
الإعادة للمستخدم

الخطوة 1: سجل الأدوات

ابنِ فئة ToolRegistry تدير تعريفات الأدوات. كل أداة تحتوي:

• name فريد (معرّف نصي)
• description (ما تفعله الأداة — يُرسل هذا لـ LLM)
• parameters بصيغة JSON Schema (يحدد أنواع المدخلات المتوقعة)
• دالة handler (التنفيذ الفعلي)

السجل يجب أن يدعم:

• register(tool) — إضافة أداة للسجل
• unregister(name) — إزالة أداة بالاسم
• get(name) — استرجاع أداة بالاسم
• list_tools() — إعادة جميع تعريفات الأدوات (لإرسالها لـ LLM)

الخطوة 2: التحقق من المعاملات

قبل تنفيذ أي أداة، تحقق من الوسائط المقدمة مقابل JSON Schema الأداة:

• تحقق من وجود الحقول المطلوبة
• تحقق من تطابق الأنواع (string، number، boolean، array، object)
• أعد رسالة خطأ واضحة إذا فشل التحقق

يمكنك تنفيذ محقق بسيط أو استخدام نمط مكتبة jsonschema.

الخطوة 3: منفّذ الأدوات

ابنِ ToolExecutor يشغّل دوال الأدوات بأمان:

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

الخطوة 4: اختيار الأدوات بواسطة LLM

ابنِ ToolSelector يسأل LLM أي أداة/أدوات يجب استدعاؤها:

• تنسيق الأدوات المتاحة كأمر مهيكل لـ LLM
• تحليل استجابة LLM لاستخراج قرارات استدعاء الأدوات
• دعم قرار LLM بعدم استدعاء أي أدوات (استجابة مباشرة)
• دعم قرار LLM باستدعاء عدة أدوات بالتسلسل

استخدم تحليل المخرجات المهيكلة: يجب أن يعيد LLM JSON مع اسم الأداة والوسائط.

الخطوة 5: حلقة محادثة الوكيل

ابنِ فئة Agent الرئيسية التي تنسق كل شيء:

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

الخطوة 6: سجل التدقيق

أضف AuditLogger يسجل كل إجراء:

• محاولات استدعاء الأدوات (اسم الأداة، الوسائط، الطابع الزمني)
• نتائج تنفيذ الأدوات (النجاح/الفشل، المدة، المخرجات)
• قرارات LLM (استدعاء أداة مقابل استجابة مباشرة)
• أحداث الأخطاء (فشل التحقق، المهلات الزمنية، الاستثناءات)

ماذا تقدّم

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

تلميحات

• لمحقق JSON Schema، ركز على فحوصات type وrequired — لا تحتاج لتنفيذ JSON Schema كامل
• للمهلة الزمنية، استخدم concurrent.futures.ThreadPoolExecutor مع معامل timeout
• لاختيار أدوات LLM، حدد تنسيق أمر واضح وهيكل استجابة JSON متوقع
• حلقة الوكيل يجب أن تحتوي معامل max_iterations (افتراضي: 10) لمنع التنفيذ الجامح