Despliegue

​

Visión general de la arquitectura

  [ Máquinas con agentes de IA ]         [ Tu infraestructura ]

    Python SDK
       |  escribe JSONL                      +----------------------+
       v                                +--->| PostgreSQL 15+       |
 agenteye-collector --HTTP--+           |    | (almacén relacional) |
                            |           |    +----------------------+
                            v           |
                       +--------+       |    +----------------------+
                       | Server |<------+--->| ClickHouse 24+       |
                       +--------+       |    | (eventos/analítica)  |
                            ^           |    +----------------------+
                        API |           |
                            |           |    +----------------------+
                      +-----------+     +- - >| Redis 7+ (opcional) |
                      | Dashboard |           +----------------------+
                      +-----------+

• Server: Servicio HTTP en Rust; recibe lotes de eventos, los escribe en ClickHouse y mantiene el estado relacional en PostgreSQL.
• Dashboard: Aplicación web Next.js; lee y escribe exclusivamente a través de la API del servidor.
• agenteye-collector: se despliega en las máquinas de los agentes, no en el host del servidor.
• Postgres 15+: OBLIGATORIO. (Actualizado desde la versión 14 en la versión multi-tenant; el esquema de pertenencia a organizaciones usa una clave foránea ON DELETE SET NULL con lista de columnas, disponible desde Postgres 15+. Actualiza Postgres antes de desplegar esta versión.) Almacena el estado OLTP: api_keys, users, sessions, evaluation_jobs (cola), dashboards, saved_queries, otp_codes, además de las tablas multi-tenant orgs, org_memberships, org_settings.
• ClickHouse 24+: OBLIGATORIO. El almacén de analítica para cada evento ingerido. Motor: ReplacingMergeTree, particionado por mes, ordenado por (session_id, ts, dedup_key). El servidor se conecta a través de CLICKHOUSE_URL; el deploy/base/clickhouse/ incluido incorpora una configuración de nodo único optimizada para rendimiento. Requisito multi-tenant: la configuración incluida habilita la gestión de acceso SQL + users_without_row_policies_can_read_rows=false para que el servidor pueda crear un usuario de ClickHouse de solo lectura + política de fila por organización (el límite de aislamiento impuesto por el motor para el editor SQL y el agente de IA). Si usas tu propia configuración de ClickHouse, incorpora estos ajustes (ver deploy/base/clickhouse/configmap.yaml).
• Redis 7+: caché compartida opcional + backend de limitación de tasa. El servidor y el panel se conectan a través de REDIS_URL. Si no está disponible, ambos degradan de forma controlada a rutas que solo usan Postgres. Consulta Redis (caché opcional) a continuación.

​

Servidor

​

Descargar la imagen

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

Las compilaciones actuales se publican con beta-latest; latest solo se asigna a versiones estables. Para producción, fija una etiqueta específica :v<versión>; consulta Etiquetas de imagen disponibles.

​

Variables de entorno

​

Ejecutar

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

​

Verificación de estado

GET /health    # liveness  - siempre {"status":"ok"} una vez que el proceso está activo
GET /ready     # readiness - 200 cuando Postgres + ClickHouse son accesibles, si no 503

​

URL del enlace mágico por correo

1. Encabezado X-AgentEye-Dashboard-Url: lo establece automáticamente el proxy /api/auth/otp/request del panel desde su propio origen público. En un despliegue del mismo origen (el servidor y el panel comparten un host detrás de un ingress que reenvía encabezados proxy), no se requiere ninguna configuración.
2. Variable de entorno DASHBOARD_URL: establécela si tu panel es accesible en un origen diferente al que ve el endpoint de solicitud OTP del servidor (dominios separados api.example.com / app.example.com), o si tu ingress no propaga el host público al pod del panel (de modo que request.nextUrl.origin de otro modo resolvería a una dirección de vinculación comodín como 0.0.0.0:3000). Ejemplo: DASHBOARD_URL=https://app.example.com.
3. Valor predeterminado: https://app.befailproof.ai, usado solo si ninguno de los anteriores está presente.

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

