Ejecuciones

Descripción general

Ejecuciones es el núcleo operativo de Verifi. Es el módulo donde se lanzan corridas de prueba sobre un agente, se monitorea su avance en tiempo real y se obtienen reportes detallados con métricas, evidencia paso a paso y errores categorizados.

Una ejecución combina tres piezas:

1. Un agente objetivo (el agente que se quiere evaluar).
2. Un Agent Tester (un agente especial que actúa como evaluador).
3. Una selección de casos de uso de la biblioteca.

La ejecución real de las pruebas no ocurre dentro de Verifi: la dispara un webhook al Agent Tester en HeyNow, que procesa los casos contra el agente objetivo y reporta los resultados de vuelta vía callbacks REST. Verifi funciona como orquestador, persiste el estado y presenta el reporte final. Esta arquitectura distribuida es relevante de conocer porque explica por qué algunas acciones tienen estados intermedios visibles (pending, en progreso, evaluando).

Para quién es este módulo

• QA que lanza corridas regulares y revisa reportes para detectar regresiones.
• Desarrolladores y prompt engineers que validan un cambio (prompt, modelo, base de conocimiento) ejecutando la misma batería antes y después.
• Responsables funcionales que evalúan la calidad del agente en términos de comportamiento esperado.
• Administradores técnicos que configuran el Agent Tester y supervisan la salud operativa de las pruebas.

Acceso al módulo

Desde el menú lateral, opción Ejecuciones (ruta /dashboard/ejecuciones).

Requiere sesión activa. La lista muestra únicamente las ejecuciones del cliente asociado al usuario; el aislamiento es automático y no hay selector de tenant.

Cómo funciona el módulo

Los tres actores

El flujo de una corrida

1. El usuario configura la ejecución desde el wizard (ver más abajo) y confirma.
2. Verifi persiste una nueva ejecución con estado pending, captura un snapshot del agente (modelos, capacidades) y snapshots de cada caso seleccionado con sus pasos. A partir de ese momento, cambios posteriores en el caso o en el agente no afectan esta corrida.
3. Verifi envía un webhook (fire-and-forget) al Agent Tester con el executionId y los datos mínimos para que lo recupere. No espera respuesta del webhook para considerar la corrida lanzada.
4. El Agent Tester consulta la ejecución, cambia su estado a running, ejecuta paso a paso y va reportando evidencia incrementalmente.
5. Cuando termina la ejecución, pasa a evaluating para emitir los veredictos finales.
6. Al cerrar, actualiza el estado a completed, failed o error con las métricas globales.
7. El frontend de Verifi hace polling cada 3 segundos mientras haya ejecuciones en estados intermedios y refresca la tabla automáticamente.

Estados de una ejecución

Una vez que una ejecución llega a un estado final (completed, failed, error, cancelled) sus datos son inmutables: ni la evidencia ni los errores aceptan modificaciones posteriores.

Tareas más comunes

Lanzar una nueva ejecución

El wizard se compone de cuatro pasos:

1. Agente objetivo. Lista de agentes principales del cliente. Incluye buscador por nombre.
2. Casos de uso. Multi-selección con contador de pasos por caso. Hay opciones Seleccionar todos y Deseleccionar todos.
3. Configuración. Muestra la configuración actual del agente objetivo (modelo, capacidades) y del Agent Tester (evaluador). Desde aquí se puede abrir HeyNow en una pestaña nueva para ajustar la configuración antes de lanzar. Si no existe un Agent Tester, aparece un banner bloqueante con el link directo para crearlo.
4. Resumen. Presenta el total de casos seleccionados, la suma de pasos que se van a correr y los agentes involucrados. Desde aquí se confirma con Iniciar ejecución.

Al confirmar, la ejecución aparece inmediatamente en la tabla con estado Pendiente y empieza a actualizarse por polling cada 3 segundos.

Requisitos que bloquean el lanzamiento:

• Sin agente objetivo seleccionado.
• Sin al menos un caso de uso seleccionado.
• Sin Agent Tester detectado en HeyNow. El wizard muestra el aviso Evaluador no configurado — Crea el agente "Agent Tester" en HeyNow para ejecutar pruebas.

