Custom agents

title: “الوكلاء المخصصون” description: “التكوين وفهرس الأحداث وقواعد الارتباط والتسليم لـ failproofai-sdk.” icon: “python”

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

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

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

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

LangChain و CrewAI و LlamaIndex و Pydantic AI توفر الأداة لنفسها بنداء واحد.

Python 3.10 أو أحدث. بدون تبعيات وقت التشغيل.

التثبيت

pip install failproofai-sdk

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

توصيل خادم Failproof

لوحة المعلومات
واجهة سطر الأوامر

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

failproofai config \
  --connect https://app.befailproof.ai \
  --token <events-add-key>
failproofai config --status

التكوين

import failproofai_sdk

failproofai_sdk.configure(
    base_dir=None,
    flush_interval=0.5,
    environment="production",
)

المعامل	الوظيفة
`environment`	التسمية على كل حدث — `production` أو `staging` أو `prod-eu`. القيمة الافتراضية `dev`.
`flush_interval`	مدى تكرار كتابة الخيط الخلفي إلى القرص، بالثواني. القيمة الافتراضية `0.5`.
`base_dir`	مكان الكتابة. القيمة الافتراضية سpool الخادم، وهو ما تريده ما لم تعرف خلاف ذلك.

اضبط عن طريق متغير البيئة بدلاً من ذلك:

المتغير	الوظيفة
`AGENTEYE_ENVIRONMENT`	يضبط `environment` دون تغيير الكود، عندما تكون التسمية تابعة للنشر وليس التطبيق. معامل `configure()` يتفوق عليه.
`FAILPROOFAI_HOME`	ينقل جذر Failproof AI الذي يحتوي على spool.
`FAILPROOFAI_SDK_STRICT`	`1` يجعل أخطاء الأداة ترفع استثناءات بدلاً من تسجيلها.
`FAILPROOFAI_SDK_STRICT_INTEGRATIONS`	`1` يجعل مشكلة توافق الإطار ترفع استثناءً بدلاً من تحذير والمتابعة.

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

تُصف الأحداث في الذاكرة وتُكتب في الخلفية كل flush_interval ثانية، مع كتابة نهائية عند خروج المفسّر. العملية المقتولة مباشرة تفقد أي شيء لم يُكتب بعد.

الهوية

ينتمي كل حدث إلى جلسة ووكيل. النطاقات تملأ كليهما، لذا نادراً ما تمرّرهما:

with failproofai_sdk.session():
    with failproofai_sdk.agent("planner"):
        failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1")

إمرار session_id أو agent_id صراحةً يعمل أيضاً ويتفوق. بدون ربط أو تمرير، يرفع النداء TypeError بدلاً من إطلاق حدث قد تتجاهله السحابة.

الهوية تعمل على متغيرات السياق. تتبع مهام asyncio تلقائياً، لكن ليس الخيوط الجديدة — غلّف عامل في failproofai_sdk.propagate() أو أحداثه ستنفصل.

فهرس الأحداث

خمس عشرة طريقة. معظمها يأتي في أزواج — تستدعي المفتاح، ثم الإغلاق، و SDK يوقت الفجوة.

	يفتح	يغلق
الوكلاء	`agent_start`	`agent_end`
	`agent_pause`	`agent_resume`
النماذج	`model_request`	`model_response`
الأدوات	`tool_use`	`tool_result`
الخطافات	`hook_triggered`	`hook_completed`
البشر	`human_wait`	`human_input`

ثلاثة تقف بمفردها: error و human_pause و human_interrupt.

كل حقل لكل طريقة

كل طريقة تأخذ أيضاً session_id و agent_id، والتي تملأ النطاقات لك. أي شيء متُرك كـ None يُحذف بدلاً من إرساله كـ JSON null، وكل طريقة تعيد None.

الطريقة	مطلوب	اختياري
`agent_start`	—	`goal`, `parent_id`
`agent_end`	—	`outcome`, `summary`
`agent_pause`	`pause_id`	`reason`, `user_id`
`agent_resume`	`pause_id`	`reason`, `user_id`
`model_request`	—	`model`, `messages`, `system`, `tools`, `request_id`
`model_response`	—	`model`, `stop_reason`, `input_tokens`, `output_tokens`, `content`, `role`, `request_id`, `duration_ms`
`tool_use`	`tool_name`, `tool_call_id`	`input`
`tool_result`	`tool_name`, `tool_call_id`	`output`, `error`
`hook_triggered`	`hook_name`, `hook_id`	`trigger_event`, `input`
`hook_completed`	`hook_name`, `hook_id`	`outcome`, `output`, `error`
`error`	`error_type`, `message`	`traceback`
`human_wait`	`input_id`	`prompt`, `options`, `reason`
`human_input`	`input_id`	`response`
`human_pause`	—	`reason`, `user_id`
`human_interrupt`	—	`reason`, `user_id`, `at_step`

لتحديد تشغيل كفاشل، يجب أن يكون outcome واحداً من failed أو error أو timeout أو rejected. أي شيء آخر — بما فيه الحالة القريبة "failure" — يُحسب كنجاح.

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

قاعدة واحدة: أعطِ حدث الإغلاق نفس المعرّف الذي لفاتح. هذا هو ما يقترنها، وما يسمح لـ SDK بقياس الفجوة.

