> ## 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 Observability Python SDK للوكيل

> انتقل من وكيل بدون أدوات قياس إلى أحداث يمكنك رؤيتها، مع قيام وكيل الترميز بالعثور على نقاط القياس وكتابتها والتحقق من وصولها.

أخبر وكيل الترميز الخاص بك *"أضف Failproof AI Observability إلى هذا الوكيل"* واتركه يقرأ حلقتك، ويحدد المكان الذي يجب أن تذهب إليه أدوات القياس، ويكتبها، ويتحقق من الأحداث قبل إكمال المهمة.

**مهارة Python SDK** (`agenteye-python-sdk`) هي *Agent Skill*: مجلد من التعليمات التي يحملها وكيل ترميز مثل Claude Code أو Codex عند الطلب عندما تطابق المهمة. تعلّم الوكيل استخدام [Python SDK](/ar/agenteye/python-sdk) — فهي ليست مكتبة، ولا تغير أي شيء عن طريقة عمل SDK.

## أدوات القياس سهلة الكتابة وسهلة الخطأ بصمت

SDK صغير: ثلاثة عشر طريقة حدث، كلها بكلمات مفتاحية فقط. يمكن لوكيل الترميز أن يقرأ [مرجع Python SDK](/ar/agenteye/python-sdk) وينتج أدوات قياس معقولة في دقيقة واحدة.

المشكلة هي أن هذا SDK لا يرفع استثناءات عندما تخطئ، وأدوات القياس الخاطئة تبدو تماماً مثل الصحيحة حتى يفتح شخص ما لوحة التحكم ويجدها فارغة. الأخطاء التي تستهلك وقتاً حقيقياً هي جميعاً الصمت:

| الخطأ                        | ما تراه                                                                         |
| ---------------------------- | ------------------------------------------------------------------------------- |
| لا يوجد `agent_start`        | كل حدث يصل. صفر جلسات.                                                          |
| لم يتم تعيين البيئة          | كل شيء يعمل، مصنف تحت `dev`.                                                    |
| `outcome="failure"`          | يظهر التشغيل باللون الأخضر — فقط `failed`, `error`, `timeout`, `rejected` تحسب. |
| اسم حقل يحتوي على خطأ إملائي | مقبول ومخزن كحقل جديد.                                                          |
| أحداث منبعثة من مجموعة خيوط  | تم حذفها بصمت.                                                                  |

لا شيء من هذا يرفع استثناءات. لا شيء يظهر في الاختبارات. كل واحد في المهارة، مذكور كعقد مع الفحص الذي يمسكه.

## ما تفعله، بالترتيب

تقوم المهارة بنفس الخطوات الثلاث التي سيتخذها المهندس الحذر:

1. **التخطيط.** تقرأ حلقة الوكيل وتطرح السؤالين اللذين يمكنك فقط الإجابة عليهما: ما الذي يحسب كتشغيل واحد (`session_id`)، ومن الممثلون القابلون للتمييز (`agent_id`). تحصل على الموافقة على تلك قبل كتابة الكود، لأن تغييرها لاحقاً يقسم السجل ويكسر الاتجاهات.
2. **الكتابة.** تربط الهوية مرة واحدة لكل تشغيل بدلاً من نقلها عبر كل موقع استدعاء، وتختار شكلاً آمناً للتزامن — تفصيل مهم، لأن الطريقة الواضحة المختصرة تخلط بصمت بين تشغيلين متداخلين في جلسة واحدة.
3. **التحقق.** تشغّل الوكيل وتقرأ ملفات الأحداث الناتجة، للتحقق من وجود `agent_start` والبيئة الصحيحة وأن تشغيلاً واحداً أنتج جلسة واحدة.

تلك الخطوة الثالثة هي التي يتخطاها الناس. يكتب SDK الأحداث إلى ملفات محلية، لذا يمكن إثبات التكامل الكامل على جهاز كمبيوتر محمول بدون خادم أو مفتاح API أو شبكة — وهذا بالضبط السبب في أن المهارة تصر على فعل ذلك.