Ver el reporte de una ejecución

Desde el menú de tres puntos de la fila:

• Ver reporte (ejecuciones en estado final): abre la vista de detalle completa con métricas globales, desglose por caso, evidencia paso a paso y lista de errores.
• Ver ejecución (ejecuciones en curso): abre la misma vista pero con métricas parciales; se va completando a medida que el Agent Tester reporta avances.

La vista de detalle incluye:

• Encabezado con nombre del agente, estado y enlace para copiar el identificador de la ejecución.
• Tarjetas de métricas globales (detalladas en la sección siguiente).
• Configuración usada: modelo y proveedor del agente objetivo y del evaluador, más los parámetros operativos de la corrida.
• Casos de uso: cada caso es expandible; al abrirse muestra los pasos con su estado.
• Evidencia: por cada paso, input enviado, respuesta del agente, comportamiento esperado, veredicto del evaluador, feedback, tiempo de respuesta, desvíos detectados y, si aplica, código de error.
• Errores de la ejecución: lista de errores reportados por el Agent Tester, con código, mensaje, categoría y severidad, asociados (cuando corresponde) al caso y paso en los que se originaron.

Reejecutar

Permite volver a correr la misma configuración. Útil para comparar el mismo agente después de un cambio, o para confirmar que un fallo se reproduce.

1. Abrir el menú de tres puntos y seleccionar Reejecutar.
2. Aparece un diálogo de confirmación que resume agente, cantidad de casos, modelo del evaluador, modo de ejecución y (si la original estaba completada) las métricas originales.
3. Confirmar con el botón Reejecutar.

Lo que se copia exactamente:

• Identificador del agente objetivo.
• Identificador del Agent Tester que actuó como evaluador.
• Lista de casos de uso seleccionados originalmente.
• Parámetros operativos (timeout, reintentos, modo paralelo, modo estricto).
• Snapshots de configuración (modelo y proveedor del agente y del evaluador).

Lo que no se copia y se genera nuevo:

• Evidencia, errores y métricas (la corrida parte vacía).
• Timestamps (createdAt, startedAt, completedAt).
• Snapshots de los casos (se vuelven a capturar, por lo que reflejarán cambios recientes en la biblioteca de casos).

Cancelar una ejecución

Disponible mientras la corrida esté en Pendiente, En progreso o Evaluando.

1. Abrir el menú de tres puntos y seleccionar Cancelar.
2. La ejecución pasa de inmediato a estado Cancelada con el mensaje interno Cancelled by user y un timestamp de cierre.

Los datos parciales (evidencia y errores ya registrados hasta ese punto) se conservan y son visibles en el reporte. El consumo de tokens ya realizado no se revierte.

Consultar estadísticas globales

La cabecera del módulo muestra cuatro tarjetas con el estado general de las ejecuciones del cliente:

• Total Ejecuciones: cantidad total registrada.
• En Ejecución: suma de ejecuciones en Pendiente, En progreso o Evaluando.
• Completadas: cantidad en estado final exitoso.
• Fallidas: cantidad en estado final con fallos funcionales.

Las tarjetas se recalculan en cada polling; mientras haya corridas activas, se actualizan automáticamente.

Campos y configuraciones importantes

Configuración operativa de la corrida

Estos parámetros se persisten junto con la ejecución y se pasan al Agent Tester para que los respete:

Actualmente estos parámetros se fijan en el backend al crear la ejecución desde el wizard; si se necesitan valores distintos a los por defecto, la ruta más directa es reejecutar una corrida previa cuyos parámetros ya estén ajustados, o usar la API directamente.

Métricas del reporte

Las métricas se emiten por el Agent Tester al finalizar la corrida, pero si faltan parcialmente, Verifi las recalcula en el cliente a partir de la evidencia. El valor mostrado prioriza lo calculado cuando hay datos suficientes.

Si la corrida no llegó a completarse o quedó cancelada, las métricas pueden mostrarse como -.

Evidencia por paso

Cada paso ejecutado genera un registro de evidencia con:

