Skip to main content
شرح لكل إعداد وطريقة وحقل. إذا كنت تقوم بالقياس للمرة الأولى، ابدأ بالدليل — هذه الصفحة مخصصة للبحث عن الأشياء.

دليل الوكلاء المخصصين

التثبيت والقياس وطرق الأحداث ومثال عملي والمشاكل الشائعة.

هل تستخدم إطار عمل؟

LangChain و CrewAI و LlamaIndex و Pydantic AI تقيس نفسها بنفسها باستدعاء واحد.
Python 3.10 أو أحدث. بدون متطلبات وقت التشغيل.

​
التثبيت

يتم تثبيت الحزمة باسم failproofai-sdk واستيرادها في Python باسم failproofai_sdk. إضافات الإطار مثل failproofai-sdk[langgraph] تثبت الإطار نفسه؛ المحولات دائماً مدرجة في العجلة الأساسية.

​
ربط مراقب Failproof

  1. انتقل إلى Admin → Keys وأنشئ مفتاحاً بصلاحية events:add.
  2. ربط مراقب Failproof بـ Cloud على جهاز الوكيل.
  3. قم بتشغيل جلسة واحدة مع القياس، ثم ابحث عن معرّفها الدقيق تحت Observe → Events.
  4. انتقل إلى Observe → Sessions، اختر نفس البيئة، وافتح الأثر المعاد بناؤه. جلسة وكيل Python مخصص معاد بناؤها كرسم بياني للتنفيذ وتسلسل حدث مرتب.

​
الإعدادات

اضبط عن طريق متغير البيئة بدلاً من ذلك:
لا توجد فواصل في environment. تقسم وحدة الاستيعاب هذا الحقل على الفواصل لبناء المرشحات، وتتخطى أي حدث تحتوي علامته على واحدة — لذلك يختفي التشغيل كله بصمت. اكتب prod-eu وليس prod,eu.configure(environment="prod,eu") ترفع لذلك تكتشفها فوراً. AGENTEYE_ENVIRONMENT لا يمكنها أن ترفع — لا أحد يناديك — لذلك تحذر مرة واحدة وتعود إلى dev.
يتم صف الأحداث في الذاكرة والكتابة في الخلفية كل flush_interval ثانية، مع كتابة نهائية عند خروج المترجم. تفقد العملية المقتولة مباشرة أي شيء لم يتم كتابته بعد.

​
الهوية

كل حدث ينتمي إلى جلسة ووكيل. النطاقات تملأ كليهما، لذا نادراً ما تمرر هما:
تمرير session_id أو agent_id بشكل صريح لا يزال يعمل ويتفوق عليه. بدون ربط أو تمرير، يرفع الاستدعاء TypeError بدلاً من إصدار حدث قد تتجاهله Cloud بصمت.
تركب الهوية على متغيرات السياق. تتابع مهام asyncio تلقائياً، لكن ليس الخيوط الجديدة — غلف العامل بـ failproofai_sdk.propagate() أو أحداثه تهبط بدون تعلق.

​
فهرس الأحداث

خمسة عشر طريقة. معظمها يأتي في أزواج — تستدعي الفتاح، ثم الإغلاق، والمراقب يوقت الفجوة. ثلاثة تقف بمفردها: error و human_pause و human_interrupt.
كل طريقة تأخذ أيضاً session_id و agent_id، والتي تملأها النطاقات لك. أي شيء يُترك كـ None يُسقط بدلاً من إرساله كـ JSON null، وكل طريقة ترجع None.
لتحديد تشغيل كفاشل، يجب أن تكون outcome واحدة من failed أو error أو timeout أو rejected. أي شيء آخر — بما في ذلك الحالة القريبة الفائتة "failure" — يُحسب كنجاح.

​
الاقتران والمدة