الزوج	مطابق على
`tool_use` → `tool_result`	`tool_call_id`
`hook_triggered` → `hook_completed`	`hook_id`
`agent_pause` → `agent_resume`	`pause_id`
`human_wait` → `human_input`	`input_id`
`model_request` → `model_response`	`request_id`

لا تمرّر duration_ms بنفسك. يقيسها SDK، وتمريرها يرفع ValueError. الاستثناء الوحيد هو model_response، حيث أنت وحدك تعرف زمن الكمون الفعلي للمزود. مرّر عدداً صحيحاً من الميلي ثانية — العدد العشري يرفع، لأن العمود عدد صحيح 32 بت وقد ينتهي به الحال فارغاً.

الحالات الحدّية

المعرّفات تحتاج فقط إلى أن تكون فريدة لكل نوع، لكل جلسة. استدعاء أداة وخطاف قد يشاركان واحداً؛ جلستان تعملان في نفس الوقت قد تعيد استخدام نفس المعرّفات دون تصادم.
لا يتم تحديد نطاقها لوكيل. زوج فُتح تحت وكيل واحد وأُغلق تحت آخر يطابق أيضاً — وهذه هي الحالة الطبيعية في كود متعدد الوكلاء.
request_id اختياري لكن موصى به. بدونه، تقترن أحداث النموذج بالترتيب الذي تصل، لذا نداءان متزامنان في نفس الوكيل قد يقترنان خطأً.
زوج مقسم عبر العمليات يطابق أيضاً في السحابة، لكن SDK لا يمكنه قياسه — لا شيء في أي عملية رأى كلا النصفين.
على الأكثر 10000 فاتح ينتظر أقرب في نفس الوقت. بعد ذلك الأقدم يُحذف، لذا تسريب لا يمكنه النمو بدون حد.

حقولك الخاصة

أي كلمة مفتاح إضافية تمررها يتم تخزينها مع الحدث:

failproofai_sdk.event.tool_use(
    tool_name="search", tool_call_id="c1",
    fw_tenant="acme", fw_region="eu-west-1",     # خاصة بك
)

فضّل أنواع JSON إذا أردت الاستعلام عنها لاحقاً. أي شيء آخر — UUID أو datetime أو Decimal أو set أو bytes أو كائن نموذج — يُخزّن كسلسلة نصية.

اجعل أسماء حقولك بادئة. الإضافات تُطبق أخيراً، لذا حقل يُسمى model أو tool_name أو outcome يستبدل الحقل الحقيقي بصمت. محولات الإطار تستخدم fw_؛ افعل الشيء نفسه ولا شيء قد يصطدم.هذا هو أيضاً السبب في أن حقل اختياري خاطئ الإملاء لا يرفع أخطاء أبداً — يصبح حقل مخصص جديد. إذا كان حقل قياسي مفقوداً في السحابة، تحقق من الإملاء أولاً.

هذه الأسماء الخمسة مreserved وترفع مباشرة: timestamp و session_id و agent_id و type و environment.

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

لوحة المعلومات
واجهة سطر الأوامر

في Observe → Events، تحقق من أن agent_start موجود أولاً و agent_end موجود أخيراً. ثم افتح Observe → Sessions وأكّد أن أحداث النموذج والأداة والإنسان والخطاف والخطأ تظهر بالترتيب المقصود. استخدم معرّف الجلسة كمفتاح استكشاف الأخطاء الأساسي.

failproofai flush --wait --timeout 60
failproofai config --status
fp sessions --since 1h --env production --session-id <session-id>
fp events --since 1h --session-id <session-id> --full

إذا كانت السحابة فارغة، افحص $FAILPROOFAI_HOME/custom-agents/events، وإلا ~/.failproofai/custom-agents/events. ملفات JSONL تثبت إطلاق SDK؛ spool متنامٍ يشير إلى تكوين الخادم أو التسليم، بينما spool فارغ يشير إلى الأداة أو عمر العملية.

افحص spool فقط عندما يكون الخادم متوقفاً. بينما يعمل، يجمع ويحذف كل دفعة في ميلي ثانية، لذا قائمة دليل تتسابق مع المجمّع وتظهر أحداثاً أقل بكثير مما تم إطلاقه.

منع الأخطاء في وقت تشغيل مخصص

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

Connect your agents

Reference

title: “الوكلاء المخصصون” description: “التكوين وفهرس الأحداث وقواعد الارتباط والتسليم لـ failproofai-sdk.” icon: “python”

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

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

التثبيت

توصيل خادم Failproof

التكوين

الهوية

فهرس الأحداث

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

حقولك الخاصة

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

منع الأخطاء في وقت تشغيل مخصص

​title: “الوكلاء المخصصون” description: “التكوين وفهرس الأحداث وقواعد الارتباط والتسليم لـ failproofai-sdk.” icon: “python”

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

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

​التثبيت

​توصيل خادم Failproof

​التكوين

​الهوية

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

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

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

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

​منع الأخطاء في وقت تشغيل مخصص

title: “الوكلاء المخصصون” description: “التكوين وفهرس الأحداث وقواعد الارتباط والتسليم لـ failproofai-sdk.” icon: “python”

التثبيت

توصيل خادم Failproof

التكوين

الهوية

فهرس الأحداث

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

حقولك الخاصة

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

منع الأخطاء في وقت تشغيل مخصص