• Input enviado al agente.
• Output recibido del agente.
• Comportamiento esperado del paso (copiado del snapshot del caso).
• Resultado de evaluación y feedback emitidos por el Agent Tester.
• Estado del paso: passed, failed o error.
• Puntaje numérico (0–100).
• Tiempo de respuesta en milisegundos.
• Containment ok: indicador booleano de si la respuesta se mantuvo dentro del comportamiento esperado.
• Desvíos: lista de motivos puntuales por los cuales la respuesta se apartó del esperado.
• Código de error (si aplica).
• Payload de la request usado para llamar al agente (útil para reproducibilidad).

La evidencia es única por combinación (ejecución, caso, número de paso) y es idempotente: si el evaluador reenvía un paso, se actualiza en lugar de duplicarse.

Errores de ejecución

Cada error registrado tiene:

• Código: identificador textual (por ejemplo AGENT_TIMEOUT, MODEL_ERROR, MALFORMED_RESPONSE; el campo es libre y depende de lo que reporte el evaluador).
• Mensaje: descripción legible.
• Categoría: una de configuration, authentication, execution, evaluation, unknown.
• Severidad: error, warning o info.
• Caso y paso asociados (opcionales).
• Detalles: payload JSON adicional con contexto técnico.

Las categorías ayudan a orientar la corrección:

• configuration: problema de setup del agente o de la corrida.
• authentication: fallo al autenticar con servicios externos.
• execution: el agente objetivo no pudo responder correctamente.
• evaluation: el evaluador no pudo emitir un veredicto.
• unknown: sin clasificar.

Resultados esperados

Al completar una ejecución normal:

• La fila pasa a Completada (o Fallida si hubo fallos funcionales) y el reporte queda disponible.
• Las estadísticas globales de la cabecera se actualizan automáticamente.
• La evidencia y los errores quedan congelados: ni el evaluador ni el usuario pueden modificarlos retroactivamente.
• Se registra un evento de auditoría con el usuario, la ejecución y el resultado.

Al reejecutar:

• Se genera una corrida independiente con nuevo identificador.
• La corrida original permanece intacta, permitiendo comparar lado a lado.
• Los snapshots de casos se vuelven a capturar con la versión vigente, lo que puede explicar diferencias entre ambas corridas aunque el agente sea el mismo.

Al cancelar:

• La ejecución queda en estado Cancelada con los datos parciales visibles.
• No se libera el consumo ya hecho de tokens ni se recupera tiempo del evaluador.

Problemas comunes y soluciones

No puedo avanzar del paso 3 del wizard: aparece el banner Evaluador no configurado

• El Agent Tester no existe o no es visible para el cliente. Crearlo en HeyNow con nombre exacto Agent Tester y marcado como agente principal. El cache interno descarta los resultados negativos, así que al volver a entrar el wizard lo detectará sin necesidad de recargar.

No aparece el agente que quiero probar en el paso 1

• Revisar que sea un agente principal en HeyNow para ese cliente. Agentes de tipo flow o proactivos no aparecen.
• Revisar el buscador por si hay un filtro de texto aplicado.

La ejecución quedó mucho tiempo en Pendiente

• Significa que el Agent Tester no llegó a tomar la ejecución. Puede deberse a que el webhook de disparo falló silenciosamente o que el Agent Tester no está operativo.
• Recomendación: cancelar la corrida y relanzarla. Si persiste, verificar el estado del Agent Tester en HeyNow.

Ejecución terminada en estado Error

• Abrir el reporte y revisar la sección de errores. La categoría orienta la causa:
  • configuration: revisar configuración del agente.
  • authentication: revisar credenciales o permisos del canal.
  • execution: revisar el agente objetivo.
  • evaluation: revisar el Agent Tester.

Métricas bajas pero los pasos parecen correctos a simple vista

• Revisar la evidencia de cada paso: a veces el veredicto del evaluador depende más del comportamiento esperado redactado que de la respuesta efectiva.
• Si el comportamiento esperado es ambiguo o poco específico, el evaluador tiende a marcar desvíos. Refinar el caso en la biblioteca y reejecutar.

