CLI-Rezepte für Agenten

Sitzungs-, Ereignis- und Evaluierungsdaten direkt aus einem Skript oder Coding-Agenten abrufen (und Neubewertungen auslösen) – mit sauberem JSON auf stdout, das sich direkt in jq pipen lässt. Diese Rezepte machen AgentEyes Observability-Daten für Terminal-Nutzer oder KI-Coding-Agenten (Claude Code, Cursor) abfragbar und automatisierbar, ohne durch das Dashboard zu klicken. Die folgenden Muster sind kopierbereit für die AgentEye CLI (agenteye). Informationen zur Installation, Authentifizierung und der vollständigen Optionsliste findest du unter CLI; führe agenteye -h oder agenteye <command> -h für die eingebaute Hilfe aus.

Grundregeln

Globale Optionen kommen vor dem Befehl. agenteye --json sessions ist korrekt; agenteye sessions --json ist es nicht. Die globalen Optionen sind --json, --base-url, --org, --token, --insecure/--secure, --timeout, --quiet, --no-color.
--json übergeben, wenn du die Ausgabe parst. Daten gehen als JSON an stdout; menschenlesbare Status- und Fehlermeldungen gehen an stderr, sodass stdout sauber in jq gepipet werden kann.
Verzweige anhand des Exit-Codes, nicht anhand des stderr-Texts: 0 ok · 2 ungültige Argumente · 3 Dashboard nicht erreichbar · 4 nicht eingeloggt oder abgelaufen · 5 fehlende Berechtigung.
Mit -h erkunden. Jeder Befehl dokumentiert seine Filter, Wertformate und die JSON-Struktur.

Einmalige Einrichtung

export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com   # damit du --base-url nicht wiederholen musst
agenteye login --email you@example.com                       # per E-Mail gesendeten Code einfügen; gültig ~24h

Auth prüfen, bevor Arbeit erledigt wird

whoami gibt bei einer fehlenden oder abgelaufenen Sitzung keinen Fehler aus; stattdessen meldet es logged_in:false, sodass ein Agent den Auth-Status sicher abfragen kann. (Es kann trotzdem mit einem Exit-Code ungleich null enden, wenn keine Basis-URL gesetzt oder das Dashboard nicht erreichbar ist.)

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

Fehlgeschlagene oder niedrig bewertete Sitzungen finden

# Sitzungen der letzten 24h, deren Evaluierung fehlgeschlagen ist
agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id'

# Evaluierungen mit <= 0.5 bei Hilfsbereitschaft, für einen Agenten
agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \
  | jq '.evaluations[] | {session_id, scores}'

Score-Filterung liegt bei evals, nicht bei sessions. --score KEY:MIN..MAX ist wiederholbar und wird mit UND verknüpft; beide Grenzen sind optional (..0.5 bedeutet ≤ 0,5; 0.9.. bedeutet ≥ 0,9). Pro Anfrage können bis zu 20 Score-Filter übergeben werden; mehr ergibt HTTP 400. sessions teilt die Filter --env, --status, --agent-id, --session-id und Zeitbereich mit evals, hat aber kein --score.

Eine Sitzung von Anfang bis Ende lesen

Es gibt keinen einzelnen Befehl session show – kombiniere den Ereignisverlauf mit der Evaluierung der Sitzung:

# die neueste Evaluierung der Sitzung (Status + Scores)
agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}'

# alle Ereignisse im Durchlauf (--limit für einen vollständigen Sweep erhöhen)
agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}'

# nur die Tool-Aufrufe in einer Sitzung
agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all \
  | jq '.events[].payload'

Alles abrufen (Paginierung)

Ergebnisse sind neueste zuerst und cursor-paginiert.

# Einmalig: bis zu 500 Zeilen in 200-Zeilen-Seiten abrufen
agenteye --json events --session-id run-001 --limit 500 --all > events.json

