CLI-Rezepte für Agenten

Sitzungs-, Ereignis- und Auswertungsdaten direkt aus einem Skript oder Coding-Agenten abrufen (und Neu-Auswertungen auslösen) – mit sauberem JSON auf stdout, das sich direkt in jq pipen lässt. Diese Rezepte verwandeln die Daten von Failproof AI Observability in etwas, das ein Terminal-Nutzer oder ein KI-Coding-Agent (Claude Code, Cursor) abfragen und automatisieren kann, ohne das Dashboard anzuklicken. Die folgenden Muster sind kopierfertig für die Failproof AI Observability CLI (agenteye). Für Installation, Authentifizierung und die vollständige Optionsliste siehe CLI; führe agenteye -h oder agenteye <command> -h für die eingebaute Hilfe aus.

Grundregeln

Globale Optionen stehen vor dem Befehl. agenteye --json sessions ist korrekt; agenteye sessions --json nicht. Die globalen Optionen sind --json, --base-url, --org, --token, --insecure/--secure, --timeout, --quiet, --no-color.
--json angeben, wenn die Ausgabe geparst wird. Daten gehen als JSON an stdout; menschlesbare Statusmeldungen und Fehler gehen an stderr, damit stdout sauber in jq gepipt werden kann.
Auf den Exit-Code verzweigen, nicht auf stderr-Text: 0 OK · 1 unerwarteter Fehler · 2 fehlerhafte Argumente · 3 Dashboard nicht erreichbar · 4 nicht angemeldet oder abgelaufen · 5 fehlende Berechtigung · 6 Ressource nicht gefunden.
Mit -h erkunden. Jeder Befehl dokumentiert seine Filter, Wertformate und JSON-Struktur.

Einmalige Einrichtung

export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com   # damit --base-url nicht wiederholt werden muss
agenteye login --email you@example.com                       # Code aus der E-Mail einfügen; gültig ca. 24h

Auth vor der Arbeit bestätigen

whoami gibt bei einer fehlenden oder abgelaufenen Sitzung keinen Fehler aus, sondern meldet logged_in:false – ein Agent kann den Auth-Status daher sicher abfragen. (Es kann dennoch mit einem Nicht-null-Exit-Code enden, wenn keine Base-URL gesetzt ist oder das Dashboard nicht erreichbar ist.)

if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then
  echo "Nicht authentifiziert. Ausführen: agenteye login" >&2; exit 1
fi

Fehlgeschlagene oder niedrig bewertete Sitzungen finden

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

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

Score-Filterung erfolgt über evals, nicht über sessions. --score KEY:MIN..MAX ist wiederholbar und wird 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 Zeitbereichsfilter mit evals, hat aber kein --score.

Eine Sitzung von Anfang bis Ende lesen

Es gibt keinen einzelnen session show-Befehl. Kombinierre den Ereignisverlauf mit der Auswertung der Sitzung:

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

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

# nur die Tool-Aufrufe in einer Sitzung (--full ist erforderlich, um den rohen Payload zu erhalten)
agenteye --json events --full --session-id run-001 --event-type tool_use,tool_result --all \
  | jq '.events[].payload'

Hinweis: Standardmäßig liest events einen schnellen Feed ohne Payload. Jedes Ereignis enthält eine server-berechnete einzeilige summary sowie Flags wie is_error und Token-Zählungen, aber payload wird als {} zurückgegeben. Um den rohen Payload abzurufen, --full (oder --fields payload) hinzufügen. Der vollständige Feed ist bei großen Datenmengen langsamer – daher begrenzt halten: --full mit einer einzelnen --session-id kombinieren.

Alles abrufen (Paginierung)

Ergebnisse sind neueste-zuerst und cursor-paginiert.

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

# manuelles Paging: next_cursor zurückspeisen
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 reduzieren

Schlüssel (sowohl in der Tabelle als auch mit --json) einschränken, um das 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) mit der Liste gültiger Namen – eine einfache Methode, um Feldnamen zu entdecken.

Gültige Filterwerte erkunden

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ültige KEY für --score KEY:MIN..MAX

Organisation auswählen (Multi-Tenant)

Wenn mehrere Organisationen vorhanden sind, beim Login den aktiven Tenant wählen (wird gespeichert):

agenteye login --org acme --email you@corp.com   # Tenant 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 Nicht-null-Exit-Code und gibt die verfügbaren Organisationen aus.

API-Key für das SDK/den Collector bereitstellen

# Das Secret wird EINMAL 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

Hinweis: Mutationen überspringen ihre Bestätigungsaufforderung automatisch unter --json oder wenn stdin kein TTY ist, damit Agenten nie hängen bleiben; --yes/-y übergeben, 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 "Sitzung abgelaufen - 'agenteye login' ausführen." >&2 ;;
  5) echo "Fehlende Berechtigung (Administrator um evaluations:read bitten)." >&2 ;;
  3) echo "Dashboard nicht erreichbar - URL prüfen." >&2 ;;
  *) echo "Unerwarteter Fehler (Exit ${code})." >&2 ;;
esac

JSON-Ausgabeformate

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` 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öschungen
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, summary, is_error, error_type, output_tokens, context_window, context_fill. Hinweis: payload ist {}, außer der vollständige Feed wird mit --full (oder --fields payload) angefordert.
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 seines eigenen Elements. Der Satz unterscheidet sich zwischen sessions und evals, daher kann ein für eines gültiger Name vom anderen abgelehnt werden.

Nächste Schritte

CLI: Installation, Authentifizierung und die vollständige Optionsreferenz für jeden Befehl.
CLI-Agenten-Skill: Diese Rezepte als Skill verpacken, den dein Coding-Agent laden kann.
API-Keys: Keys erstellen und einschränken, mit denen sich CLI, SDK und Collector authentifizieren.
Python SDK: Ereignisse in Failproof AI Observability senden, damit diese Rezepte Daten zum Abfragen haben.

Overview

Features

SDK and CLI

Administration

CLI-Rezepte für Agenten

Grundregeln

Einmalige Einrichtung

Auth vor der Arbeit bestätigen

Fehlgeschlagene oder niedrig bewertete Sitzungen finden

Eine Sitzung von Anfang bis Ende lesen

Alles abrufen (Paginierung)

Ausgabe mit —fields reduzieren

Gültige Filterwerte erkunden

Organisation auswählen (Multi-Tenant)

API-Key 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-Ausgabeformate

Nächste Schritte

​Grundregeln

​Einmalige Einrichtung

​Auth vor der Arbeit bestätigen

​Fehlgeschlagene oder niedrig bewertete Sitzungen finden

​Eine Sitzung von Anfang bis Ende lesen

​Alles abrufen (Paginierung)

​Ausgabe mit —fields reduzieren

​Gültige Filterwerte erkunden

​Organisation auswählen (Multi-Tenant)

​API-Key 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-Ausgabeformate

​Nächste Schritte

Grundregeln

Einmalige Einrichtung

Auth vor der Arbeit bestätigen

Fehlgeschlagene oder niedrig bewertete Sitzungen finden

Eine Sitzung von Anfang bis Ende lesen

Alles abrufen (Paginierung)

Ausgabe mit —fields reduzieren

Gültige Filterwerte erkunden

Organisation auswählen (Multi-Tenant)

API-Key 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-Ausgabeformate

Nächste Schritte