failproofai 1.0.1-beta.0 → 1.0.1

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

@@ -0,0 +1,349 @@
+---
+title: "CLI"
+description: "Gestisci tutta l'osservabilità di Failproof AI dal terminale o da uno script: nessun accesso necessario alla dashboard."
+---
+
+Gestisci tutta l'osservabilità di Failproof AI dal terminale o da uno script: nessun accesso necessario alla dashboard. Il CLI `agenteye` interroga i tuoi dati (sessioni, registri di eventi, valutazioni) e amministra la tua organizzazione (chiavi API, utenti, impostazioni, avvisi, incidenti, query salvate), quindi usalo quando desideri automatizzare un controllo, integrare l'osservabilità in CI, o permettere a un agente di codifica di ispezionare la produzione. Ogni comando supporta un flag `--json`, quindi funziona ugualmente bene per te al prompt o per un agente di codifica (Claude Code, Cursor) che esegue e analizza il risultato.
+
+Con un solo binario puoi:
+
+- **Leggere i tuoi dati**: `sessions`, `events`, `evals`, `errors` (filtra per ora, agente, ambiente, punteggio).
+- **Gestire la tua organizzazione**: `keys`, `users`, `settings`, `alerts`, `incidents`.
+- **Eseguire analitiche**: SQL salvate e un motore di query ad hoc (`query`).
+- **Chiedere all'assistente AI**: lo stesso analista di sola lettura con cui chatti nella dashboard (`agent`).
+
+> **Nota:** Questo è il CLI `agenteye`, uno strumento diverso dal daemon del collettore (`agenteye-collector`). Il CLI comunica con la tua dashboard; il collettore invia gli eventi al server.
+
+---
+
+## Avvio rapido
+
+Dai nulla al tuo primo risultato in quattro righe. Punta il CLI sulla tua dashboard, accedi, conferma chi sei, quindi estrai l'ultimo giorno di esecuzioni:
+
+```bash
+pipx install agenteye
+agenteye --base-url https://agenteye.example.com login --email you@example.com   # codice a 6 cifre inviato per email
+agenteye whoami                                                                  # conferma utente + organizzazione attiva
+agenteye --json sessions --since 24h                                             # una riga per esecuzione agente, ultimi 24h
+```
+
+Questo ultimo comando stampa un oggetto JSON delle sessioni più recenti (dal più recente al meno recente, limitato a 50 per impostazione predefinita). Indirizzalo in `jq` per affettarlo, o elimina `--json` per una tabella colorata e riquadrata. Ogni riga riporta lo stato dell'esecuzione e, se un valutatore l'ha valutata, i punteggi delle sue metriche (abbreviati qui):
+
+```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
+}
+```
+
+Il resto di questa pagina spiega ogni aspetto: [installazione](#installation) in isolamento, [accesso](#authentication), [configurazione](#configuration), le [convenzioni globali](#global-options--conventions) che ogni comando condivide, e il [riferimento completo dei comandi](#command-reference).
+
+---
+
+## Installazione
+
+Il CLI è un pacchetto PyPI pubblico denominato **`agenteye`**. Installalo in un ambiente isolato in modo che abbia sempre le sue dipendenze:
+
+```bash
+pipx install agenteye
+# o
+uv tool install agenteye
+```
+
+Richiede Python 3.10+. Il comando installato è **`agenteye`**:
+
+```bash
+agenteye --version
+agenteye --help
+```
+
+> **Nota:** L'SDK Python di Failproof AI Observability utilizza anche il nome di distribuzione `agenteye`. L'installazione del CLI con `pipx` o `uv tool` (piuttosto che `pip install` in un virtualenv condiviso) impedisce conflitti tra i due. Un semplice `pip install agenteye` va bene solo se l'SDK non è installato nello stesso ambiente.
+
+---
+
+## Autenticazione
+
+Il CLI si autentica alla **dashboard** con un codice monouso inviato per email:
+
+```bash
+agenteye login --email you@example.com
+# Un codice a 6 cifre ti viene inviato per email; incollalo al prompt.
+```
+
+Il token di sessione viene archiviato in `~/.agenteye/cli.json` (leggibile solo da te, modalità `0600`) ed è valido per 24 ore per impostazione predefinita. Quando scade, esegui di nuovo `agenteye login`.
+
+```bash
+agenteye whoami     # mostra l'utente corrente, l'organizzazione attiva e i permessi
+agenteye logout     # revoca la sessione e cancella il token archiviato
+```
+
+`whoami` non genera mai errori per una sessione mancante o scaduta; invece riporta `logged_in: false`, quindi uno script o agente può controllare lo stato di autenticazione in sicurezza (può comunque uscire con codice diverso da zero se nessuna URL di base è impostata o la dashboard non è raggiungibile).
+
+**Requisiti:** la tua email deve essere autorizzata ad accedere alla dashboard (chiedi all'amministratore di Failproof AI Observability), e la dashboard deve essere raggiungibile al suo URL di base (vedi [Configurazione](#configuration)). Se richiedi un codice e nessuno arriva, probabilmente la tua email non è ancora abilitata per l'accesso alla dashboard.
+
+---
+
+## Scelta della tua organizzazione (multi-tenant)
+
+Se il tuo account appartiene a più di un'organizzazione, scegli quello attivo **al login**; viene salvato e utilizzato per ogni comando successivo:
+
+```bash
+agenteye login --org acme           # autentica e imposta il tenant attivo in un passaggio
+agenteye orgs list                  # le organizzazioni a cui puoi accedere (quella attiva è contrassegnata)
+agenteye orgs switch globex         # cambia il valore predefinito salvato
+agenteye --org globex sessions      # ignora per un singolo comando
+```
+
+Se appartieni a esattamente un'organizzazione viene selezionata automaticamente e puoi ignorare completamente `--org`. Se appartieni a più organizzazioni e non ne scegli una, il CLI le elenca e ti chiede di eseguire di nuovo con `--org <slug>`. L'organizzazione attiva viene inviata alla dashboard ad ogni richiesta, e i tuoi permessi vengono risolti **per organizzazione**; `agenteye whoami` mostra l'organizzazione attiva, i tuoi permessi in essa, e tutti i tuoi memberships.
+
+---
+
+## Configurazione
+
+| Impostazione | Flag | Variabile di ambiente | Valore predefinito |
+|---|---|---|---|
+| URL di base della dashboard | `--base-url` | `AGENTEYE_DASHBOARD_URL` | **obbligatorio** (nessun valore predefinito) |
+| Organizzazione/tenant attivo | `--org` | `AGENTEYE_ORG` | scelto al login; salvato in `~/.agenteye/cli.json` |
+| Token di sessione | `--token` | `AGENTEYE_CLI_TOKEN` | da `~/.agenteye/cli.json` |
+| Output JSON | `--json` | `AGENTEYE_CLI_JSON` | disattivato |
+| Salta verifica TLS | `--insecure` / `--secure` | `AGENTEYE_INSECURE` | disattivato (salvato al login) |
+| Timeout richieste (secondi) | `--timeout` | _(nessuno)_ | 30 |
+| Disabilita telemetria di utilizzo | _(nessuno)_ | `AGENTEYE_ANALYTICS_DISABLED` (o `DO_NOT_TRACK`) | la telemetria è attualmente disabilitata; nulla viene inviato |
+
+L'ordine di risoluzione è **flag → variabile di ambiente → file di configurazione**. Non c'è valore predefinito; devi puntare il CLI sulla tua dashboard, sia per comando (`--base-url https://agenteye.example.com`) che una volta tramite l'ambiente (viene anche salvato dopo il tuo primo `login`):
+
+```bash
+export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com
+```
+
+La directory di configurazione rispetta `AGENTEYE_HOME` (la stessa convenzione utilizzata dall'SDK e dal collettore); se impostato, `cli.json` si trova in `$AGENTEYE_HOME/cli.json`.
+
+### TLS autofirmato o interno
+
+Se la tua dashboard è servita su HTTPS con un certificato autofirmato o interno (ad esempio, un nome host di bilanciamento del carico non elaborato), la verifica TLS lo rifiuta con un errore `CERTIFICATE_VERIFY_FAILED`. Passa `--insecure` per saltare la verifica del certificato:
+
+```bash
+agenteye --base-url https://agenteye.internal --insecure login
+```
+
+`--insecure` è **salvato in `cli.json` quando accedi**, quindi i comandi successivi saltano la verifica automaticamente; non devi ripetere il flag. Passa `--secure` per una singola chiamata verificata, o per salvare la verifica di nuovo al tuo prossimo login. Il CLI stampa un avviso a stderr prima di qualsiasi comando che contatta la dashboard mentre la verifica è disabilitata. Saltare la verifica rimuove la protezione contro gli attacchi man-in-the-middle; assicurati di fidarti del percorso di rete verso la tua dashboard (VPN, subnet privata, ecc.) prima di affidarti ad essa.
+
+---
+
+## Telemetria e privacy
+
+> **Nota:** Il CLI spedito **non invia alcuna telemetria di utilizzo oggi.** Un interruttore di disabilitazione principale è attivato, quindi nulla viene trasmesso indipendentemente dal tuo ambiente. La sezione sottostante descrive la capacità di esclusione per se e quando la telemetria fosse mai abilitata.
+
+Anche se abilitata, la telemetria sarebbe **solo analitiche di utilizzo anonime**, mai i tuoi dati di agente, sessione o evento:
+
+- **Nessun dato di agente, sessione o evento lascia mai la tua infrastruttura.** Solo l'utilizzo del CLI verrebbe segnalato: il nome del comando e sottocomando (ad esempio `keys create`), i **nomi** dei flag che hai usato (mai i loro valori), stato di successo/uscita e durata, più un evento per-azione per le mutazioni (ad esempio `api_key_created`, `query_run`) contenente solo nomi/enum statici e conteggi grossolani. L'URL della tua dashboard, il token di sessione, l'email, lo slug dell'organizzazione, gli id delle risorse, SQL, i segreti delle chiavi e i filtri delle query non verrebbero **mai** inviati. Gli operatori sarebbero identificati solo da un id interno opaco, mai per email.
+- **Escludi in anticipo** impostando `AGENTEYE_ANALYTICS_DISABLED=1` nell'ambiente del CLI (il CLI rispetta anche la convenzione cross-tool `DO_NOT_TRACK=1`). Questo entra in vigore nel momento in cui la telemetria viene mai attivata, quindi un ambiente consapevole della privacy può rimanere escluso in modo permanente.
+- Se la telemetria fosse abilitata, il CLI invierebbe direttamente a PostHog (`https://us.i.posthog.com`); una macchina con quell'host bloccato non invierebbe silenziosamente nulla e il CLI ne sarebbe illeso.
+
+---
+
+## Opzioni globali e convenzioni
+
+Leggi questa sezione una volta; si applica a ogni comando.
+
+- **Le opzioni globali vanno PRIMA del comando.** `agenteye --json sessions` è corretto; `agenteye sessions --json` è un errore di utilizzo. I globali sono `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, e `--no-color`.
+- **`--json` stampa pure JSON su stdout, e nulla di più.** Le righe di stato umano, gli avvisi e gli errori vanno su **stderr**, quindi un'acquisizione di stdout `--json` rimane pulita da indirizzare in `jq` anche quando viene mostrata una riga di stato. Senza `--json` ottieni una visualizzazione riquadrata e colorata per gli occhi umani.
+- **Scopri con `--help`.** Ogni comando e sottocomando ha `--help` (e l'alias `-h`): `agenteye -h`, `agenteye sessions -h`, `agenteye keys create -h`. L'aiuto di primo livello elenca anche i codici di uscita e le opzioni globali. Non c'è dump di superficie leggibile da macchina globale; usa per-comando `--help`, più il dominio-specifico `agenteye query schema` e `agenteye settings schema` per quei due registri.
+- **Le conferme auto-saltano per script e agenti.** I comandi create/update/delete chiedono "sei sicuro?" in un terminale interattivo, ma **auto-saltano quel prompt sotto `--json` o quando stdin non è un TTY** (un TTY è una sessione di terminale interattiva; una pipe o un runner CI non lo è), quindi script e agenti non rimangono mai bloccati. Passa `--yes`/`-y` per saltarlo esplicitamente. Poiché il prompt non si attiva per un agente, un agente dovrebbe confermare le azioni distruttive con l'umano per primo.
+- **Paginazione:** i risultati sono dal più recente al meno recente e paginati per cursore (ogni pagina restituisce un token che usi per recuperare il prossimo). `--limit N` (alias `-n`) limita le righe e **preimposta a 50**; `--all` auto-pagina (in chunk di 200 righe) **fino a `--limit`**, quindi un bare `--all` si ferma ancora a 50. Per un sweep completo passa un limite esplicito alto: `--all --limit 1000`. `--page-size N` controlla il chunk per-richiesta (max 200); `--cursor <id>` riprende dal `next_cursor` di una pagina precedente.
+- **Filtri di tempo:** `--since` accetta una finestra relativa: `15m`, `1h`, `6h`, `24h`, `7d`, o `all` (i preset della dashboard). Per un intervallo più lungo o personalizzato (diciamo gli ultimi 30 giorni), usa `--from`/`--to`: timestamp UTC ISO-8601 espliciti **con `T` e un fuso orario** (ad esempio `2026-06-01T00:00:00Z`) che ignorano `--since`. Un valore separato da spazi o senza fuso orario è un errore di utilizzo.
+- **`--fields a,b,c`** (su `events`, `sessions`, `evals`, `errors`) limita l'output a quelle chiavi, sia per la tabella che per `--json`. I nomi sconosciuti vengono rifiutati con l'elenco valido, un modo economico per scoprire i nomi dei campi.
+- **`--file payload.json`** (o `--file -` per leggere stdin) fornisce un corpo di richiesta JSON completo dove una risorsa ha una forma complessa (su `alerts create/update`, `settings set`, e `users create/update`). SQL di query salvate usa `--sql @file.sql` invece.
+- **I filtri multi-valore** sono comma-separated → abbinati come un insieme (unione all'interno di un filtro, AND tra i filtri): `--event-type tool_use,tool_result`. Le opzioni click non sono variadiche, quindi `--add a b` si rompe. Usa `--add a,b`, ripeti il flag (`--add a --add b`), o circonda con virgolette (`--add "a b"`).
+
+---
+
+## Riferimento dei comandi
+
+### Userai questi 5 comandi più spesso
+
+La maggior parte del lavoro quotidiano viene eseguita attraverso una manciata di comandi di lettura. Inizia qui, quindi raggiungi la superficie completa sottostante quando ne hai bisogno:
+
+| Comando | Cosa fa | Provalo |
+|---|---|---|
+| `sessions` | Una riga per esecuzione agente: ora, ambiente, agente, stato, punteggio più recente. | `agenteye --json sessions --since 24h --status error` |
+| `events` | La traccia grezza per step dentro un'esecuzione (aggiungi `--full` per i payload). | `agenteye --json events --session-id run-001 --all` |
+| `evals` | Risultati di valutazione e punteggi; `--aggregate` li raggruppa. | `agenteye --json evals --aggregate --since 7d --env prod` |
+| `errors` | Solo gli eventi con errore; `--aggregate` per conteggi per tipo. | `agenteye --json errors --since 24h --aggregate` |
+| `list` | Scopri i valori di filtro validi (agenti, ambienti, modelli, …). | `agenteye list agents` |
+
+### Tutto quello che il CLI può fare
+
+La superficie completa segue. Il CLI ha **18 comandi di primo livello**. Tutti i comandi di lettura accettano `--json` e le opzioni globali sopra; esegui `agenteye <command> -h` (o `<command> <subcommand> -h`) per l'elenco di flag esaustivo e la forma JSON di uno qualsiasi.
+
+### Identità: `login` · `logout` · `whoami` · `orgs` · `version` · `help`
+
+```bash
+agenteye login --email you@example.com [--org acme]   # codice monouso inviato per email; salva la sessione
+agenteye logout                                       # cancella la sessione salvata su questa macchina
+agenteye whoami                                       # utente corrente, organizzazione attiva, permessi
+agenteye version                                      # stampa la versione del CLI (come --version)
+agenteye help                                         # aiuto di primo livello (come --help)
+```
+
+`orgs` ispeziona e cambia il tenant attivo:
+
+```bash
+agenteye orgs list        # le tue organizzazioni + il tuo ruolo in ciascuna (quella attiva è contrassegnata)
+agenteye orgs switch acme # cambia l'organizzazione attiva salvata (ometti lo slug per scegliere da un elenco su un TTY)
+agenteye orgs current     # carta di identità per l'organizzazione attiva
+agenteye orgs perms       # i tuoi permessi nell'organizzazione attiva, raggruppati per risorsa
+```
+
+### Osserva (sola lettura): `events` · `sessions` · `evals` · `errors` · `list`
+
+Nessuno di questi ha bisogno di una conferma. Filtri condivisi: `--session-id`, `--agent-id`, `--env` (**non** `--environment`), e l'intervallo di tempo (`--since` / `--from` / `--to`).
+
+```bash
+# events (alias: la traccia grezza per step), dal più recente al meno recente
+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 riga per esecuzione agente (ora/ambiente/agente/sessione/stato; nessun filtro di punteggio)
+agenteye --json sessions --since 24h --status error
+agenteye --json sessions --agent-id checkout-bot --env prod --all --limit 1000
+
+# evals: risultati di valutazione + punteggi; --score filtra per metrica, --aggregate raggruppa
+agenteye --json evals --score helpfulness:0.5..0.8 --score tool_efficiency:..0.3
+agenteye --json evals --aggregate --since 7d --env prod        # mix di stato + stats di punteggio per chiave
+
+# errors: eventi con errore; --aggregate per conteggi/sessioni/agenti/ultimo-visto
+agenteye --json errors --since 24h --aggregate
+agenteye --json errors --since 24h --error-type timeout --all --limit 1000
+
+# list: scopri i valori di filtro validi prima di filtrare
+agenteye list envs        # inoltre: agents event_types score_filters models hooks tools error_types
+```
+
+`--score KEY:MIN..MAX` (su **`evals`**, non `sessions`) è ripetibile e AND-combinato; entrambi i limiti sono opzionali (`..0.5` significa ≤ 0.5, `0.9..` significa ≥ 0.9). Fino a 20 filtri di punteggio per richiesta. `evals --scores-full` è un flag di visualizzazione per la **tabella umana solamente**; mostra ogni coppia di punteggio invece dei primi pochi più un conteggio `+N`. Non ha effetto sotto `--json`, che restituisce sempre l'oggetto di punteggio completo. Per leggere **una sessione end-to-end**, combina la traccia di evento con la sua valutazione:
+
+```bash
+agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}'
+agenteye --json evals  --session-id run-001                       # i suoi punteggi + stato
+```
+
+### Gestisci (gated da permessi): `keys` · `users` · `settings` · `alerts` · `incidents`
+
+**`keys`**: chiavi API. Il segreto viene generato localmente, inviato al server (che memorizza solo un hash), e **mostrato una volta** su create/regenerate; catturalo allora. Con `--json` appare solo nel campo `key`. Referenziato per **nome**.
+
+```bash
+agenteye keys list                                   # chiavi attive per prime, poi revocate
+agenteye keys show ci-bot
+agenteye keys create ci-bot --add events:read.add    # circoscrivi a quello di cui hai bisogno; stampa il segreto UNA VOLTA
+agenteye keys create ops --permission-set standard --remove queries:run   # semina un preset, poi taglia
+agenteye keys update ci-bot --add evaluations:read --yes
+agenteye keys regenerate ci-bot --yes                # ruota il segreto (quello vecchio smette di funzionare)
+agenteye keys disable ci-bot --yes                   # revoca
+```
+
+I permessi funzionano come `(permission-set ∪ --add) − --remove`. I token sono `slug:action` (ad esempio `events:read`) o `slug:action.action` per espandere diversi su una risorsa (`events:read.add` → `events:read`, `events:add`). Preset: `read-only`, `standard`, `admin`. I permessi solo per umani (`keys:update`) non possono essere concessi a una chiave.
+
+**`users`**: membri dell'organizzazione, referenziati per **email** (è anche accettato un id UUID).
+
+```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 + conferma
+agenteye users disable dev@corp.com --yes            # ha protezioni/guardie di se stesso
+agenteye users enable dev@corp.com
+```
+
+**`settings`**: un registro fisso (leggi e cambia le chiavi esistenti; non puoi crearne di nuove).
+
+```bash
+agenteye settings list                               # chiave · valore · tipo · aggiornato (segreti mascherati)
+agenteye settings schema                             # cosa accetta ogni chiave (tipo · intervallo · descrizione)
+agenteye settings set session_ttl_secs --value 86400 --yes
+```
+
+**`alerts`**: definizioni di avviso, referenziate per **nome**. `create` accetta un NAME posizionale più flag o un corpo JSON completo via `--file`.
+
+```bash
+agenteye alerts list
+agenteye alerts show high-errors
+agenteye alerts create high-errors --file alert.json          # NAME è obbligatorio (posizionale)
+agenteye alerts update high-errors --severity critical --yes
+agenteye alerts test high-errors --yes                        # attiva una notifica di test
+agenteye alerts delete high-errors --yes
+```
+
+**`incidents`**: incidenti di avviso, referenziati per id (id brevi accettati). `show` stampa il registro completo di attività; leggi prima di agire.
+
+```bash
+agenteye incidents list --state firing                # inoltre: acknowledged, resolved
+agenteye incidents count
+agenteye incidents show <id>
+agenteye incidents ack <id>
+agenteye incidents assign <id> you@corp.com           # l'assegnatario deve essere un operatore
+agenteye incidents resolve <id> --yes
+agenteye incidents open --alert-id <id> --severity critical    # aprine uno manualmente contro un avviso
+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>
+```
+
+### Analitiche e assistente: `query` · `agent`
+
+**`query`**: SQL salvato contro il tuo store di analitiche più un runner ad hoc. Le query salvate sono referenziate per **nome**; l'SQL viene validato lato server (solo SELECT/WITH, timeout di statement, cap di riga).
+
+```bash
+agenteye query schema [TABLE]                         # layout di colonna delle viste analitiche
+agenteye query run --sql "select count(*) from analytics.events"
+agenteye query run errs --arg prod --limit 100        # esegui una query salvata + un positivo $1
+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`**: parla con l'**assistente AI** incorporato (lo stesso analista di sola lettura con cui puoi chattare nella dashboard). Le chat sono referenziate da uno short chat-id (risoluzione dei prefissi).
+
+```bash
+agenteye agent health                                 # l'assistente AI è configurato/raggiungibile
+agenteye agent models                                 # modelli che puoi passare a --model (predefinito contrassegnato)
+agenteye agent ask "which agents errored most in the last day?"    # avvia una chat; stampa il suo short id
+agenteye agent ask --chat <short-id> "and which tools did they call?"   # continua quella chat
+agenteye agent chats ; agenteye agent show <short-id>
+agenteye agent rename <short-id> --title "error triage" ; agenteye agent delete <short-id>
+```
+
+---
+
+## Codici di uscita
+
+| Codice | Significato |
+|---|---|
+| 0 | Successo |
+| 1 | Errore inaspettato (ad esempio la dashboard ha restituito un 5xx) |
+| 2 | Errore di utilizzo (argomenti non validi, comando/flag sconosciuto, collisione di nome) |
+| 3 | Non è possibile raggiungere la dashboard |
+| 4 | Non hai effettuato l'accesso o la sessione è scaduta; esegui `agenteye login` |
+| 5 | Autenticato, ma il tuo account manca del permesso richiesto (il messaggio lo nomina) |
+| 6 | La risorsa richiesta non è stata trovata (ad esempio id di sessione o incidente sconosciuto) |
+
+Questi rendono il CLI sicuro per scripting: un agente di codifica può dirammarsi su un `4` per chiederti di ri-autenticarti, o un `5` per visualizzare il permesso mancante. Vedi [Ricette CLI per agenti](/it/agenteye/cli-recipes) per gestione dei codici di uscita e forme di output JSON.
+
+---
+
+## Prossimi passaggi
+
+- **[Ricette CLI per agenti](/it/agenteye/cli-recipes)**: pattern di query copia-incolla, one-liner `jq`, proiezioni `--fields`, gestione dei codici di uscita, e forme di output JSON, scritti per agenti di codifica che guidano il CLI.
+- **[Skill agent CLI](/it/agenteye/cli-skill)**: compacchia questo CLI come una *skill* installabile di Claude Code / Codex in modo che un agente di codifica guidi l'osservabilità di Failproof AI da richieste in linguaggio naturale.
+- **[Chiavi API](/it/agenteye/api-keys)**: il modello di permessi dietro `keys create --add …`.
+- **[Assistente AI](/it/agenteye/assistant)**: abilitazione dell'assistente con cui `agent ask` parla.

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

@@ -0,0 +1,56 @@
+---
+---
+title: "Acquisizione di sessioni Codex"
+description: "Integra le sessioni locali di OpenAI Codex del tuo team in AgentEye come sessioni ed eventi ordinari — senza cambiare il modo in cui eseguono Codex."
+---
+
+I tuoi ingegneri usano già OpenAI Codex ogni giorno. L'acquisizione di sessioni Codex porta quelle sessioni di programmazione in AgentEye come sessioni ed eventi ordinari, così puoi cercarle, riprodurle e valutarle insieme a tutto il resto che osservi. Complementa l'[SDK Python](/it/agenteye/python-sdk): l'SDK strumenta gli agenti che scrivi, mentre questo cattura il lavoro Codex che il tuo team fa già — senza cambiare il modo in cui lo eseguono.
+
+Un piccolo collettore in background legge i trascritti delle sessioni locali di Codex man mano che vengono scritti e li invia ad AgentEye. Un collettore per macchina cattura ogni superficie Codex locale contemporaneamente — non è necessaria una configurazione per ogni superficie.
+
+Lo stesso collettore cattura anche altri agenti — vedi [OpenClaw](/it/agenteye/openclaw-capture) e [Hermes](/it/agenteye/hermes-capture). Abilita ciascuno che esegui; un singolo collettore può catturarne diversi contemporaneamente.
+
+---
+
+## Cosa cattura
+
+Ogni superficie Codex che viene eseguita **localmente** produce gli stessi trascritti di sessione su disco, e il collettore li cattura tutti:
+
+- il **CLI** di Codex e `codex exec`
+- l'**estensione VS Code / IDE**
+- l'**app desktop**, quando esegue una sessione localmente
+
+Ogni sessione Codex diventa una [sessione](/it/agenteye/sessions) di AgentEye; i suoi messaggi utente e assistente, il ragionamento, le chiamate agli strumenti, i risultati degli strumenti e l'utilizzo dei token diventano gli [eventi](/it/agenteye/event-stream) corrispondenti. La superficie da cui proviene ogni sessione (CLI, IDE o desktop) viene registrata, così puoi distinguerle.
+
+> **Le sessioni cloud non vengono catturate.** L'app desktop esegue sempre più spesso le sessioni nel cloud Codex e mantiene solo i loro metadati sulla macchina — non c'è un trascritto locale da leggere. Solo le sessioni eseguite localmente vengono catturate.
+
+---
+
+## Attivalo
+
+L'acquisizione è disabilitata finché non la abiliti. Installa il collettore con una chiave API che dispone del permesso `events:add` (vedi [Chiavi API](/it/agenteye/api-keys)), e attiva l'acquisizione di Codex:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \
+  | sh -s -- --key <YOUR_API_KEY> --codex-enabled
+```
+
+Questo installa il collettore, lo registra come servizio in background e avvia l'acquisizione. Verifica che sia in esecuzione:
+
+```bash
+agenteye-collector health
+```
+
+Al primo avvio, le tue sessioni Codex esistenti vengono riprese una volta e la nuova attività quindi viene trasmessa in streaming in pochi secondi. I file di Codex vengono letti solo — mai modificati, spostati o eliminati — e ogni sessione viene inviata esattamente una volta, anche tra i riavvii.
+
+---
+
+## Dove viene visualizzato
+
+Le sessioni catturate appaiono in **Sessions** e i loro eventi nel flusso **Events**, come per qualsiasi altro agente che osservi — quindi la [riproduzione delle sessioni](/it/agenteye/sessions), la [ricerca](/it/agenteye/queries), le [valutazioni](/it/agenteye/evaluations) e gli [avvisi](/it/agenteye/alerts) funzionano tutti su di esse. Filtra per l'agente Codex per vederle da sole.
+
+---
+
+## Privacy
+
+I trascritti di Codex contengono la sessione completa — incluso l'output dei comandi, i contenuti dei file e tutto ciò che Codex ha letto o scritto — e possono contenere segreti. Le sessioni catturate vengono inviate così come sono, quindi abilita l'acquisizione solo su macchine e per team dove centralizzare quel contenuto in AgentEye è appropriato, e dai al collettore una chiave ristretta a `events:add` solo. Vedi [Security](/it/agenteye/security) per vedere come i tuoi dati vengono mantenuti isolati.

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

@@ -0,0 +1,87 @@
+---
+title: "Concetti"
+description: "Il vocabolario dietro Failproof AI Observability — eventi, sessioni, valutazioni, audit, risultati e incidenti — definiti in un unico posto."
+---
+
+
+Questa pagina definisce il vocabolario usato da Failproof AI Observability. Se un termine in un'altra guida ti risulta sconosciuto, la sua definizione si trova qui. Non è necessario leggerla da cima a fondo: puoi scorrerla o tornare quando incontri una parola di cui vuoi precisare il significato.
+
+---
+
+## Il modello dei dati
+
+**Event**
+L'unità più piccola di dati. Un event registra un singolo step che il tuo agente ha eseguito: un `tool_use`, una `model_request`, un `hook_completed`, un `error`, e così via. Il tuo agente emette event attraverso [Python SDK](/it/agenteye/python-sdk); vengono visualizzati in tempo reale nella pagina **Events**.
+
+**Session**
+Un'esecuzione dell'agente, identificata da un `session_id`. Una session è l'insieme di tutti gli event che condividono quell'id, riepilogati in una singola riga nella pagina **Sessions** e disegnati come grafo di esecuzione nella sua pagina di dettaglio. Una session solitamente inizia con `agent_start` e termina con `agent_end`.
+
+**Agent**
+Un attore nominato all'interno di un'esecuzione, identificato da un `agent_id`. Un'esecuzione può coinvolgere diversi agenti: ad esempio un planner che genera un sub-agente summarizer. I sub-agenti contengono un `parent_id`, che consente a Failproof AI Observability di disegnarli su corsie separate nel grafo di esecuzione.
+
+**Environment**
+Un'etichetta per il luogo dove l'esecuzione è avvenuta: `production`, `staging`, `dev`. La configuri una sola volta quando imposti l'SDK. Quasi tutte le pagine del dashboard possono filtrare per environment.
+
+**Context-window fill**
+La percentuale della finestra di contesto di un modello che una risposta ha consumato. Failproof AI Observability la registra negli event `model_response` per i modelli che riconosce, in modo che la crescita del prompt e la imminente compattazione siano visibili direttamente nel flusso degli event.
+
+---
+
+## Qualità
+
+**Evaluation**
+Un punteggio di qualità per una session completata, prodotto da un servizio di scoring che gestisci. Le evaluation sono opzionali: finché non colleghi un evaluator, le session vengono registrate ma non valutate. Ogni evaluation può contenere diversi punteggi denominati (ad esempio `helpfulness`, `factuality`, `tool_efficiency`), ognuno con una breve nota di motivazione. Vedi [Evaluation suite](/it/agenteye/evaluation-suite).
+
+**Score key**
+Il nome di una dimensione che un evaluator riporta, come `helpfulness`. Gli alert e gli audit possono monitorare uno score key specifico nel tempo.
+
+**Evaluator**
+Il tuo servizio di scoring. Failproof AI Observability effettua un POST della trascrizione di un'esecuzione completata e memorizza i punteggi che restituisce. Non fornisce un evaluator predefinito; la logica di scoring è tua.
+
+---
+
+## Trovare e risolvere i guasti
+
+**Hook**
+Un guardrail o effetto collaterale che il tuo framework di agenti esegue attorno a uno step: un controllo di sicurezza dei contenuti, redazione della PII, un budget guard. Gli hook emettono event `hook_triggered` / `hook_completed` con un `outcome` (allow, deny, modify), e hanno una propria pagina di observe.
+
+**Alert rule**
+Una regola che si attiva quando una metrica supera una soglia che hai impostato: error rate, p95 latency, costo in token, o un punteggio di un evaluator. Quando una regola si attiva, apre un incident e notifica i tuoi canali scelti (email, Slack, webhook, in-dashboard). Vedi [Alerts](/it/agenteye/alerts).
+
+**Incident**
+Una questione aperta creata quando un'alert rule si attiva. Gli incident hanno un ciclo di vita (acknowledge, assign, resolve) e una timeline di attività che registra ogni azione. Puoi anche aprirne uno manualmente.
+
+**Audit**
+Un'indagine ricorrente (oraria fino settimanale) che estrae dai tuoi log *tra* le session i pattern di guasto che non hai scritto una regola per: cluster di errori, punteggi bassi, outlier di latenza, loop di chiamate tool, ed esecuzioni che non sono mai terminate. Dove un alert monitora una metrica che già conosci, un audit ti dice cosa guardare dopo. Vedi [Audits](/it/agenteye/audits).
+
+**Finding**
+Un risultato classificato e supportato da prove ottenuto da un'esecuzione di audit. Un finding nomina un pattern, si collega alle exact session dietro di esso, e ha un ciclo di vita di triage (acknowledge, resolve, mute, dismiss). Failproof AI Observability deduplica i finding di esecuzione in esecuzione così un pattern noto si aggiorna invece di accumularsi.
+
+**The AI assistant**
+La chat in-dashboard che risponde a domande sui tuoi agenti in linguaggio naturale, sui tuoi dati. È read-only per impostazione predefinita; qualsiasi cosa creer (una query salvata, un dashboard) è soggetta a approvazione, e non potrà mai eliminare. Vedi [AI assistant](/it/agenteye/assistant).
+
+---
+
+## Eseguirlo
+
+**Organization (tenant)**
+Uno spazio di lavoro isolato. Un'istanza di Failproof AI Observability può ospitare molte organizzazioni, ognuna con i propri utenti, chiavi e dati. Ogni URL del dashboard è scoped sotto il tuo slugname dell'org (`/<org-slug>/…`).
+
+**Collector**
+`agenteye-collector`, il daemon leggero che gira su ogni macchina con agenti, raggruppa gli event che l'SDK scrive su disco, e li spedisce al server.
+
+**API key**
+Un token scoped che autentica un client rispetto al server. Le chiavi portano permessi granulari (ad esempio `events:add` per il collector, scope read-only per una dashboard key). Vedi [API keys](/it/agenteye/api-keys).
+
+**Server**
+Il servizio di ingest e API. Ingerisce gli event, memorizza lo stato operativo nei tuoi database, e serve il dashboard e la CLI.
+
+**Dashboard**
+L'interfaccia web. Ogni pagina è scoped a un'organizzazione e legge attraverso l'API del server.
+
+---
+
+## Prossimi step
+
+- [Overview](/it/agenteye/overview): come questi pezzi si incastrano insieme.
+- [Observability](/it/agenteye/observability): le superfici di observe (Events, Sessions, Models, Tools, Hooks, Errors).

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

@@ -0,0 +1,46 @@
+---
+title: "Dashboard"
+description: "Trasforma i tuoi dati live degli agent in un'unica vista condivisa che tutto il team monitora."
+---
+
+
+Trasforma i tuoi dati live degli agent in un'unica vista condivisa che tutto il team monitora. Fissa le query che contano come grafici, e tutti vedono gli stessi numeri a colpo d'occhio, senza rieseguire una singola query.
+
+![Un dashboard creato da query salvate: una linea eventi-per-ora, un grafico a barre errori-per-tipo, un grafico ad area di latenza e token-per-modello](/agenteye/images/dashboard-fleet.png)
+
+*Una sola board, quattro query salvate: eventi per ora, errori per tipo, latenza e token per modello.*
+
+## Tutti vedono la stessa realtà
+
+Smetti di incollare screenshot in chat e smetti di rieseguire la stessa query cinque volte al giorno. Un dashboard è una board condivisa a livello organizzativo che chiunque nel tuo team può aprire per vedere esattamente la stessa vista. Quando i dati sottostanti cambiano, i grafici si muovono con loro, quindi la board è sempre aggiornata e nessuno discute su numeri obsoleti.
+
+Il fleet dashboard qui sopra è una buona forma iniziale per le operazioni quotidiane:
+
+- una linea **eventi-per-ora**, così puoi monitorare il throughput e catturare un calo improvviso
+- un grafico a barre **errori-per-tipo**, così le tue maggiori categorie di fallimento spicchiano
+- un grafico ad area **latenza**, così i rallentamenti emergono prima che gli utenti se ne lamentino
+- una scomposizione **token-per-modello**, così i costi rimangono visibili
+
+Troverai i tuoi dashboard su `/<org-slug>/dashboards`.
+
+## Fissa le query che hai già salvato
+
+Ogni tile inizia come una query salvata. Costruisci e salva la query che ti interessa nella libreria [Query](/it/agenteye/queries) (preset incorporati più i tuoi, sui tuoi eventi e valutazioni), quindi fissala a un dashboard come il grafico che si adatta ai dati: una **linea** per le tendenze nel tempo, un **grafico a barre** per confrontare categorie, un **grafico ad area** per il volume, o una **torta** per una scomposizione percentuale.
+
+Poiché una tile è solo la tua query salvata resa come grafico, non c'è nulla da sincronizzare manualmente. Aggiorna la query una volta e ogni dashboard che la utilizza si aggiorna automaticamente.
+
+## Monitora la qualità, non solo il volume
+
+Il volume ti dice che gli agent sono occupati. La qualità ti dice che stanno effettivamente svolgendo il lavoro. Punta un dashboard ai tuoi [punteggi di valutazione](/it/agenteye/evaluations) e ottieni una board che traccia quanto bene stanno andando le esecuzioni nel tempo, così una regressione di qualità appare come un calo su un grafico invece di una sorpresa da un cliente.
+
+![Un dashboard focalizzato sulla qualità costruito da query di valutazione salvate](/agenteye/images/dashboard-quality.png)
+
+*Una board di qualità mantiene i tuoi punteggi di valutazione in primo piano, proprio accanto ai numeri operativi.*
+
+Tieni una board di operazioni e una board di qualità affiancate e il tuo team ha un unico posto per rispondere sia a "sta funzionando?" che a "è buono?", senza che nessuno riesegua una query.
+
+## Correlati
+
+- [Query](/it/agenteye/queries): costruisci e salva le query che diventano le tue tile.
+- [Valutazioni](/it/agenteye/evaluations): valuta le tue esecuzioni così puoi tracciare la qualità nel tempo.
+- [Avvisi](/it/agenteye/alerts): trasforma una soglia su una qualsiasi di queste metriche in un alert.

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

@@ -0,0 +1,41 @@
+---
+title: "Tracciamento degli errori"
+description: "Visualizza tutti gli errori prodotti dai tuoi agenti in un unico posto, raggruppati in modo che un picco caotico venga letto come un unico problema."
+---
+
+
+Visualizza tutti gli errori prodotti dai tuoi agenti in un unico posto, raggruppati in modo che un picco caotico venga letto come un unico problema. Hai un percorso con un solo clic da "qualcosa è rosso" all'esatto run che ha causato il problema, senza scorrere un feed in tempo reale per trovarlo.
+
+![La pagina Errori: un istogramma degli errori nel tempo sopra righe di errore rosse raggruppate, ciascuna con un pulsante "+ alert" con un solo clic](/agenteye/images/errors.png)
+*La pagina Errori: un istogramma degli errori nel tempo, con gli errori ripetuti compressi in una riga per incidente.*
+
+## Ogni errore, già raccolto per te
+
+Quando un agente si interrompe, non dovresti doversi scorrere un flusso di eventi in tempo reale sperando di catturare le righe rosse prima che scompaiano. La pagina **Errors** fa la raccolta per te. Riunisce tutto ciò che il dashboard mostrebbe in rosso in un'unica superficie di triage, in modo che la prima cosa che vedi sia cosa sta fallendo, non dove cercare.
+
+E cattura più dei casi ovvi. Accanto agli eventi `error` espliciti, Failproof AI Observability evidenzia anche i fallimenti silenziosi: qualsiasi `tool_result`, `hook_completed` o `agent_end` il cui payload contiene un errore appare qui. Uno strumento che ha restituito un errore, o un hook che è uscito male, non sfugge più semplicemente perché nulla ha lanciato un'eccezione rumorosa.
+
+Nella parte superiore, un istogramma traccia gli errori nel tempo. Un'occhiata ti dice se si tratta di un flusso costante di fondo o di un picco iniziato pochi minuti fa, così sai subito se devi smettere quello che stai facendo.
+
+Come ogni superficie observe, la pagina Errors è limitata alla tua organizzazione e filtra per intervallo di date, ambiente, agente e sessione. Ciò significa che puoi prendere un elenco a livello di flotta e restringerlo all'agente o all'ambiente specifico di cui ti interessa.
+
+## Un incidente, non cento righe identiche
+
+Una singola dipendenza interrotta può attivare lo stesso errore centinaia di volte al minuto. Lasciato così com'è, è una parete di linee quasi identiche che nasconde l'unica cosa che devi effettivamente vedere.
+
+Failproof AI Observability comprime i fallimenti ripetuti che condividono la stessa sessione e tipo di errore in un'unica riga. Un picco viene letto come un incidente. Finisci per contare i problemi, non le righe di log, e il segnale che conta rimane in primo piano invece di essere annegato dal suo stesso volume.
+
+## Da "qualcosa è rosso" all'evento esatto
+
+Fai clic su qualsiasi riga per arrivare direttamente all'interno della sessione di quel run, posizionato sull'evento esatto che ha fallito. Nessuna copia di ID sessione, nessuno scorrimento per cercare il momento in cui è andato male: arrivi direttamente lì, con il grafico di esecuzione completo a un'occhiata di distanza in modo da poter vedere cosa ha fatto l'agente nei momenti prima che si interrompesse.
+
+Se hai `alerts:write`, ogni riga ha anche un pulsante **+ alert**. Fai clic e Observability apre una nuova regola di avviso già compilata per catturare lo stesso errore di nuovo. L'incidente che hai appena esaminato diventa quello che ti avviserà la prossima volta, invece di sorprenderti due volte.
+
+**Dove trovarlo:** la pagina **Errors** si trova nella sezione observe del dashboard, a `/<org-slug>/errors`.
+
+## Correlati
+
+- [Alerts](/it/agenteye/alerts): trasforma qualsiasi errore in una regola di paging.
+- [Incidents](/it/agenteye/incidents): monitora un avviso attivo da apertura a risoluzione.
+- [Sessions](/it/agenteye/sessions): apri il run completo dietro qualsiasi errore.
+- [Audits](/it/agenteye/audits): lascia che Observability trovi i pattern di errore nei tuoi run per te.