وصفات سطر الأوامر للوكلاء

اسحب بيانات الجلسة والأحداث والتقييم (وشغل إعادة التقييمات) مباشرة من سكريبت أو وكيل ترميز، مع JSON نظيف على stdout يتم توجيهه مباشرة إلى jq. هذه الوصفات تحول بيانات Failproof AI Observability إلى شيء يمكن لمستخدم المحطة الطرفية أو وكيل ترميز AI (Claude Code، Cursor) أن يستعلم عنه ويؤتمتنه، دون النقر عبر لوحة المعلومات. الأنماط أدناه جاهزة للنسخ واللصق في سطر أوامر Failproof AI Observability (agenteye). للتثبيت والمصادقة وقائمة الخيارات الكاملة، انظر CLI؛ شغّل agenteye -h أو agenteye <command> -h للحصول على المساعدة المدمجة.

القواعد الذهبية

الخيارات العامة تأتي قبل الأمر. agenteye --json sessions صحيح؛ agenteye sessions --json غير صحيح. الخيارات العامة هي --json, --base-url, --org, --token, --insecure/--secure, --timeout, --quiet, --no-color.
مرّر --json كلما قمت بتحليل المخرجات. البيانات تذهب إلى stdout كـ JSON؛ حالة المستخدم والأخطاء تذهب إلى stderr، لذلك يبقى stdout نظيفاً للتوجيه إلى jq.
تفرع بناءً على رمز الخروج، وليس على نص stderr: 0 موافق · 1 خطأ غير متوقع · 2 وسائط سيئة · 3 لا يمكن الوصول إلى لوحة المعلومات · 4 غير مسجل دخول أو انتهت صلاحية الجلسة · 5 إذن مفقود · 6 المورد غير موجود.
اكتشف باستخدام -h. كل أمر يوثق عوامل التصفية وصيغ القيم وشكل JSON.

إعداد لمرة واحدة

export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com   # كي لا تكرر --base-url
agenteye login --email you@example.com                       # الصق الرمز المرسل بالبريد؛ صالح ~24 ساعة

تأكد المصادقة قبل القيام بالعمل

whoami لا يخطئ على جلسة مفقودة أو منتهية الصلاحية؛ بدلاً من ذلك، يبلغ logged_in:false، لذا يمكن لوكيل أن يختبر حالة المصادقة بأمان. (قد يزال يخرج بقيمة غير صفرية إذا لم يتم تعيين عنوان URL أساسي أو كانت لوحة المعلومات غير قابلة للوصول.)

if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then
  echo "Not authenticated. Run: agenteye login" >&2; exit 1
fi

ابحث عن الجلسات الفاشلة أو منخفضة التصنيف

# الجلسات في آخر 24 ساعة التي حدث فيها خطأ في التقييم
agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id'

# التقييمات التي تسجل <= 0.5 في المساعدة، لوكيل واحد
agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \
  | jq '.evaluations[] | {session_id, scores}'

تصفية التصنيف موجودة على evals، وليس sessions. --score KEY:MIN..MAX قابل للتكرار ويتم دمجه بـ AND؛ أي حد اختياري (..0.5 يعني ≤ 0.5، 0.9.. يعني ≥ 0.9). يمكنك تمرير ما يصل إلى 20 مرشح تصنيف لكل طلب؛ المزيد يعيد HTTP 400. sessions يشارك مرشحات --env, --status, --agent-id, --session-id، ونطاق الوقت مع evals، لكنه لا يحتوي على --score.

اقرأ جلسة واحدة من البداية إلى النهاية

لا يوجد أمر session show واحد. اجمع بين مسار الأحداث والتقييم الخاص بالجلسة:

# آخر تقييم للجلسة (الحالة + التصنيفات)
agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}'

# كل حدث في التشغيل (رفع --limit للمسح الكامل)
agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}'

# فقط استدعاءات الأداة في جلسة (--full مطلوب للحصول على الحمل الخام)
agenteye --json events --full --session-id run-001 --event-type tool_use,tool_result --all \
  | jq '.events[].payload'