Reejecuté una corrida antigua y el resultado cambió mucho

• La reejecución toma snapshots frescos de los casos. Si la biblioteca cambió entre la corrida original y la reejecución, el agente está siendo evaluado contra comportamientos esperados distintos.
• Si se quiere comparar contra exactamente los mismos casos, conviene hacerlo sin editar los casos en el medio.

Cancelé una ejecución pero los tokens se siguieron consumiendo

• La cancelación detiene la orquestación desde Verifi, pero el evaluador puede haber emitido ya requests al agente objetivo que se siguen contabilizando en HeyNow hasta terminar.

El polling no actualiza la tabla

• El polling solo se activa cuando hay al menos una ejecución en estado intermedio. Si todas están en estado final y el usuario lanza una nueva, la actualización debería reanudarse al verse la nueva corrida en estado Pendiente.

Buenas prácticas

• Usar baterías representativas. Incluir siempre una muestra de casos felices y casos límite; evaluar solo sobre escenarios happy path da una visión sesgada.
• Ejecutar antes y después de cada cambio relevante. La forma más útil de detectar regresiones es tener una corrida base y comparar con la reejecución.
• Preferir Reejecutar antes que crear manualmente una corrida nueva cuando se busca comparar la misma configuración. Garantiza que los parámetros operativos se mantengan idénticos.
• Revisar la evidencia, no solo las métricas. Una tasa global alta puede ocultar problemas sistemáticos en un caso específico.
• Cancelar lo antes posible las corridas mal configuradas o que se lanzaron por error para evitar consumo innecesario de tokens.
• Documentar externamente las corridas clave (release, pre-producción) anotando el identificador de la ejecución. El identificador es estable y permite volver al reporte aun con alta rotación de corridas.
• Alinear el comportamiento esperado con lo que el agente realmente puede entender. Redacciones demasiado genéricas o demasiado específicas generan evaluaciones inestables.

Consideraciones importantes

• El Agent Tester es obligatorio. Sin un agente con ese nombre exacto y marcado como principal, no se pueden lanzar ejecuciones. El cache interno de Verifi solo persiste resultados positivos, por lo que crear el agente en HeyNow lo hace visible inmediatamente en el siguiente ingreso al wizard.
• Solo puede haber un Agent Tester por cliente. Si se necesitan variantes del evaluador, se debe cambiar la configuración del Agent Tester en HeyNow.
• Los snapshots son inmutables. Una vez creada la ejecución, los datos del agente y de los casos quedan congelados. Modificar la fuente no afecta la corrida.
• Los estados finales son inmutables. Completada, fallida, error o cancelada: después de eso ni el evaluador ni el usuario pueden modificar evidencia, errores o métricas.
• El disparo del webhook es fire-and-forget. Si el webhook falla silenciosamente, la ejecución quedará en Pendiente sin progresar. La mitigación actual es cancelar y relanzar.
• El polling es cliente-side y cada 3 segundos. Si se tienen muchas pestañas abiertas del módulo con ejecuciones activas, habrá una consulta por pestaña cada 3 segundos.
• El reporte no es descargable en la UI actual. Se puede navegar online o capturar por otros medios. El identificador de la ejecución queda disponible para copiarlo.
• No hay versionado de ejecuciones más allá del orden cronológico. Cada corrida es independiente y se identifica por su ID UUID.
• Multi-tenant estricto. Una ejecución solo es accesible por usuarios del mismo cliente. Los endpoints validan tanto el JWT como, en el caso de callbacks externos, el client id enviado por el evaluador.

Resumen rápido

Ejecuciones orquesta las corridas de testing: combina un agente objetivo, el Agent Tester (evaluador) y una selección de casos de la biblioteca. La corrida es disparada a HeyNow vía webhook y el evaluador reporta resultados por callbacks; Verifi persiste el estado, presenta métricas agregadas, la evidencia paso a paso y los errores categorizados. Cada corrida es un snapshot inmutable: editar un caso o el agente no afecta corridas anteriores. La función Reejecutar permite comparar escenarios contra la misma configuración para validar cambios.