Deployment

​

Panoramica dell’architettura

  [ macchine agenti AI ]                  [ Tua infrastruttura ]

    Python SDK
       |  scrive JSONL                       +----------------------+
       v                                +--->| PostgreSQL 15+       |
 agenteye-collector --HTTP--+           |    | (archivio relazionale)|
                            |           |    +----------------------+
                            v           |
                       +--------+       |    +----------------------+
                       | Server |<------+--->| ClickHouse 24+       |
                       +--------+       |    | (eventi / analytics) |
                            ^           |    +----------------------+
                        API |           |
                            |           |    +----------------------+
                      +-----------+     +- - >| Redis 7+ (opzionale) |
                      | Dashboard |           +----------------------+
                      +-----------+

• Server: servizio HTTP in Rust; riceve batch di eventi, li scrive in ClickHouse e mantiene lo stato relazionale in PostgreSQL.
• Dashboard: app web Next.js; legge e scrive esclusivamente tramite l’API del server.
• agenteye-collector: deployato su macchine agenti, non sull’host del server.
• Postgres 15+: OBBLIGATORIO. (Aumentato dalla versione 14 nel rilascio multi-tenant; lo schema delle appartenenze all’organizzazione utilizza una chiave esterna con lista di colonne ON DELETE SET NULL, che richiede Postgres 15+. Aggiorna Postgres prima di deployare questa versione.) Memorizza lo stato OLTP: api_keys, users, sessions, evaluation_jobs (coda), dashboards, saved_queries, otp_codes, più le tabelle multi-tenant orgs, org_memberships, org_settings.
• ClickHouse 24+: OBBLIGATORIO. L’archivio di analytics per ogni evento ingestionato. Engine: ReplacingMergeTree, partizionato per mese, ordinato per (session_id, ts, dedup_key). Il server si connette tramite CLICKHOUSE_URL; il deploy/base/clickhouse/ incluso fornisce una configurazione single-node ottimizzata per le prestazioni. Requisito multi-tenant: la configurazione inclusa abilita la gestione dell’accesso SQL + users_without_row_policies_can_read_rows=false affinché il server possa creare un utente ClickHouse di sola lettura + politica di riga per organizzazione (il limite di isolamento applicato dal motore per l’editor SQL e l’agente AI). Se fornisci la tua configurazione ClickHouse, riporta queste impostazioni (vedi deploy/base/clickhouse/configmap.yaml).
• Redis 7+: opzionale cache condivisa + backend per il rate-limiting. Sia il server che il dashboard si connettono tramite REDIS_URL. Se assente, entrambi si degradano elegantemente a percorsi solo Postgres. Vedi Redis (cache opzionale) di seguito.

​

Server

​

Scarica l’immagine

echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin
docker pull ghcr.io/agenteye-enterprise/server:beta-latest

I build attuali sono pubblicati sotto beta-latest; latest è assegnato solo ai rilasci stabili. Per la produzione, usa un tag specifico :v<version>; vedi Tag di immagine disponibili.

​

Variabili di ambiente

​

Esegui

docker run -d --restart unless-stopped \
  --name agenteye-server \
  -e DATABASE_URL="$DATABASE_URL" \
  -e ADMIN_KEY="$ADMIN_KEY" \
  -p 8080:8080 \
  ghcr.io/agenteye-enterprise/server:beta-latest

​

Health check

GET /health    # liveness  - sempre {"status":"ok"} una volta che il processo è attivo
GET /ready     # readiness - 200 quando Postgres + ClickHouse sono raggiungibili, altrimenti 503

​

URL link magico email

1. Header X-AgentEye-Dashboard-Url: impostato automaticamente dal proxy /api/auth/otp/request del dashboard dalla sua stessa origine pubblica. In un deployment same-origin (server e dashboard condividono un host dietro un ingress che inoltra i proxy header), nessuna configurazione è richiesta.
2. Variabile di ambiente DASHBOARD_URL: imposta questo se il tuo dashboard è raggiungibile su un’origine diversa da quella che l’endpoint OTP request del server vede (dividi api.example.com / app.example.com), o se il tuo ingress non propaga l’host pubblico nel pod dashboard (così request.nextUrl.origin altrimenti si risolverebbe in un bind wildcard come 0.0.0.0:3000). Esempio: DASHBOARD_URL=https://app.example.com.
3. Default: https://app.befailproof.ai, utilizzato solo se nessuno dei precedenti è presente.

kubectl set env deployment/server -n agenteye \
  DASHBOARD_URL=https://app.example.com

​

Dashboard

​

Scarica l’immagine