ملاحظة: بشكل افتراضي، events يقرأ موجز سريع بدون حمول. يحمل كل حدث summary محسوب على الخادم من سطر واحد بالإضافة إلى علامات مثل is_error وعدد الرموز، لكن payload يعود كـ {}. لسحب الحمل الخام، أضف --full (أو --fields payload). الموجز الكامل أبطأ بحجم كبير، لذا اجعله محدوداً: اجمع --full مع --session-id واحد.

جلب كل شيء (الترقيم)

النتائج هي الأحدث أولاً والمُرقمة بالمؤشر.

# دفعة واحدة: جلب ما يصل إلى 500 صف في صفحات 200 صف
agenteye --json events --session-id run-001 --limit 500 --all > events.json

# الترقيم اليدوي: مرّر next_cursor مرة أخرى
page=$(agenteye --json events --limit 100)
cursor=$(echo "$page" | jq -r '.next_cursor // empty')
[ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor"

قلل المخرجات باستخدام —fields

قصر المفاتيح (في الجدول و--json) لتقليل ما يجب على الوكيل قراءته.

agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]'
agenteye --json events --session-id run-001 --fields ts,event_type --all

أسماء الحقول غير المعروفة يتم رفضها (خروج 2) مع القائمة الصحيحة، وهي طريقة رخيصة لاكتشاف أسماء الحقول.

اكتشف قيم المرشحات الصحيحة

agenteye --json list envs | jq -r '.values[]'           # قيم --env
agenteye --json list tools | jq -r '.values[]'          # أسماء الأدوات؛ أيضاً وكلاء وموديلات وأنواع أحداث وغيرها
agenteye --json list score_filters | jq -r '.values[]'  # KEY صحيح لـ --score KEY:MIN..MAX

اختر المنظمة الخاصة بك (الإيجار المتعدد)

إذا كنت تنتمي إلى أكثر من منظمة واحدة، اختر المستأجر النشط عند تسجيل الدخول (يتم حفظه):

agenteye login --org acme --email you@corp.com   # عيّن المستأجر في نفس خطوة تسجيل الدخول
agenteye --json orgs list | jq -r '.orgs[].org_slug'
agenteye --org globex --json sessions --since 24h   # اسحب لأمر واحد

تسجيل دخول متعدد المنظمات بدون --org ينتج عنه خروج غير صفري ويطبع المنظمات للاختيار من بينها.

توفير مفتاح API لـ SDK/المجمع

# السر يطبع مرة واحدة فقط، مع --json إنه حقل .key
key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key')
agenteye keys regenerate ci-bot --yes    # التدوير؛ agenteye keys disable ci-bot --yes للإلغاء

شغّل استعلام محفوظ أو مخصص

agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows'
agenteye --json query run errs --arg prod | jq '.rows'   # استعلام محفوظ + وسيط موضعي $1

فرز الحادثة بشكل غير تفاعلي

id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id')
agenteye incidents ack "$id"
agenteye incidents assign "$id" --assignee you@corp.com
agenteye incidents resolve "$id" --yes

ملاحظة: الطفرات تتخطى تلقائياً موجز التأكيد الخاص بها تحت --json أو عندما لا يكون stdin TTY، لذلك الوكلاء لا ينتظرون؛ مرّر --yes/-y للتخطي صراحة في مكان آخر.

معالجة رمز الخروج في سكريبت

out=$(agenteye --json sessions --since 1h) || code=$?
case "${code:-0}" in
  0) echo "$out" | jq '.sessions | length' ;;
  4) echo "Session expired - run 'agenteye login'." >&2 ;;
  5) echo "Missing permission (ask an admin for evaluations:read)." >&2 ;;
  3) echo "Dashboard unreachable - check the URL." >&2 ;;
  *) echo "Unexpected error (exit ${code})." >&2 ;;
esac

أشكال مخرجات JSON

