failproofai 1.0.1-beta.0 → 1.0.1

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

@@ -0,0 +1,178 @@
+---
+title: "Recetas de CLI para agentes"
+description: "Patrones de consulta y recetas de jq listos para copiar y pegar que convierten datos de sesiones, eventos y evaluaciones en algo que un script o agente de código puede automatizar."
+---
+
+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](/es/agenteye/cli); ejecuta `agenteye -h` o `agenteye <command> -h` para ver la ayuda integrada.
+
+## Reglas de oro
+
+1. **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`.
+2. **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`.
+3. **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.
+4. **Explora con `-h`.** Cada comando documenta sus filtros, formatos de valores y estructura JSON.
+
+## Configuración inicial
+
+```bash
+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.)
+
+```bash
+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
+
+```bash
+# 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:
+
+```bash
+# 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.
+
+```bash
+# 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.
+
+```bash
+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
+
+```bash
+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):
+
+```bash
+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
+
+```bash
+# 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
+
+```bash
+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
+
+```bash
+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
+
+```bash
+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](/es/agenteye/cli): instalación, autenticación y la referencia completa de opciones para cada comando.
+- [Skill de agente CLI](/es/agenteye/cli-skill): empaqueta estas recetas como una skill que tu agente de código pueda cargar.
+- [Claves API](/es/agenteye/api-keys): crea y limita el alcance de las claves con las que se autentican la CLI, el SDK y el collector.
+- [Python SDK](/es/agenteye/python-sdk): envía eventos a Failproof AI Observability para que haya datos que estas recetas puedan consultar.

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

