Getting started - FailproofAI

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 per i passaggi esatti e i permessi richiesti.

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:

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:

POSTGRES_PASSWORD=your-db-password
ADMIN_KEY=your-admin-secret

Avvia lo stack:

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.

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:

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 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):

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, che elenca il download per ogni piattaforma — il comando qui sopra installa un binario Linux che non funzionerà altrove.

Configura:

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:

agenteye-collector start

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

agenteye-collector flush

Per setup Docker, systemd e launchd vedi enterprise-docs/collector-installation.md.

Passaggio 5: Installa l’SDK Python

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

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:

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 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.

La schermata di accesso di AgentEye, che invia un codice monouso alla tua email

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.

Il flusso di eventi live, codificato a colori per tipo di evento e filtrabile per ambiente, agente e sessione

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:

L'elenco delle sessioni, una riga per esecuzione, con badge di stato e punteggi di valutazione

Per configurare come vengono valutate le sessioni, vedi enterprise-docs/evaluation-suite.md. 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:

Un execution graph nello stile di git della sessione accanto alla sua timeline di eventi, con il pannello di breakdown tool/model/hook

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)…

La libreria di query salvate: una griglia di query riutilizzabili, sia preset incorporati che personalizzati

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

Il SQL query composer che esegue una query salvata, con una barra laterale dello schema e una griglia di risultati live

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

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

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.

Passaggi Successivi

Deployment: indurire per la produzione
API Keys: gestire l’accesso
Troubleshooting: diagnosticare i problemi

​title: “Iniziare con AgentEye” description: “Documentazione per iniziare con AgentEye.”

​Cos’è AgentEye?

​Passaggio 1: Autenticati

​Passaggio 2: Distribuisci il Server e il Dashboard

​Passaggio 3: Crea una Chiave API per il Collector

​Passaggio 4: Installa il Collector

​Passaggio 5: Installa l’SDK Python

​Passaggio 6: Strumenta il Tuo Agente

​Passaggio 7: Visualizza gli Eventi nel Dashboard

​Passaggio 8: Esplora, crea grafici e configura avvisi

​Passaggi Successivi