وصفات CLI للوكلاء

اسحب بيانات الجلسة والحدث والتقييم (وشغّل إعادة التقييمات) مباشرة من سكريبت أو وكيل ترميز، مع JSON نظيف على stdout يتم توجيهه مباشرة إلى jq. تحول هذه الوصفات بيانات المراقبة في AgentEye إلى شيء يمكن لمستخدم الطرفية أو وكيل ترميز AI (Claude Code، Cursor) أن يستعلم عنه ويأتمتته، دون الحاجة للنقر عبر لوحة التحكم. الأنماط أدناه جاهزة للنسخ واللصق لـ AgentEye CLI (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 حسنًا · 2 وسائط سيئة · 3 لا يمكن الوصول إلى لوحة التحكم · 4 لم تقم بتسجيل الدخول أو انتهت الجلسة · 5 إذن مفقود.
اكتشف مع -h. كل أمر يوثّق مرشحاته وتنسيقات القيمة وشكل JSON.

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

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

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

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

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

# الجلسات في آخر 24h التي فشل تقييمها
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}'

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

احصل على كل شيء (الترقيم)

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

# لقطة واحدة: احصل على ما يصل إلى 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[]'          # أسماء الأدوات؛ أيضًا وكلاء، نماذج، event_types، إلخ
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.
كل عنصر تقييم (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، لذا قد يتم رفض الاسم الصحيح لأحدهما من قبل الآخر.

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

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

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

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

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

​احصل على كل شيء (الترقيم)

​اختصر الإخراج مع —fields

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

​اختر منظمتك (متعدد المستأجرين)

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

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

​فرز حادثة طارئة بدون تفاعل

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

​أشكال إخراج JSON