Ajanlar için CLI tarifleri

Oturum, etkinlik ve değerlendirme verilerini (ve yeniden değerlendirmeleri tetikle) doğrudan bir betik veya kodlama ajanından çek. Çıktı olarak temiz JSON sağla ve doğrudan jq içine yönlendir. Bu tarifler, AgentEye’ın gözlemlenebilirlik verilerini, terminal kullanıcısı veya bir AI kodlama ajanı (Claude Code, Cursor) tarafından sorgulanabilir ve otomatikleştirilebilir hale getirir — pano aracılığıyla tıklamaya gerek kalmadan. Aşağıdaki desenler AgentEye CLI (agenteye) için kopya-yapıştır şeklinde hazırdır. Kurulum, kimlik doğrulama ve tam seçenek listesi için CLI bölümüne bakın; yerleşik yardım için agenteye -h veya agenteye <command> -h komutlarını çalıştırın.

Altın kurallar

Genel seçenekler komuttan önce gelir. agenteye --json sessions doğru; agenteye sessions --json değildir. Genel seçenekler şunlardır: --json, --base-url, --org, --token, --insecure/--secure, --timeout, --quiet, --no-color.
Çıktıyı ayrıştırırken her zaman --json geçirin. Veriler stdout olarak JSON formatında gider; insan durum ve hatalar stderr bölümüne gider, böylece stdout jq içine yönlendirilmek için temiz kalır.
Çıkış koduna göre dallanın, stderr metniyle değil: 0 tamam · 2 hatalı bağımsız değişkenler · 3 panoya ulaşamıyorum · 4 giriş yapılmamış veya süresi dolmuş · 5 izin eksik.
-h ile keşfet. Her komut filtrelerini, değer biçimlerini ve JSON şeklini belgeler.

Tek seferlik kurulum

export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com   # --base-url'i tekrar yazmamanız için
agenteye login --email you@example.com                       # e-postayla gelen kodu yapıştırın; ~24s geçerli

İş yapmadan önce kimlik doğrulamayı onaylayın

whoami hiçbir zaman eksik veya süresi dolmuş oturumda hata vermez; bunun yerine logged_in:false rapor eder, böylece bir ajan kimlik doğrulama durumunu güvenli bir şekilde araştırabilir. (Temel URL ayarlanmamışsa veya pano erişilemezse hala sıfırdan farklı çıkış yapabilir.)

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

Başarısız veya düşük puan alan oturumları bul

# son 24 saatte değerlendirmesi hata veren oturumlar
agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id'

# yardımcılık konusunda <= 0.5 puan alan değerlendirmeler, bir ajan için
agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \
  | jq '.evaluations[] | {session_id, scores}'

Puan filtreleme evals konumunda yaşar, sessions değildir. --score KEY:MIN..MAX tekrarlanabilir ve VE-birleştirilmiştir; her iki sınır da isteğe bağlıdır (..0.5 anlamı ≤ 0.5, 0.9.. anlamı ≥ 0.9). İstek başına en fazla 20 puan filtresi geçebilirsiniz; daha fazlası HTTP 400 döndürür. sessions, evals ile --env, --status, --agent-id, --session-id ve zaman aralığı filtrelerini paylaşır, ancak --score yoktur.

Bir oturumu baştan sona oku

Tek bir session show komutu yok — etkinlik izini oturumun değerlendirmesiyle birleştir:

# oturumun en son değerlendirmesi (durum + puanlar)
agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}'

# çalıştırmadaki her etkinlik (tam tarama için --limit artır)
agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}'

# yalnızca oturumdaki araç çağrıları
agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all \
  | jq '.events[].payload'

Her şeyi getir (sayfalama)

Sonuçlar en yeniden itibaren ve imleç-sayfalanmıştır.

# tek atış: 200 satır sayfasında 500 satıra kadar getir
agenteye --json events --session-id run-001 --limit 500 --all > events.json

