> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started

title: "Iniziare con AgentEye"
description: "Documentazione per iniziare con AgentEye."
--------------------------------------------------------

Questa guida ti accompagna attraverso una configurazione completa di AgentEye: distribuire il server e il dashboard, installare il collector su una macchina agente e strumentare il codice del tuo agente Python.

***

## Cos'è AgentEye?

AgentEye è una **piattaforma self-hosted di osservabilità e valutazione per agenti AI**. Registra cosa fanno i tuoi agenti — ogni fase di un'esecuzione — e valuta automaticamente la qualità di ogni esecuzione completata, in modo da poter vedere come si comportano i tuoi agenti in produzione e rilevare le regressioni prima che lo facciano i tuoi utenti.

Il flusso dei dati procede in una sola direzione: il codice del tuo agente emette **eventi** attraverso l'**SDK Python** → un daemon **collector** leggero li raggruppa e li invia al **server** → gli eventi e le analitiche vengono archiviati in **ClickHouse** (lo stato operativo come organizzazioni, utenti, chiavi API, dashboard e query salvate risiede in **Postgres**) → tu esplori tutto nel **dashboard**.

Quello che ottieni:

* **Eventi** — la traccia grezza, passo dopo passo, di ogni esecuzione dell'agente (tool call, model call, hook, errori).
* **Sessioni** — questi eventi raggruppati in una riga per esecuzione, ciascuno **automaticamente valutato** e assegnato un punteggio.
* **Valutazioni** — punteggi di qualità prodotti dai tuoi servizi di valutazione, in modo che i cali di qualità emergano senza revisione manuale.
* **Query e dashboard** — SQL ClickHouse salvato sui tuoi dati, visualizzati in dashboard condivisi a livello organizzativo.
* **Avvisi e incidenti** — regole soglia che ti notificano (email, Slack, webhook, in-dashboard) più un flusso di lavoro per gli incidenti per triagiarli.
* **CLI e assistente AI** — un client terminale (`agenteye`) e un assistente in-dashboard per fare domande in linguaggio naturale.

Esegui tutto nella tua infrastruttura, come uno stack Docker Compose singolo (questa guida), un'installazione Kubernetes di produzione, o un pod co-locato singolo. Il resto di questa guida configura lo stack Compose end to end.

***

## Passaggio 1: Autenticati

Tutti gli artefatti di AgentEye sono distribuiti dall'organizzazione GitHub `agenteye-enterprise`. Come sviluppatore enterprise puoi generare il tuo GitHub PAT. Segui [enterprise-docs/github-token.md](/it/agenteye/github-token) per i passaggi esatti e i permessi richiesti.

```bash theme={null}
export AGENTEYE_TOKEN=<your-github-pat>

# Authenticate Docker against GHCR
echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin
```

***

## Passaggio 2: Distribuisci il Server e il Dashboard

