El agente se detuvo a mitad de una tarea. Tal vez una persona debe aprobar el siguiente paso. Tal vez el proceso se reinició mientras una herramienta actualizaba un sistema externo. Cuando la ejecución vuelve, empezar desde el prompt original parece sencillo. En realidad, mezcla trabajo terminado, trabajo pendiente y efectos que nadie ha confirmado.

Para pausar y reanudar un agente de IA con seguridad, persiste una frontera de ejecución que el runtime pueda explicar. Guarda la intención, el siguiente paso, las solicitudes pendientes, la aprobación y los recibos de las herramientas. Al reanudar, usa la misma identidad de ejecución, valida la versión del estado e investiga cualquier efecto externo que pudiera haber ocurrido antes de la interrupción.

La guía sobre ejecución durable para agentes de IA cubre la elección entre una cola y un workflow. Este artículo se concentra en una frontera más pequeña: qué significa pausar una ejecución y qué evidencia hace falta antes de continuar.

El código es ilustrativo. No se ejecutó contra un SDK de agentes en este repositorio. Su propósito es hacer explícito el contrato y orientar pruebas con el adaptador que elijas.

Diagrama de un agente de IA que se pausa, guarda un checkpoint y se reanuda después de verificar un efecto externo.

Respuesta corta

  • Pausa en una transición que el runtime pueda registrar, no en medio de una acción sin recibo.
  • Separa la intención del agente, el progreso del runtime y la consecuencia de la herramienta.
  • Reanuda una sola ejecución con propiedad exclusiva, estado versionado y una aprobación todavía válida.
  • Si un efecto externo es incierto, observa el sistema antes de repetir la acción.

¿Pausar es distinto de cancelar o reintentar?

Pausar conserva la posibilidad de continuar la misma ejecución. Cancelar termina la ejecución y puede requerir una acción compensatoria. Reintentar crea otro intento, que puede repetir una decisión o una llamada de herramienta. El OpenAI Agents SDK, "Run State" describe el estado serializable como la frontera para interrumpir y reanudar flujos con participación humana.

Estos estados deben existir en el modelo del runtime. paused puede significar que la ejecución espera a una persona o a una ventana operativa. cancelled indica que no debe continuar. failed indica que terminó con un error. running solo debe volver después de recuperar el checkpoint y adquirir la propiedad de la ejecución.

No conviertas toda interrupción en un retry. Si una herramienta creó un pedido, envió un mensaje o cambió un registro, el proceso local pudo morir antes de recibir la respuesta. El nombre es distinto, pero el problema es el mismo que en las tool calls duplicadas durante un failover de LLM: el executor debe saber si el efecto ya existe.

¿Qué debe contener el checkpoint de un agente?

Un checkpoint útil guarda el estado necesario para decidir el siguiente paso, no solo el historial que vio el modelo. Microsoft Agent Framework, "Checkpoints" describe checkpoints que incluyen el estado de los executors, mensajes pendientes, solicitudes y respuestas pendientes, y estado compartido. Por eso, un checkpoint es una frontera del workflow, no un archivo de conversación.

Una estructura mínima puede contener estos campos:

Campo Propósito
runId Evita que dos workers reanuden la misma ejecución sin coordinación.
stateVersion Permite rechazar o migrar un checkpoint antiguo.
status Separa ejecución, pausa, aprobación, cancelación y fallo.
nextStep Nombra la primera transición que no está confirmada.
pendingApproval Guarda la solicitud y la representación de lo aprobado.
toolReceipts Registra resultados observados e IDs externos creados.
updatedAt Ayuda a detectar propiedad abandonada y estado obsoleto.

Puedes conservar el transcript para contexto y auditoría, pero no debe ser la única fuente de recuperación. Un resumen puede ayudar al modelo a decidir. Un recibo sin transformar ayuda al runtime a demostrar que una llamada fue aceptada, rechazada, completada o quedó desconocida.

El campo más importante no es lastMessage. Es nextStep junto con lo que el runtime sabe sobre el efecto anterior. Un mensaje pudo generarse sin persistirse. Una llamada pudo aceptarse sin que llegara su respuesta. El checkpoint debe conservar esa diferencia para que la reanudación no adivine.

¿Dónde está una frontera de pausa segura?

Crea la frontera después de una transición confirmada y antes de admitir la siguiente acción. El Google Developers Blog, "Build long-running AI agents that pause, resume, and never lose context with ADK" muestra este patrón con sesiones persistentes y checkpoints asociados al estado del agente. El almacenamiento debe sobrevivir al proceso que ejecuta la tarea.