# Manuelles Blättern: next_cursor zurückführen
page=$(agenteye --json events --limit 100)
cursor=$(echo "$page" | jq -r '.next_cursor // empty')
[ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor"

Ausgabe mit —fields einschränken

Schlüssel (sowohl in der Tabelle als auch bei --json) einschränken, um zu reduzieren, was ein Agent lesen muss.

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

Unbekannte Feldnamen werden abgelehnt (Exit 2) und die gültige Liste wird ausgegeben – eine einfache Methode, um Feldnamen zu erkunden.

Gültige Filterwerte entdecken

agenteye --json list envs | jq -r '.values[]'           # Werte für --env
agenteye --json list tools | jq -r '.values[]'          # Tool-Namen; auch agents, models, event_types, …
agenteye --json list score_filters | jq -r '.values[]'  # gültiger KEY für --score KEY:MIN..MAX

Organisation auswählen (Multi-Tenant)

Wenn du mehr als einer Organisation angehörst, wähle den aktiven Mandanten beim Login (er wird gespeichert):

agenteye login --org acme --email you@corp.com   # Mandant im selben Schritt wie Login setzen
agenteye --json orgs list | jq -r '.orgs[].org_slug'
agenteye --org globex --json sessions --since 24h   # für einen Befehl überschreiben

Ein Multi-Org-Login ohne --org endet mit einem Exit-Code ungleich null und gibt die zur Auswahl stehenden Organisationen aus.

API-Schlüssel für das SDK/den Collector bereitstellen

# Das Secret wird EINMALIG ausgegeben — mit --json ist es das .key-Feld
key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key')
agenteye keys regenerate ci-bot --yes    # rotieren; agenteye keys disable ci-bot --yes zum Widerrufen

Eine gespeicherte oder Ad-hoc-Abfrage ausführen

agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows'
agenteye --json query run errs --arg prod | jq '.rows'   # eine gespeicherte Abfrage + ein positionaler $1

Einen Vorfall nicht-interaktiv triagieren

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

Mutationen überspringen ihre Bestätigungsabfrage automatisch bei --json oder wenn stdin kein TTY ist, sodass Agenten nie hängen bleiben; übergib --yes/-y, um sie anderswo explizit zu überspringen.

Exit-Code-Behandlung in einem Skript

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-Ausgabestrukturen

Befehl	stdout JSON (mit `--json`)
`whoami`	`{"logged_in": true, "id", "email", "is_instance_admin", "active_org", "permissions": [...], "memberships": [...]}` oder `{"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` wird einmalig angezeigt)
`query run`	`{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}`
`users list` / `settings list`	`{"users": [...]}` / `{"settings": [...]}`
`alerts list` / `incidents list`	`{"alerts": [...]}` / `{"incidents": [...]}`
create/update/delete (beliebig)	das Ressourcenobjekt oder `{"deleted": true, "id"}` bei Löschvorgängen
Fehler (beliebig, mit `--json`)	`{"error": "...", "exit_code": <n>, "status"?: <http>, "hint"?: "..."}` auf stdout

Jedes event-Element (events): id, session_id, agent_id, event_type, ts, payload, environment.
Jedes evaluation-Element (evals): id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at.
Jedes session-Element (sessions): session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation.

Das --fields-Argument jedes Befehls akzeptiert genau die Feldnamen des jeweiligen Elements – der Satz unterscheidet sich zwischen sessions und evals, sodass ein für eines gültiger Name vom anderen abgelehnt werden kann.

​Grundregeln

​Einmalige Einrichtung

​Auth prüfen, bevor Arbeit erledigt wird

​Fehlgeschlagene oder niedrig bewertete Sitzungen finden

​Eine Sitzung von Anfang bis Ende lesen

​Alles abrufen (Paginierung)

​Ausgabe mit —fields einschränken

​Gültige Filterwerte entdecken

​Organisation auswählen (Multi-Tenant)

​API-Schlüssel für das SDK/den Collector bereitstellen

​Eine gespeicherte oder Ad-hoc-Abfrage ausführen

​Einen Vorfall nicht-interaktiv triagieren

​Exit-Code-Behandlung in einem Skript

​JSON-Ausgabestrukturen