Ricette CLI per gli agenti

Estrai i dati di sessione, evento e valutazione (e attiva rivalutazioni) direttamente da uno script o da un agente di codifica, con JSON pulito su stdout che si collega direttamente a jq. Queste ricette trasformano i dati di Failproof AI Observability in qualcosa che un utente di terminale o un agente di codifica IA (Claude Code, Cursor) può interrogare e automatizzare, senza navigare nella dashboard. I pattern sottostanti sono pronti per il copia-incolla per la CLI di Failproof AI Observability (agenteye). Per l’installazione, l’autenticazione e l’elenco completo delle opzioni, vedi CLI; esegui agenteye -h o agenteye <command> -h per l’aiuto integrato.

Regole d’oro

Le opzioni globali vanno prima del comando. agenteye --json sessions è corretto; agenteye sessions --json no. Le opzioni globali sono --json, --base-url, --org, --token, --insecure/--secure, --timeout, --quiet, --no-color.
Passa --json ogni volta che analizzi l’output. I dati vanno su stdout come JSON; lo stato umano e gli errori vanno su stderr, così stdout rimane pulito per il collegamento a jq.
Rama sul codice di uscita, non sul testo di stderr: 0 ok · 1 errore inaspettato · 2 argomenti non validi · 3 impossibile raggiungere la dashboard · 4 non autenticato o scaduto · 5 permesso mancante · 6 risorsa non trovata.
Scopri con -h. Ogni comando documenta i suoi filtri, i formati di valore e la forma JSON.

Configurazione una tantum

export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com   # così non ripeti --base-url
agenteye login --email you@example.com                       # incolla il codice ricevuto per email; valido ~24h

Conferma l’autenticazione prima di fare lavoro

whoami non dagli mai errori su una sessione mancante o scaduta; riporta invece logged_in:false, così un agente può controllare lo stato dell’autenticazione in sicurezza. (Può comunque uscire con codice non zero se nessun URL di base è impostato o la dashboard non è raggiungibile.)

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

Trova sessioni con errori o punteggi bassi

# sessioni nelle ultime 24h il cui stato di valutazione è errore
agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id'

# valutazioni con punteggio <= 0.5 su utilità, per un agente
agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \
  | jq '.evaluations[] | {session_id, scores}'

Il filtro del punteggio vive su evals, non su sessions. --score KEY:MIN..MAX è ripetibile e combinato con AND; entrambi i limiti sono opzionali (..0.5 significa ≤ 0.5, 0.9.. significa ≥ 0.9). Puoi passare fino a 20 filtri di punteggio per richiesta; di più restituisce HTTP 400. sessions condivide i filtri --env, --status, --agent-id, --session-id e intervallo di tempo con evals, ma non ha --score.

Leggi una sessione da capo a fondo

Non c’è un singolo comando session show. Combina la traccia degli eventi con la valutazione della sessione:

# l'ultima valutazione della sessione (stato + punteggi)
agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}'

# ogni evento nell'esecuzione (aumenta --limit per un controllo completo)
agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}'

# solo le chiamate di strumento in una sessione (--full è richiesto per ottenere il payload grezzo)
agenteye --json events --full --session-id run-001 --event-type tool_use,tool_result --all \
  | jq '.events[].payload'

Nota: Per impostazione predefinita, events legge un feed veloce senza payload. Ogni evento porta un summary di una riga calcolato dal server più flag come is_error e conteggi di token, ma payload ritorna come {}. Per estrarre il payload grezzo, aggiungi --full (o --fields payload). Il feed completo è più lento su larga scala, quindi mantienilo limitato: abbina --full a un singolo --session-id.

Estrai tutto (paginazione)

I risultati sono più recenti in primo piano e paginati con cursore.

# un colpo: estrai fino a 500 righe in pagine di 200 righe
agenteye --json events --session-id run-001 --limit 500 --all > events.json

# paginazione manuale: reinserisci 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"

Riduci l’output con —fields

Limita i tasti (sia nella tabella che in --json) per ridurre quello che un agente deve leggere.

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

I nomi di campo sconosciuti vengono rifiutati (uscita 2) con l’elenco valido, un modo economico per scoprire i nomi dei campi.

Scopri i valori di filtro validi

agenteye --json list envs | jq -r '.values[]'           # valori per --env
agenteye --json list tools | jq -r '.values[]'          # nomi degli strumenti; anche agenti, modelli, event_types, …
agenteye --json list score_filters | jq -r '.values[]'  # KEY valida per --score KEY:MIN..MAX

