Recetas de CLI para agentes

Extrae datos de sesiones, eventos y evaluaciones (y dispara reevaluaciones) directamente desde un script o agente de código, con JSON limpio en stdout que se puede redirigir a jq. Estas recetas convierten los datos de Failproof AI Observability en algo que un usuario de terminal o un agente de código de IA (Claude Code, Cursor) puede consultar y automatizar, sin necesidad de navegar por el panel. Los patrones que se muestran a continuación están listos para copiar y pegar en la CLI de Failproof AI Observability (agenteye). Para la instalación, autenticación y la lista completa de opciones, consulta CLI; ejecuta agenteye -h o agenteye <command> -h para ver la ayuda integrada.

Reglas de oro

Las opciones globales van antes del comando. agenteye --json sessions es correcto; agenteye sessions --json no lo es. Las opciones globales son --json, --base-url, --org, --token, --insecure/--secure, --timeout, --quiet, --no-color.
Usa --json siempre que vayas a parsear la salida. Los datos van a stdout como JSON; los mensajes de estado e errores van a stderr, por lo que stdout permanece limpio para redirigir a jq.
Ramifica según el código de salida, no según el texto de stderr: 0 correcto · 1 error inesperado · 2 argumentos incorrectos · 3 no se puede conectar al panel · 4 no autenticado o sesión expirada · 5 permiso insuficiente · 6 recurso no encontrado.
Explora con -h. Cada comando documenta sus filtros, formatos de valores y estructura JSON.

Configuración inicial

export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com   # para no repetir --base-url
agenteye login --email you@example.com                       # pega el código recibido por email; válido ~24h

Verifica la autenticación antes de trabajar

whoami nunca falla por una sesión ausente o expirada; en su lugar reporta logged_in:false, por lo que un agente puede verificar el estado de autenticación de forma segura. (Puede seguir saliendo con código distinto de cero si no hay URL base configurada o el panel no está accesible.)

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

Busca sesiones fallidas o con puntuación baja

# sesiones de las últimas 24h cuya evaluación tuvo error
agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id'

# evaluaciones con puntuación <= 0.5 en helpfulness, para un agente concreto
agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \
  | jq '.evaluations[] | {session_id, scores}'

El filtrado por puntuación está en evals, no en sessions. --score KEY:MIN..MAX es repetible y se combina con AND; cualquiera de los límites es opcional (..0.5 significa ≤ 0.5, 0.9.. significa ≥ 0.9). Puedes pasar hasta 20 filtros de puntuación por solicitud; más devuelve HTTP 400. sessions comparte los filtros --env, --status, --agent-id, --session-id y de rango temporal con evals, pero no tiene --score.

Lee una sesión completa de principio a fin

No existe un único comando session show. Combina el registro de eventos con la evaluación de la sesión:

# la evaluación más reciente de la sesión (estado + puntuaciones)
agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}'

# todos los eventos de la ejecución (aumenta --limit para un barrido completo)
agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}'

# solo las llamadas a herramientas de una sesión (--full es necesario para obtener el payload bruto)
agenteye --json events --full --session-id run-001 --event-type tool_use,tool_result --all \
  | jq '.events[].payload'

Nota: Por defecto, events lee un feed rápido sin payload. Cada evento incluye un summary de una línea calculado por el servidor, además de flags como is_error y contadores de tokens, pero payload se devuelve como {}. Para obtener el payload bruto, añade --full (o --fields payload). El feed completo es más lento a escala, así que mantenlo acotado: combina --full con un único --session-id.

Obtén todos los datos (paginación)

Los resultados se ordenan del más reciente al más antiguo y se pagina con cursor.

# de una vez: obtiene hasta 500 filas en páginas de 200
agenteye --json events --session-id run-001 --limit 500 --all > events.json

# paginación manual: realimenta 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"

Reduce la salida con —fields

Restringe las claves (tanto en la tabla como con --json) para reducir lo que un agente debe leer.

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

Los nombres de campo desconocidos se rechazan (salida 2) con la lista de campos válidos, una forma sencilla de descubrir los nombres disponibles.

Descubre los valores válidos de los filtros

agenteye --json list envs | jq -r '.values[]'           # valores para --env
agenteye --json list tools | jq -r '.values[]'          # nombres de herramientas; también agents, models, event_types, …
agenteye --json list score_filters | jq -r '.values[]'  # KEY válido para --score KEY:MIN..MAX

Elige tu organización (multi-tenant)

Si perteneces a más de una organización, selecciona el tenant activo al iniciar sesión (se guarda):

agenteye login --org acme --email you@corp.com   # establece el tenant en el mismo paso que el login
agenteye --json orgs list | jq -r '.orgs[].org_slug'
agenteye --org globex --json sessions --since 24h   # anula para un solo comando

