وكلاء مخصصون

قم بتتبع الآثار من وكيل مخصص باستخدام failproofai-sdk بحيث يمكن لـ Failproof AI إعادة بناء كل تشغيل، وتدقيق سلوكه، والعثور على الأخطاء المدعومة بالأدلة. يكتب SDK أحداثًا منظمة لـ Failproof daemon لتسليمها إلى Cloud. يتطلب Python 3.10 أو أحدث. يجعل التتبع الوكلاء المخصصين قابلين للملاحظة والتدقيق. يتطلب منع إجراء غير آمن قبل تنفيذه أيضًا خطاف إنفاذ في وقت التشغيل الخاص بك.

لفرض السياسات في إعداد وكيل مخصص، اتصل بـ Failproof AI. سنساعدك في ربط نموذج وقت التشغيل الخاص بك والأداة وحدود دورة الحياة بـ policy hooks.

تثبيت `failproofai-sdk`

يتم توزيع SDK حاليًا كعجلة خاصة. اطلب من جهة اتصالك في Failproof AI الحصول على الإصدار الحالي وإمكانية التنزيل.

VERSION=<sdk-version>
pip install "./failproofai_sdk-${VERSION}-py3-none-any.whl"
python -c "import failproofai; print(failproofai.__version__)"

مع uv، قم بتنزيل العجلة أولاً وقم بتشغيل uv add ./failproofai_sdk-${VERSION}-py3-none-any.whl. قم بتثبيت العجلة في مستودع آثار خاص أو قفل التبعيات. يتم تثبيت الحزمة باسم failproofai-sdk وتُستورد في Python باسم failproofai.

توصيل Failproof daemon

لوحة التحكم
CLI

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

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

تتبع تشغيل كامل

استدع configure() مرة واحدة أثناء بدء العملية. كل استدعاء حدث هو keyword-only ويتطلب session_id و agent_id مستقرة.

import traceback
import uuid

import failproofai

failproofai.configure(environment="production")

session_id = uuid.uuid4().hex
agent_id = "checkout-agent"

failproofai.event.agent_start(
    session_id=session_id,
    agent_id=agent_id,
    goal="Resolve a failed checkout",
)

try:
    tool_call_id = uuid.uuid4().hex
    failproofai.event.tool_use(
        session_id=session_id,
        agent_id=agent_id,
        tool_name="lookup_order",
        tool_call_id=tool_call_id,
        input={"order_id": "ord_8421"},
    )
    result = {"status": "payment_failed"}
    failproofai.event.tool_result(
        session_id=session_id,
        agent_id=agent_id,
        tool_name="lookup_order",
        tool_call_id=tool_call_id,
        output=result,
    )
except Exception as exc:
    failproofai.event.error(
        session_id=session_id,
        agent_id=agent_id,
        error_type=type(exc).__name__,
        message=str(exc),
        traceback=traceback.format_exc(),
    )
    failproofai.event.agent_end(
        session_id=session_id,
        agent_id=agent_id,
        outcome="failed",
    )
    raise
else:
    failproofai.event.agent_end(
        session_id=session_id,
        agent_id=agent_id,
        outcome="success",
        summary="Escalated the failed payment",
    )

أصدر agent_start مرة واحدة لكل فاعل. بالنسبة للوكلاء الفرعيين، أعد استخدام session_id الخاص بالأب، وأعط كل فاعل agent_id مميز، واضبط parent_id على معرّف الوكيل الأب، وليس معرّف الجلسة.

مرجع التكوين

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

الإعداد	السلوك
`base_dir`	جذر spool صريح. يأخذ الأولوية على جميع متغيرات البيئة.
`flush_interval`	الثواني بين الكتابات في الخلفية من الذاكرة إلى JSONL. الافتراضي: `0.5`.
`environment`	تسمية النشر على كل حدث. الافتراضي هو `dev`.
`FAILPROOFAI_HOME`	يغير جذر Failproof AI الذي يحتوي على spool `custom-agents`.