Scegli la tua org (multi-tenant)

Se appartieni a più di un’org, scegli il tenant attivo al login (viene salvato):

agenteye login --org acme --email you@corp.com   # imposta il tenant nello stesso passaggio del login
agenteye --json orgs list | jq -r '.orgs[].org_slug'
agenteye --org globex --json sessions --since 24h   # sostituisci per un comando

Un login multi-org senza --org esce con codice non zero e stampa le org tra cui scegliere.

Fornisci una chiave API per SDK/collector

# il segreto viene stampato UNA VOLTA, con --json è il campo .key
key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key')
agenteye keys regenerate ci-bot --yes    # ruota; agenteye keys disable ci-bot --yes per revocare

Esegui una query salvata o ad hoc

agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows'
agenteye --json query run errs --arg prod | jq '.rows'   # una query salvata + un $1 posizionale

Triage di un incidente in modo non interattivo

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

Nota: Le mutazioni saltano automaticamente il prompt di conferma sotto --json o quando stdin non è una TTY, così gli agenti non si bloccano mai; passa --yes/-y per saltarlo esplicitamente altrove.

Gestione del codice di uscita in uno script

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

Forme di output JSON

Comando	stdout JSON (con `--json`)
`whoami`	`{"logged_in": true, "id", "email", "is_instance_admin", "active_org", "permissions": [...], "memberships": [...]}` oppure `{"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` mostrata una volta)
`query run`	`{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}`
`users list` / `settings list`	`{"users": [...]}` / `{"settings": [...]}`
`alerts list` / `incidents list`	`{"alerts": [...]}` / `{"incidents": [...]}`
create/update/delete (qualsiasi)	l’oggetto risorsa, oppure `{"deleted": true, "id"}` per i delete
failure (qualsiasi, con `--json`)	`{"error": "...", "exit_code": <n>, "status"?: <http>, "hint"?: "..."}` su stdout

Ogni elemento event (events): id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill. Nota che payload è {} a meno che tu non richieda il feed completo con --full (o --fields payload).
Ogni elemento evaluation (evals): id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at.
Ogni elemento session (sessions): session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation.

Ogni comando --fields accetta esattamente i nomi di campo del suo elemento. L’insieme differisce tra sessions e evals, quindi un nome valido per uno può essere rifiutato dall’altro.

Prossimi passi

CLI: installazione, autenticazione e il riferimento completo delle opzioni per ogni comando.
CLI agent skill: pacchetto queste ricette come una skill che il tuo agente di codifica può caricare.
API keys: crea e delimita le chiavi con cui la CLI, SDK e collector si autenticano.
Python SDK: invia eventi in Failproof AI Observability così c’è dati per queste ricette da interrogare.

Overview

Features

SDK and CLI

Administration

Ricette CLI per gli agenti

Regole d’oro

Configurazione una tantum

Conferma l’autenticazione prima di fare lavoro

Trova sessioni con errori o punteggi bassi

Leggi una sessione da capo a fondo

Estrai tutto (paginazione)

Riduci l’output con —fields

Scopri i valori di filtro validi

Scegli la tua org (multi-tenant)

Fornisci una chiave API per SDK/collector

Esegui una query salvata o ad hoc

Triage di un incidente in modo non interattivo

Gestione del codice di uscita in uno script

Forme di output JSON

Prossimi passi

​Regole d’oro

​Configurazione una tantum

​Conferma l’autenticazione prima di fare lavoro

​Trova sessioni con errori o punteggi bassi

​Leggi una sessione da capo a fondo

​Estrai tutto (paginazione)

​Riduci l’output con —fields

​Scopri i valori di filtro validi

​Scegli la tua org (multi-tenant)

​Fornisci una chiave API per SDK/collector

​Esegui una query salvata o ad hoc

​Triage di un incidente in modo non interattivo

​Gestione del codice di uscita in uno script

​Forme di output JSON

​Prossimi passi

Regole d’oro

Configurazione una tantum

Conferma l’autenticazione prima di fare lavoro

Trova sessioni con errori o punteggi bassi

Leggi una sessione da capo a fondo

Estrai tutto (paginazione)

Riduci l’output con —fields

Scopri i valori di filtro validi

Scegli la tua org (multi-tenant)

Fornisci una chiave API per SDK/collector

Esegui una query salvata o ad hoc

Triage di un incidente in modo non interattivo

Gestione del codice di uscita in uno script

Forme di output JSON

Prossimi passi