Suite de Evaluación

1. Cómo se detecta la finalización de una sesión.
2. El contrato HTTP que debe implementar el evaluador.
3. Configuración del servidor AgentEye.
4. Visualización de resultados.
5. Solución de problemas.

​

Cómo funciona

ingest /events  ──▶  AgentEye  ──── POST /evaluate ────▶  Evaluator service
   (agent_end)        server   ◀──── done | pending ────
                          │
                          │     GET /evaluate/{job_id} ─────▶
                          │     ◀──── done ──────────────
                          ▼
                     evaluations  (terminal results)

• Devolver el resultado de forma inmediata con {"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}. El resultado se añade a la línea temporal de evaluaciones de la sesión. reasoning y summary son opcionales.
• Diferir con {"status":"pending", "job_id":"abc-123"}. AgentEye entonces llama a GET {EVALUATOR_ENDPOINT}/evaluate/abc-123 hasta que tu evaluador devuelva {"status":"done", ...} o {"status":"error", "error":"..."}. La cadencia de consulta es por trabajo: una respuesta pending puede incluir next_poll_secs para sobrescribirla; en caso contrario, AgentEye utiliza el valor default_poll_interval_secs de GET /config; si tampoco está disponible, el servidor recurre a EVALUATOR_POLLING_INTERVAL_SECS (por defecto 10s). Todos los valores se limitan al rango [1s, 1h].

​

Contrato HTTP

• Servidor AgentEye: variable de entorno EVALUATOR_TOKEN
• Servicio evaluador: configurado de la misma forma (el SDK agenteye-evaluator lee EVALUATOR_TOKEN por convención)

​

Rutas que el evaluador debe servir

​

Cuerpo EvalRequest enviado por el servidor

{
  "schema_version": "1",
  "session_id":     "session-abc123",
  "agent_id":       "planner",
  "environment":    "production",
  "started_at":     "2026-05-10T12:00:00Z",
  "ended_at":       "2026-05-10T12:05:00Z",
  "events": [
    { "id": 1234, "ts": "...", "event_type": "agent_start", "payload": { ... } },
    ...
  ]
}

​

Formas de respuesta

{
  "status": "done",
  "scores": { "helpfulness": 0.85, "tool_efficiency": 0.6 },
  "reasoning": {
    "helpfulness": "answered the question directly with citations",
    "tool_efficiency": "called list_files three times when one would have done"
  },
  "summary": "strong answer quality, weak tool selection"
}

{ "status": "pending", "job_id": "abc-123", "next_poll_secs": 30 }

{ "status": "error", "error": "model service unavailable" }

​

Escribir un evaluador con el SDK

pip install agenteye-evaluator

import os
from agenteye_evaluator import Evaluator, EvalRequest, EvalResponse

app = Evaluator(token=os.environ["EVALUATOR_TOKEN"])

@app.evaluator
def run(req: EvalRequest) -> EvalResponse:
    # Inspect req.events (the full session transcript) and return scores.
    tool_calls = sum(1 for e in req.events if e.event_type == "tool_use")
    return EvalResponse(
        scores={"tool_calls": float(tool_calls)},
        reasoning={"tool_calls": f"{tool_calls} tool invocations in the transcript"},
        summary="tight tool loop" if tool_calls < 5 else "agent looped on tools",
    )

​

Ejecutar un evaluador en Kubernetes

​

1. Conteneriza tu evaluador

FROM python:3.12-slim
WORKDIR /app
RUN pip install --no-cache-dir agenteye-evaluator uvicorn
COPY my_evaluator.py .
RUN useradd --uid 10001 --create-home --shell /usr/sbin/nologin evaluator \
    && chown -R evaluator:evaluator /app
USER evaluator
EXPOSE 9000
CMD ["uvicorn", "my_evaluator:app", "--host", "0.0.0.0", "--port", "9000"]

​

2. Crea el token bearer compartido

kubectl -n agenteye create secret generic evaluator-token \
  --from-literal=token="$(openssl rand -hex 32)"

​

3. Aplica los manifiestos de ejemplo

# Edit deploy/examples/evaluator/deployment.yaml first to point
# `image:` at your registry, then:
kubectl apply -k deploy/examples/evaluator/

• Un Deployment de 2 réplicas con runAsNonRoot, sistema de archivos raíz de solo lectura, todas las capabilities eliminadas, y liveness + readiness en /health
• Un Service de tipo ClusterIP en el puerto 9000
• Una plantilla secret.example.yaml (excluida intencionalmente de la Kustomization; crea el secret real fuera de banda para que ningún token acabe en git)

​

4. Conecta AgentEye al evaluador

EVALUATOR_ENDPOINT=http://evaluator:9000
EVALUATOR_TOKEN=<the value generated above>

​

Verificación

kubectl -n agenteye port-forward svc/evaluator 9000:9000
curl -s http://localhost:9000/health   # → {"status":"ok"}

​

Configurar el servidor AgentEye

​

Referencia de la API

​

Filtrar por rango de puntuaciones: score_filters

# helpfulness in [0.5, 0.8]
GET /evaluations?score_filters=helpfulness:0.5..0.8

# tool_efficiency at most 0.3 (no lower bound)
GET /evaluations?score_filters=tool_efficiency:..0.3

# helpfulness >= 0.5 AND factuality >= 0.9
GET /evaluations?score_filters=helpfulness:0.5..,factuality:0.9..

​

Permisos

​

Visualizar resultados

• /sessions/<id>: línea temporal de eventos + un panel lateral derecho que muestra las puntuaciones de la sesión y cualquier error del intento de despacho. Si tu clave tiene evaluations:trigger, aparece un botón re-evaluate junto al botón de exportar, útil para sesiones que nunca emitieron agent_end, o para actualizar puntuaciones tras desplegar un nuevo evaluador. El panel consulta el nuevo resultado periódicamente y actualiza el panel lateral cuando está disponible.
• /sessions: cuadrícula de sesiones filtrable; la columna de puntuación muestra el estado de evaluación y las puntuaciones de cada sesión de un vistazo.
• /dashboards: vistas guardadas de salud de evaluaciones (consulta Dashboards más abajo).

​

Dashboards

• Filtros: los mismos controles que la página de sesiones: entorno, estado, agente, una ventana de tiempo variable y filtros de rango de puntuaciones (key:min..max).
• Una configuración de visualización: qué claves de puntuación destacar, los umbrales de salud verde/ámbar/rojo, qué paneles mostrar y si colapsar a la evaluación más reciente por sesión.

​

Solución de problemas