Saltar al contenido principal
El daemon agenteye-collector garantiza que la telemetría de tus agentes llegue a AgentEye sin bloquear nunca tu aplicación. Tu código escribe eventos en un directorio local y continúa su ejecución; el collector toma el control desde ese momento, subiendo cada archivo en milisegundos y sobreviviendo reinicios, interrupciones de red y errores transitorios del servidor. Las subidas fallidas se reintentan con retroceso exponencial, y un barrido periódico de recuperación vuelve a encolar cualquier archivo que haya quedado pendiente tras un fallo o despliegue. El resultado es una entrega durable y de tipo “lanzar y olvidar”: tus agentes siguen funcionando a plena velocidad mientras el collector garantiza que ningún evento se pierda en tránsito. Mecánicamente, el collector es un daemon ligero que monitorea $AGENTEYE_HOME/events/ (por defecto: ~/.agenteye/events/) en busca de archivos .jsonl escritos por el SDK de Python y los sube al servidor de AgentEye.
Cambio de nombre: el comando del collector ahora es agenteye-collector (antes era agenteye). El nombre abreviado agenteye ahora pertenece al CLI de AgentEye. Si estás actualizando una instalación existente, consulta enterprise-docs/collector-migration.md.

Requisitos previos


Opción A: Binario (recomendado)

Hay binarios estáticos precompilados disponibles para Linux, macOS y Windows (x86_64 y arm64). Descarga el binario para tu plataforma directamente desde el repositorio agenteye-enterprise/releases, bajo la etiqueta de lanzamiento más reciente collector/v<version>. Nombres de artefactos disponibles:
PlataformaArtefacto
Linux x86_64agenteye-collector-linux-x86_64
Linux arm64agenteye-collector-linux-arm64
macOS x86_64agenteye-collector-darwin-x86_64
macOS arm64agenteye-collector-darwin-arm64
Windows x86_64agenteye-collector-windows-x86_64.exe
Windows arm64agenteye-collector-windows-arm64.exe
Descargar con el CLI gh (reemplaza la versión y elige el artefacto de tu plataforma):
O con curl:

Opción B: Docker

Las compilaciones beta actuales publican la etiqueta flotante :beta-latest; la etiqueta :latest solo se asigna a versiones estables. Para despliegues reproducibles, se recomienda usar una etiqueta de versión fija como :v0.0.1-beta.13.
Ejecutar:
La imagen oficial se ejecuta como usuario no-root, por lo que debes definir AGENTEYE_HOME explícitamente y montar el directorio de cola del host en él. El montaje de volumen comparte el mismo directorio ~/.agenteye/ en el que el SDK de Python escribe en el host. Si ya tienes AGENTEYE_HOME configurado en otra ubicación del host, monta ese directorio en lugar de $HOME/.agenteye.

Configuración

Todas las opciones pueden establecerse de tres formas (de mayor a menor prioridad):
  1. Bandera de CLI: agenteye-collector start --url https://...
  2. Variable de entorno: AGENTEYE_URL=https://...
  3. Archivo de configuración: ~/.agenteye/config.json

Opciones obligatorias

OpciónBandera CLIVariable de entornoClave en config.json
URL del backend--url <URL>AGENTEYE_URL"url"
Clave de API--key <KEY>AGENTEYE_KEY"key"

Opciones opcionales (con valores por defecto)

OpciónBandera CLIVariable de entornoClave en config.jsonPor defecto
Máx. subidas simultáneas--max-concurrent-uploads <N>AGENTEYE_MAX_CONCURRENT_UPLOADS"max_concurrent_uploads"64
Intervalo del barrido (s)--sweep-interval <S>AGENTEYE_SWEEP_INTERVAL"sweep_interval_secs"60
Edad mínima de archivo para barrido (s)--sweep-min-age <S>AGENTEYE_SWEEP_MIN_AGE"sweep_min_age_secs"120
Máx. archivos por barrido--sweep-max-files <N>AGENTEYE_SWEEP_MAX_FILES"sweep_max_files"64
Máx. intentos de subida--max-retries <N>AGENTEYE_MAX_RETRIES"max_retries"5
Retardo base de reintento (ms)--retry-base-delay <MS>AGENTEYE_RETRY_BASE_DELAY"retry_base_delay_ms"1000

Opciones mTLS (opcionales)

Para despliegues que requieren TLS mutuo (mTLS), el collector puede presentar un certificado de cliente durante el protocolo de enlace TLS. Si no se configuran estas opciones, el collector utiliza HTTPS estándar.
OpciónBandera CLIVariable de entornoClave en config.json
Certificado de cliente (PEM)--tls-cert <PATH>AGENTEYE_TLS_CERT"tls_cert"
Clave privada del cliente (PEM)--tls-key <PATH>AGENTEYE_TLS_KEY"tls_key"
Certificado CA personalizado (PEM)--tls-ca <PATH>AGENTEYE_TLS_CA"tls_ca"
--tls-cert y --tls-key deben configurarse juntos. Los archivos deben estar codificados en PEM. --tls-ca es independiente y solo es necesario cuando el servidor de AgentEye presenta un certificado TLS que no ha sido emitido por una CA de confianza pública (por ejemplo, autofirmado por un emisor cert-manager dentro del clúster cuando no tienes un dominio DNS real). El collector añade la CA proporcionada como ancla de confianza adicional; las raíces públicas estándar siguen siendo de confianza, por lo que los despliegues existentes no se ven afectados. El archivo puede contener un único certificado PEM o una cadena completa (múltiples bloques PEM concatenados). ¿Ejecutas el collector como sidecar en tu pod de aplicación? Consulta enterprise-docs/single-pod-deployment.md para ver el patrón completo en EKS: paquete mTLS entregado mediante AWS Secrets Manager + Secrets Store CSI Driver + IRSA, con rotación automática. Cuando se ejecuta en Kubernetes con el patrón de transferencia de Secrets, monta el Secret del certificado como un volumen y apunta estas rutas a los archivos montados:

