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

# Getting started

title: "البدء مع AgentEye"
description: "وثائق البدء مع AgentEye."
---------------------------------------

يرشدك هذا الدليل خلال إعداد AgentEye الكامل: نشر الخادم واللوحة، وتثبيت جامع البيانات على جهاز الوكيل، وتجهيز كود وكيل Python الخاص بك.

***

## ما هو AgentEye؟

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

تتدفق البيانات في اتجاه واحد: يصدر كود الوكيل **أحداثاً** عبر **Python SDK** → تجميع **جامع** خفيف الوزن وشحن الأحداث إلى **الخادم** → تخزين الأحداث والتحليلات في **ClickHouse** (الحالة التشغيلية مثل المنظمات والمستخدمين ومفاتيح API والمجلات والاستعلامات المحفوظة توجد في **Postgres**) → استكشاف كل شيء في **لوحة المعلومات**.

ما تحصل عليه:

* **الأحداث** — مسار خام مفصل لكل دورة وكيل (استدعاءات الأدوات، استدعاءات النموذج، الخطافات، الأخطاء).
* **الجلسات** — تلك الأحداث مدمجة في صف واحد لكل دورة، كل منها **تقيّم تلقائياً** وتسجيل.
* **التقييمات** — درجات الجودة التي تنتجها خدمات المقيّم الخاصة بك، حتى تظهر انخفاضات الجودة بدون مراجعة يدوية.
* **الاستعلامات والمجلات** — استعلامات ClickHouse SQL المحفوظة على بيانات الخاص بك، مرسومة في مجلات مشتركة محدودة بالمنظمة.
* **التنبيهات والحوادث** — قواعد العتبة التي تخطرك (بريد إلكتروني، Slack، webhook، لوحة المعلومات) بالإضافة إلى سير عمل الحادث لفحصها.
* **واجهة سطر الأوامر ومساعد AI** — عميل محطة (`agenteye`) ومساعد لوحة المعلومات للإجابة على الأسئلة بلغة إنجليزية بسيطة.

تشغّل كل شيء في البنية التحتية الخاصة بك، كمكدس Docker Compose واحد (هذا الدليل)، تثبيت Kubernetes للإنتاج، أو وحدة واحدة موضوعة بشكل مشترك. يقوم باقي هذا الدليل بإعداد مكدس Compose من البداية إلى النهاية.

***

## الخطوة 1: المصادقة

يتم توزيع جميع تقنيات AgentEye من منظمة GitHub `agenteye-enterprise`. كمطور مؤسسة، يمكنك إنشاء رمز PAT خاص بـ GitHub الخاص بك. اتبع [enterprise-docs/github-token.md](/ar/agenteye/github-token) للحصول على الخطوات الدقيقة والأذونات المطلوبة.

```bash theme={null}
export AGENTEYE_TOKEN=<your-github-pat>

# Authenticate Docker against GHCR
echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin
```

***

## الخطوة 2: نشر الخادم ولوحة المعلومات

يستقبل الخادم الأحداث من جامعي البيانات ويجعلها قابلة للاستعلام؛ لوحة المعلومات هي المكان الذي تستكشف فيه الأحداث. الأحداث المدخولة والتحليلات موجودة في ClickHouse (متجر التحليلات المطلوب)، بينما يحتفظ Postgres بالحالة التشغيلية مثل المنظمات والمستخدمين ومفاتيح API والمجلات والاستعلامات المحفوظة.

**قم بتحميل ملف compose المنشور:**

```bash theme={null}
mkdir -p ./agenteye
curl -fsSL \
  -H "Authorization: token $AGENTEYE_TOKEN" \
  https://raw.githubusercontent.com/agenteye-enterprise/releases/main/docker-compose.yml \
  -o ./agenteye/docker-compose.yml
cd agenteye
```

**عيّن أسرارك:**

أنشئ ملف `.env` حتى لا يعمل النشر على بيانات اعتماد `admin` الافتراضية. عيّن كحد أدنى `ADMIN_KEY` و `POSTGRES_PASSWORD`:

```bash theme={null}
POSTGRES_PASSWORD=your-db-password
ADMIN_KEY=your-admin-secret
```

**بدء المكدس:**

```bash theme={null}
docker compose up -d
```

يؤدي هذا إلى إطلاق المكدس الكامل، بما في ذلك متجر تحليلات ClickHouse المطلوب وذاكرة تخزين مؤقت Redis اختيارية، إلى جانب الخادم ولوحة المعلومات. يجب أن يكون ClickHouse صحياً حتى يبدأ الخادم.

الخادم يستمع الآن في `http://localhost:8080` ولوحة المعلومات في `http://localhost:3000`.

