agenteye عن بيانات النظام (الجلسات وسجلات الأحداث والتقييمات) ويدير مؤسستك (مفاتيح API والمستخدمون والإعدادات والتنبيهات والحوادث والاستعلامات المحفوظة)، لذا استخدمه عندما تريد أتمتة فحص أو دمج الملاحظة في CI أو السماح لوكيل ترميز بفحص الإنتاج. يدعم كل أمر علم --json، لذلك يعمل بنفس الكفاءة سواء كنت في موجه الأوامر أو وكيل ترميز (Claude Code أو Cursor) يقوم بتنفيذ الأمر وتحليل النتيجة.
باستخدام ملف ثنائي واحد يمكنك:
- قراءة بيانانك:
sessionsوeventsوevalsوerrors(تصفية حسب الوقت والوكيل والبيئة والنتيجة). - إدارة مؤسستك:
keysوusersوsettingsوalertsوincidents. - تشغيل التحليلات: SQL محفوظ وأداة استعلام مخصصة (
query). - اطلب من مساعد الذكاء الاصطناعي: نفس محلل القراءة فقط الذي تتحدث معه في لوحة التحكم (
agent).
ملاحظة: هذا هو CLIagenteye، وهي أداة مختلفة عن عفريت المجمع (agenteye-collector). يتحدث CLI مع لوحة التحكم الخاصة بك؛ المجمع يرسل الأحداث إلى الخادم.
البدء السريع
من الصفر إلى أول نتيجة في أربعة أسطر. وجه CLI إلى لوحة التحكم الخاصة بك وقم بتسجيل الدخول والتأكد من هويتك ثم اسحب آخر يوم من التشغيلات:jq لتقطيعه، أو أزل --json للحصول على جدول مربع وملون. يحمل كل صف حالة التشغيل والنتائج المترية إذا قام المقيم بتقييمه (مختصرة هنا):
التثبيت
CLI عبارة عن حزمة PyPI عامة تسمىagenteye. ثبتها في بيئة معزولة حتى يكون لديها دائماً اعتماديات خاصة بها:
agenteye:
ملاحظة: SDK Python الخاص بـ Failproof AI Observability يستخدم أيضاً اسم توزيعagenteye. يحافظ تثبيت CLI باستخدامpipxأوuv tool(بدلاً منpip installفي virtualenv مشترك) على عدم تضارب الاثنين.pip install agenteyeعادي جيد فقط إذا لم يكن SDK مثبتاً في نفس البيئة.
المصادقة
يوثق CLI إلى لوحة التحكم باستخدام كود لمرة واحدة يتم إرساله بالبريد الإلكتروني:~/.agenteye/cli.json (قابل للقراءة فقط من قبلك، mode 0600) وصالح لمدة 24 ساعة افتراضياً. عند انتهاء صلاحيته، قم بتشغيل agenteye login مرة أخرى.
whoami أبداً في جلسة مفقودة أو منتهية الصلاحية؛ بدلاً من ذلك يبلغ عن logged_in: false، لذا يمكن لنص برمجي أو وكيل التحقق من حالة المصادقة بأمان (لا يزال يمكن أن يخرج مع كود غير صفري إذا لم يتم تعيين عنوان URL أساسي أو كانت لوحة التحكم غير قابلة للوصول).
المتطلبات: يجب السماح لبريدك الإلكتروني بتسجيل الدخول إلى لوحة التحكم (اطلب من مسؤول Failproof AI Observability)، ويجب أن تكون لوحة التحكم قابلة للوصول على عنوان URL الأساسي الخاص بها (انظر الإعدادات). إذا طلبت كوداً ولم يصل أي، فمن المحتمل أن بريدك الإلكتروني لم يتم تفعيله بعد للوصول إلى لوحة التحكم.
اختيار مؤسستك (متعدد الإيجار)
إذا كان حسابك ينتمي إلى أكثر من مؤسسة واحدة، اختر المؤسسة النشطة عند تسجيل الدخول؛ يتم حفظها واستخدامها لكل أمر لاحق:--org تماماً. إذا كنت تنتمي إلى عدة مؤسسات ولم تختر واحدة، يسرد CLI القائمة ويطلب منك إعادة التشغيل باستخدام --org <slug>. يتم إرسال المؤسسة النشطة إلى لوحة التحكم في كل طلب، وتتم معالجة أذوناتك لكل مؤسسة؛ agenteye whoami يظهر المؤسسة النشطة وأذوناتك فيها وجميع عضوياتك.
الإعدادات
ترتيب الدقة هو العلم → متغير البيئة → ملف الإعدادات. لا يوجد افتراضي؛ يجب عليك توجيه CLI إلى لوحة التحكم الخاصة بك، إما لكل أمر (
--base-url https://agenteye.example.com) أو مرة واحدة عبر البيئة (يتم حفظها أيضاً بعد أول login):
AGENTEYE_HOME (نفس الاتفاقية المستخدمة من قبل SDK والمجمع)؛ إذا تم التعيين، يعيش cli.json في $AGENTEYE_HOME/cli.json.
TLS ذاتي التوقيع أو داخلي
إذا كانت لوحة التحكم الخاصة بك تُقدم عبر HTTPS مع شهادة ذاتية التوقيع أو داخلية (على سبيل المثال، اسم مضيف موازن تحميل خام)، يرفضها التحقق من TLS مع خطأCERTIFICATE_VERIFY_FAILED. مرر --insecure لتخطي التحقق من الشهادة:
--insecure إلى cli.json عند تسجيل الدخول، لذلك تتخطى الأوامر اللاحقة التحقق تلقائياً؛ لا تضطر إلى تكرار العلم. مرر --secure لاستدعاء موثق لمرة واحدة، أو لحفظ التحقق مرة أخرى عند تسجيل الدخول التالي. يطبع CLI تحذيراً على stderr قبل أي أمر يتواصل مع لوحة التحكم أثناء تعطيل التحقق. يزيل تخطي التحقق الحماية من هجمات الرجل في الوسط؛ تأكد من أنك تثق بمسار الشبكة إلى لوحة التحكم الخاصة بك (VPN أو subnet خاص وما إلى ذلك) قبل الاعتماد عليه.
قياس الاستخدام والخصوصية
ملاحظة: CLI المُشحون لا يرسل قياس اليستخدام اليوم. مفتاح القتل الرئيسي مفعل، لذلك لا يتم نقل شيء بغض النظر عن البيئة الخاصة بك. يوضح القسم أدناه إمكانية عدم الاشتراك في حالة تفعيل قياس الاستخدام في المستقبل.حتى عند تفعيله، سيكون قياس الاستخدام فقط تحليلات الاستخدام المجهولة، وليس أبداً وكيلك أو جلستك أو بيانات الحدث:
- لا تترك بيانات الوكيل أو الجلسة أو الحدث أبداً البنية التحتية الخاصة بك. سيتم الإبلاغ عن استخدام CLI فقط: اسم الأمر والأمر الفرعي (على سبيل المثال
keys create)، و أسماء الأعلام التي استخدمتها (وليس قيمها أبداً)، وحالة النجاح/الخروج والمدة، بالإضافة إلى حدث لكل إجراء للطفرات (على سبيل المثالapi_key_createdوquery_run) يحمل فقط الأسماء الثابتة/التعداد والأعداد الإجمالية. عنوان URL لوحة التحكم الخاصة بك ورمز الجلسة والبريد الإلكتروني وslug المؤسسة وhids الموارد و SQL وأسرار المفاتيح وفلاتر الاستعلام لن يتم إرسالها أبداً. سيتم تحديد المشغلين فقط بواسطة معرف داخلي معتم، وليس بالبريد الإلكتروني. - لا تشترك مقدماً بتعيين
AGENTEYE_ANALYTICS_DISABLED=1في بيئة CLI (يحترم CLI أيضاً اتفاقية أداة متقاطعةDO_NOT_TRACK=1). يسري هذا في اللحظة التي يتم فيها تفعيل قياس الاستخدام، لذا يمكن للبيئة الواعية بالخصوصية البقاء غير مشترك إلى الأبد. - إذا تم تفعيل قياس الاستخدام، فسيرسل CLI مباشرة إلى PostHog (
https://us.i.posthog.com)؛ الجهاز الذي لديه هذا المضيف محظور سيرسل بصمت شيء والـ CLI لن يتأثر.
الخيارات العامة والاتفاقيات
اقرأ هذا مرة واحدة؛ ينطبق على كل أمر.- تذهب الخيارات العامة قبل الأمر.
agenteye --json sessionsصحيح؛agenteye sessions --jsonخطأ استخدام. العامة هي--jsonو--base-urlو--orgو--tokenو--insecure/--secureو--timeoutو--quietو--no-color. --jsonيطبع JSON خالص إلى stdout، وشيء آخر. خطوط حالة الإنسان والتحذيرات والأخطاء تذهب إلى stderr، لذا يبقى التقاط stdout--jsonنظيفاً لأنابيب إلىjqحتى عندما يتم عرض سطر حالة. بدون--jsonتحصل على عرض مربع وملون لعيون الإنسان.- اكتشف باستخدام
--help. لكل أمر وأمر فرعي--help(والاسم المستعار-h):agenteye -hوagenteye sessions -hوagenteye keys create -h. تسرد الشرعة عالية المستوى أيضاً أكواد الخروج والخيارات العامة. لا يوجد تفريغ سطح قابل للقراءة من الآلة عالمي؛ استخدم--helpلكل أمر، بالإضافة إلىagenteye query schemaوagenteye settings schemaالخاصة بالمجال لتلك السجلات. - الأكثر تأكيداً للتخطي التلقائي للنصوص البرمجية والوكلاء. إنشاء/تحديث/حذف أوامر اطلب “هل أنت متأكد؟” في محطة طرفية تفاعلية، لكن تخطي هذا الطلب تلقائياً تحت
--jsonأو عندما لا تكون stdin TTY (TTY هي جلسة محطة طرفية تفاعلية؛ الأنابيب أو عداء CI ليست)، لذا لا تعلق النصوص البرمجية والوكلاء أبداً. مرر--yes/-yلتخطيها بشكل صريح. لأن الطلب لن يحترق لوكيل، يجب على الوكيل تأكيد الإجراءات المدمرة مع الإنسان أولاً. - الترقيم: النتائج هي الأحدث أولاً والترقيم المستند إلى المؤشر (يُرجع كل صفحة رمزاً تستخدمه لجلب النتيجة التالية).
--limit N(alias-n) يغطي الصفوف و يفترض 50؛--allيصفحة تلقائياً (في أجزاء بـ 200 صف) حتى--limit، لذا--allمجرد يتوقف عند 50. لكنسة كاملة قم بتمرير حد أعلى صريح:--all --limit 1000.--page-size Nيتحكم في الجزء لكل طلب (max 200)؛--cursor <id>يستأنف منnext_cursorالصفحة السابقة. - مرشحات الوقت:
--sinceيأخذ نافذة نسبية:15mأو1hأو6hأو24hأو7dأوall(إعدادات لوحة التحكم المسبقة). لنطاق أطول أو مخصص (قل آخر 30 يوماً)، استخدم--from/--to: طوابع زمنية UTC صريحة بصيغة ISO-8601 معTومنطقة زمنية (على سبيل المثال2026-06-01T00:00:00Z) التي تتجاوز--since. القيمة المفصولة بمسافة أو بدون منطقة زمنية هي خطأ استخدام. --fields a,b,c(علىeventsوsessionsوevalsوerrors) يقيد المخرجات إلى تلك المفاتيح، لكل من الجدول و--json. يتم رفض الأسماء غير المعروفة بالقائمة الصحيحة، طريقة رخيصة لاكتشاف أسماء الحقول.--file payload.json(أو--file -لقراءة stdin) توفر جسم طلب JSON كامل حيث يكون لدى مورد شكل معقد (علىalerts create/updateوsettings setوusers create/update). يستخدم SQL المحفوظ بدلاً من ذلك--sql @file.sql.- مرشحات متعددة القيم مفصولة بفواصل → مطابقة كمجموعة (اتحاد ضمن مرشح واحد، AND عبر المرشحات):
--event-type tool_use,tool_result. خيارات النقر ليست متغيرة الطول، لذا--add a bفواصل. استخدم--add a,bأو كرر العلم (--add a --add b) أو علامة اقتباس (--add "a b").
مرجع الأمر
ستستخدم هذه 5 أوامر الأكثر
يعمل معظم العمل اليومي من خلال حفنة من أوامر القراءة. ابدأ هنا، ثم اوصل إلى السطح الكامل أدناه عند الحاجة إليه:كل شيء يمكن أن يفعله CLI
يتبع السطح الكامل. لديها CLI 18 أمر على المستوى الأعلى. تقبل جميع أوامر القراءة--json والخيارات العامة أعلاه؛ قم بتشغيل agenteye <command> -h (أو <command> <subcommand> -h) لقائمة العلم الشاملة وشكل JSON لأي واحد.
الهوية: login · logout · whoami · orgs · version · help
orgs يفحص ويبدل المستأجر النشط:
ملاحظة (قراءة فقط): events · sessions · evals · errors · list
لا يحتاج أي من هؤلاء تأكيداً. مرشحات مشتركة: --session-id و --agent-id و --env (ليس --environment) ونطاق الوقت (--since / --from / --to).
--score KEY:MIN..MAX (على evals وليس sessions) قابلة للتكرار و AND-combined؛ كل حد اختياري (..0.5 يعني ≤ 0.5 و 0.9.. يعني ≥ 0.9). حتى 20 مرشح نتيجة لكل طلب. evals --scores-full هي علم عرض لـ الجدول البشري فقط؛ يُظهر كل زوج نتيجة بدلاً من الأول والقليل بالإضافة إلى عد +N. لا تأثير تحت --json، الذي يُرجع دائماً كائن النتيجة الكامل. لقراءة جلسة واحدة من البداية إلى النهاية، دمج مسار الحدث مع تقييمه:
إدارة (تحت حراسة الأذونات): keys · users · settings · alerts · incidents
keys: مفاتيح API. يتم إنشاء السر محلياً وإرساله إلى الخادم (الذي يخزن فقط تجزئة) و يظهر مرة واحدة على الإنشاء/إعادة الإنشاء؛ التقطها إذاً. مع --json يظهر فقط في حقل key. المرجعية ب الاسم.
(permission-set ∪ --add) − --remove. الرموز هي slug:action (على سبيل المثال events:read) أو slug:action.action لتوسيع عدة على مورد واحد (events:read.add → events:read و events:add). الإعدادات المسبقة: read-only و standard و admin. الأذونات البشرية فقط (keys:update) لا يمكن منحها لمفتاح.
users: أعضاء المنظمة، المرجعية ب البريد الإلكتروني (يُقبل أيضاً معرف UUID).
settings: سجل ثابت (تقرأ وتغير المفاتيح الموجودة؛ لا يمكنك إنشاء واحد جديد).
alerts: تعريفات التنبيه، المرجعية ب الاسم. create يأخذ NAME موضعي بالإضافة إلى الأعلام أو جسم JSON كامل عبر --file.
incidents: حوادث التنبيه، المرجعية بـ id (معرفات قصيرة مقبولة). show يطبع سجل النشاط الكامل؛ اقرأه قبل التصرف.
التحليلات والمساعد: query · agent
query: SQL محفوظ مقابل متجر التحليلات بالإضافة إلى عداء مخصص. الاستعلامات المحفوظة المرجعية ب الاسم؛ يتم التحقق من SQL من جانب الخادم (SELECT/WITH فقط، مهلة البيان، حد الصف).
agent: يتحدث إلى مساعد الذكاء الاصطناعي المدمج (نفس محلل القراءة فقط الذي يمكنك الدردشة معه في لوحة التحكم). يتم الإشارة إلى الدردشات بـ chat-id قصير (قابل للدقة البادئة).
أكواد الخروج
وهذا يجعل CLI آمنة للنص البرمجي: يمكن لوكيل ترميز فرع على
4 لمطالبتك بإعادة المصادقة، أو 5 لسطح الأذن المفقودة. انظر وصفات CLI للوكلاء لأنماط معالجة أكواد الخروج وأشكال مخرجات JSON.
الخطوات التالية
- وصفات CLI للوكلاء: أنماط استعلام نسخ لصق،
jqسطر واحد، إسقاطات--fields، معالجة أكواد الخروج وأشكال مخرجات JSON، مكتوبة لوكلاء ترميز يقودون CLI. - مهارة عامل CLI: حزم هذا CLI كمهارة قابلة للتثبيت Claude Code / Codex بحيث يقود وكيل ترميز Failproof AI Observability من طلبات اللغة الطبيعية.
- مفاتيح API: نموذج الأذن خلف
keys create --add …. - مساعد الذكاء الاصطناعي: تفعيل المساعد الذي يتحدث معه
agent ask.

