> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# وكلاء مخصصون

> قم بتتبع الآثار من الوكلاء المخصصين باستخدام Failproof AI حتى يتمكن من إعادة بناء التشغيلات والعثور على الأخطاء.

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

يجعل التتبع الوكلاء المخصصين قابلين للملاحظة والتدقيق. يتطلب منع إجراء غير آمن قبل تنفيذه أيضًا خطاف إنفاذ في وقت التشغيل الخاص بك.

<Info>
  لفرض السياسات في إعداد وكيل مخصص، [اتصل بـ Failproof AI](mailto:support@befailproof.ai). سنساعدك في ربط نموذج وقت التشغيل الخاص بك والأداة وحدود دورة الحياة بـ policy hooks.
</Info>

<div style={{ position: "relative", width: "100%", paddingBottom: "56.25%", height: 0, overflow: "hidden", borderRadius: "12px", margin: "1.5rem 0" }}>
  <iframe src="https://www.youtube.com/embed/VWxukZc5k7s?rel=0&playsinline=1" title="Agent tracing with the Failproof AI Python SDK" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture; fullscreen" allowFullScreen style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }} />
</div>

## تثبيت `failproofai-sdk`

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

```bash theme={null}
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

<Tabs>
  <Tab title="لوحة التحكم">
    1. انتقل إلى **Admin → Keys** وأنشئ مفتاحًا باستخدام `events:add`.
    2. [وصّل Failproof daemon إلى Cloud](/ar/start/setup#connect-a-machine-to-cloud) على جهاز الوكيل.
    3. قم بتشغيل جلسة واحدة مزودة بتتبع، ثم ابحث عن معرّفها الدقيق ضمن **Observe → Events**.
    4. انتقل إلى **Observe → Sessions**، واختر نفس البيئة، وافتح الآثار المعاد بناؤها.

           <img src="https://mintcdn.com/exosphere/WgPwQzedeDNwJBTy/images/dashboard/session-detail.png?fit=max&auto=format&n=WgPwQzedeDNwJBTy&q=85&s=7b5f022dd5c485565a8cd92b2e936235" alt="جلسة وكيل Python مخصص معاد بناؤها كرسم بياني للتنفيذ وآثار الأحداث المرتبة." width="3200" height="2000" data-path="images/dashboard/session-detail.png" />
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    failproofai config \
      --connect https://app.befailproof.ai \
      --token <events-add-key>
    failproofai config --status
    ```
  </Tab>
</Tabs>

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

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

```python theme={null}
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` على معرّف الوكيل الأب، وليس معرّف الجلسة.

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

```python theme={null}
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.

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

<Tabs>
  <Tab title="لوحة التحكم">
    في **Observe → Events**، تحقق من وجود `agent_start` أولاً و `agent_end` أخيرًا. ثم افتح **Observe → Sessions** وتأكد من ظهور أحداث النموذج والأداة والإنسان والخطاف والخطأ بالترتيب المقصود. استخدم معرّف الجلسة كمفتاح استكشاف الأخطاء الأساسي.
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    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
    ```
  </Tab>
</Tabs>

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

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

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

أرسل بريدًا إلى [support@befailproof.ai](mailto:support@befailproof.ai) لتصميم والتحقق من هذا التكامل لوقت التشغيل الخاص بك.