الاختبارات والمحاكاة

يُعدّ اختبار الوكلاء قدرة أساسية في الإطار، لا أمراً ثانوياً. يأتي Agent-Lab مع بيئتي اختبار متكاملتين يمكنك استخدامهما للتحقق من الإطار نفسه وكذلك من الوكلاء التي تبنيها فوقه:

• اختبارات التكامل تختبر النظام مقابل بنية تحتية حقيقية (Postgres، وRedis، وKeycloak، والتضمينات، وChrome بلا واجهة) تُشغَّل عند الطلب باستخدام testcontainers — وتغطي الخدمات الخارجية، وعمليات قاعدة البيانات، والبحث المتّجهي، ونقاط نهاية الواجهة البرمجية.
• محاكاة الوكلاء تقيّم سلوك الوكلاء من طرف إلى طرف مقابل نماذج LLM حية، ويمنحها الدرجات مُحكِّم من نوع LLM-as-judge، وتُتابَع بمرور الوقت في Langfuse وLangWatch.

يوجد الإعداد الرئيسي لاختبارات التكامل في tests/conftest.py؛ خصّصه بما يناسب بيئتك.

ملاحظة: تُجري اختبارات التكامل والمحاكاة استدعاءات حقيقية لخدمات خارجية وقد تترتب عليها تكاليف. شغّلها في بيئة مضبوطة وراقب الاستهلاك.

اختبارات التكامل

تتطلب Docker (أو بيئة تشغيل حاويات أخرى) — إذ تجهّز الحزمة حاويات حقيقية عبر testcontainers.

make test_unit         # fast lane: boots the app with no infrastructure
make test_integration  # the full real-infrastructure suite
make test              # both, with coverage (gate: 90%)

قد يستغرق التنفيذ الأول عدة دقائق — إذ تُنزَّل صور Docker ونماذج التضمين مرة واحدة. وتُفرض تغطية agent_lab/ في CI (SonarCloud).

وتحاكي المشاريع المُولَّدة هذا النهج: يحتوي tests/ على اختبارات أولية (smoke tests) دون حاويات إضافة إلى حزمة testcontainers اختيارية.

محاكاة الوكلاء

توجد محاكاة الوكلاء من طرف إلى طرف في tests/simulation/ وتستدعي مزوّدي LLM حقيقيين. وهي موسومة بـ agent_test ومستبعدة افتراضياً؛ شغّلها باستخدام:

make test_simulations
# or a single track:
make scenario_simulation
make langwatch_simulation
make langfuse_simulation

تتشارك ثلاثة مسارات متكاملة دوال تهيئة الوكلاء المساعدة، والمُحكِّم، وتعريفات مجموعات البيانات ضمن tests/simulation/datasets/:

• tests/simulation/scenario/ — محاكاة محادثات باستخدام إطار langwatch-scenario: يقود محاكي مستخدم الوكيلَ بينما يمنح وكيل مُحكِّم درجات للتفاعل.
• tests/simulation/langfuse/ — تجارب قائمة على مجموعات البيانات باستخدام مجموعات بيانات Langfuse. يزامن كل تشغيل تعريفات مجموعات البيانات، ويستدعي الوكيل لكل عنصر، ويمنح المخرجات درجات عبر مُحكِّم LLM-as-judge على جانب العميل، ويسجّل التشغيل والدرجات في Langfuse للمقارنة بمرور الوقت. ويُتخطّى تلقائياً عند عدم ضبط LANGFUSE_BASE_URL (أو LANGFUSE_HOST المُهمَل) وLANGFUSE_PUBLIC_KEY وLANGFUSE_SECRET_KEY.
• tests/simulation/langwatch/ — تجارب مجموعات البيانات نفسها منسوخة إلى LangWatch عبر langwatch.experiment، مع تسجيل درجة المُحكِّم لكل عنصر. تُزامَن التعريفات بشكل متساوي القوة (idempotent) في مجموعة بيانات موحّدة واحدة باسم simulations (يحدّد العمود dataset التعريف المصدر، لأن الخطة المجانية في LangWatch تسمح بثلاث مجموعات بيانات كحد أقصى لكل مشروع). ويُتخطّى تلقائياً عند عدم ضبط LANGWATCH_ENDPOINT وLANGWATCH_API_KEY.

الوكلاء المرجعيون الذين تغطيهم هذه المسارات: وكيل المنسّق-المخطّط-المشرف، ووكيل react RAG، ووكيل الرؤية/المستندات، ووكيل أتمتة المتصفح، ووكيل المذكرات الصوتية، ووكيل RAG التكيّفي.

إعداد LLM للمُحكِّم والوكلاء

يستخدم المُحكِّم (ومحاكي المستخدم في السيناريو) معرّفات نماذج litellm مع أي نقطة نهاية متوافقة مع OpenAI API:

تعمل الوكلاء قيد الاختبار على LLM افتراضي تقدّمه أي نقطة نهاية متوافقة مع OpenAI (مثل خادم استدلال على الشبكة المحلية)، ويُجهَّز لكل اختبار عبر tests/simulation/common/llm_factory.py. والاستثناء هو وكيل المذكرات الصوتية، الذي يبقى على OpenAI (لأنه يحتاج إلى إدخال صوتي في المحادثة). وتستمر التضمينات في استخدام البديل EMBEDDINGS_ENDPOINT (حاوية Ollama الخاصة بالاختبار التي تقدّم bge-m3)، بما يتوافق مع تفريغ pgvector. ويجب أن تدعم نقطة النهاية استدعاء الأدوات / المخرجات المنظّمة للحزم المعتمدة على المشرف (أتمتة المتصفح، والمشرف):

إعداد منصات التقييم

يشغّل make test_simulations (والأهداف الخاصة بكل مسار) خطوة sync_simulation_evals أولاً، والتي تنسخ تعريفات مجموعات البيانات إلى كل منصة مُعدّة. ولتجهيز إعداد التقييم على جانب خادم Langfuse أيضاً (اتصال LLM لنموذج المُحكِّم، ومُقيِّم simulation_llm_as_judge، وقاعدة تقييم واحدة لكل مجموعة بيانات محاكاة — تظهر في قسم Evaluations في Langfuse)، شغّل:

uv run python tests/setup_simulation_evals.py

السكربت متساوي القوة (idempotent) ويمكن إعادة تشغيله بأمان.