Cómo diseñar checkpoints para que un agente largo pueda detenerse y reanudar sin repetir trabajo

Empieza por la unidad de recuperación. Antes de guardar estados, define qué fase tendría sentido repetir de manera independiente. Una investigación puede separarse en recopilación, selección, redacción, validación y publicación. Un flujo comercial puede dividirse en lectura, preparación, aprobación y envío. El checkpoint debe ubicarse después de una fase cuyo resultado pueda verificarse y reutilizarse. Si se guarda estado a mitad de una acción que no puede reconstruirse, la reanudación seguirá siendo ambigua. La meta es que cada punto seguro tenga una entrada, una salida y una condición de completitud comprensible.

Guarda artefactos y decisiones. No basta con recordar que «fase dos terminó». Conserva el archivo generado, su hash o versión, las fuentes relevantes y las decisiones que determinaron el resultado. Si una persona aprobó una variante, registra qué variante y bajo qué condiciones. El checkpoint debería permitir que otra ejecución entienda qué puede reutilizar sin volver a interpretar toda la conversación. Evita almacenar más datos de los necesarios; la recuperación necesita evidencia suficiente, no una copia indiscriminada de cada detalle temporal.

Separa estado interno de estado externo. Un plan puede decir que el documento estaba listo, pero el archivo remoto pudo cambiar después. Antes de reanudar una fase que depende de recursos externos, vuelve a leerlos y compara identificadores, versiones o hashes. Define qué diferencias invalidan el checkpoint y cuáles son irrelevantes. Por ejemplo, un cambio de metadatos puede permitir continuar, mientras una modificación del contenido obliga a recalcular. Esta revalidación evita ejecutar pasos sobre un mundo que ya no coincide con el estado que el agente guardó.

Diseña claves de idempotencia. Toda acción con efectos externos debería tener una identidad estable, como runKey más nombre de fase. Antes de enviar, crear o publicar, busca si esa acción ya ocurrió y verifica el resultado. Si existe y coincide, reutiliza; si existe y difiere, detén el flujo y registra conflicto. Esta regla evita duplicados cuando una ejecución se reinicia después de perder la confirmación. El objetivo no es impedir reintentos, sino hacer que repetir el mismo intento produzca el mismo estado o una señal clara de inconsistencia.

Define qué puede reintentarse. No todos los fallos son iguales. Un timeout puede justificar un nuevo intento; una validación de contenido fallida necesita corregir la entrada; un conflicto de versión puede requerir intervención humana. Clasifica errores por fase y especifica la respuesta. Mantén un máximo de reintentos para evitar bucles y registra el último error exacto. Cuando se agote el límite, conserva el checkpoint y termina. Un buen sistema falla dejando un lugar claro desde el que continuar, no destruyendo todo el trabajo acumulado.

Haz visible el progreso. Presenta estados que una persona pueda entender: preparado, ejecutando, esperando aprobación, verificado, bloqueado. Cada estado debería enlazar con evidencia relevante sin obligar al usuario a leer logs completos. Si una ejecución se reanuda, muestra desde qué checkpoint y qué dependencias se volvieron a comprobar. Esta transparencia reduce la tentación de iniciar otra corrida «por si acaso», que es una fuente común de duplicados. La interfaz puede ser simple siempre que describa fielmente la realidad técnica.

Prueba la recuperación, no solo el camino feliz. Interrumpe deliberadamente el flujo después de cada checkpoint, cambia un archivo externo, simula un timeout y repite una acción con el mismo identificador. Comprueba que la ejecución reutiliza lo válido, detecta lo que cambió y no duplica efectos. Mide cuánto trabajo se repite después de un fallo. La meta es que una interrupción tarde en recuperar solo la fase necesaria. Cuando este comportamiento es reproducible, la duración deja de ser un riesgo y se convierte en una capacidad del producto.