Cómo verificar que un agente de IA realmente terminó una tarea

Pediste a Claude Code, Codex u otro agente que organizara archivos, actualizara una hoja de cálculo o creara registros de negocio. El agente respondió “terminado” y no apareció un error evidente. Eso demuestra que la ejecución acabó; no demuestra que el resultado de negocio exista.

Una aceptación fiable empieza por definir el estado final esperado, releer el resultado desde los sistemas de destino y comprobar tanto efectos faltantes como efectos inesperados. Solo entonces conviene cerrar la tarea. Si el resultado es desconocido, primero consulta los registros en lugar de volver a ejecutar todo el flujo.

Por qué una herramienta exitosa no prueba que la tarea terminó

Un agente puede mostrar señales tranquilizadoras: una herramienta devuelve success, el proceso sale con código 0, se genera un informe o el último mensaje afirma que todos los pasos se completaron. Aun así, siguen abiertas preguntas importantes:

• ¿Se escribió el archivo correcto, en la ubicación correcta y con el contenido correcto?
• ¿La hoja o la base de datos guardó todos los registros previstos?
• ¿Se crearon filas, pedidos, correos o archivos duplicados?
• ¿Un trabajo asíncrono sigue en cola o una escritura fue revertida después?
• ¿El agente consultó un registro pero olvidó actualizarlo?

El ThinkingBox-Bench v1.0 público de Microsoft es un benchmark sintético, no una tasa de incidentes de producción. Incluye 507 tareas ejecutables de cinco dominios y solo acepta un intento cuando pasan las comprobaciones del estado final, los efectos secundarios y propiedades concretas del diálogo. Su documentación etiquetada no concede crédito parcial. Los estados “parcial” y “no verificado” de esta guía son etiquetas operativas, no puntuaciones del benchmark.

Define un contrato de aceptación antes de ejecutar

Verificar resulta mucho más fácil cuando las condiciones finales están escritas de antemano:

Elemento	Qué definir	Ejemplo
Estado obligatorio	Objetos, campos, cantidades y relaciones que deben existir	120 archivos renombrados y 120 ID únicos en la hoja
Estado prohibido	Cambios y efectos que no deben ocurrir	No borrar originales, no enviar un segundo correo, no tocar otras pestañas
Fuente de verdad	Sistema cuyo estado almacenado decide la aceptación	Carpeta de destino, celdas, CRM o estado del ticket
Identidad del reintento	Clave que identifica esta operación concreta	Un operation_id o número de pedido acotado a la tarea u operación actual; el ID de cliente, nombre de archivo, ID de objeto y hash del manifiesto identifican objetos de consulta, no esta operación por sí solos

Describe el resultado de negocio, no la acción del agente. “La herramienta de hoja fue llamada” no es un estado final. “La pestaña tiene 120 filas, los ID son únicos y los totales concuerdan con el manifiesto” sí lo es.

También define el orden de las acciones irreversibles. Completa y verifica primero los cambios recuperables; después envía el correo, registra el pedido o dispara el pago. Así un fallo temprano no obliga a repetir a ciegas una acción sensible a duplicados.

Conserva la evidencia mínima de ejecución

Guarda la información necesaria para relacionar una ejecución con sus escrituras:

• tarea original, alcance permitido y estado final esperado;
• horas de inicio y fin, directorio de trabajo y manifiesto de destinos;
• ID de sesión y cualquier job ID devuelto;
• operation_id u otra clave de negocio única;
• cantidades, versiones, campos clave o hashes anteriores;
• errores, timeouts, rechazos de permisos y pasos omitidos.

No necesitas el razonamiento privado del agente. Necesitas entradas reproducibles, identificadores, alcance y estado del destino. No guardes API keys, tokens ni secretos del cliente en el registro de aceptación.

Espera al estado final del sistema, no al último mensaje

Cargas, importaciones masivas, informes y escrituras en terceros pueden continuar después de la respuesta. Guarda el job ID y consulta el sistema autorizado a intervalos razonables hasta obtener éxito, fallo, cancelación o timeout.

Registra progreso y hora de última actualización. Si el sistema es eventualmente consistente, define una ventana de asentamiento y vuelve a leer. No declares fallo porque una escritura reciente aún no aparece, pero tampoco esperes indefinidamente. Si la ventana termina sin evidencia decisiva, el estado es no verificado, no “no ejecutado”.

Relee el resultado en seis capas

1. Confirma que el objeto existe y pertenece a esta ejecución

Comprueba ruta, nombre, ID, fecha de modificación y versión. Un archivo antiguo con el mismo nombre no sirve. Un registro nuevo ligado al cliente equivocado tampoco.

2. Comprueba contenido e invariantes de negocio

Verifica cantidades, unicidad, totales, campos obligatorios, relaciones y formato. En una hoja, compara ID, filas y sumas. En archivos, manifiesto, tamaños, hashes o muestras. En registros, estado, importe, propietario y rango temporal.

3. Usa el sistema de registro autorizado

El resumen del agente, la terminal y la caché son evidencia auxiliar. La aceptación debe venir del sistema que almacena el resultado: servicio de archivos, celdas reales, CRM, tickets, base de datos o libro de pagos.