بالنسبة للنشرات الإنتاجية (Postgres مخصص، TLS، reverse proxy)، انظر [enterprise-docs/deployment.md](/ar/agenteye/deployment).

***

## الخطوة 3: إنشاء مفتاح API لجامع البيانات

يتم مصادقة كل جامع بمفتاح API محدود النطاق. استخدم `ADMIN_KEY` الذي عينته في الخطوة 2 لإنشاء واحد:

```bash theme={null}
curl -s -X POST http://localhost:8080/keys \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"prod-collector","key":"your-collector-secret","permissions":["events:add"]}'
```

أنت توفر قيمة `key` بنفسك؛ استخدمها في تكوين جامع البيانات في الخطوة 4. راجع [enterprise-docs/api-keys.md](/ar/agenteye/api-keys) لإدارة المفاتيح الكاملة.

***

## الخطوة 4: تثبيت جامع البيانات

على كل جهاز يشغّل وكلاء AI الخاص بك، ثبّت جامع البيانات daemon.

**قم بتحميل البرنامج الثنائي (Linux x86\_64):**

```bash theme={null}
VERSION=0.0.1-beta.13
GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download "collector/v${VERSION}" \
  --repo agenteye-enterprise/releases \
  --pattern 'agenteye-collector-linux-x86_64'
chmod +x agenteye-collector-linux-x86_64
sudo mv agenteye-collector-linux-x86_64 /usr/local/bin/agenteye-collector
```

> يقوم هذا بتحميل **Linux x86\_64** البناء. بالنسبة إلى macOS (Apple Silicon أو Intel)، Linux arm64، أو Docker/systemd/launchd setup، انظر [collector-installation.md](/ar/agenteye/collector-installation)، التي تسرد التحميل لكل منصة — الأمر أعلاه يثبت ملف ثنائي Linux لن يعمل في مكان آخر.

**تكوين:**

```bash theme={null}
mkdir -p ~/.agenteye
cat > ~/.agenteye/config.json <<EOF
{
  "url": "http://your-server-host:8080/events",
  "key": "the-key-from-step-3"
}
EOF
```

**بدء daemon:**

```bash theme={null}
agenteye-collector start
```

تحقق من الاتصال باستخدام مسح لمرة واحدة (يخرج بعد استنزاف أي أحداث معلقة):

```bash theme={null}
agenteye-collector flush
```

بالنسبة إلى Docker وsetup systemd وlaunchd راجع [enterprise-docs/collector-installation.md](/ar/agenteye/collector-installation).

***

## الخطوة 5: تثبيت Python SDK

على كل جهاز تريد فيه تجهيز كود الوكيل، ثبّت wheel من GitHub Releases.

```bash theme={null}
VERSION=0.0.1b9
GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download "python-sdk/v${VERSION}" \
  --repo agenteye-enterprise/releases \
  --pattern 'agenteye-*.whl'
pip install agenteye-${VERSION}-py3-none-any.whl
```

***

## الخطوة 6: تجهيز وكيل الخاص بك

أضف أحداثاً إلى كود الوكيل الخاص بك. على الحد الأدنى، أصدر `agent_start` و `agent_end`:

```python theme={null}
import agenteye

agenteye.event.agent_start(
    session_id="run-001",
    agent_id="my-agent",
    goal="answer the user query",
)

# your agent logic here

agenteye.event.agent_end(
    session_id="run-001",
    agent_id="my-agent",
    outcome="success",
)
```

يتم تجميع الأحداث في الذاكرة المؤقتة ومسحها إلى `$AGENTEYE_HOME/events/` (أو `~/.agenteye/events/` إذا لم تكن `AGENTEYE_HOME` محددة) كل 500 ميلي ثانية. جامع البيانات يلتقطها تلقائياً.

راجع [enterprise-docs/python-sdk.md](/ar/agenteye/python-sdk) لـ API الأحداث الكاملة.

***

## الخطوة 7: عرض الأحداث في لوحة المعلومات

افتح `http://your-dashboard-host:3000` وقم بتسجيل الدخول. AgentEye ترسل لك بريداً إلكترونياً برمز لاستخدام واحد (أو رابط سحري بنقرة واحدة)، لذلك لا توجد كلمة مرور لتدارها.

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/login.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=8f83cb747193d872f7883cb709587635" alt="شاشة تسجيل دخول AgentEye، التي ترسل رمز لاستخدام واحد إلى بريدك الإلكتروني" width="2880" height="1800" data-path="agenteye/images/login.png" />

