> ## 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. # SDK de Evaluador > Construye un servicio que puntúe sesiones de Failproof AI de forma síncrona o asíncrona. Un evaluador recibe una sesión de agente completada y devuelve las señales de calidad que te interesan: puntuaciones numéricas, una explicación para cada puntuación y un resumen opcional. Failproof AI almacena estos resultados junto al rastro y los representa gráficamente a lo largo de agentes y entornos. ## Configurar un evaluador Instala el SDK y el servidor necesario para ejecutarlo. ```bash theme={null} pip install failproofai-sdk uvicorn ``` Crea `evaluator.py`. Este ejemplo comprueba si una sesión contiene alguna llamada a herramienta fallida. ```python theme={null} import os from failproofai.evaluator import Evaluator, EvalResponse app = Evaluator(token=os.environ.get("EVALUATOR_TOKEN")) @app.config def config(): return {"inactivity_timeout_secs": 1800} @app.evaluator def evaluate(req): tool_errors = sum( 1 for item in req.events if item.event_type == "tool_result" and item.payload.get("error") ) return EvalResponse( scores={"tool_reliability": 1.0 if tool_errors == 0 else 0.0}, reasoning={"tool_reliability": f"{tool_errors} tool errors"}, ) ``` Establece un token compartido, inicia el evaluador y confirma que su endpoint de salud responde. ```bash theme={null} export EVALUATOR_TOKEN= uvicorn evaluator:app --host 0.0.0.0 --port 8080 ``` En otra terminal: ```bash theme={null} curl http://127.0.0.1:8080/health ``` ## Conectar el evaluador a Failproof AI 1. Despliega el evaluador en una URL HTTPS accesible por Failproof AI Cloud. 2. Configura `EVALUATOR_ENDPOINT` con esa URL y establece `EVALUATOR_TOKEN` con el mismo token utilizado por el evaluador. Para Cloud gestionado, contacta con [support@befailproof.ai](mailto:support@befailproof.ai) para configurar la conexión. 3. Ejecuta una evaluación y confirma que sus puntuaciones aparecen en Failproof AI. Abre una sesión completada en **Observe → Sessions** y selecciona **Run evaluation** si no se evaluó automáticamente. Revisa el estado, las puntuaciones, el razonamiento y el resumen en el panel **Evaluation** de la sesión. Usa **Observe → Evaluations** para comparar puntuaciones entre agentes o entornos. Usa **Observe → Metrics** para mediciones de latencia, coste, tokens y otros valores numéricos. Comienza con una sola sesión para confirmar que el evaluador devolvió las claves de puntuación esperadas y un razonamiento útil para esa ejecución específica. Vista detallada de una sesión que muestra las puntuaciones de evaluación y el razonamiento junto a su rastro. Una vez que los resultados individuales parezcan correctos, usa el panel de evaluación para comparar esas puntuaciones a lo largo del tiempo y entre agentes o entornos. Panel de calidad con las puntuaciones del evaluador representadas a lo largo del tiempo. Un gráfico saludable debe usar nombres de puntuación estables; cambiar una clave crea una serie separada. ```bash theme={null} fp evals --since 1h --score tool_reliability:0..1 fp evals --since 24h --aggregate ``` Para una instancia de Cloud autohospedada, la evaluación automática está deshabilitada hasta que se establezca `EVALUATOR_ENDPOINT` en el proceso del servidor. Reinicia el servidor después de cambiar las variables de entorno del evaluador. El servicio expone `GET /health`, `GET /config`, `POST /evaluate` y opcionalmente `GET /evaluate/{job_id}`. Devuelve `JobPending` para trabajo asíncrono y registra `@app.job_lookup` para que Failproof AI pueda consultarlo periódicamente. Cuando hay un token configurado, todas las rutas excepto health requieren el mismo token bearer que Failproof AI envía como `EVALUATOR_TOKEN`. ## Tipos del SDK | Tipo | Campos | | ----------------- | --------------------------------------------------------------------------------------------- | | `AgentEvent` | `id`, `ts`, `event_type`, `payload` | | `EvalRequest` | `schema_version`, `session_id`, `agent_id`, `environment`, `started_at`, `ended_at`, `events` | | `EvalResponse` | `scores`, `reasoning`, `summary` | | `JobPending` | `job_id`, `next_poll_secs` | | `EvaluatorConfig` | `inactivity_timeout_secs`, `default_poll_interval_secs` | ## Decoradores y rutas | Decorador | Ruta | Obligatorio | | ----------------- | ------------------------ | ------------------------ | | `@app.evaluator` | `POST /evaluate` | Sí | | `@app.job_lookup` | `GET /evaluate/{job_id}` | Al devolver `JobPending` | | `@app.config` | `GET /config` | No | El SDK limita el cuerpo de las solicitudes de evaluación a 25 MiB. Los campos desconocidos de la solicitud se ignoran, de modo que los servicios permanecen compatibles a medida que el contrato de eventos evoluciona. ## Devolver trabajo asíncrono Usa `JobPending` cuando la evaluación no puede completarse dentro de una sola solicitud. El ID de trabajo es opaco para Failproof AI y debe permanecer resoluble por tu servicio hasta que el resultado sea recogido o expire el tiempo de espera del servidor. ```python theme={null} from failproofai.evaluator import EvalRequest, EvalResponse, Evaluator, JobPending app = Evaluator(token="shared-secret") @app.evaluator def start(req: EvalRequest) -> JobPending: job_id = enqueue(req) return JobPending(job_id=job_id, next_poll_secs=30) @app.job_lookup def lookup(job_id: str): result = get_result(job_id) if result is None: return JobPending(job_id=job_id, next_poll_secs=30) return EvalResponse( scores=result.scores, reasoning=result.reasoning, summary=result.summary, ) ``` La cadencia de consulta se selecciona en este orden: `JobPending.next_poll_secs`, `EvaluatorConfig.default_poll_interval_secs` y luego el `EVALUATOR_POLLING_INTERVAL_SECS` del servidor. Los valores se limitan entre 1 segundo y 1 hora. El límite de tiempo de consulta por reloj del servidor es de una hora por defecto. ## Campos de solicitud y respuesta | Campo | Tipo | Notas | | --------------------------------------- | -------------------------- | ---------------------------------------------------------------------- | | `EvalRequest.schema_version` | `str` | Actualmente `"1"`. | | `session_id`, `agent_id`, `environment` | `str` | Identidad de sesión y entorno. | | `started_at` | `datetime` | Marca de tiempo del primer evento. | | `ended_at` | `datetime \| None` | Presente cuando la sesión emitió un evento de fin. | | `events` | `list[AgentEvent]` | Flujo de eventos completo y ordenado. | | `AgentEvent.id` | `int` | Identificador de fila del evento en el backend. | | `AgentEvent.ts` | `datetime` | Marca de tiempo del evento. | | `AgentEvent.event_type` | `str` | Familia del evento, como `tool_use`. | | `AgentEvent.payload` | `dict[str, Any]` | Carga útil completa del evento. | | `EvalResponse.scores` | `dict[str, float] \| None` | Dimensiones numéricas representadas en las evaluaciones. | | `EvalResponse.reasoning` | `dict[str, str] \| None` | Explicaciones por puntuación; las claves deben coincidir con `scores`. | | `EvalResponse.summary` | `str \| None` | Narrativa general de la evaluación. | ## Configuración para el operador del servidor La evaluación automática afecta a todo el despliegue y permanece deshabilitada cuando `EVALUATOR_ENDPOINT` no está definido. | Variable | Valor por defecto | Propósito | | ---------------------------------- | ----------------- | --------------------------------------------------- | | `EVALUATOR_ENDPOINT` | no definido | URL base del servicio evaluador. | | `EVALUATOR_TOKEN` | no definido | Token bearer compartido con `Evaluator(token=...)`. | | `EVALUATOR_WORKERS` | `2` | Trabajadores del despachador concurrentes. | | `EVALUATOR_CLAIM_BATCH` | `4` | Sesiones reclamadas por pasada del despachador. | | `EVALUATOR_POLLING_INTERVAL_SECS` | `10` | Cadencia de consulta asíncrona de reserva. | | `EVALUATOR_REQUEST_TIMEOUT_MS` | `30000` | Tiempo de espera del evaluador por solicitud. | | `EVALUATOR_MAX_ATTEMPTS` | `5` | Intentos de entrega antes de fallo terminal. | | `EVALUATOR_CONFIG_REFRESH_SECS` | `300` | Cadencia de actualización para `/config`. | | `EVALUATOR_MAX_POLL_DURATION_SECS` | `3600` | Tiempo máximo de consulta asíncrona por reloj. | El servidor también puede restringir qué organizaciones usan el evaluador global del despliegue. Trata los cambios en el endpoint, el token, los reintentos y las restricciones por organización como configuración del operador, y reinicia o rota el servidor tras modificarlos. ## Seguridad y operaciones * Coloca el evaluador detrás de HTTPS cuando el tráfico cruce un límite de red de confianza. * Configura un token bearer no vacío y mantenlo idéntico en ambos servicios. * No registres en logs el token ni los prompts sensibles completos de las cargas útiles de las solicitudes. * Haz que los manejadores síncronos sean idempotentes; los reintentos pueden repetir una solicitud. * Persiste el estado de los trabajos asíncronos fuera de la memoria del proceso en producción. * Devuelve claves de puntuación estables. Renombrar una clave crea una nueva serie en el gráfico en lugar de modificar la anterior. El SDK emite logs de ciclo de vida estructurados como `eval received`, `eval responded`, `job lookup`, `config returned`, `auth rejected` y excepciones de manejadores. No configura manejadores de logging; utiliza la configuración de logging de la aplicación anfitriona.