> ## 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.

# Custom agents

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

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

<Columns cols={2}>
  <Card title="دليل الوكلاء المخصصين" icon="code" href="/ar/start/integrations/custom-agents">
    التثبيت والأداة وطرق الأحداث ومثال عملي والمشاكل الشائعة.
  </Card>

  <Card title="هل تستخدم إطار عمل؟" icon="plug" href="/ar/start/integrations">
    LangChain و CrewAI و LlamaIndex و Pydantic AI توفر الأداة لنفسها بنداء واحد.
  </Card>
</Columns>

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

## التثبيت

```bash theme={null}
pip install failproofai-sdk
```

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

## توصيل خادم Failproof

<Tabs>
  <Tab title="لوحة المعلومات">
    1. انتقل إلى **Admin → Keys** وأنشئ مفتاحاً بصلاحية `events:add`.
    2. [وصّل خادم Failproof إلى السحابة](/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="واجهة سطر الأوامر">
    ```bash theme={null}
    failproofai config \
      --connect https://app.befailproof.ai \
      --token <events-add-key>
    failproofai config --status
    ```
  </Tab>
</Tabs>

## التكوين

```python theme={null}
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` يجعل مشكلة توافق الإطار ترفع استثناءً بدلاً من تحذير والمتابعة.                                              |

<Warning>
  **بدون فواصل في `environment`.** يقسم الاستيعاب هذا الحقل على الفواصل لبناء مرشحاته، وينطبق أي حدث يحتوي التسمية على واحد — لذا قد يختفي التشغيل الكامل بصمت. اكتب `prod-eu` وليس `prod,eu`.

  `configure(environment="prod,eu")` يرفع الاستثناء لتكتشف على الفور. `AGENTEYE_ENVIRONMENT` لا يمكنه الرفع — لا أحد يناديك — لذا يحذر مرة واحدة ويعود إلى `dev`.
</Warning>

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

## الهوية

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

```python theme={null}
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` بدلاً من إطلاق حدث قد تتجاهله السحابة.

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

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

خمس عشرة طريقة. معظمها يأتي في **أزواج** — تستدعي المفتاح، ثم الإغلاق، و 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`.

<Accordion title="كل حقل لكل طريقة" icon="table">
  كل طريقة تأخذ أيضاً `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`                                                                          |
</Accordion>

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

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

**قاعدة واحدة: أعطِ حدث الإغلاق نفس المعرّف الذي لفاتح.** هذا هو ما يقترنها، وما يسمح لـ 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 بت وقد ينتهي به الحال فارغاً.

<Accordion title="الحالات الحدّية" icon="circle-help">
  * **المعرّفات تحتاج فقط إلى أن تكون فريدة لكل نوع، لكل جلسة.** استدعاء أداة وخطاف قد يشاركان واحداً؛ جلستان تعملان في نفس الوقت قد تعيد استخدام نفس المعرّفات دون تصادم.
  * **لا يتم تحديد نطاقها لوكيل.** زوج فُتح تحت وكيل واحد وأُغلق تحت آخر يطابق أيضاً — وهذه هي الحالة الطبيعية في كود متعدد الوكلاء.
  * **`request_id` اختياري لكن موصى به.** بدونه، تقترن أحداث النموذج بالترتيب الذي تصل، لذا نداءان متزامنان في نفس الوكيل قد يقترنان خطأً.
  * **زوج مقسم عبر العمليات** يطابق أيضاً في السحابة، لكن SDK لا يمكنه قياسه — لا شيء في أي عملية رأى كلا النصفين.
  * **على الأكثر 10000 فاتح ينتظر أقرب في نفس الوقت.** بعد ذلك الأقدم يُحذف، لذا تسريب لا يمكنه النمو بدون حد.
</Accordion>

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

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

```python theme={null}
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 أو كائن نموذج — يُخزّن كسلسلة نصية.

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

  هذا هو أيضاً السبب في أن حقل اختياري خاطئ الإملاء لا يرفع أخطاء أبداً — يصبح حقل مخصص جديد. إذا كان حقل قياسي مفقوداً في السحابة، تحقق من الإملاء أولاً.
</Warning>

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

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

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

  <Tab title="واجهة سطر الأوامر">
    ```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>

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

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

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

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

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