بمجرد أن تكون فيها، تعرض صفحة **الأحداث** مسار مباشر من جميع الأحداث المدخولة. قم بالتصفية حسب `session_id` أو `agent_id` للتعمق في دورة محددة.

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/events-stream.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=79714903a85d10773f4f9b36cb44b1cf" alt="تدفق الأحداث المباشر، مرمز بالألوان حسب نوع الحدث وقابل للتصفية حسب البيئة والوكيل والجلسة" width="2880" height="1800" data-path="agenteye/images/events-stream.png" />

تجمع صفحة **الجلسات** تلك الأحداث في صف واحد لكل دورة. AgentEye تقيّم الجلسات المكتملة تلقائياً، لذا يتم تسجيل كل دورة وتظهر انحدارات الجودة بدون مراجعة يدوية؛ تظهر درجة التقييم الأحدث على كل صف في لمحة:

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/sessions-list.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=10de161665eef64465d3d100e80b643f" alt="قائمة الجلسات، صف واحد لكل دورة، مع شارات الحالة وشارات درجة التقييم" width="2880" height="1800" data-path="agenteye/images/sessions-list.png" />

لتكوين كيفية تسجيل الجلسات، انظر [enterprise-docs/evaluation-suite.md](/ar/agenteye/evaluation-suite).

انقر فوق أي جلسة لفتح **رسم بياني التنفيذ**، وهو عرض بأسلوب git لكيفية تطور الوكلاء والأدوات والخطافات واستدعاءات النموذج بمرور الوقت، مع وكلاء فرعيين متوازيين على خطوطهم الخاصة وتفصيل لكل دورة في السكة الصحيحة:

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/session-detail.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=63cc2480e8124a05ea6a0a92d5f20690" alt="رسم بياني تنفيذ الجلسة بأسلوب git بجانب الخط الزمني للأحداث، مع لوحة الأداة/النموذج/الخطاف" width="2880" height="1800" data-path="agenteye/images/session-detail.png" />

***

## الخطوة 8: استكشاف والرسم البياني والتنبيه

مع تدفق الأحداث، تحول صفحات **التحليل** النشاط الخام إلى إجابات، حتى تتمكن من قياس سلوك الوكيل ومشاركة النتائج عبر الفريق والحصول على صفحة اللحظة التي يحدث فيها انحدار ما. صفحات لوحة المعلومات محدودة النطاق بالمنظمة، لذا فإن عناوين URL التي تراها في شريط العناوين مع بادئة slug المؤسسة الخاصة بك (`/<org>/…`).

* **الاستعلامات** (`/<org>/queries`): ابدأ من مكتبة الاستعلامات المحفوظة وقابلة لإعادة الاستخدام على الأحداث والتقييمات الخاصة بك (الإعدادات المدمجة بالإضافة إلى الخاصة بك)…

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/queries.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=1b42be492d5b650b4bd6b8a2241f6633" alt="مكتبة الاستعلامات المحفوظة: شبكة من الاستعلامات القابلة لإعادة الاستخدام، سواء الإعدادات المدمجة أو الاستعلامات المخصصة" width="2880" height="1800" data-path="agenteye/images/queries.png" />

…ثم افتح واحداً في منشئ SQL لتعديله وتشغيله مع النتائج المباشرة:

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/query-lab.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=aec1a1d95bb0bf1280d62a2e2430f20e" alt="منشئ استعلام SQL يقوم بتشغيل استعلام محفوظ، مع شريط جانبي للمخطط وشبكة نتائج مباشرة" width="2880" height="1800" data-path="agenteye/images/query-lab.png" />

* **لوحات المعلومات** (`/<org>/dashboards`): اضبط الاستعلامات كخط أو شريط أو منطقة أو بلاط دائري في لوحات معلومات مشتركة في جميع أنحاء المنظمة.

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/dashboard-fleet.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=d1fed0deace0ebb0bc02421f3b994107" alt="لوحة معلومات مبنية من الاستعلامات المحفوظة: خط أحداث في الساعة، شريط أخطاء حسب النوع، مخطط منطقة الكمون، والرموز حسب النموذج" width="2880" height="1800" data-path="agenteye/images/dashboard-fleet.png" />

* **التنبيهات** (`/<org>/alerts`): ارفع أي عتبة إلى قاعدة تصفية تخطر عبر البريد الإلكتروني أو Slack أو webhook أو لوحة المعلومات. انظر [enterprise-docs/alerts.md](/ar/agenteye/alerts).

***

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

* [النشر](/ar/agenteye/deployment): تصلب للإنتاج
* [مفاتيح API](/ar/agenteye/api-keys): إدارة الوصول
* [استكشاف الأخطاء والإصلاح](/ar/agenteye/troubleshooting): تشخيص المشاكل