failproofai 1.0.1-beta.1 → 1.0.1

package/.next/standalone/docs-old/it/agenteye/python-sdk.mdx

@@ -0,0 +1,437 @@
+---
+---
+title: "Python SDK"
+description: "Vedi esattamente cosa hanno fatto i tuoi agenti AI in produzione: ogni esecuzione dell'agente, chiamata di strumento, richiesta del modello, hook e intervento umano."
+---
+
+
+Vedi esattamente cosa hanno fatto i tuoi agenti AI in produzione: ogni esecuzione dell'agente, chiamata di strumento, richiesta del modello, hook e intervento umano. L'SDK Python per l'Observability di Failproof AI registra questa traccia dall'interno del codice del tuo agente, così puoi eseguire il debug, audit e valutazione di ciò che è accaduto. Usalo ogni volta che vuoi che Failproof AI Observability osservi i tuoi agenti.
+
+Sotto il cofano, l'SDK scrive eventi strutturati in file JSONL locali e il daemon collector li preleva e li invia automaticamente alla piattaforma. Non devi gestire tu stesso questi file.
+
+> **Consiglio:** Nuovo a Failproof AI Observability? Questa pagina è il riferimento completo degli eventi SDK.
+
+<div style={{ position: "relative", width: "100%", paddingBottom: "56.25%", height: 0, overflow: "hidden", borderRadius: "12px", margin: "1.5rem 0" }}>
+  <iframe src="https://www.youtube.com/embed/VWxukZc5k7s?autoplay=1&mute=1&loop=1&playlist=VWxukZc5k7s&rel=0&playsinline=1" title="Watch: Agent Tracing by Failproof AI (2 min)" allow="autoplay; encrypted-media; picture-in-picture; fullscreen" allowFullScreen style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }}></iframe>
+</div>
+
+---
+
+## Installazione
+
+L'SDK viene distribuito ai clienti come wheel privato piuttosto che da un indice di pacchetti pubblico. L'onboarding copre come ottenerlo, installarlo e pinarlo — parla con il tuo contatto Failproof AI se hai bisogno di accesso.
+
+Una volta installato, confermalo:
+
+```bash
+python -c "import agenteye; print(agenteye.__version__)"
+```
+
+Preferisci lasciare che un agente di codifica gestisca l'intera integrazione? L'[Agent Skill Python SDK](/it/agenteye/python-sdk-skill) conosce il percorso di installazione, pianifica i punti di strumentazione, li scrive e verifica che gli eventi arrivino.
+
+---
+
+## Quick Start
+
+```python
+import agenteye
+
+agenteye.configure(environment="production")
+
+agenteye.event.agent_start(session_id="run-001", agent_id="planner", goal="answer user query")
+
+agenteye.event.tool_use(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="web_search",
+    tool_call_id="toolu_01",
+    input={"query": "latest AI research"},
+)
+
+agenteye.event.tool_result(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="web_search",
+    tool_call_id="toolu_01",
+    output={"results": ["..."]},
+)
+
+agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="success")
+```
+
+### Strumentazione di una chiamata reale
+
+In pratica racchiudi il tuo codice agente esistente. Circonda una chiamata al modello con `model_request` prima e `model_response` dopo, in modo che i due eventi abbracciamo la richiesta reale e Failproof AI Observability possa abbinarli:
+
+```python
+import anthropic
+import agenteye
+
+agenteye.configure(environment="production")
+client = anthropic.Anthropic()
+
+messages = [{"role": "user", "content": "Summarise today's incidents."}]
+
+agenteye.event.model_request(
+    session_id="run-001",
+    agent_id="planner",
+    model="claude-sonnet-4-6",
+    messages=messages,
+)
+
+reply = client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=512,
+    messages=messages,
+)
+
+agenteye.event.model_response(
+    session_id="run-001",
+    agent_id="planner",
+    model=reply.model,
+    stop_reason=reply.stop_reason,
+    input_tokens=reply.usage.input_tokens,
+    output_tokens=reply.usage.output_tokens,
+    content=[block.model_dump() for block in reply.content],
+)
+```
+
+Racchiudi le chiamate ai strumenti allo stesso modo con `tool_use` e `tool_result`, riutilizzando uno stesso `tool_call_id` per la coppia.
+
+Ecco come appaiono questi eventi una volta raggiunto il dashboard, codificati per colore per tipo e filtrabili per ambiente, agente e sessione:
+
+![Lo stream live degli Events, codificato per colore per tipo di evento e filtrabile per ambiente, agente e sessione](/agenteye/images/events-stream.png)
+
+---
+
+## configure()
+
+```python
+agenteye.configure(
+    base_dir=None,           # Path | str | None. Default: $AGENTEYE_HOME or ~/.agenteye
+    flush_interval=0.5,      # float, seconds between flush cycles
+    environment=None,        # str | None. Deployment environment label
+)
+```
+
+Chiamalo una volta prima di qualsiasi chiamata `event.*`. Sicuro da omettere; i valori predefiniti funzionano subito. Tutti gli argomenti sono solo keyword; passali per nome come mostrato sopra.
+
+Quando `base_dir` è `None` (il valore predefinito), l'SDK legge `$AGENTEYE_HOME` se impostato,
+altrimenti ricade a `~/.agenteye`. Questo corrisponde alla risoluzione del collector stesso,
+quindi una singola variabile env `AGENTEYE_HOME` configura lo spool di eventi condiviso per entrambi
+l'SDK e il collector.
+
+---
+
+## Ambiente
+
+Etichetta ogni evento con un ambiente di deployment (`production`, `staging`, `qa`, `canary`, ecc.). Impostalo una volta; l'SDK lo allega a ogni evento automaticamente.
+
+**Opzione 1: via `configure()`:**
+
+```python
+agenteye.configure(environment="production")
+```
+
+**Opzione 2: via variabile d'ambiente:**
+
+```bash
+export AGENTEYE_ENVIRONMENT=production
+```
+
+**Priorità:** `configure(environment=...)` prevale sulla variabile d'ambiente. Se nessuno è impostato, il valore predefinito è `"dev"`.
+
+Il valore dell'ambiente appare come filtro di prima classe nel dashboard ed è memorizzato sul server per query veloci.
+
+> **Avvertenza:** I valori dell'ambiente non devono contenere una virgola letterale `,`. I filtri del dashboard utilizzano multi-select separato da virgole sul filo (`?environment=prod,staging`), quindi un ambiente denominato `prod,blue` verrebbe diviso in due valori. Gli eventi con ambienti contenenti virgole vengono rifiutati al momento dell'ingestione.
+
+---
+
+## Dati e privacy
+
+L'SDK registra solo i campi che tu esplicitamente passi. Prompt, messaggi, input e output dei strumenti e il contenuto del modello vengono catturati solo perché li consegni a una chiamata `event.*`. Nulla viene letto dal tuo processo o catturato implicitamente. Qualsiasi campo che lasci non impostato viene omesso dall'evento interamente; non viene scritto su disco.
+
+Questo rende la redazione tua scelta e tua responsabilità. Se un prompt o payload dello strumento contiene PII o segreti che preferisci non memorizzare, rimuovili o mascherali prima di passarli al metodo dell'evento.
+
+---
+
+## Riferimento degli eventi
+
+La maggior parte degli eventi viene in coppie start/end che condividono un ID di correlazione: `tool_use` e `tool_result` condividono un `tool_call_id`, `hook_triggered` e `hook_completed` condividono un `hook_id`, e `human_wait` e `human_input` condividono un `input_id`. Emetti l'evento di inizio, fai il lavoro, poi emetti l'evento di fine con lo stesso ID. Failproof AI Observability abbina la coppia e calcola `duration_ms` per te, così non passi mai `duration_ms` da solo.
+
+![Un grafo di esecuzione in stile git di una sessione accanto alla sua timeline degli eventi, ricostruito da eventi appaiati, con il pannello di breakdown strumento/modello/hook](/agenteye/images/session-detail.png)
+
+Tutti i metodi degli eventi richiedono questi due campi:
+
+| Campo | Tipo | Descrizione |
+|---|---|---|
+| `session_id` | `str` | Identifica l'esecuzione dell'agente di livello superiore |
+| `agent_id` | `str` | Identifica quale agente all'interno della sessione ha emesso l'evento |
+
+Tutti i metodi accettano anche `**kwargs` arbitrari per metadati personalizzati (vedi [Custom Fields](#custom-fields)).
+
+---
+
+### `event.agent_start()`
+
+Emesso quando un agente inizia il lavoro.
+
+```python
+agenteye.event.agent_start(
+    session_id="run-001",
+    agent_id="planner",
+    goal="answer user query",   # str | None
+    parent_id=None,             # str | None - parent agent_id for nested agents
+)
+```
+
+---
+
+### `event.agent_end()`
+
+Emesso quando un agente termina il lavoro.
+
+```python
+agenteye.event.agent_end(
+    session_id="run-001",
+    agent_id="planner",
+    outcome="success",          # str | None
+    summary="Answered query",   # str | None
+)
+```
+
+---
+
+### `event.tool_use()`
+
+Emesso quando un agente invoca uno strumento. Accoppia con `tool_result`; l'SDK calcola automaticamente `duration_ms`.
+
+```python
+agenteye.event.tool_use(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="web_search",     # str, required
+    tool_call_id="toolu_01",    # str, required - correlation key for the matching tool_result
+    input={"query": "..."},     # dict | None
+)
+```
+
+---
+
+### `event.tool_result()`
+
+Emesso quando uno strumento ritorna. Si correla con `tool_use` via `tool_call_id`.
+
+```python
+agenteye.event.tool_result(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="web_search",
+    tool_call_id="toolu_01",        # must match the prior tool_use
+    output={"results": ["..."]},    # Any | None
+    error=None,                     # str | None - set if the tool raised
+    # duration_ms is computed automatically - do not pass it
+)
+```
+
+---
+
+### `event.model_request()`
+
+Emesso appena prima di inviare un prompt a un LLM.
+
+```python
+agenteye.event.model_request(
+    session_id="run-001",
+    agent_id="planner",
+    model="claude-sonnet-4-6", # str | None - any provider/model string; not validated
+    messages=[                   # list[dict] | None - conversation turns
+        {"role": "user", "content": "..."},
+    ],
+    system="You are helpful.",   # Any | None - str or list of content blocks
+    tools=[                      # list[dict] | None - tool schemas offered to the model
+        {"name": "search", "input_schema": {"type": "object"}},
+    ],
+)
+```
+
+Le voci `messages` accettano sia un `content` di stringa semplice che Anthropic-style list-of-blocks `content`. I parametri di campionamento (`temperature`, `max_tokens`, ecc.) possono essere passati come kwargs extra.
+
+---
+
+### `event.model_response()`
+
+Emesso quando l'LLM ritorna una risposta.
+
+```python
+agenteye.event.model_response(
+    session_id="run-001",
+    agent_id="planner",
+    model="claude-sonnet-4-6", # str | None - any provider/model string; not validated
+    stop_reason="end_turn",     # str | None
+    input_tokens=1024,          # int | None
+    output_tokens=256,          # int | None
+    content=[                    # Any | None - str, or list of content blocks
+        {"type": "text", "text": "..."},
+    ],
+    role="assistant",            # str | None
+)
+```
+
+`content` accetta sia una stringa semplice (provider generici) che una lista di content blocks in stile Anthropic. Le chiamate ai strumenti vivono dentro `content` come blocchi `{"type": "tool_use", ...}`, senza un campo `tool_calls` separato.
+
+---
+
+### `event.hook_triggered()`
+
+Emesso quando un hook si attiva. Accoppia con `hook_completed`; l'SDK calcola automaticamente `duration_ms`.
+
+```python
+agenteye.event.hook_triggered(
+    session_id="run-001",
+    agent_id="planner",
+    hook_name="pre_tool_use",   # str, required
+    hook_id="hook-abc",         # str, required - correlation key
+    trigger_event="tool_use",   # str | None
+    input={"tool": "search"},   # Any | None
+)
+```
+
+---
+
+### `event.hook_completed()`
+
+Emesso quando un hook termina. Si correla con `hook_triggered` via `hook_id`.
+
+```python
+agenteye.event.hook_completed(
+    session_id="run-001",
+    agent_id="planner",
+    hook_name="pre_tool_use",
+    hook_id="hook-abc",         # must match the prior hook_triggered
+    outcome="allow",            # str | None
+    output=None,                # Any | None
+    error=None,                 # str | None
+    # duration_ms is computed automatically - do not pass it
+)
+```
+
+---
+
+### `event.error()`
+
+Emesso quando si verifica un errore non gestito.
+
+```python
+agenteye.event.error(
+    session_id="run-001",
+    agent_id="planner",
+    error_type="TimeoutError",  # str, required
+    message="timed out",        # str, required
+    traceback="Traceback...",   # str | None
+)
+```
+
+---
+
+## Eventi Human-in-the-Loop
+
+Gli eventi human-in-the-loop ti danno visibilità sui momenti in cui una persona entra nell'esecuzione dell'agente (in attesa di approvazione, fornitura di input, pausa o arresto dell'agente). Ti permettono di misurare quanto tempo gli umani impiegano a rispondere (l'SDK calcola automaticamente `duration_ms` sugli eventi appaiati), audit chi ha messo in pausa o interrotto un agente, e di costruire flussi di lavoro di approvazione e supervisione che emergono nel dashboard.
+
+### `event.human_wait()`
+
+Emesso quando l'agente mette in pausa l'esecuzione per attendere che un umano fornisca input. Accoppia con `human_input`; l'SDK calcola automaticamente `duration_ms` (quanto tempo l'umano ha impiegato a rispondere).
+
+```python
+agenteye.event.human_wait(
+    session_id="run-001",
+    agent_id="planner",
+    input_id="inp-abc",                          # str, required - correlation key for the matching human_input
+    prompt="Do you approve this action?",        # str | None - the question shown to the human
+    options=["approve", "reject", "defer"],      # list[str] | None - choices presented to the human
+    reason="approval_required",                  # str | None - why the agent is waiting
+)
+```
+
+### `event.human_input()`
+
+Emesso quando un umano fornisce input e l'agente riprende. Si correla con `human_wait` via `input_id`. `duration_ms` viene calcolato automaticamente e non deve essere passato dal chiamante.
+
+```python
+agenteye.event.human_input(
+    session_id="run-001",
+    agent_id="planner",
+    input_id="inp-abc",    # str, required - must match the prior human_wait
+    response="approve",    # str | None - the human's answer (free text or selected option)
+    # duration_ms is computed automatically - do not pass it
+)
+```
+
+### `event.human_pause()`
+
+Emesso quando un umano mette attivamente in pausa l'agente (ad es. tramite un controllo del dashboard). L'agente è sospeso ma non terminato.
+
+```python
+agenteye.event.human_pause(
+    session_id="run-001",
+    agent_id="planner",
+    reason="user_requested",  # str | None
+    user_id="usr_42",         # str | None - who paused the agent
+)
+```
+
+### `event.human_interrupt()`
+
+Emesso quando un umano arresta attivamente l'agente a metà dell'esecuzione. A differenza di `human_pause`, il lavoro dell'agente viene terminato piuttosto che sospeso.
+
+```python
+agenteye.event.human_interrupt(
+    session_id="run-001",
+    agent_id="planner",
+    reason="output_incorrect",       # str | None
+    user_id="usr_42",                # str | None - who interrupted the agent
+    at_step="tool_use:web_search",   # str | None - what the agent was doing when stopped
+)
+```
+
+---
+
+## Custom Fields
+
+Qualsiasi argomento di parola chiave extra viene aggiunto all'evento dopo i campi standard:
+
+```python
+agenteye.event.tool_use(
+    session_id="run-001",
+    agent_id="planner",
+    tool_name="db_query",
+    tool_call_id="toolu_02",
+    tenant_id="acme",           # custom field
+    region="us-east-1",         # custom field
+)
+```
+
+`timestamp`, `type`, e `environment` sono riservati e sollevano `ValueError` (`Reserved field names cannot be used as custom fields: [...]`) se passati come custom fields. `session_id` e `agent_id` sono parametri richiesti su ogni metodo dell'evento e non possono essere forniti una seconda volta; Python solleva `TypeError` se lo fai. Imposta l'ambiente con `configure(environment=...)` (o la variabile `AGENTEYE_ENVIRONMENT`) invece.
+
+Mantieni i payload come JSON strutturato quando vuoi interrogare i loro campi. I valori che JSON non supporta nativamente — come datetime, UUID, decimali, set, byte o oggetti modello — vengono convertiti in stringhe in modo che la registrazione continui in sicurezza.
+
+---
+
+## Come vengono scritti gli eventi
+
+Gli eventi vengono memorizzati nel buffer in-process e svuotati su disco ogni `flush_interval` secondi (default 500 ms). Ogni flush scrive un file JSONL:
+
+```text
+~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl
+```
+
+Il collector guarda questa directory e carica i file automaticamente. Non hai bisogno di gestire questi file direttamente.
+
+Ogni file viene scritto atomicamente: l'SDK scrive in un file temporaneo e poi lo rinomina in posizione, quindi il collector non vede mai un file a metà della scrittura. Un flush finale è anche eseguito quando il tuo processo esce, quindi gli eventi memorizzati nell'intervallo finale non vengono persi. Se il collector è offline, gli eventi semplicemente si accumulano come file su disco e vengono inviati una volta che torna online.
+
+---
+
+## Prossimi step
+
+- [Event stream](/it/agenteye/event-stream): guarda questi eventi arrivare in tempo reale, codificati per colore e filtrabili per ambiente, agente e sessione.
+- [Sessions](/it/agenteye/sessions): vedi come gli eventi appaiati ricostruiscono ogni esecuzione dell'agente come un grafo di esecuzione e timeline.

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

@@ -0,0 +1,55 @@
+---
+title: "Query"
+description: "Poni qualsiasi domanda sui dati del tuo agente e ottieni una risposta in pochi secondi."
+---
+
+Poni qualsiasi domanda sui dati del tuo agente e ottieni una risposta in pochi secondi. Failproof AI Observability ti offre una libreria di query salvate e pronte all'uso sui tuoi eventi e valutazioni, così puoi partire da un esempio funzionante invece di un editor SQL vuoto.
+
+![La libreria delle query salvate: una griglia di query riutilizzabili, sia preset built-in che personalizzati](/agenteye/images/queries.png)
+
+*La tua libreria di query salvate in `/<org-slug>/queries`: i preset built-in accanto alle query che il tuo team ha salvato.*
+
+## Parti da un preset, non da una pagina bianca
+
+Non devi ricordare i nomi delle tabelle o scrivere SQL da zero. La libreria si apre con preset built-in per le domande che i team pongono più frequentemente, accanto alle query che il tuo team ha salvato e denominato. Scegline una che si avvicina a quello che cerchi e sarai già a metà strada verso la risposta.
+
+Ogni query salvata ha ambito organizzativo e è condivisa, quindi le query utili che i tuoi colleghi scrivono diventano anche tue. Denominata una query e aggiunta una descrizione una volta, chiunque nella tua organizzazione può trovarla, eseguirla o fissarne i risultati in un dashboard in seguito.
+
+Trovalo in `/<org-slug>/queries`.
+
+## Regolala ed eseguila nel compositore SQL
+
+Apri qualsiasi query e arriverà nel compositore SQL, dove puoi modificarla e vedere la risposta immediatamente: nessuna esportazione, nessun andata e ritorno, nessuna attesa di qualcun altro.
+
+![Il compositore di query SQL che esegue una query salvata, con una barra laterale dello schema e una griglia di risultati live](/agenteye/images/query-lab.png)
+
+*Il compositore SQL: la tua query a sinistra, una barra laterale dello schema per non dimenticare mai un nome di colonna, e una griglia di risultati live sotto.*
+
+- **Una barra laterale dello schema** illustra le tabelle analitiche e le loro colonne, così puoi strutturare una query senza cercare i nomi dei campi.
+- **Una griglia di risultati live** restituisce le righe nel momento in cui le esegui, così iteri in pochi secondi anziché indovinare e riindovinare.
+- **Progettato per sola lettura.** Le query vengono eseguite nel tuo event store e convalidate sul server: sono consentiti solo statement `SELECT` e `WITH`, con un timeout di statement e un limite di righe. Una query esplorativa non può mai modificare i tuoi dati e una che si impalla viene fermata per te.
+
+Soddisfatto del risultato? Salvalo nella libreria in modo che l'intero team lo erediti, oppure fissa il suo output in un dashboard come un tile lineare, a barre, ad area o a torta.
+
+## Eseguile dal terminale, o lascia che l'assistente le scriva
+
+Le stesse query salvate ti seguono ovunque lavori:
+
+- **Dal terminale.** La CLI `agenteye` elenca, esegue e salva le stesse identiche query, così puoi inserire un risultato in uno script, collegarlo in CI o passarlo a un agente di codifica.
+
+```bash
+agenteye query list                 # le stesse query salvate, dal tuo terminale
+agenteye query run errs --arg prod  # eseguine una e stampa le righe (aggiungi --json per usarla in pipe)
+```
+
+  Vedi [CLI e agenti](/it/agenteye/cli-and-agents) per l'insieme completo di comandi.
+
+- **Dall'assistente AI.** Non sei sicuro di come formulare l'SQL? Chiedi all'[assistente AI](/it/agenteye/assistant) nel dashboard in inglese naturale e ti farà uno schema della query e la salverà nella tua libreria per te.
+
+L'esecuzione di una query salvata è controllata dal permesso `queries:run`, mantenuto separato dai permessi per creare o eliminare query, così puoi concedere accesso in lettura senza permettere a tutti di riscrivere la libreria.
+
+## Correlati
+
+- [Dashboard](/it/agenteye/dashboards): fissa i risultati delle query in grafici condivisi a livello organizzativo.
+- [Assistente AI](/it/agenteye/assistant): poni domande in inglese naturale e ottieni una query in cambio.
+- [CLI e agenti](/it/agenteye/cli-and-agents): esegui e salva le stesse query dal tuo terminale.

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

@@ -0,0 +1,68 @@
+---
+title: "Sicurezza"
+description: "Failproof AI Observability è costruito per stare vicino ai tuoi agenti in produzione, il che significa che vede i tuoi prompt, gli input degli strumenti e gli output."
+---
+
+
+Failproof AI Observability è costruito per stare vicino ai tuoi agenti in produzione, il che significa che vede i tuoi prompt, gli input degli strumenti e gli output. Questa pagina spiega come mantiene questi dati isolati, controllati e nelle tue mani. Se stai valutando Failproof AI Observability per una revisione di sicurezza, inizia da qui.
+
+---
+
+## I tuoi dati rimangono nel tuo ambiente
+
+Failproof AI Observability è self-hosted. Gli eventi, i prompt, le risposte del modello e l'analitca sono memorizzati nei tuoi database, nel tuo ambiente. Nessun dato viene inviato a un servizio SaaS di terze parti per l'archiviazione, e i tuoi dati rimangono nel tuo account cloud.
+
+---
+
+## Isolamento dei tenant
+
+Un'istanza di Failproof AI Observability può ospitare molte organizzazioni, ognuna isolata a livello di storage — applicato dal database, non solo dall'interfaccia utente:
+
+- I dati operativi di un'organizzazione (utenti, chiavi, dashboard, query salvate) sono vincolati a quell'organizzazione, e le letture cross-org sono bloccate dal database stesso.
+- Ogni evento acquisito è contrassegnato con l'organizzazione proprietaria, quindi gli eventi di un'organizzazione non possono mai essere letti da un'altra.
+
+Ogni rotta della dashboard è vincolata sotto uno slug dell'organizzazione (`/<org-slug>/…`).
+
+---
+
+## Accesso
+
+Failproof AI Observability utilizza l'accesso senza password basato su email. Non c'è alcuna password da phishare o perdere. Un utente richiede un codice monouso (o un link magic a un click), che gli viene inviato per email e scade rapidamente. L'accesso è controllato da una **lista di whitelist**: solo gli indirizzi email (o i domini) che permetti possono autenticarsi.
+
+![La schermata di accesso di Failproof AI Observability, che invia un codice monouso alla tua email](/agenteye/images/login.png)
+
+---
+
+## Accesso con ambito limitato con chiavi API
+
+Ogni client si autentica con una chiave API che possiede permessi granulari e con il principio del minimo privilegio. Un collector ha bisogno solo di `events:add`; una chiave dashboard o assistant può essere di sola lettura; le azioni distruttive (eliminazione, rigenerazione) sono grant separati che scegli di includere.
+
+![La pagina delle chiavi API: i grant di permessi di ogni chiave, codificati per colore in base all'ambito di lettura, scrittura e distruttività](/agenteye/images/api-keys.png)
+
+Mantieni la chiave bootstrap dell'admin per la configurazione e emetti chiavi ristrette per tutto il resto. Vedi [Chiavi API](/it/agenteye/api-keys).
+
+---
+
+## Un assistente di sola lettura e controllato da approvazione
+
+L'[assistente AI](/it/agenteye/assistant) nel dashboard risponde a domande sui tuoi dati, ma è vincolato da design:
+
+- È **di sola lettura per impostazione predefinita**: il suo SQL viene eseguito attraverso una guardia che consente solo query `SELECT`/`WITH`, a singola istruzione, con un limite di righe.
+- Tutto quello che crea (una query salvata, una dashboard) è **controllato dall'approvazione**: esamini e approvi ogni scrittura prima che accada.
+- **Non può mai eliminare**.
+
+Quindi un collega può chiedere "quali agenti hanno avuto il maggior numero di errori questa settimana?" e agire in base alla risposta, senza che l'assistente sia in grado di modificare o rimuovere i tuoi dati da solo.
+
+---
+
+## In transito
+
+Tutto il traffico avviene su HTTPS. Termini TLS con i tuoi certificati, quindi il traffico da collector a server e da browser a server è crittografato in transito.
+
+---
+
+## Passaggi successivi
+
+- [Panoramica](/it/agenteye/overview): come Failproof AI Observability si collega insieme.
+- [Chiavi API](/it/agenteye/api-keys): limita l'accesso per il collector, la dashboard e l'assistente.
+- [Observability](/it/agenteye/observability): cosa cattura Failproof AI Observability dai tuoi agenti.

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

@@ -0,0 +1,57 @@
+---
+title: "Sessioni e Grafico di Esecuzione"
+description: "Ogni evento da un'esecuzione, tutto in una riga leggibile e visualizzato come un grafico di esecuzione in stile git che puoi leggere in pochi secondi."
+---
+
+
+Smetti di indovinare perché un'esecuzione è fallita. Failproof AI Observability raggruppa ogni evento da un'esecuzione in una riga leggibile, poi disegna l'intera esecuzione come un'immagine in stile git che puoi leggere in pochi secondi, così vedi esattamente cosa ha fatto il tuo agent, passo dopo passo.
+
+![L'elenco delle Sessioni: una riga per esecuzione, tra ambienti e agent, con badge di stato e valutazione](/agenteye/images/sessions-list.png)
+
+*Una riga per esecuzione: il badge di stato ti dice come è terminata l'esecuzione a prima vista, e un badge di punteggio appare quando è collegato un valutatore.*
+
+<div style={{ position: "relative", width: "100%", paddingBottom: "56.25%", height: 0, overflow: "hidden", borderRadius: "12px", margin: "1.5rem 0" }}>
+  <iframe src="https://www.youtube.com/embed/VWxukZc5k7s?autoplay=1&mute=1&loop=1&playlist=VWxukZc5k7s&rel=0&playsinline=1" title="Watch: Agent Tracing by Failproof AI (2 min)" allow="autoplay; encrypted-media; picture-in-picture; fullscreen" allowFullScreen style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }}></iframe>
+</div>
+
+*Tracciamento dell'agent: segui una singola esecuzione passo dopo passo, dal goal agli strumenti alla risposta finale.*
+
+---
+
+## Vedi ogni esecuzione a prima vista
+
+Il percorso degli eventi grezzi è la verità di ogni passo, ma quando hai migliaia di passi su dozzine di esecuzioni, ti serve l'esecuzione, non il passo. La pagina Sessions raggruppa tutti gli eventi di un'esecuzione in una riga, così un giorno di attività diventa un elenco scansionabile invece di un diluvio di informazioni.
+
+Ogni riga ha un badge di stato, quindi un'esecuzione fallita si distingue da una sana prima ancora di fare clic. Filtra per intervallo di date, ambiente, agent o sessione per passare da "tutto" a "l'esecuzione che mi interessa" in un paio di clic.
+
+Una volta collegato un valutatore, ogni esecuzione completata viene valutata automaticamente e il suo punteggio più recente appare sulla riga come badge. Puoi filtrare per qualsiasi intervallo di punteggio, così "mostrami ogni esecuzione prod con punteggio basso questa settimana" è un filtro, non una revisione manuale. Finché non ne configuri uno, le sessioni continuano a catturare l'esecuzione completa; semplicemente non hanno ancora un punteggio.
+
+---
+
+## Leggi l'intera esecuzione come un'immagine
+
+![Un grafico di esecuzione in stile git della sessione accanto alla sua timeline di eventi, con il pannello di scomposizione di strumenti, modelli e hook](/agenteye/images/session-detail.png)
+
+*Il grafico di esecuzione (a sinistra) si siede accanto alla timeline degli eventi; il pannello di destra scompone gli strumenti, i modelli, gli hook e la spesa in token per l'esecuzione.*
+
+Fai clic su qualsiasi sessione per aprire il suo grafico di esecuzione: una visualizzazione in stile git di come agent, strumenti, hook e chiamate ai modelli si sono svolti nel tempo. I sub-agent paralleli si diramano ognuno nella propria corsia, così puoi vedere quale lavoro è stato eseguito affiancato, quale sub-agent si è bloccato e dove l'esecuzione è andata fuori strada, senza riprenderla mentalmente da un muro di log.
+
+Il pannello di destra ti dà la scomposizione per esecuzione: quali strumenti e modelli sono stati eseguiti, quali hook sono stati attivati e cosa l'esecuzione ha speso in token. Questa è la risposta a "perché questa esecuzione è costata così tanto?" o "quale strumento è quello lento?" seduta proprio accanto al grafico che l'ha causata.
+
+I singoli eventi sono indirizzabili, così puoi dare a qualcuno un link a un momento specifico piuttosto che "la sessione, circa due terzi più in giù". Copia il link da qualsiasi evento o segui uno da un risultato di [audit](/it/agenteye/audits) o un errore, e la sessione si apre con quell'evento selezionato e fatto scorrere in vista. Questo vale anche per esecuzioni molto lunghe: la timeline carica una finestra limitata per il bene del tuo browser, e un link che punta oltre quella finestra comunque trova il suo evento piuttosto che lasciarti all'inizio. Se l'evento è invecchiato oltre la tua finestra di conservazione, la pagina te lo dice invece di selezionare silenziosamente nulla.
+
+---
+
+## Dove trovarla
+
+Ogni pagina della dashboard è scoped alla tua org (`/<org-slug>/…`). Sessions si trova sotto **Observe** nella barra laterale sinistra, accanto a Events, con i filtri di intervallo di date, ambiente, agent e sessione nella parte superiore dell'elenco. Ogni riga è a un clic dal suo grafico di esecuzione completo.
+
+Per attivare i badge di punteggio e il filtraggio per intervallo di punteggio, collega un valutatore: vedi [Evaluations](/it/agenteye/evaluations).
+
+---
+
+## Correlati
+
+- [Event stream](/it/agenteye/event-stream): il percorso grezzo e per-passo da cui ogni sessione è stata raggruppata.
+- [Evaluations](/it/agenteye/evaluations): collega un valutatore in modo che ogni esecuzione ottenga un badge di punteggio per cui puoi filtrare.
+- [Telemetry](/it/agenteye/telemetry): come le esecuzioni vanno dal tuo agent in queste sessioni.