Ajanlar için CLI tarifleri

Oturum, olay ve değerlendirme verilerini (ve yeniden değerlendirmeleri tetikleyin) doğrudan bir betikten veya kodlama ajanından çekin, stdout’a temiz JSON çıkışı ile jq’ya doğrudan aktarılan veriler. Bu tarifler Failproof AI Observability’nin verilerini terminal kullanıcısı veya bir AI kodlama ajandan (Claude Code, Cursor) sorgulanabilir ve otomatikleştirilebilir şeye dönüştürür, pano üzerinde tıklama yapmanız gerekmeden. Aşağıdaki desenleri Failproof AI Observability CLI’sı (agenteye) için copy-paste olarak kullanabilirsiniz. Kurulum, kimlik doğrulama ve tam seçenek listesi için bkz. CLI; yerleşik yardım için agenteye -h veya agenteye <command> -h komutunu çalıştırın.

Altın kurallar

Global seçenekler komuttan öncesine gelir. agenteye --json sessions doğrudur; agenteye sessions --json değildir. Global seçenekler şunlardır: --json, --base-url, --org, --token, --insecure/--secure, --timeout, --quiet, --no-color.
Çıktıyı ayrıştırırken --json geçirin. Veriler stdout’a JSON olarak gider; insan durumu ve hatalar stderr’e gider, bu nedenle stdout jq’ya aktarılmak üzere temiz kalır.
Exit kodu üzerinden branch yapın, stderr metni üzerinden değil: 0 tamam · 1 beklenmeyen hata · 2 hatalı argümanlar · 3 panoya ulaşılamıyor · 4 oturum açılmamış veya süresi dolmuş · 5 izin eksik · 6 kaynak bulunamadı.
-h ile keşfedin. Her komut filtrelerini, değer biçimlerini ve JSON şeklini belgeler.

Tek seferlik kurulum

export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com   # böylece --base-url tekrarlamayın
agenteye login --email you@example.com                       # emaille gelen kodu yapıştırın; ~24s geçerli

İşe başlamadan önce kimlik doğrulamayı onaylayın

whoami eksik veya süresi dolmuş oturumda hiçbir zaman hata vermez; bunun yerine logged_in:false raporlar, bu nedenle bir ajan auth durumunu güvenli bir şekilde araştırabilir. (Base URL ayarlanmamışsa veya pano erişilemezse yine de sıfır olmayan bir şekilde çıkabilir.)

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 puanlı oturumları bulun

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

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

Puan filtreleme evals üzerinde canlıdır, sessions üzerinde değil. --score KEY:MIN..MAX tekrarlanabilir ve AND-birleştirilmiş; 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 20’ye kadar puan filtresi geçirebilirsiniz; 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’a sahip değildir.

Bir oturumu baştan sona okuyun

Tek bir session show komutu yoktur. Olay kaydını oturumun değerlendirmesiyle birleştirin:

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

# çalıştırmada her olay (tam bir gezinti için --limit yükseltin)
agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}'

# bir oturumdaki yalnızca araç çağrıları (ham yükü almak için --full gereklidir)
agenteye --json events --full --session-id run-001 --event-type tool_use,tool_result --all \
  | jq '.events[].payload'

Not: Varsayılan olarak, events hızlı, yüksüz bir akış okur. Her olay sunucu tarafından hesaplanan tek satırlık bir summary ve is_error ve belirteç sayıları gibi bayraklar taşır, ancak payload {} olarak geri gelir. Ham yükü çekmek için --full (veya --fields payload) ekleyin. Tam akış ölçekte daha yavaştır, bu nedenle onu sınırlandırılmış tutun: --full ile tek bir --session-id eşleyin.

Tümünü getir (sayfalandırma)

Sonuçlar yeniden başlayan ve imleç sayfalandırılmıştır.

# bir kez: 200 satırlık sayfalarda 500 satıra kadar getir
agenteye --json events --session-id run-001 --limit 500 --all > events.json

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

`--fields` ile çıktıyı azalt