docker pull ghcr.io/agenteye-enterprise/dashboard:beta-latest

​

Variabili di ambiente

​

Esegui

docker run -d --restart unless-stopped \
  --name agenteye-dashboard \
  -e AGENTEYE_SERVER_URL="http://your-server-host:8080" \
  -e AGENTEYE_API_KEY="$ADMIN_KEY" \
  -p 3000:3000 \
  ghcr.io/agenteye-enterprise/dashboard:beta-latest

​

Telemetria & privacy

• Nessun dato di agente, sessione o evento lascia mai la tua infrastruttura. Solo l’utilizzo dell’interfaccia utente del dashboard è segnalato. Gli URL delle pagine vengono spogliati degli identificatori prima dell’invio, e gli operatori sono identificati solo da un id opaco interno, mai per email.
• La telemetria è abilitata per default. Per disabilitarla completamente, imposta AE_ANALYTICS_DISABLED=1 sul contenitore dashboard e riavvia.
• Gli analytics vengono inviati al percorso /ingest del dashboard, che il dashboard rimanda tramite proxy a PostHog (https://us.i.posthog.com). Mantenere le richieste first-party significa che gli ad-blocker del browser non le eliminano. Il contenitore dashboard ha bisogno di accesso in uscita a PostHog; se è bloccato, la telemetria silenziosamente non fa nulla e il dashboard non è interessato.

​

Assistente AI (opzionale)

​

ClickHouse (archivio analytics obbligatorio)

​

Schema

• agenteye.events: ReplacingMergeTree(ingested_at), partizionato per toYYYYMM(ts), ordinato per (session_id, ts, dedup_key). Gli inserti duplicati (tentativi di raccoglitore) collassano a una singola riga al momento del merge; il server calcola un dedup_key SHA-256 deterministico per ogni evento affinché i tentativi siano sicuri.
• agenteye.evaluations: ReplacingMergeTree(ingested_at), partizionato per toYYYYMM(finished_at), ordinato per (session_id, finished_at, dedup_key). Scritto una volta per risultato di valutazione terminale dalla pipeline di valutatore. Stesso modello di dedup-key come events.
• agenteye.agent_sessions: una VIEW su agenteye.events, non una tabella fisica. Ogni colonna è derivata (started_at = min(ts), last_event_at = max(ts), ended_at = max(if event_type='agent_end', ts, NULL), event_count = count(), ecc.). Nessun upsert per evento e nessun backfill separato; la view si riflette automaticamente in qualunque cosa sia in events.

​

Configurazione

• 2 GiB richiesto / 4 GiB limite di memoria nell’overlay base fornito (dimensionato per adattarsi a piccoli nodi POC/staging); i clienti di produzione dovrebbero sovrapporre verso l’alto — il minimo consigliato è 2c / 4Gi richiesta, 6c / 8Gi limite. max_server_memory_usage_to_ram_ratio=0.9
• 5 GiB mark cache + 8 GiB cache non compressa
• background_pool_size=16, background_merges_mutations_concurrency_ratio=2
• MergeTree: parts_to_throw_insert=3000, parts_to_delay_insert=1500, non_replicated_deduplication_window=1000
• local_io_method=auto (io_uring su kernel supportati)
• fsync_metadata=0: accettabile per l’ingest almeno una volta + dedup ReplacingMergeTree
• query_log abilitato con TTL di 30 giorni; query_thread_log rimosso (costoso a QPS elevato)
• max_execution_time=30 per query lato utente
• 100 GiB PVC al template StatefulSet (gli overlay dei clienti DOVREBBERO sovraporre a una classe di archiviazione SSD veloce per la produzione)

​

Backup

​

Redis (cache opzionale)

• Server memorizza in cache le ricerche di chiavi API autenticate, gli elenchi /events/environments + /evaluations/environments, il rollup /events/latency_aggregate (la query più pesante che il dashboard polling), l’elenco /sessions, e passa il rate-limiting delle richieste OTP da un COUNT(*) di Postgres a un INCR + EXPIRE di Redis.
• Dashboard memorizza in cache i risultati di validateSession() così le 10-20 chiamate API autenticate che un tipico caricamento di pagina emette condividono tutti una singola verifica di sessione upstream. Limita anche le richieste OTP-request e OTP-verify nel lato edge del dashboard.

​

Configurazione

​

Memoria + persistenza

​

Quando NON deployare Redis

• Single-instance dev/QA. Le cache in-process sul server solo forniscono la maggior parte del beneficio per replica; Redis aggiunge la condivisione cross-replica che i setup single-instance non hanno bisogno.
• Installazioni air-gapped dove il costo operazionale di eseguire un servizio in più supera il guadagno di latenza.

​

Docker Compose (consigliato)

GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download \
  --repo agenteye-enterprise/releases \
  --pattern 'docker-compose.yml' \
  --dir ./agenteye
cd agenteye

# Usa password sicure per URL (senza /, +, o = caratteri).
# Genera con: openssl rand -hex 24
POSTGRES_PASSWORD=your-db-password
ADMIN_KEY=your-admin-secret

# Autenticazione dashboard
ADMIN_EMAIL=admin@yourcompany.com
ALLOWED_EMAILS=*@yourcompany.com

# SMTP per email OTP (ometti per registrare i codici OTP a stdout)
# SMTP_HOST=smtp.yourprovider.com
# SMTP_PORT=587
# SMTP_USERNAME=your-smtp-user
# SMTP_PASSWORD=your-smtp-password
# SMTP_FROM=noreply@yourcompany.com

RUST_LOG=info

docker compose up -d

docker compose down

docker compose down -v

​

Impostazioni operative

​

Come funziona il bootstrap

• Per un deploy fresco, imposta le variabili di ambiente come mostrato sopra e l’organizzazione predefinita le legge al primo avvio.
• Per modificare un valore successivamente, accedi al dashboard e modificalo sotto /<org>/settings. La modifica si applica entro pochi secondi su tutte le repliche del server; nessun riavvio necessario.
• Una linea di log all’avvio registra cosa è stato seminato vs. cosa era già presente, così puoi confermare che il bootstrap ha avuto effetto:
  INFO settings bootstrap: seeded default-org row key=allowed_sign_ins env_var=ALLOWED_EMAILS seeded_from_env=true
  

​

Semantica di accesso attraverso le organizzazioni

• Durata sessione / OTP: il più rigoroso (più breve) il tempo di vita tra le organizzazioni di cui l’utente è membro vince.
• Accessi consentiti: il gate ORs ogni lista di consentiti dell’organizzazione insieme all’appartenenza all’organizzazione: un utente può richiedere un OTP se la lista consentiti di qualunque organizzazione ammette la sua email o sono già membri di qualunque organizzazione.

​

Permessi

• settings:read: vedi la pagina e i valori attuali.
• settings:write: salva le modifiche.

​

Organizzazioni (multi-tenancy)

# Docker Compose - exec nel servizio server in esecuzione:
docker compose exec server agenteye-orgctl org create --slug acme --name "Acme Corp"
docker compose exec server agenteye-orgctl member add --org acme --email alice@acme.example --set admin

# Kubernetes - exec nel Deployment server in esecuzione:
kubectl -n agenteye exec deploy/server -- agenteye-orgctl org list

​

Riempimento della finestra di contesto

# anteprima (stampa la mutazione per-organizzazione, non cambia nulla):
kubectl -n agenteye exec deploy/server -- agenteye-backfill-context-window --dry-run
# applica:
kubectl -n agenteye exec deploy/server -- agenteye-backfill-context-window
# docker compose:
docker compose exec server agenteye-backfill-context-window

​

Considerazioni sulla produzione

• Postgres: Usa un servizio Postgres gestito o un’istanza dedicata con backup regolari. Il DATABASE_URL supporta tutti i parametri libpq standard, incluso sslmode=require per le connessioni criptate.
• TLS: Metti il server e il dashboard dietro un reverse proxy (nginx, Caddy, Traefik) che termina TLS.
• Firewall: La porta del server (default 8080) dovrebbe essere raggiungibile solo da macchine di raccoltore e dall’host del dashboard, non da internet pubblico.
• Chiave admin: Imposta ADMIN_KEY su un segreto casuale forte. Dopo il bootstrap, crea chiavi scoped dedicate per i raccoglitori e il dashboard piuttosto che usare la chiave admin ovunque.
• Tag di immagine: Fissa alla versione nei tuoi manifesti di release (ad esempio, server:v0.0.1-beta.48) in produzione piuttosto che un tag fluttuante per evitare aggiornamenti non intenzionali. I build beta attuali vengono pubblicati sotto beta-latest; latest è assegnato solo ai rilasci stabili.
• Monitoraggio della salute: Su Kubernetes il probe di readiness utilizza /ready (raggiungibilità Postgres + ClickHouse) mentre la liveness rimane su /health. Per il “AgentEye stesso è su?” alerting a livello di flotta a Slack, abilita il complemento Robusta opt-in; vedi enterprise-docs/health-monitoring.md.

​

Tag di immagine disponibili