@@ -0,0 +1,159 @@
+---
+title: "Habilidad de CLI para Observabilidad de Failproof AI"
+description: "Pregúntale a tu agente de codificación «¿hay algo roto hoy?» y deja que responda con tus datos en vivo de Observabilidad de Failproof AI, sin comandos que memorizar."
+---
+
+
+Pregúntale a tu agente de codificación *«¿hay algo roto hoy?»* y deja que responda con tus datos en vivo de Observabilidad de Failproof AI, sin comandos que memorizar. La **habilidad de CLI de Observabilidad de Failproof AI** (`agenteye-cli`) es una *Agent Skill*: una pequeña carpeta de instrucciones que un agente de codificación como Claude Code o Codex carga bajo demanda. Le enseña al agente a operar tu despliegue de Observabilidad a través de la [`agenteye` CLI](/es/agenteye/cli) mediante solicitudes en lenguaje natural como *«dale a CI una clave que solo pueda enviar eventos»* o *«acepta el incidente activo y asígnamelo»*.
+
+**No** es un servicio ni un binario independiente; no hay nada que desplegar. Se apoya en la CLI que ya tienes instalada: el agente invoca `agenteye --json …`, analiza el JSON limpio resultante y te responde en prosa. Todo lo que puede hacer, tú también podrías hacerlo escribiendo los mismos comandos.
+
+---
+
+## Relación con las demás interfaces de Observabilidad de Failproof AI
+
+Failproof AI Observability te ofrece cuatro formas de acceder a los mismos datos y controles. Se complementan entre sí:
+
+| Interfaz | Qué es | Dónde se ejecuta | Úsala cuando |
+|---|---|---|---|
+| **[CLI](/es/agenteye/cli)** | La referencia de comandos y opciones de `agenteye` | Tu terminal | Quieres ejecutar o automatizar un comando específico |
+| **[Recetas de CLI](/es/agenteye/cli-recipes)** | Patrones de `jq`/pipeline listos para copiar y pegar | Tu terminal / scripts | Estás integrando la CLI en automatizaciones |
+| **Habilidad de CLI** (este doc) | Una puerta de entrada en lenguaje natural a la CLI | Tu agente de codificación, en tu estación de trabajo | Quieres *simplemente preguntar* y dejar que el agente elija el comando |
+| **[Habilidad de evaluador](/es/agenteye/evaluator-skill)** | Una habilidad hermana que diseña y construye tu servicio de puntuación | Tu agente de codificación, en tu estación de trabajo | Quieres *producir* puntuaciones de evaluación en lugar de leerlas |
+| **[Habilidad del SDK de Python](/es/agenteye/python-sdk-skill)** | Una habilidad hermana que instrumenta tu agente para que emita telemetría | Tu agente de codificación, en tu estación de trabajo | Quieres que tu agente *produzca* los eventos que esta habilidad lee |
+| **[Asistente de IA en el dashboard](/es/agenteye/assistant)** | Un chat integrado en el dashboard | Del lado del servidor (en el dashboard) | Quieres hacer preguntas sobre tus datos dentro del dashboard |
+
+La habilidad en sí no tiene privilegios propios; simplemente convierte tus palabras en llamadas a la CLI que se ejecutan como tú:
+
+```mermaid
+flowchart TD
+    YOU["tú: 'acepta el incidente activo'"] --> AGENT["agente de codificación (Claude Code / Codex)<br/>carga la habilidad agenteye-cli"]
+    AGENT --> CLI["agenteye --json incidents ack ..."]
+    CLI -->|tu sesión autenticada de CLI| API["API del dashboard de Observabilidad"]
+```
+
+### vs. el asistente de IA en el dashboard: una distinción importante
+
+Son dos herramientas distintas con radios de acción muy diferentes:
+
+- El **asistente de IA en el dashboard** ([asistente de IA](/es/agenteye/assistant)) es un chat integrado en el dashboard, respaldado por el servicio de agente. Es **de solo lectura más autoría con aprobación**: puede redactar consultas guardadas y dashboards, pero cada escritura se pausa para esperar tu aprobación explícita con un clic, y nunca elimina nada. Requiere el permiso `agent:use` y solo accede a los datos de la organización que estás viendo.
+- La **habilidad de CLI** se ejecuta en *tu* estación de trabajo dentro de *tu* agente de codificación y maneja la `agenteye` CLI **como tú**. Puede realizar la **superficie completa de la CLI, incluidas las mutaciones** (crear/rotar/deshabilitar claves API, cambiar configuraciones de la organización, resolver incidentes, eliminar consultas guardadas), limitada únicamente por los permisos de tu sesión de CLI. Trátala con exactamente el mismo cuidado con el que tratarías ejecutar esos comandos tú mismo.
+
+---
+
+## Requisitos previos
+
+1. La **CLI `agenteye` instalada** y disponible en el `PATH` (consulta la referencia de [CLI](/es/agenteye/cli): `pipx install agenteye`).
+2. Tu **URL del dashboard** configurada (`AGENTEYE_DASHBOARD_URL`, o el agente pasa `--base-url`).
+3. Una **sesión activa**: ejecuta `agenteye login` tú mismo primero. La habilidad **no puede** completar el proceso de inicio de sesión con código de un solo uso enviado por correo; te indicará que ejecutes `agenteye login` si la sesión falta o ha expirado (código de salida `4` de la CLI).
+
+---
+
+## Dónde obtenerla
+
+La habilidad está publicada en la colección pública de habilidades de Failproof AI:
+
+**[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-cli/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-cli)
+
+No hay ninguna restricción de acceso: el repositorio es público y la habilidad no necesita credenciales propias, ya que solo maneja la `agenteye` CLI **pública** contra *tu* dashboard, usando la sesión con la que *tú* iniciaste sesión. No necesitas pedírsela a nadie.
+
+Ten en cuenta que se distribuye como su propia carpeta y **no** está incluida en el paquete `pipx install agenteye`, así que no la busques allí.
+
+## Instalación de la habilidad
+
+La forma más rápida es usando la CLI [`skills`](https://skills.sh), que descarga la carpeta y la coloca donde tu agente la busca:
+
+```bash
+# Claude Code, solo este proyecto
+npx skills add FailproofAI/skills --skill agenteye-cli -a claude-code
+
+# todos los proyectos (instala en ~/.claude/skills/)
+npx skills add FailproofAI/skills --skill agenteye-cli -a claude-code -g --copy
+
+# Codex en su lugar
+npx skills add FailproofAI/skills --skill agenteye-cli -a codex
+```
+
+Luego adminístrala como cualquier otra habilidad:
+
+```bash
+npx skills list -a claude-code      # qué está instalado
+npx skills update agenteye-cli      # obtener la última versión
+npx skills remove agenteye-cli      # eliminarla
+```
+
+¿Prefieres instalarla manualmente? Una Agent Skill es simplemente una carpeta que contiene un `SKILL.md` (más referencias opcionales), así que copiarla también funciona:
+
+- **Claude Code**: coloca la carpeta `agenteye-cli/` en `~/.claude/skills/` (todos los proyectos) o `<tu-repositorio>/.claude/skills/` (solo ese repositorio). Claude Code la descubre automáticamente — verifica con la lista `/skills`, o simplemente haz una pregunta que coincida con su descripción.
+- **Codex (OpenAI)**: Codex lee el mismo `SKILL.md`. El archivo `agents/openai.yaml` incluido configura `allow_implicit_invocation: true`, por lo que Codex selecciona automáticamente la habilidad cuando una tarea coincide; de lo contrario, invócala explícitamente como `$agenteye-cli`.
+
+---
+
+## Seguridad: las mutaciones NO solicitan confirmación cuando un agente ejecuta la CLI
+
+> **Advertencia:** Lee esto antes de permitir que un agente realice cambios.
+
+La `agenteye` CLI normalmente pregunta *«¿estás seguro?»* antes de una acción destructiva. **Omite automáticamente esa confirmación cuando no está conectada a un terminal (que es exactamente cómo la ejecuta un agente de codificación), y `--json` también la omite.** Por lo tanto, el aviso de seguridad **no** se activará para el agente.
+
+La habilidad está diseñada para compensar esto: está instruida para indicar el comando exacto que ejecutará y obtener tu **aprobación explícita antes de cualquier cambio de estado**. Mantén esa disciplina. Cuando manejas Failproof AI Observability a través de un agente, *tú* eres el paso de confirmación. Los comandos que cambian estado a los que debes prestar atención:
+
+- `keys create` / `update` / `disable` / `regenerate`
+- `users create` / `update` / `disable` / `enable`
+- `settings set`
+- `alerts create` / `update` / `delete` / `test`
+- los subcomandos de escritura de `incidents`: `ack` / `assign` / `resolve` / `open` / `comment-add` / `comment-delete` / `subscribe` / `unsubscribe`
+- `query create` / `update` / `delete`
+- `agent rename` / `delete`
+- `orgs switch`
+
+Todo lo que está bajo **Observe** (`events`, `sessions`, `evals`, `errors`, `list`, `whoami`, `orgs list/current/perms`) es de solo lectura y no cambia nada.
+
+Dado que el agente actúa **como tú**, solo puede hacer lo que tu sesión tiene permiso para hacer; los permisos se resuelven **por organización** (consulta [API keys](/es/agenteye/api-keys)). Un comando para el que no tienes permiso devuelve el código de salida `5` con el nombre exacto del permiso requerido, por lo que el agente puede decirte exactamente qué pedirle a un administrador en lugar de fallar de forma opaca.
+
+---
+
+## Qué puedes pedirle
+
+Aquí tienes un ejemplo de una interacción real completa: primero una lectura, luego un cambio que espera tu aprobación:
+
+```text
+tú    ▸ ¿Hay algo roto en el último día?
+
+agente▸ Ejecutando: agenteye --json errors --since 24h --aggregate
+        3 tipos de error en las últimas 24h. El más frecuente es TimeoutError
+        (18 ocurrencias, todas en checkout-agent), luego RateLimited (5).
+        ¿Quieres ver las sesiones fallidas de TimeoutError?
+
+tú    ▸ Dale a CI una clave que solo pueda enviar eventos.
+
+agente▸ Esto crea una clave API. Ejecutaré:
+          agenteye keys create ci --add events:add
+        ¿Procedo?
+
+tú    ▸ sí
+
+agente▸ Listo. Clave "ci" creada con solo events:add.
+        El secreto se muestra una sola vez, así que guárdalo ahora. No puedo volver a mostrarlo.
+```
+
+La habilidad mapea cada intención en lenguaje natural al comando `agenteye` correcto, descubriendo primero los valores válidos (`list <kind>`, `whoami`) para no adivinar, e indicando el comando exacto antes de cualquier cambio. Más ejemplos:
+
+- *«¿Hay algo roto o fallando en las últimas 24 horas?»* → `errors --since 24h --aggregate`, luego un desglose.
+- *«¿Por qué falló la sesión `run-001`?»* → `events --session-id run-001 --all` + `evals --session-id run-001`.
+- *«¿Cómo está evolucionando la calidad esta semana?»* → `evals --aggregate --since 7d`, luego profundizar en las ejecuciones con puntuación baja.
+- *«Dale a CI una clave que solo pueda enviar eventos.»* → `keys create ci --add events:add` (indica el comando, luego lo crea y captura el secreto de un solo uso).
+- *«¿Quién tiene acceso? Dale a Dana permisos de solo lectura.»* → `users list` → `users update dana@… --permission-set read-only` (después de confirmar contigo).
+- *«Acepta el incidente activo y asígnamelo.»* → `incidents list --state firing` → `incidents ack <id>` / `incidents assign <id> you@…`.
+
+Para los comandos exactos, opciones y formatos JSON detrás de estos, consulta la referencia de [CLI](/es/agenteye/cli) y las [recetas de CLI para agentes](/es/agenteye/cli-recipes).
+
+---
+
+## Próximos pasos
+
+- **[CLI](/es/agenteye/cli)**: referencia completa de comandos y opciones de `agenteye`.
+- **[Recetas de CLI para agentes](/es/agenteye/cli-recipes)**: patrones de `jq` listos para copiar y pegar, y manejo de códigos de salida.
+- **[Habilidad del agente evaluador](/es/agenteye/evaluator-skill)**: la habilidad hermana, para construir el evaluador cuyas puntuaciones lee `agenteye evals`.
+- **[Habilidad del agente SDK de Python](/es/agenteye/python-sdk-skill)**: la habilidad hermana, para instrumentar un agente y que emita la telemetría que lee `agenteye`.
+- **[Asistente de IA](/es/agenteye/assistant)**: el asistente integrado en el dashboard (no confundir con esta habilidad de terminal).
+- **[API keys](/es/agenteye/api-keys)**: el modelo de permisos por organización que limita lo que la habilidad puede hacer.