الأمر	stdout JSON (مع `--json`)
`whoami`	`{"logged_in": true, "id", "email", "is_instance_admin", "active_org", "permissions": [...], "memberships": [...]}` أو `{"logged_in": false}`
`orgs list`	`{"active_org", "orgs": [{"org_slug","org_name","permission_set","permissions"}]}`
`events`	`{"events": [...], "next_cursor": <cursor or null>}`
`evals`	`{"evaluations": [...], "next_cursor": <cursor or null>}`
`sessions`	`{"sessions": [...], "next_cursor": <cursor or null>}`
`errors`	`{"errors": [...], "next_cursor": <cursor or null>}`
`list <kind>`	`{"kind", "values": [...]}`
`keys list` / `keys create`	`{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` يظهر مرة واحدة)
`query run`	`{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}`
`users list` / `settings list`	`{"users": [...]}` / `{"settings": [...]}`
`alerts list` / `incidents list`	`{"alerts": [...]}` / `{"incidents": [...]}`
إنشاء/تحديث/حذف (أي)	كائن المورد، أو `{"deleted": true, "id"}` للحذف
فشل (أي، مع `--json`)	`{"error": "...", "exit_code": <n>, "status"?: <http>, "hint"?: "..."}` على stdout

كل عنصر الحدث (events): id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill. لاحظ أن payload هو {} إلا إذا طلبت الموجز الكامل مع --full (أو --fields payload).
كل عنصر التقييم (evals): id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at.
كل عنصر الجلسة (sessions): session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation.

كل أمر --fields يقبل أسماء الحقول الخاصة به بالضبط. تختلف المجموعة بين sessions وevals، لذا قد يتم رفض الاسم الصالح لأحدهما من قبل الآخر.

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

CLI: التثبيت والمصادقة ومرجع الخيارات الكامل لكل أمر.
CLI agent skill: احزم هذه الوصفات كمهارة يمكن لوكيل الترميز الخاص بك تحميلها.
مفاتيح API: أنشئ وحدد نطاق المفاتيح التي يستخدمها CLI و SDK والمجمع للمصادقة.
Python SDK: أرسل الأحداث إلى Failproof AI Observability بحيث يكون هناك بيانات لهذه الوصفات للاستعلام عنها.

Overview

Features

SDK and CLI

Administration

وصفات سطر الأوامر للوكلاء

القواعد الذهبية

إعداد لمرة واحدة

تأكد المصادقة قبل القيام بالعمل

ابحث عن الجلسات الفاشلة أو منخفضة التصنيف

اقرأ جلسة واحدة من البداية إلى النهاية

جلب كل شيء (الترقيم)

قلل المخرجات باستخدام —fields

اكتشف قيم المرشحات الصحيحة

اختر المنظمة الخاصة بك (الإيجار المتعدد)

توفير مفتاح API لـ SDK/المجمع

شغّل استعلام محفوظ أو مخصص

فرز الحادثة بشكل غير تفاعلي

معالجة رمز الخروج في سكريبت

أشكال مخرجات JSON

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

​القواعد الذهبية

​إعداد لمرة واحدة

​تأكد المصادقة قبل القيام بالعمل

​ابحث عن الجلسات الفاشلة أو منخفضة التصنيف

​اقرأ جلسة واحدة من البداية إلى النهاية

​جلب كل شيء (الترقيم)

​قلل المخرجات باستخدام —fields

​اكتشف قيم المرشحات الصحيحة

​اختر المنظمة الخاصة بك (الإيجار المتعدد)

​توفير مفتاح API لـ SDK/المجمع

​شغّل استعلام محفوظ أو مخصص

​فرز الحادثة بشكل غير تفاعلي

​معالجة رمز الخروج في سكريبت

​أشكال مخرجات JSON

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

القواعد الذهبية

إعداد لمرة واحدة

تأكد المصادقة قبل القيام بالعمل

ابحث عن الجلسات الفاشلة أو منخفضة التصنيف

اقرأ جلسة واحدة من البداية إلى النهاية

جلب كل شيء (الترقيم)

قلل المخرجات باستخدام —fields

اكتشف قيم المرشحات الصحيحة

اختر المنظمة الخاصة بك (الإيجار المتعدد)

توفير مفتاح API لـ SDK/المجمع

شغّل استعلام محفوظ أو مخصص

فرز الحادثة بشكل غير تفاعلي

معالجة رمز الخروج في سكريبت

أشكال مخرجات JSON

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