يكتب SDK إلى base_dir الصريح عند تعيينه. وإلا، فإنه يستخدم spool custom-agents الخاص بـ Failproof daemon ضمن FAILPROOFAI_HOME أو ~/.failproofai. يقوم SDK بطلب الاستدعاءات في الذاكرة ويكتب دفعات على سلسلة خيط في الخلفية. كما يحاول التنظيف النهائي من خلال معالجة Python atexit. بالنسبة للعمال قصيري الأجل، اسمح بإيقاف المترجم الطبيعي؛ قد يؤدي إنهاء العملية الثابتة إلى فقدان الأحداث التي لا تزال في الذاكرة.

فهرس الأحداث

جميع الطرق ترجع None. يتم حذف الحقول المتروكة كـ None بدلاً من كتابتها كـ JSON null.

الطريقة	الحقول المطلوبة بخلاف الهوية	الحقول الاختيارية
`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`
`model_response`	—	`model`, `stop_reason`, `input_tokens`, `output_tokens`, `content`, `role`
`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"، لا تُصنف كفشل من قبل backend الحالي.

قواعد الارتباط والمدة

أعد استخدام نفس tool_call_id أو hook_id أو pause_id أو input_id لحدث الإكمال المطابق.
يحسب SDK duration_ms لـ tool_result و hook_completed و agent_resume و human_input. تمرير قيمة بنفسك إلى تلك الطرق يرفع ValueError.
معرفات الأداة والخطاف تشترك في خريطة انتظار واحدة على مستوى العملية. اجعلها فريدة عالميًا عبر الجلسات المتزامنة وعبر كلا المساحة؛ معرّفات الموفر أو UUIDs هي الأكثر أمانًا.
الزوج المنقسم عبر العمليات لا يزال يرتبط بالتطبيق، لكن SDK لا يمكنه حساب مدته داخل العملية.
تحتفظ خريطة الانتظار بـ 10000 بداية على الأكثر وتزيل الإدخال الأقدم عند امتلاء الحد.

الحقول المخصصة والبيانات الضخمة

كل حدث يقبل حقول keyword إضافية. استخدم القيم المتوافقة مع JSON عندما تحتاج الاستعلامات الموضوعية إلى البنية. الأوراق غير المدعومة مثل UUIDs والتواريخ والكسور العشرية والمجموعات والبايتات وكائنات النموذج يتم تحويلها إلى نصوص من قبل الكاتب. الأسماء المخصصة المحجوزة هي timestamp و session_id و agent_id و type و environment. الأخطاء المطبعية في الحقول الاختيارية يتم قبولها كحقول مخصصة جديدة، لذلك قم بمراجعة JSON المُرسل عندما لا يظهر حقل قياسي في Cloud.

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

لوحة التحكم
CLI

في 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

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

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

استخدم النتائج المدققة والآثار المرتبطة لتحديد الإجراء غير الآمن والأدلة المطلوبة والاستجابة المقصودة. يجب أن يكشف تكامل الإنفاذ المخصص الإجراء قبل التنفيذ، وتمرير مدخلاته المنظمة إلى محرك السياسة، وتطبيق قرار allow أو instruct أو deny الناتج. أرسل بريدًا إلى support@befailproof.ai لتصميم والتحقق من هذا التكامل لوقت التشغيل الخاص بك.

Connect your agents

Reference

HTTP API

وكلاء مخصصون

تثبيت `failproofai-sdk`

توصيل Failproof daemon

تتبع تشغيل كامل

مرجع التكوين

فهرس الأحداث

قواعد الارتباط والمدة

الحقول المخصصة والبيانات الضخمة

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

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

​تثبيت failproofai-sdk

​توصيل Failproof daemon

​تتبع تشغيل كامل

​مرجع التكوين

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

​قواعد الارتباط والمدة

​الحقول المخصصة والبيانات الضخمة

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

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

تثبيت `failproofai-sdk`

توصيل Failproof daemon

تتبع تشغيل كامل

مرجع التكوين

فهرس الأحداث

قواعد الارتباط والمدة

الحقول المخصصة والبيانات الضخمة

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

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