failproofai 1.0.1-beta.0 → 1.0.1

package/.next/standalone/docs-old/es/agenteye/cli.mdx

@@ -0,0 +1,350 @@
+---
+title: "CLI"
+description: "Controla toda la observabilidad de Failproof AI desde la terminal o un script: sin idas y vueltas al dashboard."
+---
+
+
+Controla toda la observabilidad de Failproof AI desde la terminal o un script: sin idas y vueltas al dashboard. El CLI `agenteye` consulta tus datos (sesiones, registros de eventos, evaluaciones) y administra tu organización (claves de API, usuarios, configuraciones, alertas, incidentes, consultas guardadas), así que úsalo cuando quieras automatizar una verificación, integrar Observabilidad en CI, o permitir que un agente de código inspeccione producción. Todos los comandos admiten el flag `--json`, por lo que funciona igual de bien para ti en un prompt o para un agente de código (Claude Code, Cursor) que ejecuta el comando y parsea el resultado.
+
+Con un solo binario puedes:
+
+- **Leer tus datos**: `sessions`, `events`, `evals`, `errors` (filtra por tiempo, agente, entorno, puntuación).
+- **Administrar tu organización**: `keys`, `users`, `settings`, `alerts`, `incidents`.
+- **Ejecutar análisis**: SQL guardado y un ejecutor de consultas ad-hoc (`query`).
+- **Consultar al asistente de IA**: el mismo analista de solo lectura con el que chateas en el dashboard (`agent`).
+
+> **Nota:** Este es el CLI `agenteye`, una herramienta distinta del daemon recolector (`agenteye-collector`). El CLI se comunica con tu dashboard; el recolector envía eventos al servidor.
+
+---
+
+## Inicio rápido
+
+De cero a tu primer resultado en cuatro líneas. Apunta el CLI a tu dashboard, inicia sesión, confirma quién eres y luego extrae el último día de ejecuciones:
+
+```bash
+pipx install agenteye
+agenteye --base-url https://agenteye.example.com login --email you@example.com   # código de 6 dígitos enviado por email
+agenteye whoami                                                                  # confirma usuario + org activa
+agenteye --json sessions --since 24h                                             # una fila por ejecución de agente, últimas 24h
+```
+
+Ese último comando imprime un objeto JSON con las sesiones más recientes (más nuevas primero, limitado a 50 por defecto). Pásalo por `jq` para filtrarlo, o quita `--json` para obtener una tabla enmarcada y con colores. Cada fila contiene el estado de la ejecución y, si un evaluador la puntuó, sus métricas (abreviadas aquí):
+
+```json
+{
+  "sessions": [
+    {
+      "session_id": "run-8f2a",
+      "agent_id": "checkout-bot",
+      "environment": "prod",
+      "status": "error",
+      "scores": { "helpfulness": 0.42, "tool_efficiency": 0.55 },
+      "event_count": 37,
+      "started_at": "2026-07-16T09:14:02Z",
+      "last_event_at": "2026-07-16T09:14:48Z"
+    }
+  ],
+  "next_cursor": null
+}
+```
+
+El resto de esta página explica cada parte: [instalación](#installation) en aislamiento, [inicio de sesión](#authentication), [configuración](#configuration), las [convenciones globales](#global-options--conventions) que comparten todos los comandos, y la [referencia completa de comandos](#command-reference).
+
+---
+
+## Instalación
+
+El CLI es un paquete público de PyPI llamado **`agenteye`**. Instálalo en un entorno aislado para que siempre tenga sus propias dependencias:
+
+```bash
+pipx install agenteye
+# o
+uv tool install agenteye
+```
+
+Requiere Python 3.10+. El comando instalado es **`agenteye`**:
+
+```bash
+agenteye --version
+agenteye --help
+```
+
+> **Nota:** El SDK de Python de Observabilidad de Failproof AI también usa el nombre de distribución `agenteye`. Instalar el CLI con `pipx` o `uv tool` (en lugar de `pip install` en un virtualenv compartido) evita conflictos entre ambos. Un simple `pip install agenteye` solo es seguro si el SDK no está instalado en el mismo entorno.
+
+---
+
+## Autenticación
+
+El CLI se autentica en el **dashboard** con un código de un solo uso enviado por email:
+
+```bash
+agenteye login --email you@example.com
+# Se te envía un código de 6 dígitos por email; pégalo en el prompt.
+```
+
+El token de sesión se almacena en `~/.agenteye/cli.json` (legible solo por ti, modo `0600`) y es válido por 24 horas por defecto. Cuando expire, ejecuta `agenteye login` de nuevo.
+
+```bash
+agenteye whoami     # muestra el usuario actual, la org activa y los permisos
+agenteye logout     # revoca la sesión y elimina el token almacenado
+```
+
+`whoami` nunca falla por una sesión ausente o expirada; en su lugar reporta `logged_in: false`, por lo que un script o agente puede verificar el estado de autenticación de forma segura (igual puede salir con código distinto de cero si no hay URL base configurada o el dashboard no está disponible).
+
+**Requisitos:** tu email debe tener permiso para iniciar sesión en el dashboard (consulta a tu administrador de Observabilidad de Failproof AI), y el dashboard debe ser accesible en su URL base (ver [Configuración](#configuration)). Si solicitas un código y no llega, probablemente tu email todavía no tiene acceso habilitado al dashboard.
+
+---
+
+## Elegir tu organización (multi-tenant)
+
+Si tu cuenta pertenece a más de una organización, elige la activa **al iniciar sesión**; se guarda y se usa en todos los comandos posteriores:
+
+```bash
+agenteye login --org acme           # autentícate y establece el tenant activo en un solo paso
+agenteye orgs list                  # las orgs a las que tienes acceso (la activa aparece marcada)
+agenteye orgs switch globex         # cambia el valor predeterminado guardado
+agenteye --org globex sessions      # anula la org solo para un comando
+```
+
+Si perteneces a exactamente una org, se selecciona automáticamente y puedes ignorar `--org` por completo. Si perteneces a varias y no eliges una, el CLI las lista y te pide que vuelvas a ejecutar con `--org <slug>`. La org activa se envía al dashboard en cada solicitud, y tus permisos se resuelven **por org**; `agenteye whoami` muestra la org activa, tus permisos en ella y todas tus membresías.
+
+---
+
+## Configuración
+
+| Parámetro | Flag | Variable de entorno | Por defecto |
+|---|---|---|---|
+| URL base del dashboard | `--base-url` | `AGENTEYE_DASHBOARD_URL` | **requerida** (sin valor predeterminado) |
+| Org/tenant activo | `--org` | `AGENTEYE_ORG` | elegida al iniciar sesión; guardada en `~/.agenteye/cli.json` |
+| Token de sesión | `--token` | `AGENTEYE_CLI_TOKEN` | desde `~/.agenteye/cli.json` |
+| Salida JSON | `--json` | `AGENTEYE_CLI_JSON` | desactivado |
+| Omitir verificación TLS | `--insecure` / `--secure` | `AGENTEYE_INSECURE` | desactivado (guardado al iniciar sesión) |
+| Tiempo de espera de solicitud (segundos) | `--timeout` | _(ninguna)_ | 30 |
+| Deshabilitar telemetría de uso | _(ninguna)_ | `AGENTEYE_ANALYTICS_DISABLED` (o `DO_NOT_TRACK`) | la telemetría está actualmente deshabilitada; no se envía nada |
+
+El orden de resolución es **flag → variable de entorno → archivo de configuración**. No hay valor por defecto; debes apuntar el CLI a tu dashboard, ya sea por comando (`--base-url https://agenteye.example.com`) o una vez mediante la variable de entorno (también se guarda tras tu primer `login`):
+
+```bash
+export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com
+```
+
+El directorio de configuración respeta `AGENTEYE_HOME` (la misma convención que usan el SDK y el recolector); si está definido, `cli.json` se ubica en `$AGENTEYE_HOME/cli.json`.
+
+### TLS autofirmado o interno
+
+Si tu dashboard se sirve sobre HTTPS con un certificado autofirmado o interno (por ejemplo, el nombre de host de un balanceador de carga), la verificación TLS lo rechazará con un error `CERTIFICATE_VERIFY_FAILED`. Usa `--insecure` para omitir la verificación de certificados:
+
+```bash
+agenteye --base-url https://agenteye.internal --insecure login
+```
+
+`--insecure` se **guarda en `cli.json` al iniciar sesión**, por lo que los comandos posteriores omiten la verificación automáticamente; no necesitas repetir el flag. Usa `--secure` para una llamada verificada puntual, o para volver a habilitar la verificación en tu próximo inicio de sesión. El CLI muestra una advertencia en stderr antes de cualquier comando que contacte el dashboard con la verificación deshabilitada. Omitir la verificación elimina la protección contra ataques de intermediario (man-in-the-middle); asegúrate de confiar en la ruta de red a tu dashboard (VPN, subred privada, etc.) antes de depender de esta opción.
+
+---
+
+## Telemetría y privacidad
+
+> **Nota:** El CLI incluido **no envía telemetría de uso hoy en día.** Hay un interruptor maestro activado, por lo que no se transmite nada independientemente de tu entorno. La sección a continuación describe la capacidad de exclusión voluntaria para el caso de que la telemetría alguna vez se habilite.
+
+Incluso cuando esté habilitada, la telemetría sería **únicamente análisis de uso anónimos**, nunca datos de tu agente, sesión o eventos:
+
+- **Ningún dato de agente, sesión o evento sale jamás de tu infraestructura.** Solo se reportaría el uso del CLI: el nombre del comando y subcomando (p. ej., `keys create`), los **nombres** de los flags que usaste (nunca sus valores), estado de éxito/salida, y duración, más un evento por acción para mutaciones (p. ej., `api_key_created`, `query_run`) que solo lleva nombres/enums estáticos y conteos aproximados. Tu URL de dashboard, token de sesión, email, slug de org, IDs de recursos, SQL, secretos de claves y filtros de consulta **nunca se enviarían**. Los operadores se identificarían únicamente por un ID interno opaco, nunca por email.
+- **Excluirte con antelación** establece `AGENTEYE_ANALYTICS_DISABLED=1` en el entorno del CLI (el CLI también respeta la convención multiplataforma `DO_NOT_TRACK=1`). Esto tiene efecto en el momento en que la telemetría se active, por lo que un entorno con conciencia de privacidad puede permanecer excluido permanentemente.
+- Si la telemetría estuviera habilitada, el CLI enviaría directamente a PostHog (`https://us.i.posthog.com`); una máquina con ese host bloqueado simplemente no enviaría nada y el CLI no se vería afectado.
+
+---
+
+## Opciones globales y convenciones
+
+Lee esto una vez; aplica a todos los comandos.
+
+- **Las opciones globales van ANTES del comando.** `agenteye --json sessions` es correcto; `agenteye sessions --json` es un error de uso. Las globales son `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet` y `--no-color`.
+- **`--json` imprime JSON puro en stdout, y nada más.** Las líneas de estado para humanos, advertencias y errores van a **stderr**, por lo que una captura de stdout con `--json` se mantiene limpia para pasar a `jq` incluso cuando se muestra una línea de estado. Sin `--json` obtienes una vista enmarcada y con colores para lectura humana.
+- **Explora con `--help`.** Cada comando y subcomando tiene `--help` (y el alias `-h`): `agenteye -h`, `agenteye sessions -h`, `agenteye keys create -h`. La ayuda de nivel superior también lista los códigos de salida y las opciones globales. No hay un volcado de superficie legible por máquina a nivel global; usa `--help` por comando, más los específicos de dominio `agenteye query schema` y `agenteye settings schema` para esos dos registros.
+- **Las confirmaciones se omiten automáticamente en scripts y agentes.** Los comandos de creación/actualización/eliminación muestran el mensaje "¿estás seguro?" en una terminal interactiva, pero **omiten ese prompt automáticamente con `--json` o cuando stdin no es un TTY** (un TTY es una sesión de terminal interactiva; una tubería o un runner de CI no lo es), por lo que los scripts y agentes nunca quedan bloqueados. Usa `--yes`/`-y` para omitirlo explícitamente. Como el prompt no se mostrará para un agente, este debería confirmar las acciones destructivas con el humano primero.
+- **Paginación:** los resultados están ordenados de más nuevo a más antiguo y paginados por cursor (cada página devuelve un token que usas para obtener la siguiente). `--limit N` (alias `-n`) limita las filas y **por defecto es 50**; `--all` pagina automáticamente (en bloques de 200 filas) **hasta `--limit`**, por lo que un `--all` sin más aún se detiene en 50. Para un barrido completo, pasa un límite explícito alto: `--all --limit 1000`. `--page-size N` controla el bloque por solicitud (máximo 200); `--cursor <id>` reanuda desde el `next_cursor` de una página anterior.
+- **Filtros de tiempo:** `--since` acepta una ventana relativa: `15m`, `1h`, `6h`, `24h`, `7d`, o `all` (los presets del dashboard). Para un rango más largo o personalizado (digamos los últimos 30 días), usa `--from`/`--to`: timestamps UTC explícitos en ISO-8601 **con `T` y zona horaria** (p. ej., `2026-06-01T00:00:00Z`) que sobreescriben `--since`. Un valor separado por espacios o sin zona horaria es un error de uso.
+- **`--fields a,b,c`** (en `events`, `sessions`, `evals`, `errors`) restringe la salida a esas claves, tanto en la tabla como en `--json`. Los nombres desconocidos se rechazan con la lista válida, una forma rápida de descubrir los nombres de campos.
+- **`--file payload.json`** (o `--file -` para leer stdin) proporciona un cuerpo de solicitud JSON completo donde un recurso tiene una forma compleja (en `alerts create/update`, `settings set` y `users create/update`). El SQL de consultas guardadas usa `--sql @file.sql` en su lugar.
+- **Los filtros de múltiples valores** son separados por comas → se comparan como un conjunto (unión dentro de un filtro, AND entre filtros): `--event-type tool_use,tool_result`. Las opciones de Click no son variádicas, así que `--add a b` no funciona. Usa `--add a,b`, repite el flag (`--add a --add b`), o entrecomíllalo (`--add "a b"`).
+
+---
+
+## Referencia de comandos
+
+### Los 5 comandos que más usarás
+
+La mayor parte del trabajo diario se realiza con un puñado de comandos de lectura. Empieza aquí y recurre a la superficie completa cuando lo necesites:
+
+| Comando | Qué hace | Pruébalo |
+|---|---|---|
+| `sessions` | Una fila por ejecución de agente: tiempo, entorno, agente, estado, última puntuación. | `agenteye --json sessions --since 24h --status error` |
+| `events` | El rastro sin procesar de cada paso dentro de una ejecución (añade `--full` para los payloads). | `agenteye --json events --session-id run-001 --all` |
+| `evals` | Resultados de evaluación y puntuaciones; `--aggregate` los agrupa. | `agenteye --json evals --aggregate --since 7d --env prod` |
+| `errors` | Solo los eventos con error; `--aggregate` para conteos por tipo. | `agenteye --json errors --since 24h --aggregate` |
+| `list` | Descubre los valores de filtro válidos (agentes, entornos, modelos, …). | `agenteye list agents` |
+
+### Todo lo que puede hacer el CLI
+
+La superficie completa aparece a continuación. El CLI tiene **18 comandos de nivel superior**. Todos los comandos de lectura aceptan `--json` y las opciones globales anteriores; ejecuta `agenteye <command> -h` (o `<command> <subcommand> -h`) para la lista exhaustiva de flags y la forma JSON de cualquiera.
+
+### Identidad: `login` · `logout` · `whoami` · `orgs` · `version` · `help`
+
+```bash
+agenteye login --email you@example.com [--org acme]   # código de un solo uso por email; guarda la sesión
+agenteye logout                                       # limpia la sesión guardada en esta máquina
+agenteye whoami                                       # usuario actual, org activa, permisos
+agenteye version                                      # muestra la versión del CLI (igual que --version)
+agenteye help                                         # ayuda de nivel superior (igual que --help)
+```
+
+`orgs` inspecciona y cambia el tenant activo:
+
+```bash
+agenteye orgs list        # tus orgs + tu rol en cada una (la activa aparece marcada)
+agenteye orgs switch acme # cambia la org activa guardada (omite el slug para elegir de una lista en TTY)
+agenteye orgs current     # tarjeta de identidad de la org activa
+agenteye orgs perms       # tus permisos en la org activa, agrupados por recurso
+```
+
+### Observar (solo lectura): `events` · `sessions` · `evals` · `errors` · `list`
+
+Ninguno de estos requiere confirmación. Filtros compartidos: `--session-id`, `--agent-id`, `--env` (**no** `--environment`), y el rango de tiempo (`--since` / `--from` / `--to`).
+
+```bash
+# events (alias: el rastro sin procesar por paso), más nuevos primero
+agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all --limit 1000
+agenteye --json events --since 1h --search timeout --all | jq '.events[].payload'
+
+# sessions: una fila por ejecución de agente (tiempo/entorno/agente/sesión/estado; sin filtrado por puntuación)
+agenteye --json sessions --since 24h --status error
+agenteye --json sessions --agent-id checkout-bot --env prod --all --limit 1000
+
+# evals: resultados de evaluación + puntuaciones; --score filtra por métrica, --aggregate agrupa
+agenteye --json evals --score helpfulness:0.5..0.8 --score tool_efficiency:..0.3
+agenteye --json evals --aggregate --since 7d --env prod        # mezcla de estados + estadísticas de puntuación por clave
+
+# errors: eventos con error; --aggregate para conteos/sesiones/agentes/última aparición
+agenteye --json errors --since 24h --aggregate
+agenteye --json errors --since 24h --error-type timeout --all --limit 1000
+
+# list: descubre los valores de filtro válidos antes de filtrar
+agenteye list envs        # también: agents event_types score_filters models hooks tools error_types
+```
+
+`--score KEY:MIN..MAX` (en **`evals`**, no en `sessions`) es repetible y se combina con AND; cualquiera de los límites es opcional (`..0.5` significa ≤ 0.5, `0.9..` significa ≥ 0.9). Hasta 20 filtros de puntuación por solicitud. `evals --scores-full` es un flag de visualización **solo para la tabla humana**; muestra todos los pares de puntuación en lugar de los primeros más un conteo `+N`. No tiene efecto con `--json`, que siempre devuelve el objeto de puntuación completo. Para leer **una sesión de principio a fin**, combina el rastro de eventos con su evaluación:
+
+```bash
+agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}'
+agenteye --json evals  --session-id run-001                       # sus puntuaciones + estado
+```
+
+### Administrar (con permisos requeridos): `keys` · `users` · `settings` · `alerts` · `incidents`
+
+**`keys`**: claves de API. El secreto se genera localmente, se envía al servidor (que solo almacena un hash), y se **muestra una única vez** al crear/regenerar; captúralo en ese momento. Con `--json` aparece solo en el campo `key`. Se referencian por **nombre**.
+
+```bash
+agenteye keys list                                   # claves activas primero, luego revocadas
+agenteye keys show ci-bot
+agenteye keys create ci-bot --add events:read.add    # limita al alcance necesario; imprime el secreto UNA VEZ
+agenteye keys create ops --permission-set standard --remove queries:run   # comienza con un preset y recorta
+agenteye keys update ci-bot --add evaluations:read --yes
+agenteye keys regenerate ci-bot --yes                # rota el secreto (el anterior deja de funcionar)
+agenteye keys disable ci-bot --yes                   # revoca
+```
+
+Los permisos funcionan como `(permission-set ∪ --add) − --remove`. Los tokens son `slug:acción` (p. ej., `events:read`) o `slug:acción.acción` para expandir varios en un recurso (`events:read.add` → `events:read`, `events:add`). Presets: `read-only`, `standard`, `admin`. Los permisos exclusivos de humanos (`keys:update`) no pueden concederse a una clave.
+
+**`users`**: miembros de la org, referenciados por **email** (también se acepta un UUID id).
+
+```bash
+agenteye users list [--active-only]
+agenteye users show dev@corp.com
+agenteye users create dev@corp.com --permission-set standard
+agenteye users update dev@corp.com --add alerts:write --remove queries:delete   # predice + confirma
+agenteye users disable dev@corp.com --yes            # tiene protecciones de usuarios protegidos/propios
+agenteye users enable dev@corp.com
+```
+
+**`settings`**: un registro fijo (lees y cambias claves existentes; no puedes crear nuevas).
+
+```bash
+agenteye settings list                               # clave · valor · tipo · actualizado (secretos enmascarados)
+agenteye settings schema                             # lo que acepta cada clave (tipo · rango · descripción)
+agenteye settings set session_ttl_secs --value 86400 --yes
+```
+
+**`alerts`**: definiciones de alertas, referenciadas por **nombre**. `create` toma un NAME posicional más flags o un cuerpo JSON completo vía `--file`.
+
+```bash
+agenteye alerts list
+agenteye alerts show high-errors
+agenteye alerts create high-errors --file alert.json          # NAME es requerido (posicional)
+agenteye alerts update high-errors --severity critical --yes
+agenteye alerts test high-errors --yes                        # dispara una notificación de prueba
+agenteye alerts delete high-errors --yes
+```
+
+**`incidents`**: incidentes de alertas, referenciados por ID (se aceptan IDs cortos). `show` imprime el registro de actividad completo; léelo antes de actuar.
+
+```bash
+agenteye incidents list --state firing                # también: acknowledged, resolved
+agenteye incidents count
+agenteye incidents show <id>
+agenteye incidents ack <id>
+agenteye incidents assign <id> you@corp.com           # el asignado debe ser un operador
+agenteye incidents resolve <id> --yes
+agenteye incidents open --alert-id <id> --severity critical    # abre uno manualmente contra una alerta
+agenteye incidents comment-add <id> "root cause: upstream 5xx"
+agenteye incidents comment-list <id> ; agenteye incidents comment-delete <id> <comment-id>
+agenteye incidents subscribe <id> ; agenteye incidents unsubscribe <id> ; agenteye incidents subscribers <id>
+```
+
+### Análisis y asistente: `query` · `agent`
+
+**`query`**: SQL guardado contra tu almacén de análisis más un ejecutor ad-hoc. Las consultas guardadas se referencian por **nombre**; el SQL se valida en el servidor (solo SELECT/WITH, timeout de declaración, límite de filas).
+
+```bash
+agenteye query schema [TABLE]                         # estructura de columnas de las vistas de análisis
+agenteye query run --sql "select count(*) from analytics.events"
+agenteye query run errs --arg prod --limit 100        # ejecuta una consulta guardada + un $1 posicional
+agenteye query list ; agenteye query show errs
+agenteye query create errs --sql @errs.sql --description "errored events (24h)"
+agenteye query update errs --sql @errs.sql --yes ; agenteye query delete errs --yes
+```
+
+**`agent`**: habla con el **asistente de IA** integrado (el mismo analista de solo lectura con el que puedes chatear en el dashboard). Los chats se referencian por un chat-id corto (resuelto por prefijo).
+
+```bash
+agenteye agent health                                 # si el asistente de IA está configurado/accesible
+agenteye agent models                                 # modelos que puedes pasar a --model (el predeterminado aparece marcado)
+agenteye agent ask "which agents errored most in the last day?"    # inicia un chat; imprime su ID corto
+agenteye agent ask --chat <short-id> "and which tools did they call?"   # continúa ese chat
+agenteye agent chats ; agenteye agent show <short-id>
+agenteye agent rename <short-id> --title "error triage" ; agenteye agent delete <short-id>
+```
+
+---
+
+## Códigos de salida
+
+| Código | Significado |
+|---|---|
+| 0 | Éxito |
+| 1 | Error inesperado (p. ej., el dashboard devolvió un 5xx) |
+| 2 | Error de uso (argumentos inválidos, comando/flag desconocido, colisión de nombres) |
+| 3 | No se puede alcanzar el dashboard |
+| 4 | No has iniciado sesión o la sesión expiró; ejecuta `agenteye login` |
+| 5 | Autenticado, pero tu cuenta no tiene el permiso requerido (el mensaje lo nombra) |
+| 6 | El recurso solicitado no se encontró (p. ej., sesión o ID de incidente desconocido) |
+
+Esto hace que el CLI sea seguro para usar en scripts: un agente de código puede ramificar en un `4` para pedirte que te vuelvas a autenticar, o en un `5` para mostrar el permiso faltante. Consulta [recetas de CLI para agentes](/es/agenteye/cli-recipes) para patrones de manejo de códigos de salida y formas de salida JSON.
+
+---
+
+## Próximos pasos
+
+- **[Recetas de CLI para agentes](/es/agenteye/cli-recipes)**: patrones de consulta listos para copiar, one-liners de `jq`, proyecciones con `--fields`, manejo de códigos de salida y formas de salida JSON, escritos para agentes de código que controlan el CLI.
+- **[Habilidad de CLI para agentes](/es/agenteye/cli-skill)**: empaqueta este CLI como una *skill* instalable de Claude Code / Codex para que un agente de código controle la Observabilidad de Failproof AI desde solicitudes en lenguaje natural.
+- **[Claves de API](/es/agenteye/api-keys)**: el modelo de permisos detrás de `keys create --add …`.
+- **[Asistente de IA](/es/agenteye/assistant)**: cómo habilitar el asistente con el que habla `agent ask`.

package/.next/standalone/docs-old/es/agenteye/codex-capture.mdx

@@ -0,0 +1,55 @@
+---
+title: "Captura de sesiones de Codex"
+description: "Lleva las sesiones locales de OpenAI Codex de tu equipo a AgentEye como sesiones y eventos ordinarios, sin modificar la forma en que los ejecutan."
+---
+
+Tus ingenieros ya usan OpenAI Codex a diario. La captura de sesiones de Codex trae esas sesiones de trabajo a AgentEye como sesiones y eventos ordinarios, para que puedas buscarlas, reproducirlas y evaluarlas junto con todo lo demás que observas. Complementa el [SDK de Python](/es/agenteye/python-sdk): el SDK instrumenta los agentes que tú escribes, mientras que esto captura el trabajo en Codex que tu equipo ya realiza, sin cambiar nada en su flujo habitual.
+
+Un pequeño recolector en segundo plano lee las transcripciones de sesiones locales de Codex a medida que se van escribiendo y las envía a AgentEye. Un único recolector por máquina captura todas las superficies locales de Codex a la vez — no es necesario configurar nada por cada superficie.
+
+El mismo recolector también captura otros agentes — consulta [OpenClaw](/es/agenteye/openclaw-capture) y [Hermes](/es/agenteye/hermes-capture). Activa los que uses; un solo recolector puede capturar varios a la vez.
+
+---
+
+## Qué captura
+
+Todas las superficies de Codex que se ejecutan **localmente** producen las mismas transcripciones de sesión en disco, y el recolector las recoge todas:
+
+- la **CLI** de Codex y `codex exec`
+- la **extensión de VS Code / IDE**
+- la **aplicación de escritorio**, cuando ejecuta una sesión de forma local
+
+Cada sesión de Codex se convierte en una [sesión](/es/agenteye/sessions) de AgentEye; sus mensajes de usuario y asistente, razonamiento, llamadas a herramientas, resultados de herramientas y uso de tokens se convierten en los [eventos](/es/agenteye/event-stream) correspondientes. La superficie de la que proviene cada sesión (CLI, IDE o escritorio) queda registrada para que puedas distinguirlas.
+
+> **Las sesiones en la nube no se capturan.** La aplicación de escritorio ejecuta cada vez más sesiones en la nube de Codex y solo guarda sus metadatos en la máquina local — no hay transcripción local que leer. Solo se capturan las sesiones ejecutadas localmente.
+
+---
+
+## Cómo activarlo
+
+La captura está desactivada hasta que la habilites. Instala el recolector con una clave de API que tenga el permiso `events:add` (consulta [Claves de API](/es/agenteye/api-keys)) y activa la captura de Codex:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \
+  | sh -s -- --key <YOUR_API_KEY> --codex-enabled
+```
+
+Esto instala el recolector, lo registra como servicio en segundo plano y comienza la captura. Confirma que está en ejecución:
+
+```bash
+agenteye-collector health
+```
+
+En el primer arranque, las sesiones de Codex existentes se importan de una sola vez y la actividad nueva fluye en cuestión de segundos. Los archivos propios de Codex solo se leen — nunca se modifican, mueven ni eliminan — y cada sesión se envía exactamente una vez, incluso tras reinicios.
+
+---
+
+## Dónde aparece
+
+Las sesiones capturadas aparecen en **Sessions**, y sus eventos en el flujo de **Events**, igual que cualquier otro agente que observes — así que la [reproducción de sesiones](/es/agenteye/sessions), la [búsqueda](/es/agenteye/queries), las [evaluaciones](/es/agenteye/evaluations) y las [alertas](/es/agenteye/alerts) funcionan con ellas. Filtra por el agente de Codex para verlas por separado.
+
+---
+
+## Privacidad
+
+Las transcripciones de Codex contienen la sesión completa — incluyendo la salida de comandos, el contenido de archivos y todo lo que Codex leyó o escribió — y pueden contener secretos. Las sesiones capturadas se envían tal cual, así que activa la captura únicamente en las máquinas y para los equipos en los que centralizar ese contenido en AgentEye sea apropiado, y proporciona al recolector una clave con alcance exclusivo a `events:add`. Consulta [Seguridad](/es/agenteye/security) para saber cómo se mantienen aislados tus datos.

package/.next/standalone/docs-old/es/agenteye/concepts.mdx

@@ -0,0 +1,87 @@
+---
+title: "Conceptos"
+description: "El vocabulario de Failproof AI Observability — eventos, sesiones, evaluaciones, auditorías, hallazgos e incidentes — definido en un solo lugar."
+---
+
+
+Esta página define el vocabulario que utiliza Failproof AI Observability. Si algún término en otra guía te resulta desconocido, aquí encontrarás su definición. No es necesario leerla de principio a fin: puedes hojearla o volver cuando encuentres una palabra que quieras aclarar.
+
+---
+
+## El modelo de datos
+
+**Evento**
+La unidad mínima de datos. Un evento registra un único paso que realizó tu agente: un `tool_use`, un `model_request`, un `hook_completed`, un `error`, entre otros. Tu agente emite eventos a través del [Python SDK](/es/agenteye/python-sdk); aparecen en tiempo real en la página de **Events**.
+
+**Sesión**
+Una ejecución del agente, identificada por un `session_id`. Una sesión agrupa todos los eventos que comparten ese identificador, se muestra como una fila en la página de **Sessions** y se representa como un grafo de ejecución en su página de detalle. Por lo general, una sesión comienza con `agent_start` y termina con `agent_end`.
+
+**Agente**
+Un actor con nombre dentro de una ejecución, identificado por un `agent_id`. Una ejecución puede involucrar varios agentes: por ejemplo, un planificador que genera un sub-agente de resumen. Los sub-agentes llevan un `parent_id`, que es lo que permite a Failproof AI Observability representarlos en sus propios carriles dentro del grafo de ejecución.
+
+**Entorno**
+Una etiqueta que indica dónde ocurrió la ejecución: `production`, `staging`, `dev`. Se configura una sola vez al configurar el SDK. Casi todas las páginas del panel permiten filtrar por entorno.
+
+**Llenado de la ventana de contexto**
+El porcentaje de la ventana de contexto de un modelo que consumió una respuesta. Failproof AI Observability lo registra en los eventos `model_response` para los modelos que reconoce, de modo que el crecimiento del prompt y la compactación inminente sean visibles directamente en el flujo de eventos.
+
+---
+
+## Calidad
+
+**Evaluación**
+Una puntuación de calidad para una sesión finalizada, generada por un servicio de puntuación que tú ejecutas. Las evaluaciones son opcionales: hasta que conectes un evaluador, las sesiones se registran pero no se puntúan. Cada evaluación puede incluir varias puntuaciones con nombre (por ejemplo, `helpfulness`, `factuality`, `tool_efficiency`), cada una con una breve nota de razonamiento. Consulta [Evaluation suite](/es/agenteye/evaluation-suite).
+
+**Clave de puntuación**
+El nombre de una dimensión que reporta un evaluador, como `helpfulness`. Las alertas y auditorías pueden monitorear una clave de puntuación específica a lo largo del tiempo.
+
+**Evaluador**
+Tu servicio de puntuación. Failproof AI Observability envía mediante POST la transcripción de una ejecución finalizada y almacena las puntuaciones que devuelve. No incluye un evaluador predeterminado; la lógica de puntuación es tuya.
+
+---
+
+## Detección y corrección de fallos
+
+**Hook**
+Una barrera de protección o efecto secundario que el framework de tu agente ejecuta alrededor de un paso: una verificación de seguridad de contenido, la eliminación de PII, un control de presupuesto. Los hooks emiten eventos `hook_triggered` / `hook_completed` con un `outcome` (allow, deny, modify), y tienen su propia página de observabilidad.
+
+**Regla de alerta**
+Una regla que se activa cuando una métrica supera un umbral que tú defines: tasa de errores, latencia p95, costo en tokens o una puntuación del evaluador. Cuando se activa una regla, abre un incidente y notifica a los canales que hayas configurado (correo electrónico, Slack, webhook, panel de control). Consulta [Alerts](/es/agenteye/alerts).
+
+**Incidente**
+Un problema abierto que se crea cuando se activa una regla de alerta. Los incidentes tienen un ciclo de vida (reconocer, asignar, resolver) y una línea de tiempo de actividad que registra cada acción. También puedes abrir uno manualmente.
+
+**Auditoría**
+Una investigación recurrente (de cada hora a semanal) que analiza tus registros *entre* sesiones en busca de patrones de fallo para los que aún no has escrito una regla: clústeres de errores, puntuaciones bajas, valores atípicos de latencia, bucles de llamadas a herramientas y ejecuciones que nunca terminaron. Mientras que una alerta monitorea una métrica que ya conoces, una auditoría te indica qué deberías revisar a continuación. Consulta [Audits](/es/agenteye/audits).
+
+**Hallazgo**
+Un resultado priorizado y respaldado por evidencia de una ejecución de auditoría. Un hallazgo identifica un patrón, enlaza con las sesiones exactas que lo respaldan y tiene un ciclo de vida de triaje (reconocer, resolver, silenciar, descartar). Failproof AI Observability deduplica los hallazgos entre ejecuciones, de modo que un patrón conocido se actualiza en lugar de acumularse.
+
+**El asistente de IA**
+El chat integrado en el panel que responde preguntas sobre tus agentes en lenguaje natural, utilizando tus propios datos. Es de solo lectura por defecto; todo lo que crea (una consulta guardada, un panel de control) requiere aprobación, y nunca puede eliminar datos. Consulta [AI assistant](/es/agenteye/assistant).
+
+---
+
+## Ejecución
+
+**Organización (tenant)**
+Un espacio de trabajo aislado. Una instancia de Failproof AI Observability puede albergar muchas organizaciones, cada una con sus propios usuarios, claves y datos. Cada URL del panel está delimitada por el slug de tu organización (`/<org-slug>/…`).
+
+**Recolector**
+`agenteye-collector`, el daemon ligero que se ejecuta en cada máquina de agente, agrupa los eventos que el SDK escribe en disco y los envía al servidor.
+
+**Clave de API**
+Un token con permisos acotados que autentica a un cliente frente al servidor. Las claves tienen permisos granulares (por ejemplo, `events:add` para el recolector, permisos de solo lectura para una clave de panel). Consulta [API keys](/es/agenteye/api-keys).
+
+**Servidor**
+El servicio de ingesta y API. Recibe eventos, almacena el estado operativo en tus bases de datos y sirve el panel de control y la CLI.
+
+**Panel de control**
+La interfaz web. Cada página está delimitada a una organización y accede a los datos a través de la API del servidor.
+
+---
+
+## Próximos pasos
+
+- [Overview](/es/agenteye/overview): cómo encajan todas estas piezas.
+- [Observability](/es/agenteye/observability): las superficies de observabilidad (Events, Sessions, Models, Tools, Hooks, Errors).

package/.next/standalone/docs-old/es/agenteye/dashboards.mdx

@@ -0,0 +1,46 @@
+---
+title: "Dashboards"
+description: "Convierte los datos en vivo de tus agentes en una vista compartida que todo tu equipo puede consultar."
+---
+
+
+Convierte los datos en vivo de tus agentes en una vista compartida que todo tu equipo puede consultar. Fija las consultas más importantes como gráficos, y todos verán los mismos números de un vistazo, sin necesidad de volver a ejecutar ni una sola consulta.
+
+![Un dashboard construido a partir de consultas guardadas: una línea de eventos por hora, una barra de errores por tipo, un gráfico de área de latencia y tokens por modelo](/agenteye/images/dashboard-fleet.png)
+
+*Un tablero, cuatro consultas guardadas: eventos por hora, errores por tipo, latencia y tokens por modelo.*
+
+## Todos ven la misma realidad
+
+Deja de pegar capturas de pantalla en el chat y de volver a ejecutar la misma consulta cinco veces al día. Un dashboard es un tablero compartido a nivel de organización que cualquier miembro de tu equipo puede abrir para ver exactamente la misma información. Cuando los datos subyacentes cambian, los gráficos cambian con ellos, por lo que el tablero siempre está actualizado y nadie discute sobre números desactualizados.
+
+El dashboard de flota de arriba es un buen punto de partida para las operaciones del día a día:
+
+- una línea de **eventos por hora**, para monitorear el rendimiento y detectar caídas repentinas
+- una barra de **errores por tipo**, para identificar de inmediato las categorías de fallos más frecuentes
+- un gráfico de área de **latencia**, para detectar ralentizaciones antes de que los usuarios se quejen
+- un desglose de **tokens por modelo**, para mantener los costos bajo control
+
+Encontrarás tus tableros en `/<org-slug>/dashboards`.
+
+## Fija las consultas que ya tienes guardadas
+
+Cada mosaico comienza como una consulta guardada. Crea y guarda la consulta que necesitas en la biblioteca de [Consultas](/es/agenteye/queries) (presets integrados más los tuyos propios, sobre tus eventos y evaluaciones), y luego fíjala en un dashboard como el gráfico que mejor se adapte a los datos: una **línea** para tendencias en el tiempo, una **barra** para comparar categorías, un **área** para volumen, o un **pastel** para mostrar proporciones.
+
+Como un mosaico no es más que tu consulta guardada representada como gráfico, no hay nada que mantener sincronizado manualmente. Actualiza la consulta una vez y todos los dashboards que la usan se actualizan también.
+
+## Monitorea la calidad, no solo el volumen
+
+El volumen te dice que los agentes están ocupados. La calidad te dice que realmente están haciendo bien su trabajo. Apunta un dashboard a tus [puntuaciones de evaluación](/es/agenteye/evaluations) y obtendrás un tablero que rastrea el rendimiento de las ejecuciones a lo largo del tiempo, de modo que una regresión de calidad aparece como una caída en el gráfico en lugar de como una sorpresa de un cliente.
+
+![Un dashboard enfocado en calidad, construido a partir de consultas de evaluación guardadas](/agenteye/images/dashboard-quality.png)
+
+*Un tablero de calidad mantiene tus puntuaciones de evaluación en primer plano, justo junto a los números operativos.*
+
+Mantén un tablero de operaciones y un tablero de calidad lado a lado, y tu equipo tendrá un único lugar para responder tanto "¿está funcionando?" como "¿lo está haciendo bien?", sin que nadie tenga que volver a ejecutar una consulta.
+
+## Relacionados
+
+- [Consultas](/es/agenteye/queries): crea y guarda las consultas que se convertirán en tus mosaicos.
+- [Evaluaciones](/es/agenteye/evaluations): puntúa tus ejecuciones para poder graficar la calidad a lo largo del tiempo.
+- [Alertas](/es/agenteye/alerts): convierte un umbral en cualquiera de estas métricas en una notificación.

package/.next/standalone/docs-old/es/agenteye/error-tracking.mdx

@@ -0,0 +1,41 @@
+---
+title: "Seguimiento de Errores"
+description: "Ve todos los fallos que producen tus agentes en un solo lugar, agrupados para que una ráfaga ruidosa se lea como un único problema."
+---
+
+
+Ve todos los fallos que producen tus agentes en un solo lugar, agrupados para que una ráfaga ruidosa se lea como un único problema. Tienes un camino de un solo clic desde "algo está en rojo" hasta la ejecución exacta que falló, sin tener que desplazarte por un feed en vivo para encontrarlo.
+
+![La página de Errores: un histograma de fallos a lo largo del tiempo encima de filas de errores en rojo agrupados, cada una con un botón "+ alert" de un solo clic](/agenteye/images/errors.png)
+*La página de Errores: un histograma de fallos a lo largo del tiempo, con los fallos repetidos colapsados en una sola fila por incidente.*
+
+## Todos los fallos, ya recopilados por ti
+
+Cuando un agente falla, no deberías tener que desplazarte por un stream de eventos en vivo esperando capturar las filas en rojo antes de que desaparezcan. La página **Errors** se encarga de la recopilación por ti. Reúne todo lo que el panel pintaría de rojo en una única superficie de triaje, para que lo primero que veas sea qué está fallando, no dónde tienes que ir a buscarlo.
+
+Y detecta más que los fallos obvios. Además de los eventos explícitos de tipo `error`, Failproof AI Observability también muestra los fallos silenciosos: cualquier `tool_result`, `hook_completed` o `agent_end` cuyo payload contenga un fallo aparece aquí. Una herramienta que devolvió un error, o un hook que terminó mal, ya no pasa desapercibido simplemente porque nada lanzó una excepción sonora.
+
+En la parte superior, un histograma muestra los errores a lo largo del tiempo. Un vistazo te dice si se trata de un goteo de fondo constante o de un pico que empezó hace unos minutos, para que sepas de inmediato si debes dejar lo que estás haciendo.
+
+Como cualquier superficie de observabilidad, la página de Errores está delimitada por tu organización y se filtra por rango de fechas, entorno, agente y sesión. Eso significa que puedes partir de una lista de toda la flota y reducirla al agente o al entorno que realmente te interesa.
+
+## Un incidente, no cien filas idénticas
+
+Una sola dependencia rota puede disparar el mismo error cientos de veces por minuto. Tal cual, eso es una pared de líneas casi idénticas que entierra lo único que realmente necesitas ver.
+
+Failproof AI Observability colapsa los fallos repetidos que comparten la misma sesión y tipo de error en una sola fila. Una ráfaga se lee como un único incidente. Acabas contando problemas, no líneas de log, y la señal que importa se mantiene en primer plano en lugar de ahogarse en su propio volumen.
+
+## De "algo está en rojo" al evento exacto
+
+Haz clic en cualquier fila para ir directamente al interior de la sesión de esa ejecución, posicionado en el evento exacto que falló. Sin copiar IDs de sesión, sin desplazarte buscando el momento en que algo salió mal: llegas justo ahí, con el grafo de ejecución completo a un vistazo para que puedas ver qué hizo el agente en los momentos previos al fallo.
+
+Si tienes `alerts:write`, cada fila también incluye un botón **+ alert**. Haz clic en él y Observability abre una nueva regla de alerta ya configurada para detectar ese mismo fallo de nuevo. El incidente que acabas de triar se convierte en el que te avisará la próxima vez, en lugar de sorprenderte dos veces.
+
+**Dónde encontrarlo:** la página **Errors** se encuentra en la sección de observabilidad del panel, en `/<org-slug>/errors`.
+
+## Relacionado
+
+- [Alerts](/es/agenteye/alerts): convierte cualquier fallo en una regla de notificación.
+- [Incidents](/es/agenteye/incidents): sigue una alerta activa desde que se abre hasta que se resuelve.
+- [Sessions](/es/agenteye/sessions): abre la ejecución completa detrás de cualquier error.
+- [Audits](/es/agenteye/audits): deja que Observability encuentre patrones de fallos en tus ejecuciones por ti.