Getting started - FailproofAI

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 للحصول على الخطوات الدقيقة والأذونات المطلوبة.

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 المنشور:

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:

POSTGRES_PASSWORD=your-db-password
ADMIN_KEY=your-admin-secret

بدء المكدس:

docker compose up -d

يؤدي هذا إلى إطلاق المكدس الكامل، بما في ذلك متجر تحليلات ClickHouse المطلوب وذاكرة تخزين مؤقت Redis اختيارية، إلى جانب الخادم ولوحة المعلومات. يجب أن يكون ClickHouse صحياً حتى يبدأ الخادم. الخادم يستمع الآن في http://localhost:8080 ولوحة المعلومات في http://localhost:3000. بالنسبة للنشرات الإنتاجية (Postgres مخصص، TLS، reverse proxy)، انظر enterprise-docs/deployment.md.

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

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

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 لإدارة المفاتيح الكاملة.

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

على كل جهاز يشغّل وكلاء AI الخاص بك، ثبّت جامع البيانات daemon. قم بتحميل البرنامج الثنائي (Linux x86_64):

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، التي تسرد التحميل لكل منصة — الأمر أعلاه يثبت ملف ثنائي Linux لن يعمل في مكان آخر.

تكوين:

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

بدء daemon:

agenteye-collector start

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

agenteye-collector flush

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

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

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

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:

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 لـ API الأحداث الكاملة.

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

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

شاشة تسجيل دخول AgentEye، التي ترسل رمز لاستخدام واحد إلى بريدك الإلكتروني

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

تدفق الأحداث المباشر، مرمز بالألوان حسب نوع الحدث وقابل للتصفية حسب البيئة والوكيل والجلسة

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

قائمة الجلسات، صف واحد لكل دورة، مع شارات الحالة وشارات درجة التقييم

لتكوين كيفية تسجيل الجلسات، انظر enterprise-docs/evaluation-suite.md. انقر فوق أي جلسة لفتح رسم بياني التنفيذ، وهو عرض بأسلوب git لكيفية تطور الوكلاء والأدوات والخطافات واستدعاءات النموذج بمرور الوقت، مع وكلاء فرعيين متوازيين على خطوطهم الخاصة وتفصيل لكل دورة في السكة الصحيحة:

رسم بياني تنفيذ الجلسة بأسلوب git بجانب الخط الزمني للأحداث، مع لوحة الأداة/النموذج/الخطاف

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

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

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

مكتبة الاستعلامات المحفوظة: شبكة من الاستعلامات القابلة لإعادة الاستخدام، سواء الإعدادات المدمجة أو الاستعلامات المخصصة

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

منشئ استعلام SQL يقوم بتشغيل استعلام محفوظ، مع شريط جانبي للمخطط وشبكة نتائج مباشرة

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

لوحة معلومات مبنية من الاستعلامات المحفوظة: خط أحداث في الساعة، شريط أخطاء حسب النوع، مخطط منطقة الكمون، والرموز حسب النموذج

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

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

النشر: تصلب للإنتاج
مفاتيح API: إدارة الوصول
استكشاف الأخطاء والإصلاح: تشخيص المشاكل

​title: “البدء مع AgentEye” description: “وثائق البدء مع AgentEye.”

​ما هو AgentEye؟

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

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

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

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

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

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

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

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

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