​

Panel de control

​

Descargar la imagen

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

​

Variables de entorno

​

Ejecutar

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

​

Telemetría y privacidad

• Ningún dato de agente, sesión o evento sale nunca de tu infraestructura. Solo se informa el uso de la interfaz de usuario del panel. Las URL de las páginas se eliminan de identificadores antes de enviarlas, y los operadores se identifican solo por un ID interno opaco, nunca por correo electrónico.
• La telemetría está habilitada de forma predeterminada. Para desactivarla completamente, establece AE_ANALYTICS_DISABLED=1 en el contenedor del panel y reinícialo.
• La analítica se envía a la propia ruta /ingest del panel, que el panel envía en proxy inverso a PostHog (https://us.i.posthog.com). Mantener las solicitudes como propias significa que los bloqueadores de anuncios del navegador no las descartan. El contenedor del panel necesita acceso saliente a PostHog; si está bloqueado, la telemetría no hace nada silenciosamente y el panel no se ve afectado.

​

Asistente de IA (opcional)

​

ClickHouse (almacén de analítica obligatorio)

​

Esquema

• agenteye.events: ReplacingMergeTree(ingested_at), particionado por toYYYYMM(ts), ordenado por (session_id, ts, dedup_key). Las inserciones duplicadas (reintentos del collector) colapsan a una sola fila en el momento de la fusión; el servidor calcula un dedup_key SHA-256 determinista para cada evento de modo que los reintentos son seguros.
• agenteye.evaluations: ReplacingMergeTree(ingested_at), particionado por toYYYYMM(finished_at), ordenado por (session_id, finished_at, dedup_key). Escrito una vez por resultado de evaluación terminal por la canalización del evaluador. Mismo modelo de clave de deduplicación que events.
• agenteye.agent_sessions: una VISTA sobre agenteye.events, no una tabla física. Cada columna es derivada (started_at = min(ts), last_event_at = max(ts), ended_at = max(if event_type='agent_end', ts, NULL), event_count = count(), etc.). Sin upsert por evento y sin relleno retroactivo separado; la vista refleja automáticamente lo que hay en events.

​

Configuración

• 2 GiB solicitados / 4 GiB límite de memoria en el overlay base incluido (dimensionado para nodos pequeños de POC/staging); los clientes de producción deberían aumentarlo — el mínimo recomendado es 2c / 4Gi de solicitud, 6c / 8Gi de límite. max_server_memory_usage_to_ram_ratio=0.9
• 5 GiB de caché de marcas + 8 GiB de caché sin comprimir
• 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 en kernels compatibles)
• fsync_metadata=0: aceptable por la ingestión at-least-once + deduplicación ReplacingMergeTree
• query_log habilitado con TTL de 30 días; query_thread_log eliminado (costoso con QPS alto)
• max_execution_time=30 para consultas del lado del usuario
• 100 GiB PVC en la plantilla StatefulSet (los overlays de los clientes DEBEN sobreescribir a una clase de almacenamiento SSD rápida para producción)

​

Copias de seguridad

​

Redis (caché opcional)

• El servidor almacena en caché las búsquedas de claves API autenticadas, las listas /events/environments + /evaluations/environments, el rollup /events/latency_aggregate (la consulta más pesada que sondea el panel), la lista /sessions, y cambia la limitación de tasa de solicitudes OTP de un COUNT(*) de Postgres a un INCR + EXPIRE de Redis.
• El panel almacena en caché los resultados de validateSession() para que las 10-20 llamadas API autenticadas que emite una carga de página típica compartan una sola verificación de sesión ascendente. También limita la tasa de solicitudes OTP y verificación OTP en el edge del panel.

​

Configuración

​

Memoria + persistencia

​

Cuándo NO desplegar Redis