# manuel sayfalama: sonraki_imleç geri aktar
page=$(agenteye --json events --limit 100)
cursor=$(echo "$page" | jq -r '.next_cursor // empty')
[ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor"

Çıktıyı —fields ile daralt

Bir ajanın okuması gereken şeyi azaltmak için (tablo ve --json içinde) anahtarları kısıtla.

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

Bilinmeyen alan adları reddedilir (çıkış 2) geçerli listeyle birlikte, alan adlarını keşfetmenin ucuz bir yolu.

Geçerli filtre değerlerini keşfet

agenteye --json list envs | jq -r '.values[]'           # --env değerleri
agenteye --json list tools | jq -r '.values[]'          # araç adları; ayrıca ajanlar, modeller, event_types, …
agenteye --json list score_filters | jq -r '.values[]'  # --score KEY:MIN..MAX için geçerli ANAHTAR

Kuruluşunuzu seçin (çok kiracılı)

Birden fazla kuruluşa aitseniz, etkin kiracıyı giriş sırasında seçin (kaydedilir):

agenteye login --org acme --email you@corp.com   # giriş ile aynı adımda kiracıyı ayarla
agenteye --json orgs list | jq -r '.orgs[].org_slug'
agenteye --org globex --json sessions --since 24h   # bir komut için geçersiz kıl

--org olmayan çok kuruluşlu giriş sıfırdan farklı çıkış yapar ve seçilecek kuruluşları yazdırır.

SDK/toplayıcı için bir API anahtarı sağla

# gizli dizi BİR KERE yazdırılır — --json ile .key alanı
key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key')
agenteye keys regenerate ci-bot --yes    # döndür; iptal etmek için agenteye keys disable ci-bot --yes

Kaydedilmiş veya geçici bir sorguyu çalıştır

agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows'
agenteye --json query run errs --arg prod | jq '.rows'   # kaydedilmiş bir sorgu + konumsal $1

Bir olayı etkileşimsiz olarak değerlendir

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

Değişimler --json altında veya stdin bir TTY olmadığında onay istemini otomatik olarak atlar, böylece ajanlar asla takılmaz; açık olarak başka yerlerde atlamak için --yes/-y geçirin.

Bir betikteki çıkış kodu işleme

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 çıkış şekilleri

Komut	stdout JSON (`--json` ile)
`whoami`	`{"logged_in": true, "id", "email", "is_instance_admin", "active_org", "permissions": [...], "memberships": [...]}` veya `{"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` bir kez gösteriliyor)
`query run`	`{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}`
`users list` / `settings list`	`{"users": [...]}` / `{"settings": [...]}`
`alerts list` / `incidents list`	`{"alerts": [...]}` / `{"incidents": [...]}`
oluştur/güncelle/sil (herhangi biri)	kaynak nesnesi veya silmeler için `{"deleted": true, "id"}`
başarısızlık (herhangi biri, `--json` ile)	stdout üzerinde `{"error": "...", "exit_code": <n>, "status"?: <http>, "hint"?: "..."}`

Her etkinlik öğesi (events): id, session_id, agent_id, event_type, ts, payload, environment.
Her değerlendirme öğesi (evals): id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at.
Her oturum öğesi (sessions): session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation.

Her komutun --fields tam olarak kendi öğesinin alan adlarını kabul eder — set sessions ve evals arasında farklıdır, bu nedenle biri için geçerli olan ad diğeri tarafından reddedilebilir.

​Altın kurallar

​Tek seferlik kurulum

​İş yapmadan önce kimlik doğrulamayı onaylayın

​Başarısız veya düşük puan alan oturumları bul

​Bir oturumu baştan sona oku

​Her şeyi getir (sayfalama)

​Çıktıyı —fields ile daralt

​Geçerli filtre değerlerini keşfet

​Kuruluşunuzu seçin (çok kiracılı)

​SDK/toplayıcı için bir API anahtarı sağla

​Kaydedilmiş veya geçici bir sorguyu çalıştır

​Bir olayı etkileşimsiz olarak değerlendir

​Bir betikteki çıkış kodu işleme

​JSON çıkış şekilleri