En la práctica, hay cuatro momentos distintos:

  1. El agente propuso una herramienta, pero todavía no se envió. Pausa y guarda la propuesta como pendiente.
  2. La herramienta se envió y un recibo confirma el resultado. Guarda el recibo y avanza nextStep.
  3. La herramienta se envió, pero el proceso murió antes del recibo. Marca el efecto como unknown y observa el sistema externo antes de decidir.
  4. Una persona aprobó una acción, pero el contexto cambió. Revalida la aprobación o vuelve a la revisión manual.

Un checkpoint dentro de una función que combina una llamada al modelo y un efecto externo es una frontera débil. Si el proceso muere entre ambas partes, el runtime no puede decir cuál ocurrió. Separa preparación, commit y observación cuando una operación cree un efecto difícil de deshacer.

¿Cómo debe modelar el runtime la pausa y la reanudación?

El runtime debe decidir si puede avanzar. El modelo debe proponer el siguiente paso. El código siguiente representa esa separación con tipos sencillos. Estos nombres no son una API de proveedor y no sustituyen el contrato de tu executor.

type RunStatus =
  | "running"
  | "paused"
  | "waiting_for_approval"
  | "failed"
  | "cancelled"
  | "completed";

type ToolReceipt = {
  operationId: string;
  status: "committed" | "rejected" | "unknown";
  externalId?: string;
};

type AgentCheckpoint = {
  runId: string;
  stateVersion: number;
  status: RunStatus;
  nextStep: string;
  pendingApproval?: { inputHash: string; approvedBy?: string };
  toolReceipts: ToolReceipt[];
};

function canResume(checkpoint: AgentCheckpoint): boolean {
  return checkpoint.status === "paused" ||
    checkpoint.status === "waiting_for_approval";
}

Un adaptador de producción todavía debe hacer la parte difícil: guardar el checkpoint de forma atómica, adquirir un lease u otra forma de propiedad exclusiva y consultar IDs externos antes de ejecutar una operación unknown. Los tipos solo hacen visibles las decisiones. No crean idempotencia por sí solos.

¿Cómo reanudar después de una aprobación humana?

Reanuda la ejecución original cuando el checkpoint contiene la aprobación, la solicitud aprobada y la identidad de sesión que necesita. El OpenAI Agents SDK, "Sessions" recomienda conservar la misma sesión al reanudar un RunState. También describe protecciones para evitar que una salida ambigua se persista como definitiva.

La aprobación debe estar vinculada a lo que la persona revisó. Guarda un hash o una representación canónica de la entrada aprobada, además del revisor y el identificador de política cuando tu sistema los necesite. Al reanudar, compara la entrada actual con la aprobada. Si cambió el plan, destinatario, importe o permiso, pide aprobación de nuevo.

Esto separa dos preguntas que suelen mezclarse: "¿puede continuar la ejecución?" y "¿el efecto sigue autorizado?". La primera pertenece al runtime. La segunda depende del estado actual, la política y la herramienta. La guía sobre cuándo un agente debe pedir aprobación humana cubre la decisión de pedir revisión. Aquí, el problema es evitar que una aprobación vieja actúe como un pase permanente.

¿Qué ocurre cuando un efecto externo es desconocido?

No repitas una herramienta cuando el único hecho conocido es que el cliente no recibió la respuesta. AWS, "Implement comprehensive state management and checkpoint-based recovery" conecta la recuperación segura con pasos idempotentes, claves de idempotencia, escrituras condicionales y deduplicación de eventos.

La ruta de reanudación debe consultar la fuente externa con operationId, si existe esa consulta. Hay tres respuestas útiles:

  • committed: se encontró el efecto. Guarda el recibo y avanza sin volver a llamar a la operación.
  • not_found: el sistema confirma que el efecto no existe. Revisa la política y ejecuta con la misma identidad de operación si es seguro.
  • unknown: no hay evidencia suficiente. Detén la ejecución, márcala para revisión o usa una acción de reconciliación del dominio.

No uses el transcript como recibo. Demuestra que el modelo pidió una acción, pero no que el servicio externo la aceptó. Tampoco ocultes unknown detrás de un resumen optimista. La guía de observabilidad de agentes de código en CI usa la misma frontera: las decisiones y los efectos deben distinguirse en el registro.