• Desarrollo/QA de instancia única. Las cachés en proceso del servidor por sí solas ofrecen la mayor parte del beneficio por réplica; Redis añade el uso compartido entre réplicas que las configuraciones de instancia única no necesitan.
• Instalaciones aisladas de la red donde el coste operativo de ejecutar un servicio más supera la mejora de latencia.

​

Docker Compose (recomendado)

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

# Usa contraseñas seguras para URL (sin caracteres /, + ni =).
# Genera con: openssl rand -hex 24
POSTGRES_PASSWORD=your-db-password
ADMIN_KEY=your-admin-secret

# Autenticación del panel
ADMIN_EMAIL=admin@yourcompany.com
ALLOWED_EMAILS=*@yourcompany.com

# SMTP para correos OTP (omite para registrar los códigos OTP en 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

​

Ajustes operativos

​

Cómo funciona el arranque

• Para un despliegue nuevo, establece las variables de entorno como se muestra arriba y la organización predeterminada las leerá en el primer arranque.
• Para cambiar un valor más adelante, inicia sesión en el panel y edítalo en /<org>/settings. El cambio se aplica en segundos en todas las réplicas del servidor; no se necesita reinicio.
• Una línea de registro al inicio registra qué se sembró frente a qué ya estaba presente, para que puedas confirmar que el arranque surtió efecto:
  INFO settings bootstrap: seeded default-org row key=allowed_sign_ins env_var=ALLOWED_EMAILS seeded_from_env=true
  

​

Semántica de inicio de sesión entre organizaciones

• Duración de sesión / OTP: gana la duración más estricta (más corta) entre las organizaciones a las que pertenece el usuario.
• Inicios de sesión permitidos: la puerta hace un OR de la lista de permitidos de cada organización junto con la pertenencia a la organización: un usuario puede solicitar un OTP si la lista de permitidos de cualquier organización admite su correo electrónico o ya es miembro de cualquier organización.

​

Permisos

• settings:read: ver la página y los valores actuales.
• settings:write: guardar cambios.

​

Organizaciones (multi-tenancy)

# Docker Compose - ejecutar dentro del servicio de servidor en ejecución:
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 - ejecutar dentro del Deployment del servidor en ejecución:
kubectl -n agenteye exec deploy/server -- agenteye-orgctl org list

​

Relleno de la ventana de contexto

# vista previa (imprime la mutación por organización, no cambia nada):
kubectl -n agenteye exec deploy/server -- agenteye-backfill-context-window --dry-run
# aplicar:
kubectl -n agenteye exec deploy/server -- agenteye-backfill-context-window
# docker compose:
docker compose exec server agenteye-backfill-context-window

​

Consideraciones de producción

• Postgres: Usa un servicio de Postgres gestionado o una instancia dedicada con copias de seguridad regulares. El DATABASE_URL admite todos los parámetros libpq estándar, incluido sslmode=require para conexiones cifradas.
• TLS: Coloca el servidor y el panel detrás de un proxy inverso (nginx, Caddy, Traefik) que termine TLS.
• Firewall: El puerto del servidor (por defecto 8080) solo debe ser accesible desde las máquinas del collector y el host del panel, no desde internet público.
• Clave de administrador: Establece ADMIN_KEY en un secreto aleatorio robusto. Después del arranque inicial, crea claves con alcance dedicado para los collectors y el panel en lugar de usar la clave de administrador en todas partes.
• Etiquetas de imagen: Fija la versión en los manifiestos de tu versión (por ejemplo, server:v0.0.1-beta.48) en producción en lugar de una etiqueta flotante para evitar actualizaciones no intencionadas. Las compilaciones beta actuales se publican con beta-latest; latest solo se asigna a versiones estables.
• Monitoreo de salud: En Kubernetes, el sondeo de readiness usa /ready (accesibilidad de Postgres + ClickHouse) mientras que el de liveness permanece en /health. Para alertas de “¿está AgentEye en sí mismo activo?” a toda la flota en Slack, habilita el complemento opcional de Robusta; consulta enterprise-docs/health-monitoring.md.

​

Etiquetas de imagen disponibles