## كيف تتعلق بالمهارات الأخرى

ثلاث مهارات، تقسيم واضح:

| المهارة                                             | استخدمها عندما                                                                             | ما الذي تلمسه                                |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------- |
| **مهارة Python SDK** (هذه الصفحة)                   | تريد من الوكيل أن *ينبعث* من بيانات المراقبة — "أضف المراقبة"، "لماذا لا يظهر الوكيل لدي؟" | تكتب الكود في مستودع الوكيل. لا تقرأ أي شيء. |
| **[مهارة Evaluator](/ar/agenteye/evaluator-skill)** | تريد *تقييم* التشغيلات — "ماذا يجب أن نقيس حتى؟"                                           | تكتب الكود في المستودع؛ تقرأ بيانات المراقبة |
| **[مهارة CLI](/ar/agenteye/cli-skill)**             | تريد *قراءة* ما حدث، أو تشغيل النشر                                                        | تشغّل CLI كما أنت، بما في ذلك التغييرات      |

يسلمون التسليم بهذا الترتيب: تحصل هذه المهارة على الأحداث المتدفقة، ثم يسجل المقيّم، ثم يقرأ CLI. لا يوجد شيء لتقييمه ولا شيء للقراءة حتى ينبعث الوكيل من الجلسات، لذا إذا كنت تبدأ من الصفر، ابدأ هنا.

## المتطلبات الأساسية

1. **Python 3.10+** وقاعدة كود الوكيل التي تريد توصيلها.
2. **SDK.** يتم توزيعها للعملاء كعجلة خاصة بدلاً من فهرس عام — يغطي الإعداد الخاص بك كيفية الحصول عليها وتثبيتها. تعرف المهارة مسار التثبيت وستسألك بدلاً من التخمين إذا لم تتمكن من العثور عليها.
3. **لا شيء آخر.** لا توجد ولوج لوحة تحكم، لا مفتاح API، لا شبكة. تتحقق المهارة من ملفات الأحداث التي يكتبها SDK، لذا يمكنها الانتهاء والتحقق من عملها في وضع بدون اتصال.

## أين تحصل عليها