Cuando un agente puede esperar mucho tiempo, RemoteCode es la herramienta que uso para mantener visibles las sesiones y el contexto de los agentes. Eso describe mi uso de la herramienta, no una prueba de rendimiento de este artículo.

¿Dónde guardar el estado del agente?

Guarda el checkpoint en un almacenamiento durable, privado y accesible para el worker que reanudará la ejecución. La memoria local solo funciona mientras el mismo proceso sigue vivo. El artículo de Google sobre agentes de larga duración usa almacenamiento de sesión persistente porque el proceso puede reiniciarse o permanecer inactivo entre pasos.

Microsoft Agent Framework, "Checkpoints" también trata el almacenamiento de checkpoints como una frontera de confianza. Protege las lecturas y escrituras, valida el formato antes de deserializar y no aceptes checkpoints de una fuente no confiable. Un snapshot con objetos o instrucciones inesperadas puede convertirse en un problema de seguridad al reanudar.

Separa responsabilidades según el volumen y el riesgo:

Dato Almacenamiento y regla
Estado actual Base de datos transaccional o store con versión y propiedad.
Recibos de herramientas Registro durable consultable por operationId.
Contexto del modelo Sesión o resumen compacto con retención definida.
Eventos de auditoría Log append-only con secretos ocultos.

No elijas Redis, SQLite, un workflow gestionado o una base relacional solo porque la documentación de un proveedor lo menciona. La decisión depende de la durabilidad, la concurrencia, la retención, la recuperación y el control que necesita el executor.

¿Cómo probar una reanudación sin duplicar trabajo?

Prueba la interrupción en las fronteras donde el estado puede divergir. La documentación de testing del OpenAI Agents SDK describe cómo probar ejecuciones y respuestas de agentes. En este caso, el fixture también debe controlar el almacenamiento y un executor falso.

Un conjunto mínimo debe verificar:

Interrupción Resultado esperado
Antes de enviar la herramienta La reanudación envía una sola operación pendiente.
Después de confirmar la herramienta La reanudación usa el recibo y no envía otra vez.
Después del envío, antes del recibo La reanudación consulta el efecto antes de decidir.
Mientras espera aprobación La reanudación conserva la solicitud y valida su entrada.
Después de cambiar la versión del estado El runtime migra o rechaza el checkpoint explícitamente.
Dos workers intentan reanudar Uno obtiene la propiedad; el otro no ejecuta la tarea.
El usuario cancela durante la pausa La ejecución termina como cancelled y no vuelve a running.

Mata el proceso en cada punto, restaura el estado e inspecciona los efectos en el executor falso. Después repite con una respuesta distinta del modelo. Si la finalización depende de que el modelo elija exactamente la misma herramienta, estás reproduciendo un prompt, no demostrando seguridad de reanudación.

Preguntas frecuentes

¿Pausar un agente guarda todo el historial de la conversación?

No necesariamente. Un checkpoint necesita el estado que el runtime requiere para continuar, mientras que el historial puede tener otra política de retención. El OpenAI Agents SDK, "Run State" separa el snapshot serializable, los elementos generados, el contexto y las interrupciones. Guarda lo que necesita la próxima decisión y conserva el transcript según tu política.

¿Puedo reanudar el agente en otro proceso?

Sí, cuando el estado vive en almacenamiento compartido y el nuevo proceso puede rehidratar el contexto necesario. La identidad de la ejecución necesita propiedad exclusiva durante la reanudación. Si el SDK depende de la misma sesión o identificador de conversación, conserva ese vínculo. Si el estado es ambiguo, detente y repáralo manualmente.

¿El checkpointing garantiza que una tool call ocurra una sola vez?

No. Un checkpoint informa qué se persistió, pero la herramienta debe reconocer la operación y consultar sus propios efectos. La guía de AWS sobre recuperación basada en checkpoints recomienda idempotencia y deduplicación porque la reanudación puede encontrar una ventana en la que la llamada fue aceptada, pero su resultado no se registró.

Conclusión

Una reanudación segura no reconstruye el pasado a partir del prompt. Carga un checkpoint que el runtime pueda explicar, conserva la intención y el siguiente paso, y comprueba las consecuencias antes de repetir una acción.

El diseño puede empezar pequeño: estado explícito, runId, nextStep, una versión del estado y recibos de herramientas. Después añade propiedad exclusiva, revalidación de aprobaciones, migración de schema, retención y pruebas de interrupción. La frontera de responsabilidad debe seguir clara: el runtime decide el progreso y la herramienta es responsable del efecto que deja en el mundo.

Fuentes consultadas