Puntos de control (checkpointing) en una tarea larga de un agente: archivos de progreso, pasos idempotentes y reanudación

Objetivo

Hacer que cualquier interrupción de una tarea larga cueste como máximo un paso de trabajo y cero efectos secundarios duplicados, ya sea la interrupción un fallo del proceso, una ventana de contexto que hubo que reiniciar, o un traspaso a otro agente.

Requisitos previos

Una tarea que pueda escribirse como una secuencia de pasos con criterios de finalización observables, un lugar donde escribir archivos que sobreviva a la interrupción, y sistemas externos cuyas operaciones de escritura acepten una clave de idempotencia o puedan consultarse para saber qué ha ocurrido ya.

Pasos

1. Antes del primer efecto secundario, escribir un archivo de plan: pasos numerados, la comprobación de finalización de cada uno («el archivo existe y se puede analizar», «el registro 4711 tiene el estado enviado», «la batería de pruebas está en verde»), y las entradas de las que dependen los pasos.
2. Mantener junto a él un archivo de progreso y actualizarlo después de cada paso completado, nunca antes: número de paso, marca de tiempo, la evidencia de finalización (un hash, un identificador, el código de salida de un comando) y cualquier cosa que el siguiente paso necesite y que se haya aprendido en este.
3. Dar a toda escritura externa una clave de idempotencia derivada de la tarea y del paso, de modo que una petición repetida tras un fallo la reconozca quien la recibe en lugar de ejecutarla dos veces; donde quien la recibe no tenga ese mecanismo, consultar primero si el efecto ya se produjo y omitir la escritura si está presente.
4. Hacer que cada paso pueda reiniciarse de forma aislada: lee sus entradas de archivos o identificadores, nunca de la conversación, y tolera su propia salida parcial de un intento anterior (sobrescribir o limpiar, nunca añadir a ciegas).
5. Al reanudar, leer el plan y el archivo de progreso, verificar la evidencia del último paso registrado frente al estado real (el registro realmente está enviado, el archivo realmente se puede analizar), y continuar desde el primer paso no verificado. No confiar nunca solo en el archivo de progreso; verificar, y después continuar.
6. Registrar en el archivo de progreso las decisiones tomadas por el camino junto con su motivo, para que una ejecución reanudada no las reabra, y registrar explícitamente las incógnitas abiertas para que no se confundan con asuntos resueltos.
7. Al final, redactar el resumen final a partir del archivo de progreso, que para entonces contiene todos los pasos con su evidencia; después archivar ambos archivos con el identificador de la ejecución.

Resultado esperado

Una ejecución interrumpida en cualquier punto puede reanudarla el mismo agente u otro a partir solo de los archivos, repite como máximo el paso que estaba en curso, y no produce ningún efecto externo duplicado.

Límites y base de verificación

Un protocolo propuesto. Asume pasos con una finalización comprobable; el trabajo cuyo único artefacto es la comprensión (leer, explorar) necesita una nota escrita como evidencia, lo cual es una comprobación más débil. La idempotencia depende de que el sistema receptor respete la clave.

Efectos no consultables: registrar primero la intención

Para un paso cuyo efecto no se pueda consultar después (un mensaje enviado, un webhook entregado a un tercero, un pago capturado sin un endpoint de consulta), invertir el orden del paso 2: escribir un registro de intención con la clave de idempotencia reservada antes del efecto, realizar el efecto, y después escribir el registro de finalización. Una ejecución reanudada que encuentre una intención sin finalización sabe que el efecto puede haber ocurrido o no, y debe preguntar a quien lo recibe con la misma clave, o entregar el paso a una persona, en lugar de repetirlo. Escribir ambos registros de forma atómica (archivo temporal y después renombrado) para que un fallo durante la escritura no pueda dejar un archivo de progreso escrito a medias.