تعيش المهارة في مجموعة [`FailproofAI/skills`](https://github.com/FailproofAI/skills) العامة:

```bash theme={null}
npx skills add FailproofAI/skills --skill agenteye-python-sdk -a claude-code
```

أضف `-g` لتثبيتها لكل مشروع بدلاً من المشروع الحالي فقط، و `--copy` إذا كانت بيئتك لا تتابع الرموز الرمزية. بالنسبة لـ Codex، مرر `-a codex`.

## تثبيتها يدويًا

Agent Skills عبارة عن مجلدات تحتوي على `SKILL.md` بالإضافة إلى المراجع. إذا فضلت عدم استخدام المثبت:

* **Claude Code**: انسخ مجلد `agenteye-python-sdk/` إلى `~/.claude/skills/` (كل مشروع) أو `<your-repo>/.claude/skills/` (هذا المستودع فقط). يكتشفه Claude Code تلقائياً — تحقق من قائمة `/skills`، أو ببساطة اسأل شيئاً يطابقه.
* **Codex**: يقرأ Codex نفس `SKILL.md`. يعيّن `agents/openai.yaml` المجمّع `allow_implicit_invocation: true`، لذا يتم اختياره تلقائياً عندما تطابق المهمة؛ وإلا قم باستدعاؤه كـ `$agenteye-python-sdk`.

قم بتشغيل الوكيل الخاص بك **في المستودع الذي يحتفظ بالكود الذي تريد توصيله** — تقرأ المهارة حلقة الوكيل قبل أن تقترح أي شيء.

## كيف تبدو الجلسة

```text theme={null}
you   ▸ Add Failproof AI Observability to this agent.

agent ▸ Read your loop — one tool dispatcher in tools.py, one Anthropic
        wrapper in llm.py. Two questions before I write anything.

        What counts as one run? You handle requests concurrently, so I'd
        use the request id you already have in ctx.request_id — then a
        session here and a request in your logs are the same string.

        And who are the actors? I see a planner path and a researcher
        path. Label them separately, or is that one agent to you?

you   ▸ Request id is right. They're one agent, call it "assistant".

agent ▸ Done. Wrapped the dispatcher and the LLM client; agent_start and
        agent_end bracket handle_request, including the error path. Used
        a context-local for identity — your dispatcher runs tools in a
        thread pool, and the simpler approach would have mixed concurrent
        runs into one session without complaining.

        Verified against a real run: 11 events across 4 files —
        agent_start, model_request/response, tool_use/tool_result x3,
        agent_end (outcome=success). environment=production, one session
        per request, durations paired.

        One thing I did NOT do: your worker pool in batch.py submits
        straight to the executor, so events from there would be dropped.
        Want me to fix those too?
```

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

## ما الذي يمكنك أن تطلبه

* *"لماذا لا يظهر الوكيل الخاص بي على لوحة التحكم؟"* → يمشي في السلم: هل يتم كتابة الأحداث، هل `agent_start` موجود، هل البيئة صحيحة، هل يقرأ الجامع نفس المكان.
* *"كل شيء يهبط تحت dev."* → لم يتم تعيين البيئة أبداً، أو تم إعادة تعيينها بواسطة استدعاء لاحق.
* *"أضف تتبع الرموز."* → يجد محقق LLM الخاص بك ويسجل النموذج وسبب الإيقاف والاستخدام.
* *"أدرج الوكلاء الفرعيين أيضاً."* → جلسة واحدة، علامات وكيل مميزة، متداخلة تحت والديهم.
* *"اكتب اختبارات لأدوات القياس."* → يشير إلى SDK في مجلد مؤقت ويؤكد على الأحداث التي كتبها.

## ما يجب الانتباه له

**اتركها تتحقق.** الخطوة التي تجعل هذه المهارة تستحق الاستخدام هي الخطوة الأخيرة — تشغيل الوكيل الخاص بك وقراءة الأحداث مرة أخرى. الوكيل الذي يكتب أدوات القياس ويتوقف قد قام بالنصف السهل، والنصف الذي يفشل بصمت هو النصف الآخر.

**وافق على الأسماء قبل الكود.** `session_id` و `agent_id` هما المحوران اللذان تجمعهما كل واجهة. إعادة تسميتها لاحقاً تقسم السجل: التشغيلات القديمة تحتفظ بالعلامات القديمة واتجاهاتك تكسر. ستسأل المهارة؛ الإجابة تستحق دقيقة من التفكير.

**إذا اقترح الوكيل الخاص بك تثبيت SDK من فهرس عام، فإن المهارة لم تُحمّل.** يتم توزيع SDK بشكل خاص. هذا الاقتراح هو إخبار موثوق به بأن وكيل الترميز الخاص بك يخمن بدلاً من اتباع المهارة — توقفه هناك وتحقق من تثبيت المهارة.

بعد ذلك، نطاق الانفجار صغير: يكتب الكود في دليل العمل الخاص بك وملفات الأحداث حيث تخبره. لا تقرأ أي شيء من النشر الخاص بك ولا تغير أي شيء عنه.

## الخطوات التالية

* **[Python SDK](/ar/agenteye/python-sdk)**: المرجع الكامل للأحداث — كل نوع حدث وحقل — خلف ما تؤتمتتة هذه المهارة.
* **[الجلسات](/ar/agenteye/sessions)**: ما ينتجه التسجيل الخاص بك بمجرد وصول الأحداث.
* **[مهارة Evaluator Agent](/ar/agenteye/evaluator-skill)**: الخطوة التالية بمجرد هبوط التشغيلات — تقييمها.
* **[مهارة CLI Agent](/ar/agenteye/cli-skill)**: قراءة بيانات المراقبة الخاصة بك مرة أخرى.