Recettes CLI pour agents

Récupérez les données de sessions, d’événements et d’évaluations (et déclenchez des réévaluations) directement depuis un script ou un agent de codage, avec du JSON propre sur stdout qui s’enchaîne directement dans jq. Ces recettes transforment les données de Failproof AI Observability en quelque chose qu’un utilisateur de terminal ou un agent de codage IA (Claude Code, Cursor) peut interroger et automatiser, sans cliquer dans le tableau de bord. Les patterns ci-dessous sont prêts à être copiés-collés pour la CLI Failproof AI Observability (agenteye). Pour l’installation, l’authentification et la liste complète des options, consultez CLI ; exécutez agenteye -h ou agenteye <command> -h pour l’aide intégrée.

Règles d’or

Les options globales vont avant la commande. agenteye --json sessions est correct ; agenteye sessions --json ne l’est pas. Les globales sont --json, --base-url, --org, --token, --insecure/--secure, --timeout, --quiet, --no-color.
Passez --json dès que vous analysez la sortie. Les données vont sur stdout en JSON ; les statuts lisibles par l’humain et les erreurs vont sur stderr, donc stdout reste propre pour être transmis à jq.
Basez-vous sur le code de sortie, pas sur le texte de stderr : 0 ok · 1 erreur inattendue · 2 arguments invalides · 3 tableau de bord inaccessible · 4 non connecté ou session expirée · 5 permission manquante · 6 ressource introuvable.
Explorez avec -h. Chaque commande documente ses filtres, les formats de valeurs et la forme JSON.

Configuration initiale

export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com   # pour ne pas répéter --base-url
agenteye login --email you@example.com                       # collez le code reçu par email ; valable ~24h

Vérifier l’authentification avant de travailler

whoami ne renvoie jamais d’erreur en cas de session manquante ou expirée ; il signale logged_in:false à la place, ce qui permet à un agent de sonder l’état d’authentification en toute sécurité. (Il peut tout de même sortir avec un code non nul si aucune URL de base n’est définie ou si le tableau de bord est inaccessible.)

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

Trouver les sessions en échec ou avec un score bas

# sessions des dernières 24h dont l'évaluation est en erreur
agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id'

# évaluations avec un score helpfulness <= 0.5, pour un agent donné
agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \
  | jq '.evaluations[] | {session_id, scores}'

Le filtrage par score s’effectue sur evals, pas sur sessions. --score KEY:MIN..MAX est répétable et combiné par ET ; chaque borne est optionnelle (..0.5 signifie ≤ 0.5, 0.9.. signifie ≥ 0.9). Vous pouvez passer jusqu’à 20 filtres de score par requête ; au-delà, le serveur renvoie HTTP 400. sessions partage les filtres --env, --status, --agent-id, --session-id et de plage temporelle avec evals, mais ne dispose pas de --score.

Lire une session de bout en bout

Il n’existe pas de commande session show unique. Combinez la trace d’événements avec l’évaluation de la session :

# la dernière évaluation de la session (statut + scores)
agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}'

# tous les événements de l'exécution (augmentez --limit pour un balayage complet)
agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}'

# uniquement les appels d'outils dans une session (--full est requis pour obtenir le payload brut)
agenteye --json events --full --session-id run-001 --event-type tool_use,tool_result --all \
  | jq '.events[].payload'

Note : Par défaut, events lit un flux rapide sans payload. Chaque événement porte un résumé summary calculé côté serveur ainsi que des indicateurs comme is_error et les compteurs de tokens, mais payload est renvoyé sous la forme {}. Pour récupérer le payload brut, ajoutez --full (ou --fields payload). Le flux complet est plus lent à grande échelle, donc limitez-le : associez --full à un seul --session-id.

Tout récupérer (pagination)

Les résultats sont triés du plus récent au plus ancien et paginés par curseur.

# en une fois : récupère jusqu'à 500 lignes par pages de 200
agenteye --json events --session-id run-001 --limit 500 --all > events.json

# pagination manuelle : réinjectez 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"

Réduire la sortie avec —fields

Restreignez les clés (dans le tableau et avec --json) pour limiter ce qu’un agent doit lire.

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

Les noms de champs inconnus sont rejetés (sortie 2) avec la liste des valeurs valides — un moyen simple de découvrir les noms de champs.

Découvrir les valeurs de filtre valides

agenteye --json list envs | jq -r '.values[]'           # valeurs pour --env
agenteye --json list tools | jq -r '.values[]'          # noms d'outils ; aussi agents, models, event_types, …
agenteye --json list score_filters | jq -r '.values[]'  # KEY valide pour --score KEY:MIN..MAX