Ejemplo de ~/.agenteye/config.json

Con mTLS:
Con mTLS más una CA personalizada (servidor AgentEye autofirmado):
Si AGENTEYE_HOME está definido, se usará ese directorio en lugar de ~/.agenteye.

Configuración inicial

Tras la instalación, configura el collector con la URL de tu servidor y la clave de API:
Usa https para cualquier despliegue que atraviese una red no confiable, de modo que los eventos no se envíen en texto plano. El formato en texto plano http://your-server-host:8080/events solo es apropiado para pruebas puramente locales contra un servidor en el mismo host.
Probar la conexión (vaciado puntual, finaliza tras drenar los eventos pendientes):
flush reporta su progreso por stdout. Cuando la cola está vacía, imprime No pending files. y termina con código 0. En caso contrario, imprime una línea por archivo ([UPLOADED] <file> o [FAILED] <file> (<reason>)), seguida de un resumen Done: <uploaded>/<total> uploaded, <failed> failed.. Esto convierte a flush en una verificación puntual muy práctica para comprobar que tu URL, clave y configuración TLS son correctos antes de iniciar el daemon.

Ejecución como daemon

Directamente

Contenedor / Docker

Cuando el collector y tu aplicación comparten un contenedor, ejecútalos bajo un supervisor de procesos. La opción más sencilla es supervisord; está disponible en todas las distribuciones principales, reinicia los procesos que fallen, reenvía señales y espera a un apagado controlado. Dockerfile:
supervisord.conf:
Por qué estas configuraciones:
  • autorestart=true en agenteye-collector: reinicia ante cualquier salida (fallo, pánico, OOM).
  • autorestart=unexpected en la aplicación: solo reinicia en caso de salida con código distinto de cero, de modo que un agente puntual que termine con código 0 no entre en bucle.
  • stopwaitsecs=30: da al collector margen para drenar las subidas pendientes al recibir SIGTERM antes de que supervisord escale a SIGKILL.
  • stdout_logfile=/dev/stdout, *_maxbytes=0: redirige la salida de ambos programas al stdout del contenedor; sin archivos de log dentro del contenedor.
Pasa AGENTEYE_URL / AGENTEYE_KEY (y cualquier variable de entorno TLS) con docker run -e como de costumbre; supervisord hereda el entorno.
¿Contenedores separados? Si ejecutas el collector en su propio contenedor (servicio de Docker Compose, sidecar de Kubernetes, etc.), no uses supervisord; la política de reinicio del runtime de contenedores ya se encarga de eso. Consulta enterprise-docs/single-pod-deployment.md para ver el patrón de sidecar en EKS.
Sonda de liveness de Kubernetes (aplica tanto si el collector se ejecuta solo como bajo supervisord):
El daemon en ejecución escribe un latido en $AGENTEYE_HOME/health.json cada 30 segundos. agenteye-collector health lee ese archivo y termina con código 0 (saludable) solo cuando el latido es reciente y las tareas de subida se están ejecutando con normalidad; termina con código 1 (no saludable) cuando el latido tiene más de 90 segundos de antigüedad (por ejemplo, el daemon se ha detenido) o mientras el observador y el barredor se están reiniciando tras una salida inesperada. El latido solo es escrito por start, así que ejecuta la sonda contra el daemon de larga duración y no contra el comando puntual flush.

systemd (Linux, recomendado para producción)

Crea /etc/agenteye/env:

launchd (macOS)


Actualización del Collector

El collector no se actualiza a sí mismo. Para actualizarlo:
  • Binario: descarga el nuevo artefacto agenteye-collector-<os>-<arch> desde la última versión collector/v<version> (consulta Opción A), reemplaza /usr/local/bin/agenteye-collector y reinicia el servicio (sudo systemctl restart agenteye-collector, vuelve a ejecutar launchctl load, o reinicia tu supervisor).
  • Docker: ejecuta docker pull ghcr.io/agenteye-enterprise/collector:beta-latest (o una etiqueta fija :v<version>; :latest solo existe para versiones estables) y recrea el contenedor.
AGENTEYE_TOKEN es necesario para descargar nuevos binarios/imágenes del repositorio de versiones privado, pero no es necesario para el daemon en ejecución.

Subcomandos

ComandoDescripción
agenteye-collector startInicia el daemon de larga duración. Al arrancar, vacía cualquier evento que haya quedado de una ejecución anterior, luego monitorea nuevos archivos y los sube. El observador y el barredor se reinician automáticamente ante salidas inesperadas, y se escribe un latido en health.json cada 30 segundos.
agenteye-collector flushPuntual: sube todos los archivos pendientes y termina. Imprime No pending files. cuando la cola está vacía; en caso contrario, un registro [UPLOADED]/[FAILED] por archivo y un resumen Done: <uploaded>/<total> uploaded, <failed> failed..
agenteye-collector healthLee el latido health.json del daemon. Termina con código 0 cuando está reciente y saludable; termina con código 1 cuando el latido está desactualizado (más de 90s) o las tareas se están reiniciando.

Estructura de directorios

Los archivos en failed/ no se reintentan automáticamente. Para volver a ponerlos en cola manualmente, muévelos de nuevo a events/ y ejecuta agenteye-collector flush.