Gestionar fallos, reintentos y recuperación

Un agente ejecuta una secuencia de acciones. Si falla en el paso siete, el problema no es solo reintentar el modelo: debes saber qué acciones ya ocurrieron, cuáles pueden repetirse y desde qué estado continuar.

La fiabilidad de agentes es fiabilidad de sistemas distribuidos.

Clasifica cada fallo

Modelo Timeout, rechazo, error de proveedor.

Tool 5xx, rate limit, validation error.

Estado Recurso cambió.

Permiso Acceso revocado.

Plan No existe siguiente acción útil.

Entorno Sandbox, filesystem o dependencia fallida.

Budget Tiempo, coste o pasos.

Cada tipo necesita respuesta distinta.

No reintentes indiscriminadamente

Un GET fallido puede ser reintentable.

Un create_payment() incierto no debe repetirse sin comprobar si el pago existe.

Define para cada tool:

• retryable;
• max_attempts;
• idempotency key;
• reconciliation;
• compensating action.

Persiste estado del run

Un esquema puede contener:

run_id
status
step
checkpoint
tool_calls
effects
approvals
budget
last_error
locked_until

El run puede sobrevivir a un proceso muerto.

Checkpoints

Guarda un checkpoint después de estados relevantes:

• evidencia completada;
• aprobación;
• escritura;
• artifact generado.

No después de cada token.

El checkpoint permite reanudar sin repetir trabajo.

Reconciliación

Ante timeout:

1. pregunta al sistema externo;
2. comprueba si el efecto ocurrió;
3. actualiza estado;
4. decide siguiente paso.

No deduzcas «no ocurrió» porque no recibiste respuesta.

Compensaciones

Si una acción fue reversible:

reservar → cancelar

puedes implementar compensación.

Pero una compensación no es rollback perfecto. Enviar un email no se «desenvía».

Distingue acciones reversibles y no reversibles en el contrato.

Recupera con contexto limpio

Después de un fallo, no siempre conviene reenviar todo el transcript.

Construye:

• objetivo;
• checkpoint;
• efectos confirmados;
• error;
• recursos actuales.

El agente debe partir del estado real.

Concurrencia

Dos runs pueden intentar modificar el mismo recurso.

Usa:

• locks;
• version checks;
• optimistic concurrency;
• estados;
• idempotencia.

Si el recurso cambió, el agente debe replanificar.

Evita cascadas

En multi-agent, un subagente fallido no debe provocar que otros repitan acciones incompatibles.

OWASP identifica cascading failures como riesgo.

Define:

• ownership;
• cancelación;
• error propagation;
• límites.

Ejemplo

Agente crea una tarea, después el proveedor LLM falla.

Al reanudar:

• ve task_id;
• no vuelve a crear;
• continúa con el siguiente paso.

Si la creación tuvo timeout:

• consulta por idempotency key;
• reconcilia.

Diseña semántica exactly-once con realismo

En sistemas distribuidos, garantizar exactamente una vez de extremo a extremo puede ser difícil.

No prometas «exactly once» si en realidad implementas:

• at-least-once + idempotencia;
• deduplicación;
• reconciliación.

Documenta la semántica real.

Separa errores del agente y del mundo

El agente puede equivocarse aunque todas las APIs funcionen.

Ejemplos:

• elige tool incorrecta;
• interpreta mal observación;
• termina pronto.

Eso no es un error 500.

Necesita evaluación y, a veces, replanificación.

Define un recovery policy

Para cada tipo:

RETRY
REPLAN
ASK_USER
ASK_HUMAN
ROLLBACK
COMPENSATE
STOP

El modelo puede sugerir, pero el harness decide qué opciones están permitidas.

Usa snapshots en entornos con estado complejo

Si el agente trabaja en:

• filesystem;
• código;
• configuración;

un snapshot puede permitir volver a un estado conocido.

OpenAI documenta snapshots en sandbox agents para trabajos con entornos de ejecución.

No sustituyen backups reales de producción.

Maneja resultados tardíos

Un resultado puede llegar después de que:

• el run se canceló;
• el usuario inició otro;
• otro worker completó la tarea.

Incluye run_id y version checks antes de aplicar.

Dead-letter y revisión

Cuando un run falla repetidamente:

• no bloquees toda la cola;
• márcalo;
• conserva evidencia;
• envíalo a revisión.

Una cola de fallos es parte de operación normal.

Ejercicio

Simula una trayectoria de ocho pasos con fallos en:

• lectura;
• escritura;
• timeout;
• permiso;
• presupuesto.

Para cada uno define:

• retry;
• reconcile;
• compensate;
• stop;
• escalate.

Resultado de la lección

Debes terminar con un run recuperable que distingue razonamiento de efectos externos. Un agente fiable no «empieza otra vez» cuando falla: reconstruye el estado y continúa solo si puede hacerlo sin duplicar consecuencias.