Choisir son organisation (multi-tenant)

Si vous appartenez à plusieurs organisations, choisissez le tenant actif à la connexion (il est sauvegardé) :

agenteye login --org acme --email you@corp.com   # définit le tenant en même temps que la connexion
agenteye --json orgs list | jq -r '.orgs[].org_slug'
agenteye --org globex --json sessions --since 24h   # remplace pour une seule commande

Une connexion multi-org sans --org se termine avec un code non nul et affiche les organisations disponibles.

Créer une clé API pour le SDK/collecteur

# le secret est affiché UNE SEULE FOIS ; avec --json, c'est le champ .key
key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key')
agenteye keys regenerate ci-bot --yes    # rotation ; agenteye keys disable ci-bot --yes pour révoquer

Exécuter une requête enregistrée ou ad hoc

agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows'
agenteye --json query run errs --arg prod | jq '.rows'   # une requête enregistrée + un $1 positionnel

Traiter un incident de manière non interactive

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

Note : Les mutations ignorent automatiquement leur invite de confirmation sous --json ou quand stdin n’est pas un TTY, afin que les agents ne restent jamais bloqués ; passez --yes/-y pour l’ignorer explicitement ailleurs.

Gestion des codes de sortie dans un 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

Formes de la sortie JSON

Commande	JSON sur stdout (avec `--json`)
`whoami`	`{"logged_in": true, "id", "email", "is_instance_admin", "active_org", "permissions": [...], "memberships": [...]}` ou `{"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` affiché une seule fois)
`query run`	`{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}`
`users list` / `settings list`	`{"users": [...]}` / `{"settings": [...]}`
`alerts list` / `incidents list`	`{"alerts": [...]}` / `{"incidents": [...]}`
create/update/delete (toute commande)	l’objet ressource, ou `{"deleted": true, "id"}` pour les suppressions
échec (toute commande, avec `--json`)	`{"error": "...", "exit_code": <n>, "status"?: <http>, "hint"?: "..."}` sur stdout

Chaque élément event (events) : id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill. Notez que payload vaut {} sauf si vous demandez le flux complet avec --full (ou --fields payload).
Chaque élément evaluation (evals) : id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at.
Chaque élément session (sessions) : session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation.

Le --fields de chaque commande accepte exactement les noms de champs de ses propres éléments. L’ensemble diffère entre sessions et evals, donc un nom valide pour l’un peut être rejeté par l’autre.

Étapes suivantes

CLI : installation, authentification et référence complète des options pour chaque commande.
Compétence CLI pour agent : regroupez ces recettes en une compétence que votre agent de codage peut charger.
Clés API : créez et délimitez les clés avec lesquelles la CLI, le SDK et le collecteur s’authentifient.
SDK Python : envoyez des événements dans Failproof AI Observability pour que ces recettes aient des données à interroger.

Overview

Features

SDK and CLI

Administration

Recettes CLI pour agents

Règles d’or

Configuration initiale

Vérifier l’authentification avant de travailler

Trouver les sessions en échec ou avec un score bas

Lire une session de bout en bout

Réduire la sortie avec —fields

Découvrir les valeurs de filtre valides

Choisir son organisation (multi-tenant)

Créer une clé API pour le SDK/collecteur

Exécuter une requête enregistrée ou ad hoc

Traiter un incident de manière non interactive

Gestion des codes de sortie dans un script

Formes de la sortie JSON

Étapes suivantes

​Règles d’or

​Configuration initiale

​Vérifier l’authentification avant de travailler

​Trouver les sessions en échec ou avec un score bas

​Lire une session de bout en bout

​Tout récupérer (pagination)

​Réduire la sortie avec —fields

​Découvrir les valeurs de filtre valides

​Choisir son organisation (multi-tenant)

​Créer une clé API pour le SDK/collecteur

​Exécuter une requête enregistrée ou ad hoc

​Traiter un incident de manière non interactive

​Gestion des codes de sortie dans un script

​Formes de la sortie JSON

​Étapes suivantes

Règles d’or

Configuration initiale

Vérifier l’authentification avant de travailler

Trouver les sessions en échec ou avec un score bas

Lire une session de bout en bout

Tout récupérer (pagination)

Réduire la sortie avec —fields

Découvrir les valeurs de filtre valides

Choisir son organisation (multi-tenant)

Créer une clé API pour le SDK/collecteur

Exécuter une requête enregistrée ou ad hoc

Traiter un incident de manière non interactive

Gestion des codes de sortie dans un script

Formes de la sortie JSON

Étapes suivantes