قاعدة واحدة: أعط حدث الإغلاق نفس المعرّف مثل فاتحه. هذا ما يقرنهما، وما يسمح للمراقب بتوقيت الفجوة. لا تمرر duration_ms بنفسك. المراقب يقيسه، وتمريره يرفع ValueError. الاستثناء الوحيد هو model_response، حيث أنت فقط تعرف كمون المزود الحقيقي. مرر عدداً صحيحاً من الميلي ثانية — تمرير عدد عشري يرفع، لأن العمود عدد صحيح 32 بت وسيهبط فارغاً وإلا.
  • المعرّفات لا تحتاج فقط أن تكون فريدة حسب النوع لكل جلسة. استدعاء أداة وخطاف يمكنهما مشاركة واحد؛ جلستان تعمل مرة واحدة يمكنهما إعادة استخدام نفس المعرّفات بدون تصادم.
  • لا تقتصر على وكيل. زوج مفتوح تحت وكيل واحد ومغلق تحت آخر لا يزال يطابق — وهي الحالة الطبيعية في الكود متعدد الوكلاء.
  • request_id اختياري لكن موصى به. بدونه، أحداث النموذج تقترن بالترتيب الذي تصل به، لذا استدعاءان متزامنان في نفس الوكيل يمكنهما عدم الاقتران بشكل صحيح.
  • زوج منقسم عبر العمليات لا يزال يطابق في Cloud، لكن المراقب لا يمكنه توقيت ذلك — لا شيء في أي عملية رأى كلا النصفين.
  • بحد أقصى 10،000 فاتح ينتظرون إغلاق في وقت واحد. بعد ذلك الأقدم يُسقط، لذا تسرب لا يمكن أن ينمو بدون حد.

​
حقولك الخاصة

أي كلمة أساسية إضافية تمررها يتم تخزينها مع الحدث:
فضّل أنواع JSON إذا كنت تريد الاستعلام عنها لاحقاً. أي شيء آخر — UUID أو datetime أو Decimal أو set أو bytes أو كائن نموذج — يتم تخزينه كسلسلة.
ضع بادئة لأسماء حقولك. الإضافات يتم تطبيقها أخيراً، لذا حقل يسمى model أو tool_name أو outcome يستبدل الحقيقي بصمت. محولات الإطار تستخدم fw_؛ افعل الشيء نفسه والشيء الوحيد الذي يمكن أن يتصادم.هذا هو أيضاً السبب في أن حقل اختياري مكتوب بخطأ لا يخطئ أبداً — إنه ببساطة يصبح حقل مخصص جديد. إذا كان حقل قياسي مفقوداً في Cloud، تحقق من الإملاء أولاً.
هذه الأسماء الخمسة محجوزة ومرفوضة بشكل مباشر: timestamp و session_id و agent_id و type و environment.

​
التسليم والتحقق

في Observe → Events، تحقق من وجود agent_start أولاً و agent_end أخيراً. ثم افتح Observe → Sessions وأكّد ظهور أحداث النموذج والأداة والبشر والخطاف والخطأ بالترتيب المقصود. استخدم معرّف الجلسة كمفتاح استكشاف الأخطاء الأساسي.
إذا كانت Cloud فارغة، افحص $FAILPROOFAI_HOME/custom-agents/events، وإلا ~/.failproofai/custom-agents/events. ملفات JSONL تثبت إصدار المراقب؛ سبول متنام يشير إلى إعدادات المراقب أو التسليم، بينما سبول فارغ يشير إلى القياس أو عمر العملية.
افحص السبول فقط عندما يكون المراقب متوقفاً. بينما يعمل، يجمع ويحذف كل دفعة في ميلي ثانية، لذا قائمة الدليل تتسابق مع المجمع وتظهر أحداث أقل بكثير مما تم إصدارها.

​
منع الإخفاقات في وقت تشغيل مخصص

استخدم النتائج القابلة للتدقيق والآثار المرتبطة لتعريف الإجراء غير الآمن والأدلة المطلوبة والاستجابة المقصودة. يجب أن تعريض تكامل الإنفاذ المخصص الإجراء قبل التنفيذ، وتمرير إدخاله المنظم إلى محرك السياسة، وتطبيق قرار allow أو instruct أو deny الناتج. اتصل بـ Failproof AI وسنساعدك على ربط نموذج وقت التشغيل الخاص بك وحدود الأداة والدورة الحياتية بخطافات السياسة، ثم التحقق من التكامل معك.