4. Verifica todos los efectos obligatorios

Una tarea puede requerir archivo, índice, registro asociado y notificación. Comprueba cada elemento con la misma identidad de negocio. Si falta uno, el resultado es parcial.

5. Busca efectos que no deberían existir

Revisa filas y registros duplicados, correos extra, archivos borrados, cambios fuera de alcance y escrituras en el objeto equivocado. Un efecto inesperado debe detener el reintento automático.

6. Concilia entre sistemas

Si la tarea abarca archivos, hojas y aplicaciones, limita primero cada consulta al operation_id o al alcance de la tarea actual; después verifica los ID de cliente y objeto, el estado o la versión exigidos y el manifiesto. Coincidir con un identificador de objeto no demuestra que esta operación se haya aplicado. Compara conjuntos de ID y enumera faltantes y extras.

Clasifica el resultado en cuatro estados

Estado	Cuándo usarlo	Siguiente acción
Completo	Se verificaron todas las condiciones y no hay efectos extra inaceptables	Guardar evidencia y cerrar
Parcial	Parte del resultado está confirmada, pero faltan elementos concretos	Reparar solo lo que falta
No verificado	El sistema no está disponible, aún se asienta o no permite saber si hubo escritura	Consultar o esperar; no repetir a ciegas
Efecto inesperado	Hay duplicado, borrado, cambio fuera de alcance o escritura incorrecta	Detener automatización y revisar

“No verificado” no significa “fallido”. Significa que todavía no sabes qué ocurrió.

Decide el reintento en este orden

1. Consulta primero esta operación. Acota la búsqueda en la fuente de verdad con el operation_id o número de pedido y combínala con nombre de archivo, ID de cliente u objeto y el estado o versión exigidos. Encontrar solo el objeto no demuestra esta escritura.
2. Identifica el límite completado. Lista objetos correctos y faltantes.
3. Repara de forma idempotente. Si la misma clave no puede crear un segundo resultado, envía solo lo faltante. Si no conoces la idempotencia, no repitas automáticamente una acción irreversible.
4. Separa registros, notificaciones y transacciones. Si el registro existe y falló el correo, reenvía solo el correo. Si el correo salió y el registro es incierto, consulta primero.
5. Detente ante efectos inesperados. Corrige o revierte los objetos erróneos antes de reanudar.

Regla corta: reintenta solo cuando confirmes la ausencia; repara únicamente lo que falta tras una escritura parcial; consulta antes de actuar si el resultado es desconocido; detente si el estado es incorrecto.

Ejemplo: archivos, hoja y CRM

Es un escenario hipotético, no un incidente real ni un log reproducido.

El agente debe renombrar 120 archivos, escribir 120 filas, crear 12 registros resumen en CRM y enviar un correo. La relectura muestra archivos y filas correctos, solo 9 registros CRM y el correo ya enviado.

El estado correcto es parcial. La recuperación segura consiste en:

• consultar CRM con el operation_id y las 12 claves esperadas;
• identificar los 9 existentes y crear solo los 3 faltantes con claves de deduplicación;
• conciliar los 12 ID finales con los resúmenes de archivos y hoja;
• no renombrar de nuevo, no reescribir 120 filas y no reenviar el correo.

Si CRM no puede consultarse, marca no verificado. Una repetición completa podría crear duplicados y otra notificación.

Copia este registro de aceptación

Campo	Qué registrar
Tarea y alcance	Acción prevista, destinos permitidos y cambios prohibidos
Estado final esperado	Objetos, campos, cantidades, relaciones y estados
Identidad de ejecución	ID de sesión, job ID, operation_id y claves de negocio
Evidencia autorizada	Objetos de destino, hora de consulta, ID y enlaces
Efectos faltantes	Objetos o acciones obligatorios ausentes
Efectos extra	Duplicados, borrados, cambios fuera de alcance o notificaciones extra
Estado de aceptación	Completo, parcial, no verificado o efecto inesperado
Siguiente acción	Cerrar, esperar, reparar, reintentar, revertir o escalar

Adjunta listas de ID, diferencias y horas de consulta; “revisado” sin datos no es suficiente.

BetterToken ofrece la conexión del modelo, no la aceptación del resultado

Para conectar Claude Code mediante BetterToken, consulta la guía actual de configuración y comprobación. Una respuesta normal sin errores de conexión o modelo confirma la configuración, pero no demuestra que el archivo, la hoja o el registro externo llegó al estado previsto.

Usa identificadores de sesión para localizar la ejecución, pero acepta el trabajo según los sistemas de destino. Disponibilidad del modelo, respuesta exitosa o consumo de tokens no prueban la finalización de negocio.

Cierra solo después de tres preguntas

1. ¿Veo el estado final esperado en el sistema autorizado y no solo en la descripción del agente?
2. ¿Comprobé faltantes, duplicados y otros efectos inesperados?
3. Si el resultado es desconocido, ¿consultaré por clave única antes de reparar o reintentar?

Cierra la tarea únicamente cuando las tres respuestas sean claras. Antes del próximo trabajo de alto impacto, copia el registro anterior y completa el estado final, los cambios prohibidos y la identidad de reintento. Es más barato que deshacer una operación duplicada.