Un inicio de sesión multi-organización sin --org termina con código distinto de cero e imprime las organizaciones disponibles para elegir.

Provisiona una clave API para el SDK/collector

# el secreto se imprime UNA SOLA VEZ; con --json está en el campo .key
key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key')
agenteye keys regenerate ci-bot --yes    # rotación; agenteye keys disable ci-bot --yes para revocar

Ejecuta una consulta guardada 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 consulta guardada + un argumento posicional $1

Gestiona un incidente de forma no interactiva

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: Las mutaciones omiten automáticamente la confirmación cuando se usa --json o cuando stdin no es un TTY, por lo que los agentes nunca quedan bloqueados; usa --yes/-y para omitirla explícitamente en otros contextos.

Manejo de códigos de salida en 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

Estructuras de la salida JSON

Comando	JSON en stdout (con `--json`)
`whoami`	`{"logged_in": true, "id", "email", "is_instance_admin", "active_org", "permissions": [...], "memberships": [...]}` o `{"logged_in": false}`
`orgs list`	`{"active_org", "orgs": [{"org_slug","org_name","permission_set","permissions"}]}`
`events`	`{"events": [...], "next_cursor": <cursor o null>}`
`evals`	`{"evaluations": [...], "next_cursor": <cursor o null>}`
`sessions`	`{"sessions": [...], "next_cursor": <cursor o null>}`
`errors`	`{"errors": [...], "next_cursor": <cursor o null>}`
`list <kind>`	`{"kind", "values": [...]}`
`keys list` / `keys create`	`{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` se muestra una sola vez)
`query run`	`{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}`
`users list` / `settings list`	`{"users": [...]}` / `{"settings": [...]}`
`alerts list` / `incidents list`	`{"alerts": [...]}` / `{"incidents": [...]}`
create/update/delete (cualquiera)	el objeto del recurso, o `{"deleted": true, "id"}` para eliminaciones
error (cualquiera, con `--json`)	`{"error": "...", "exit_code": <n>, "status"?: <http>, "hint"?: "..."}` en stdout

Cada elemento de evento (events): id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill. Ten en cuenta que payload es {} a menos que solicites el feed completo con --full (o --fields payload).
Cada elemento de evaluación (evals): id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at.
Cada elemento de sesión (sessions): session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation.

El argumento --fields de cada comando acepta exactamente los nombres de campo de su propio elemento. El conjunto varía entre sessions y evals, por lo que un nombre válido para uno puede ser rechazado por el otro.

Próximos pasos

CLI: instalación, autenticación y la referencia completa de opciones para cada comando.
Skill de agente CLI: empaqueta estas recetas como una skill que tu agente de código pueda cargar.
Claves API: crea y limita el alcance de las claves con las que se autentican la CLI, el SDK y el collector.
Python SDK: envía eventos a Failproof AI Observability para que haya datos que estas recetas puedan consultar.

Overview

Features

SDK and CLI

Administration

Recetas de CLI para agentes

Reglas de oro

Configuración inicial

Verifica la autenticación antes de trabajar

Busca sesiones fallidas o con puntuación baja

Lee una sesión completa de principio a fin

Obtén todos los datos (paginación)

Reduce la salida con —fields

Descubre los valores válidos de los filtros

Elige tu organización (multi-tenant)

Provisiona una clave API para el SDK/collector

Ejecuta una consulta guardada o ad-hoc

Gestiona un incidente de forma no interactiva

Manejo de códigos de salida en un script

Estructuras de la salida JSON

Próximos pasos

​Reglas de oro

​Configuración inicial

​Verifica la autenticación antes de trabajar

​Busca sesiones fallidas o con puntuación baja

​Lee una sesión completa de principio a fin

​Obtén todos los datos (paginación)

​Reduce la salida con —fields

​Descubre los valores válidos de los filtros

​Elige tu organización (multi-tenant)

​Provisiona una clave API para el SDK/collector

​Ejecuta una consulta guardada o ad-hoc

​Gestiona un incidente de forma no interactiva

​Manejo de códigos de salida en un script

​Estructuras de la salida JSON

​Próximos pasos

Reglas de oro

Configuración inicial

Verifica la autenticación antes de trabajar

Busca sesiones fallidas o con puntuación baja

Lee una sesión completa de principio a fin

Obtén todos los datos (paginación)

Reduce la salida con —fields

Descubre los valores válidos de los filtros

Elige tu organización (multi-tenant)

Provisiona una clave API para el SDK/collector

Ejecuta una consulta guardada o ad-hoc

Gestiona un incidente de forma no interactiva

Manejo de códigos de salida en un script

Estructuras de la salida JSON

Próximos pasos