> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Primeros pasos con AgentEye

> Documentación de 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](/es/agenteye/github-token) para ver los pasos exactos y los permisos requeridos.

```bash theme={null}
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:**

```bash theme={null}
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`:

```bash theme={null}
POSTGRES_PASSWORD=your-db-password
ADMIN_KEY=your-admin-secret
```

**Inicia la pila:**

```bash theme={null}
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](/es/agenteye/deployment).

***

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

```bash theme={null}
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](/es/agenteye/api-keys) 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):**

```bash theme={null}
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](/es/agenteye/collector-installation), que lista la descarga para cada plataforma; el comando anterior instala un binario de Linux que no funcionará en otros entornos.

**Configura:**

```bash theme={null}
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:**

```bash theme={null}
agenteye-collector start
```

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

```bash theme={null}
agenteye-collector flush
```

Para la configuración con Docker, systemd y launchd, consulta [enterprise-docs/collector-installation.md](/es/agenteye/collector-installation).

***

## Paso 5: Instalar el SDK de Python

En cada máquina donde quieras instrumentar código de agente, instala el wheel desde GitHub Releases.

```bash theme={null}
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`:

```python theme={null}
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](/es/agenteye/python-sdk) 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.

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/login.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=8f83cb747193d872f7883cb709587635" alt="La pantalla de inicio de sesión de AgentEye, que envía un código de un solo uso a tu email" width="2880" height="1800" data-path="agenteye/images/login.png" />

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.

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/events-stream.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=79714903a85d10773f4f9b36cb44b1cf" alt="El flujo de eventos en vivo, codificado por colores según el tipo de evento y filtrable por entorno, agente y sesión" width="2880" height="1800" data-path="agenteye/images/events-stream.png" />

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:

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/sessions-list.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=10de161665eef64465d3d100e80b643f" alt="La lista de sesiones, una fila por ejecución, con indicadores de estado e insignias de puntuación de evaluación" width="2880" height="1800" data-path="agenteye/images/sessions-list.png" />

Para configurar cómo se puntúan las sesiones, consulta [enterprise-docs/evaluation-suite.md](/es/agenteye/evaluation-suite).

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:

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/session-detail.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=63cc2480e8124a05ea6a0a92d5f20690" alt="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" width="2880" height="1800" data-path="agenteye/images/session-detail.png" />

***

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

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/queries.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=1b42be492d5b650b4bd6b8a2241f6633" alt="La biblioteca de consultas guardadas: una cuadrícula de consultas reutilizables, tanto preajustes integrados como personalizadas" width="2880" height="1800" data-path="agenteye/images/queries.png" />

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

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/query-lab.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=aec1a1d95bb0bf1280d62a2e2430f20e" alt="El compositor de consultas SQL ejecutando una consulta guardada, con una barra lateral de esquema y una cuadrícula de resultados en vivo" width="2880" height="1800" data-path="agenteye/images/query-lab.png" />

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

<img src="https://mintcdn.com/exosphere/RgxYS1UZshqb4m7m/agenteye/images/dashboard-fleet.png?fit=max&auto=format&n=RgxYS1UZshqb4m7m&q=85&s=d1fed0deace0ebb0bc02421f3b994107" alt="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" width="2880" height="1800" data-path="agenteye/images/dashboard-fleet.png" />

* **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](/es/agenteye/alerts).

***

## Próximos pasos

* [Despliegue](/es/agenteye/deployment): configuración robusta para producción
* [Claves API](/es/agenteye/api-keys): gestión de accesos
* [Solución de problemas](/es/agenteye/troubleshooting): diagnóstico de incidencias