Primeros pasos con AgentEye

Esta guía te lleva a través de una configuración completa de AgentEye: desplegar el servidor y el panel de control, instalar el recopilador en una máquina agente e instrumentar tu código de agente Python.

¿Qué es AgentEye?

AgentEye es una plataforma de observabilidad y evaluación autoalojada para agentes de IA. Registra lo que hacen tus agentes —cada paso de una ejecución— y puntúa automáticamente la calidad de cada ejecución completada, para que puedas ver cómo se comportan tus agentes en producción y detectar regresiones antes de que las vean tus usuarios. Los datos fluyen en una sola dirección: tu código de agente emite eventos a través del SDK de Python → un daemon recopilador ligero los agrupa y los envía al servidor → los eventos y los análisis se almacenan en ClickHouse (el estado operacional, como organizaciones, usuarios, claves API, paneles de control y consultas guardadas, vive en Postgres) → explores todo en el panel de control. Lo que obtienes:

Eventos — el rastro en bruto, paso a paso, de cada ejecución del agente (llamadas a herramientas, llamadas a modelos, hooks, errores).
Sesiones — esos eventos consolidados en una fila por ejecución, cada una evaluada y puntuada automáticamente.
Evaluaciones — puntuaciones de calidad producidas por tus propios servicios evaluadores, para que los descensos de calidad sean visibles sin revisión manual.
Consultas y paneles — SQL de ClickHouse guardado sobre tus datos, representado en paneles compartidos con alcance por organización.
Alertas e incidentes — reglas de umbral que te notifican (email, Slack, webhook, dentro del panel) más un flujo de trabajo de incidentes para gestionarlos.
CLI y asistente de IA — un cliente de terminal (agenteye) y un asistente integrado en el panel para hacer preguntas en lenguaje natural.

Todo se ejecuta en tu propia infraestructura, como una pila Docker Compose (esta guía), una instalación Kubernetes de producción o un único pod coubicado. El resto de esta guía configura la pila Compose de principio a fin.

Paso 1: Autenticarte

Todos los artefactos de AgentEye se distribuyen desde la organización GitHub agenteye-enterprise. Como desarrollador empresarial, puedes generar tu propio GitHub PAT. Sigue enterprise-docs/github-token.md para ver los pasos exactos y los permisos requeridos.

export AGENTEYE_TOKEN=<your-github-pat>

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

Paso 2: Desplegar el servidor y el panel de control

El servidor recibe eventos de los recopiladores y los hace consultables; el panel de control es donde los exploras. Los eventos ingeridos y los análisis viven en ClickHouse (el almacén de análisis requerido), mientras que Postgres almacena el estado operacional como organizaciones, usuarios, claves API, paneles de control y consultas guardadas. Descarga el archivo compose publicado:

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

Configura tus secretos: Crea un archivo .env para que el despliegue no se ejecute con la credencial predeterminada admin. Como mínimo, establece ADMIN_KEY y POSTGRES_PASSWORD:

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

Inicia la pila:

docker compose up -d

Esto levanta la pila completa, incluido el almacén de análisis ClickHouse requerido y una caché Redis opcional, junto con el servidor y el panel de control. ClickHouse debe estar en buen estado para que el servidor arranque. El servidor está ahora escuchando en http://localhost:8080 y el panel de control en http://localhost:3000. Para despliegues en producción (Postgres personalizado, TLS, proxy inverso), consulta enterprise-docs/deployment.md.

Paso 3: Crear una clave API para el recopilador

Cada recopilador se autentica con una clave API con alcance definido. Usa el ADMIN_KEY que estableciste en el Paso 2 para crear 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"]}'

Tú proporcionas el valor de key; úsalo en la configuración del recopilador en el Paso 4. Consulta enterprise-docs/api-keys.md para la gestión completa de claves.

Paso 4: Instalar el recopilador

En cada máquina que ejecute tus agentes de IA, instala el daemon recopilador. Descarga el 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

Esto descarga la compilación para Linux x86_64. Para macOS (Apple Silicon o Intel), Linux arm64, o la configuración con Docker / systemd / launchd, consulta collector-installation.md, que lista la descarga para cada plataforma; el comando anterior instala un binario de Linux que no funcionará en otros entornos.

Configura:

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

Inicia el daemon:

agenteye-collector start