Il server riceve eventi dai collector e li rende interrogabili; il dashboard è dove li esplori. Gli eventi e le analitiche acquisiti risiedono in ClickHouse (l'analytics store richiesto), mentre Postgres contiene lo stato operativo come organizzazioni, utenti, chiavi API, dashboard e query salvate.

**Scarica il file compose pubblicato:**

```bash theme={null}
mkdir -p ./agenteye
curl -fsSL \
  -H "Authorization: token $AGENTEYE_TOKEN" \
  https://raw.githubusercontent.com/agenteye-enterprise/releases/main/docker-compose.yml \
  -o ./agenteye/docker-compose.yml
cd agenteye
```

**Imposta i tuoi secret:**

Crea un file `.env` in modo che la distribuzione non venga eseguita con le credenziali predefinite `admin`. Come minimo imposta `ADMIN_KEY` e `POSTGRES_PASSWORD`:

```bash theme={null}
POSTGRES_PASSWORD=your-db-password
ADMIN_KEY=your-admin-secret
```

**Avvia lo stack:**

```bash theme={null}
docker compose up -d
```

Questo avvia lo stack completo, incluso l'analytics store ClickHouse richiesto e una cache Redis opzionale, insieme al server e al dashboard. ClickHouse deve essere sano affinché il server si avvii.

Il server ora è in ascolto su `http://localhost:8080` e il dashboard su `http://localhost:3000`.

Per distribuzioni di produzione (Postgres personalizzato, TLS, reverse proxy), vedi [enterprise-docs/deployment.md](/it/agenteye/deployment).

***

## Passaggio 3: Crea una Chiave API per il Collector

Ogni collector si autentica con una chiave API con scope. Utilizza l'`ADMIN_KEY` che hai impostato nel Passaggio 2 per crearne una:

```bash theme={null}
curl -s -X POST http://localhost:8080/keys \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"prod-collector","key":"your-collector-secret","permissions":["events:add"]}'
```

Fornisci tu stesso il valore `key`; usalo nella configurazione del collector nel Passaggio 4. Vedi [enterprise-docs/api-keys.md](/it/agenteye/api-keys) per la gestione completa delle chiavi.

***

## Passaggio 4: Installa il Collector

Su ogni macchina che esegue i tuoi agenti AI, installa il daemon collector.

**Scarica il binario (Linux x86\_64):**

```bash theme={null}
VERSION=0.0.1-beta.13
GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download "collector/v${VERSION}" \
  --repo agenteye-enterprise/releases \
  --pattern 'agenteye-collector-linux-x86_64'
chmod +x agenteye-collector-linux-x86_64
sudo mv agenteye-collector-linux-x86_64 /usr/local/bin/agenteye-collector
```

> Questo scarica il build **Linux x86\_64**. Per macOS (Apple Silicon o Intel), Linux arm64, o setup Docker / systemd / launchd, vedi [collector-installation.md](/it/agenteye/collector-installation), che elenca il download per ogni piattaforma — il comando qui sopra installa un binario Linux che non funzionerà altrove.

**Configura:**

```bash theme={null}
mkdir -p ~/.agenteye
cat > ~/.agenteye/config.json <<EOF
{
  "url": "http://your-server-host:8080/events",
  "key": "the-key-from-step-3"
}
EOF
```

**Avvia il daemon:**

```bash theme={null}
agenteye-collector start
```

Verifica la connettività con uno svuotamento una tantum (esce dopo aver drenato eventuali eventi in sospeso):

```bash theme={null}
agenteye-collector flush
```

Per setup Docker, systemd e launchd vedi [enterprise-docs/collector-installation.md](/it/agenteye/collector-installation).

***

## Passaggio 5: Installa l'SDK Python

Su ogni macchina dove vuoi strumentare il codice dell'agente, installa il wheel da GitHub Releases.

```bash theme={null}
VERSION=0.0.1b9
GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download "python-sdk/v${VERSION}" \
  --repo agenteye-enterprise/releases \
  --pattern 'agenteye-*.whl'
pip install agenteye-${VERSION}-py3-none-any.whl
```

***

## Passaggio 6: Strumenta il Tuo Agente

Aggiungi eventi al codice del tuo agente. Come minimo, emetti `agent_start` e `agent_end`:

```python theme={null}
import agenteye

agenteye.event.agent_start(
    session_id="run-001",
    agent_id="my-agent",
    goal="answer the user query",
)

# your agent logic here

agenteye.event.agent_end(
    session_id="run-001",
    agent_id="my-agent",
    outcome="success",
)
```

Gli eventi vengono messi in buffer e svuotati a `$AGENTEYE_HOME/events/` (o `~/.agenteye/events/` se `AGENTEYE_HOME` non è impostato) ogni 500 ms. Il collector li raccoglie automaticamente.

Vedi [enterprise-docs/python-sdk.md](/it/agenteye/python-sdk) per l'API di evento completa.

***

## Passaggio 7: Visualizza gli Eventi nel Dashboard

Apri `http://your-dashboard-host:3000` ed effettua l'accesso. AgentEye ti invia un codice monouso (o un link magic one-click), quindi non c'è una password da gestire.

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/login.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=8f83cb747193d872f7883cb709587635" alt="La schermata di accesso di AgentEye, che invia un codice monouso alla tua email" width="2880" height="1800" data-path="agenteye/images/login.png" />

Una volta dentro, la pagina **Events** mostra una traccia live di tutti gli eventi acquisiti. Filtra per `session_id` o `agent_id` per approfondire un'esecuzione specifica.

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/events-stream.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=79714903a85d10773f4f9b36cb44b1cf" alt="Il flusso di eventi live, codificato a colori per tipo di evento e filtrabile per ambiente, agente e sessione" width="2880" height="1800" data-path="agenteye/images/events-stream.png" />

La pagina **Sessions** raggruppa questi eventi in una riga per esecuzione. AgentEye valuta automaticamente le sessioni completate, quindi ogni esecuzione viene assegnata un punteggio e le regressioni di qualità emergono senza revisione manuale; il punteggio di valutazione più recente appare su ogni riga a colpo d'occhio:

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/sessions-list.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=10de161665eef64465d3d100e80b643f" alt="L'elenco delle sessioni, una riga per esecuzione, con badge di stato e punteggi di valutazione" width="2880" height="1800" data-path="agenteye/images/sessions-list.png" />

Per configurare come vengono valutate le sessioni, vedi [enterprise-docs/evaluation-suite.md](/it/agenteye/evaluation-suite).

Fai clic su qualsiasi sessione per aprire il suo **execution graph**, una vista nello stile di git di come agenti, tool, hook e model call si sono svolti nel tempo, con sotto-agenti paralleli sulle loro corsie e un breakdown per esecuzione nella barra destra:

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/session-detail.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=63cc2480e8124a05ea6a0a92d5f20690" alt="Un execution graph nello stile di git della sessione accanto alla sua timeline di eventi, con il pannello di breakdown tool/model/hook" width="2880" height="1800" data-path="agenteye/images/session-detail.png" />

***

## Passaggio 8: Esplora, crea grafici e configura avvisi

Con gli eventi in flusso, le pagine **analyze** trasformano l'attività grezza in risposte, in modo da poter misurare il comportamento dell'agente, condividere i risultati con il team e ricevere una notifica nel momento in cui qualcosa regredisce. Le pagine del dashboard hanno scope organizzativo, quindi gli URL che vedi nella barra degli indirizzi hanno il prefisso del tuo slug org (`/<org>/…`).

* **Queries** (`/<org>/queries`): inizia da una libreria di query salvate e riutilizzabili sui tuoi eventi e valutazioni (preset incorporati più i tuoi)…

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/queries.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=1b42be492d5b650b4bd6b8a2241f6633" alt="La libreria di query salvate: una griglia di query riutilizzabili, sia preset incorporati che personalizzati" width="2880" height="1800" data-path="agenteye/images/queries.png" />

…quindi aprine una nel SQL composer per modificarla ed eseguirla con risultati live:

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/query-lab.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=aec1a1d95bb0bf1280d62a2e2430f20e" alt="Il SQL query composer che esegue una query salvata, con una barra laterale dello schema e una griglia di risultati live" width="2880" height="1800" data-path="agenteye/images/query-lab.png" />

* **Dashboards** (`/<org>/dashboards`): fissa le query come tile di linea, barra, area o torta in dashboard condivisi a livello organizzativo.

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/dashboard-fleet.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=d1fed0deace0ebb0bc02421f3b994107" alt="Un dashboard costruito da query salvate: una linea di eventi per ora, un istogramma di errori per tipo, un grafico di area di latenza e token per modello" width="2880" height="1800" data-path="agenteye/images/dashboard-fleet.png" />

* **Alerts** (`/<org>/alerts`): promuovi qualsiasi soglia in una regola di paging che notifica via email, Slack, webhook o in-dashboard. Vedi [enterprise-docs/alerts.md](/it/agenteye/alerts).

***

## Passaggi Successivi

* [Deployment](/it/agenteye/deployment): indurire per la produzione
* [API Keys](/it/agenteye/api-keys): gestire l'accesso
* [Troubleshooting](/it/agenteye/troubleshooting): diagnosticare i problemi