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 code, avec du JSON propre sur stdout qui s’enchaîne directement avec jq. Ces recettes transforment les données d’observabilité d’AgentEye en quelque chose qu’un utilisateur de terminal ou un agent de code IA (Claude Code, Cursor) peut interroger et automatiser, sans passer par le tableau de bord. Les patterns ci-dessous sont prêts à copier-coller pour le CLI AgentEye (agenteye). Pour l’installation, l’authentification et la liste complète des options, consultez CLI ; lancez agenteye -h ou agenteye <command> -h pour l’aide intégrée.

Règles d’or

Les options globales se placent avant la commande. agenteye --json sessions est correct ; agenteye sessions --json ne l’est pas. Les options 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 humains et les erreurs vont sur stderr, ce qui permet à stdout de rester propre pour être redirigé vers jq.
Branchez-vous sur le code de sortie, pas sur le texte de stderr : 0 ok · 2 arguments invalides · 3 impossible de joindre le tableau de bord · 4 non connecté ou session expirée · 5 permission manquante.
Explorez avec -h. Chaque commande documente ses filtres, formats de valeurs et structure 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 e-mail ; valable ~24h

Vérifier l’authentification avant d’agir

whoami ne retourne jamais d’erreur pour une session manquante ou expirée ; il rapporte logged_in:false à la place, ce qui permet à un agent de tester l’état d’authentification en toute sécurité. (Il peut quand 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 "Non authentifié. Lancez : agenteye login" >&2; exit 1
fi

Trouver les sessions en échec ou mal notées

# 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’applique à evals, pas à sessions. --score KEY:MIN..MAX est répétable et combiné en AND ; 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à, la réponse est HTTP 400. sessions partage les filtres --env, --status, --agent-id, --session-id et de plage temporelle avec evals, mais n’a pas de --score.

Lire une session de bout en bout

Il n’existe pas de commande unique session show — combinez le journal d’événements avec l’évaluation de la session :

# 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 parcours complet)
agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}'

# uniquement les appels d'outils dans une session
agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all \
  | jq '.events[].payload'

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 seule fois : récupère jusqu'à 500 lignes en pages de 200
agenteye --json events --session-id run-001 --limit 500 --all > events.json

# pagination manuelle : réinjecter 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 valide, un moyen pratique 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éfinir 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   # remplacement pour une seule commande

Une connexion multi-org sans --org sort avec un code non nul et affiche les organisations parmi lesquelles choisir.

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 sauvegardé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 sauvegardée + un $1 positionnel

Gérer un incident sans interaction

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

Les mutations ignorent automatiquement leur invite de confirmation sous --json ou lorsque stdin n’est pas un TTY, de sorte 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 expirée - lancez 'agenteye login'." >&2 ;;
  5) echo "Permission manquante (demandez à un admin evaluations:read)." >&2 ;;
  3) echo "Tableau de bord inaccessible - vérifiez l'URL." >&2 ;;
  *) echo "Erreur inattendue (sortie ${code})." >&2 ;;
esac

Structures de 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 (tous)	l’objet ressource, ou `{"deleted": true, "id"}` pour les suppressions
échec (tous, 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.
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 uniquement 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.

​Règles d’or

​Configuration initiale

​Vérifier l’authentification avant d’agir

​Trouver les sessions en échec ou mal notées

​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 sauvegardée ou ad hoc

​Gérer un incident sans interaction

​Gestion des codes de sortie dans un script

​Structures de sortie JSON