Suite de Evaluación

Nota: Tú defines las dimensiones de puntuación. Tu evaluador puede devolver las claves numéricas que quiera; Observability almacena, analiza tendencias y muestra todo lo que le envíes.

​

Resumen rápido

1. Escribe un evaluador. Levanta un pequeño servicio HTTP que lea la transcripción de una sesión y devuelva puntuaciones. Observability incluye una referencia funcional que puedes copiar. Consulta Escribir un evaluador con el SDK.
2. Apunta Observability hacia él. Configura EVALUATOR_ENDPOINT (y un EVALUATOR_TOKEN compartido) en el proceso del servidor.
3. Observa cómo llegan las puntuaciones. Cada sesión completada se puntúa automáticamente; los resultados aparecen en la página de detalle de sesión, la cuadrícula de sesiones y los dashboards guardados.

​

Cómo funciona

• 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 la respuesta con {"status":"pending", "job_id":"abc-123"}. Observability entonces llama a GET {EVALUATOR_ENDPOINT}/evaluate/abc-123 hasta que tu evaluador devuelva {"status":"done", ...} o {"status":"error", "error":"..."}. La cadencia de sondeo es por trabajo: una respuesta pending puede incluir next_poll_secs para sobreescribirla; de lo contrario, Observability usa el valor default_poll_interval_secs de GET /config; si tampoco está definido, el servidor recurre a EVALUATOR_POLLING_INTERVAL_SECS (10s por defecto). Todos los valores se limitan al rango [1s, 1h].

​

Contrato HTTP

• Servidor de Observability: 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": { ... } },
    ...
  ]
}

​

Formatos 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

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 tu evaluador

​

Configurar el servidor

​

Referencia de la API

​

Filtrar por rango de puntuación: score_filters

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

# tool_efficiency como máximo 0.3 (sin límite inferior)
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

​

Ver 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 de re-evaluate junto al botón de exportación, útil para sesiones que nunca emitieron agent_end o para actualizar puntuaciones tras desplegar un nuevo evaluador. El dashboard sondea el nuevo resultado y actualiza el panel lateral cuando llega.
• /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 evaluación (consulta Dashboards más abajo).

​

Dashboards

• Filtros: los mismos controles que la página de sesiones: entorno, estado, agente, una ventana de tiempo deslizante y filtros de rango de puntuación (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 última evaluación por sesión.

​

Resolución de problemas

​

Próximos pasos

• Habilidad de agente evaluador: haz que un agente de programación diseñe tus dimensiones a partir de sesiones reales y construya este servicio por ti.
• Python SDK: emite los eventos agent_end que desencadenan la puntuación.
• Claves de API: los permisos evaluations:read y evaluations:trigger.
• Auditorías: la otra función de calidad automatizada de Observability, para revisión basada en políticas.