Anahtarları kısıtlayın (hem tabloda hem de --json’da) bir ajanın okuması gereken şeyi azaltmak için.

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ı 2 çıkışı (exit) ile reddedilir ve geçerli listesi vardır, alan adlarını keşfetmenin ucuz bir yoludur.

Geçerli filtre değerlerini keşfedin

agenteye --json list envs | jq -r '.values[]'           # --env için değerler
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 KEY

Org’unuzu seçin (çok kiracılı)

Birden fazla org’a aitse, login sırasında etkin kiracıyı seçin (kaydedilir):

agenteye login --org acme --email you@corp.com   # login 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 org login sıfır olmayan bir değerle çıkar ve seçilebilecek org’ları yazdırır.

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

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

Kaydedilmiş veya geçici bir sorgu çalıştırın

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

Etkileşimsiz bir olayı ayıkla

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

Not: Mutasyonlar --json altında veya stdin bir TTY olmadığında onay istemini otomatik olarak atlar, bu nedenle ajanlar asla takılmaz; başka yerlerde açıkça atlamak için --yes/-y geçirin.

Bir betikte exit-code 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österilir)
`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)	kaynak nesnesi, veya silmeler için `{"deleted": true, "id"}`
başarısızlık (herhangi, `--json` ile)	`{"error": "...", "exit_code": <n>, "status"?: <http>, "hint"?: "..."}` stdout’da

Her olay öğesi (events): id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill. payload’ın --full (veya --fields payload) ile tam akışı istememedikçe {} olduğuna dikkat edin.
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 birisi için geçerli bir ad diğeri tarafından reddedilebilir.

Sonraki adımlar

CLI: kurulum, kimlik doğrulama ve her komut için tam seçenek başvurusu.
CLI ajan becerisi: bu tarifleri kodlama ajanınızın yükleyebileceği bir beceri olarak paketleyin.
API anahtarları: CLI, SDK ve toplayıcının kimlik doğrulaması yaptığı anahtarları oluşturun ve kapsamlayın.
Python SDK: Failproof AI Observability’ye olaylar gönderin, böylece bu tarifler tarafından sorgulanacak veriler olur.

Overview

Features

SDK and CLI

Administration

Ajanlar için CLI tarifleri

Altın kurallar

Tek seferlik kurulum

İşe başlamadan önce kimlik doğrulamayı onaylayın

Başarısız veya düşük puanlı oturumları bulun

Bir oturumu baştan sona okuyun

Tümünü getir (sayfalandırma)

`--fields` ile çıktıyı azalt

Geçerli filtre değerlerini keşfedin

Org’unuzu seçin (çok kiracılı)

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

Kaydedilmiş veya geçici bir sorgu çalıştırın

Etkileşimsiz bir olayı ayıkla

Bir betikte exit-code işleme

JSON çıkış şekilleri

Sonraki adımlar

​Altın kurallar

​Tek seferlik kurulum

​İşe başlamadan önce kimlik doğrulamayı onaylayın

​Başarısız veya düşük puanlı oturumları bulun

​Bir oturumu baştan sona okuyun

​Tümünü getir (sayfalandırma)

​--fields ile çıktıyı azalt

​Geçerli filtre değerlerini keşfedin

​Org’unuzu seçin (çok kiracılı)

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

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

​Etkileşimsiz bir olayı ayıkla

​Bir betikte exit-code işleme

​JSON çıkış şekilleri

​Sonraki adımlar

Altın kurallar

Tek seferlik kurulum

İşe başlamadan önce kimlik doğrulamayı onaylayın

Başarısız veya düşük puanlı oturumları bulun

Bir oturumu baştan sona okuyun

Tümünü getir (sayfalandırma)

`--fields` ile çıktıyı azalt

Geçerli filtre değerlerini keşfedin

Org’unuzu seçin (çok kiracılı)

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

Kaydedilmiş veya geçici bir sorgu çalıştırın

Etkileşimsiz bir olayı ayıkla

Bir betikte exit-code işleme

JSON çıkış şekilleri

Sonraki adımlar