Verifica la conectividad con un vaciado puntual (finaliza tras vaciar cualquier evento pendiente):

agenteye-collector flush

Para la configuración con Docker, systemd y launchd, consulta enterprise-docs/collector-installation.md.

Paso 5: Instalar el SDK de Python

En cada máquina donde quieras instrumentar código de agente, instala el wheel desde 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

Paso 6: Instrumentar tu agente

Añade eventos a tu código de agente. Como mínimo, emite agent_start y 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",
)

Los eventos se almacenan en búfer y se vacían en $AGENTEYE_HOME/events/ (o ~/.agenteye/events/ si AGENTEYE_HOME no está definido) cada 500 ms. El recopilador los recoge automáticamente. Consulta enterprise-docs/python-sdk.md para la API completa de eventos.

Paso 7: Ver eventos en el panel de control

Abre http://your-dashboard-host:3000 e inicia sesión. AgentEye te envía por email un código de un solo uso (o un enlace mágico de un clic), por lo que no hay contraseña que gestionar.

La pantalla de inicio de sesión de AgentEye, que envía un código de un solo uso a tu email

Una vez dentro, la página Events muestra un rastro en tiempo real de todos los eventos ingeridos. Filtra por session_id o agent_id para profundizar en una ejecución específica.

El flujo de eventos en vivo, codificado por colores según el tipo de evento y filtrable por entorno, agente y sesión

La página Sessions consolida esos eventos en una fila por ejecución. AgentEye evalúa automáticamente las sesiones completadas, por lo que cada ejecución queda puntuada y las regresiones de calidad son visibles sin revisión manual; la puntuación de evaluación más reciente aparece en cada fila de un vistazo:

La lista de sesiones, una fila por ejecución, con indicadores de estado e insignias de puntuación de evaluación

Para configurar cómo se puntúan las sesiones, consulta enterprise-docs/evaluation-suite.md. Haz clic en cualquier sesión para abrir su grafo de ejecución, una vista estilo git de cómo se desplegaron agentes, herramientas, hooks y llamadas a modelos a lo largo del tiempo, con subagentes paralelos en sus propios carriles y un desglose por ejecución en el panel derecho:

El grafo de ejecución estilo git de una sesión junto a su línea de tiempo de eventos, con el panel de desglose de herramientas/modelos/hooks

Paso 8: Explorar, visualizar y configurar alertas

Con los eventos fluyendo, las páginas de análisis convierten la actividad en bruto en respuestas, para que puedas medir el comportamiento de los agentes, compartir hallazgos con el equipo y recibir notificaciones en el momento en que algo regresione. Las páginas del panel tienen alcance por organización, por lo que las URL que ves en la barra de direcciones llevan el prefijo de tu slug de organización (/<org>/…).

Queries (/<org>/queries): comienza desde una biblioteca de consultas guardadas y reutilizables sobre tus eventos y evaluaciones (preajustes integrados más los tuyos)…

La biblioteca de consultas guardadas: una cuadrícula de consultas reutilizables, tanto preajustes integrados como personalizadas

…luego abre una en el compositor SQL para ajustarla y ejecutarla con resultados en tiempo real:

El compositor de consultas SQL ejecutando una consulta guardada, con una barra lateral de esquema y una cuadrícula de resultados en vivo

Dashboards (/<org>/dashboards): ancla consultas como mosaicos de líneas, barras, áreas o sectores en paneles compartidos para toda la organización.

Un panel construido con consultas guardadas: una línea de eventos por hora, una barra de errores por tipo, un gráfico de área de latencia y tokens por modelo

Alerts (/<org>/alerts): convierte cualquier umbral en una regla de notificación que avisa por email, Slack, webhook o dentro del panel. Consulta enterprise-docs/alerts.md.

Próximos pasos

Despliegue: configuración robusta para producción
Claves API: gestión de accesos
Solución de problemas: diagnóstico de incidencias

​¿Qué es AgentEye?

​Paso 1: Autenticarte

​Paso 2: Desplegar el servidor y el panel de control

​Paso 3: Crear una clave API para el recopilador

​Paso 4: Instalar el recopilador

​Paso 5: Instalar el SDK de Python

​Paso 6: Instrumentar tu agente

​Paso 7: Ver eventos en el panel de control

​Paso 8: Explorar, visualizar y configurar alertas

​Próximos pasos