Reversión automatizada de los efectos secundarios de un agente

Una reversión de un agente puede restaurar código, configuración o determinados datos de la aplicación. No puede hacer que otra organización olvide una solicitud, sacar un correo entregado de una bandeja de entrada ni fingir que un cargo de tarjeta nunca llegó a un procesador de pagos. Los equipos que llaman «reversión» a todas estas operaciones crean un control tranquilizador que falla justo cuando importan las consecuencias.

Un diseño seguro separa cuatro mecanismos: instantáneas de la aplicación, reversiones de Git, recuperación de bases de datos y acciones compensatorias. Cada uno tiene un límite distinto. Toda acción que cruce el límite de la aplicación necesita su propia aprobación, evidencia, regla de reintento y ruta de recuperación antes de que el agente la ejecute. Si nadie puede expresar esa ruta en una frase, la acción no está lista para ejecutarse sin supervisión.

La reversión tiene cuatro significados distintos

La reversión solo sirve cuando el equipo nombra el estado que restaurará y el estado que no puede tocar. La palabra suele ocultar cuatro mecanismos con garantías muy diferentes.

Una instantánea restaura una versión capturada de una aplicación o espacio de trabajo. Según el producto, esa instantánea puede incluir código generado, configuración y estado gestionado seleccionado. No dice nada sobre servicios externos salvo que el contrato de la instantánea los incluya explícitamente.

Un git revert registra un nuevo commit cuyos cambios invierten un commit anterior. Repara el historial del código fuente sin borrar ese historial. No contacta con los servicios a los que llamó el código anterior mientras se ejecutaba.

La recuperación de una base de datos modifica los registros que guarda la base de datos. La reversión de una transacción descarta escrituras no confirmadas dentro de una transacción. Restaurar una copia de seguridad o usar recuperación a un punto en el tiempo es una operación mucho mayor que acerca un clúster de bases de datos a un estado anterior. Ninguna de las dos operaciones reconcilia automáticamente sistemas externos a esa base de datos.

Una acción compensatoria crea un nuevo efecto pensado para contrarrestar otro anterior. Un reembolso compensa un pago capturado. Una solicitud de cancelación compensa un pedido. Un correo de corrección puede mitigar un correo equivocado, aunque no puede retirar el primer mensaje. La compensación conserva la incómoda verdad de que la acción original ocurrió.

Uso una tabla de responsabilidad de efectos durante las revisiones de diseño porque obliga a dar respuestas precisas:

La última columna es la más importante. Una operación inversa no prueba que el original haya desaparecido. Pueden persistir registros de auditoría, copias de destinatarios, asientos de liquidación, webhooks y trabajo físico.

Una reversión de código cambia el programa, no el pasado

Una reversión de código evita o cambia el comportamiento futuro. No invierte el comportamiento que ya provocó la versión anterior. Esto sigue siendo cierto tanto si el equipo usa Git como una instantánea de plataforma o una reversión de despliegue.

La documentación de Git describe git revert como el registro de commits que invierten cambios introducidos por commits anteriores. La formulación es precisa: Git aplica un parche inverso al contenido del repositorio. Git no sabe nada de correos, pagos, recursos en la nube, tickets de soporte o API de socios creados cuando se ejecutó el commit revertido.

Supongamos que un agente modifica una función de facturación, la despliega y la invoca dos veces antes de que la monitorización detecte el defecto. Revertir el commit puede impedir que la función defectuosa vuelva a ejecutarse. Deja dos intentos de pago en el procesador. Si la base de datos local registró solo uno, la reversión puede incluso dificultar la investigación al eliminar la ruta de código que comprendía la segunda respuesta.

La reversión de despliegue tiene el mismo límite. Redirigir el tráfico a una compilación anterior restaura el comportamiento ejecutable. Las solicitudes que ya aceptó la compilación reemplazada conservan sus consecuencias. Los trabajos en cola también pueden sobrevivir al despliegue y ejecutar supuestos antiguos contra la versión restaurada.

Antes de revertir, conserva la evidencia operativa que produjo la compilación anterior:

• Identificador de despliegue y commit de origen
• Identificadores de ejecución e intención del agente
• Identificadores de mensajes de cola y estado del arrendamiento
• Identificadores de solicitudes externas
• Respuestas del proveedor y marcas de tiempo

Después, detén nuevas ejecuciones, reconcilia operaciones incompletas y restaura el código. Revertir primero y hacer preguntas después suele destruir la vía más fácil para entender qué efectos se escaparon.

Una instantánea puede ser más amplia que un commit de Git, pero se aplica la misma regla. El contrato de la instantánea debe indicar exactamente qué recursos contiene. Si contiene código y configuración, llámala mecanismo de recuperación de código y configuración. No la conviertas en una función universal para deshacer mediante una redacción optimista en la interfaz.

La recuperación de bases de datos tiene un alcance más limitado de lo que se suele pensar

La recuperación de bases de datos restaura el estado de la base de datos, no la realidad del negocio en todos los participantes de una transacción. Una transacción puede ser atómica dentro de una base de datos mientras la operación que la rodea sigue dividida entre varios sistemas.

Considera esta secuencia:

1. El agente inserta una fila de factura.
2. Llama a una API de pagos.
3. El procesador acepta el cargo.
4. Falla la confirmación de la base de datos.

La reversión local elimina la fila de factura. El cargo sigue existiendo. Reintentar toda la operación sin reconciliación puede volver a cobrar al cliente. Este es el clásico fallo de escritura dual: la aplicación intentó hacer atómica una acción empresarial entre sistemas que no comparten un coordinador de transacciones.

Invertir el orden no lo resuelve. Si la aplicación confirma primero la factura y luego falla la llamada de pago, la base de datos contiene una factura sin pagar. Ese estado es más fácil de inspeccionar, pero la aplicación aún necesita una máquina de estados que distinga payment_pending, payment_confirmed, payment_failed y payment_unknown.

La documentación de PostgreSQL explica la recuperación a un punto en el tiempo como la restauración de una copia de seguridad base y la reproducción de registros de escritura anticipada hasta un objetivo de recuperación elegido. Es un procedimiento de operador para recuperar un clúster de bases de datos. No es una forma de deshacer selectivamente una ejecución de agente y no puede pedir a un procesador de pagos o a un servicio de correo que vuelvan a la misma marca de tiempo.

Retroceder la base de datos puede crear un segundo desajuste. Imagina restaurar a las 10:00 después de una caída. Un proveedor aceptó solicitudes hasta las 10:07, pero la base de datos restaurada ya no contiene sus registros. Los agentes que vean filas «ausentes» pueden recrear los siete minutos de trabajo. Por eso la recuperación necesita una fase de reconciliación externa antes de que se reanuden los trabajadores.

El patrón outbox reduce un hueco peligroso. La aplicación confirma el cambio empresarial y una intención de efecto en la misma transacción local:

BEGIN;

INSERT INTO invoices (invoice_id, customer_id, status)
VALUES ('inv_2048', 'cust_91', 'payment_pending');

INSERT INTO effect_intents
  (intent_id, operation, subject_id, status)
VALUES
  ('eff_7f31', 'capture_payment', 'inv_2048', 'pending');

COMMIT;

Más tarde, un trabajador reclama eff_7f31, llama al proveedor con un valor de idempotencia estable y registra el resultado. El outbox no hace atómica la llamada externa. Da al sistema evidencia duradera de que el trabajo se pretendía realizar, lo que permite reintentos y reconciliación.

Las acciones externas necesitan compensaciones, y algunas no tienen ninguna

Un efecto externo necesita una compensación específica del proveedor o una declaración explícita de que no existe una compensación significativa. Tratar cada acción como reversible es peor que admitir que algunas acciones requieren aprobación.

El correo electrónico es el ejemplo más sencillo. Antes de que el proveedor acepte el mensaje, la aplicación puede cancelar un trabajo en cola. Tras la aceptación, el proveedor quizá permita cancelarlo durante una breve fase interna, pero no existe una garantía general de retirada entre destinatarios y sistemas de correo. Una vez entregado, un segundo mensaje puede corregir el registro, no borrar el primero. Los datos sensibles, los avisos legales y el daño reputacional siguen expuestos.

Los pagos tienen varios estados que los equipos suelen resumir como «cobrado». Una autorización reserva capacidad de gasto. Una captura solicita el movimiento de fondos contra esa autorización. Una anulación puede liberar una autorización que aún no se ha liquidado. Un reembolso crea un asiento financiero posterior que devuelve dinero después de la captura. Estas operaciones tienen tiempos, comisiones, permisos e impacto en el cliente distintos. Una herramienta genérica undo_payment oculta información que el agente necesita para actuar con seguridad.

Otras API colaboran aún menos. Una solicitud puede pedir inventario, aprovisionar infraestructura, publicar contenido, conceder acceso, enviar un paquete o hacer que una persona empiece a trabajar. Un endpoint DELETE no prueba que haya reversibilidad. Eliminar un recurso puede dejar registros de auditoría, datos copiados, notificaciones, recursos dependientes o consecuencias físicas.

Clasifica la compensación según lo que pueda lograr con honestidad:

• Un inverso local exacto devuelve el estado controlado a su valor anterior.
• La cancelación del proveedor detiene trabajo que aún no ha terminado.
• La compensación financiera crea un reembolso o crédito.
• La comunicación correctiva reconoce que el primer mensaje sigue visible.
• La corrección manual gestiona efectos cuyo contexto no cabe en una regla automatizada segura.

La compensación también puede fallar. El endpoint de reembolso puede agotar el tiempo de espera. La ventana de cancelación puede cerrarse. La dirección del destinatario puede rechazar la corrección. La cuenta que usa el agente puede no tener permiso. Por eso el sistema debe rastrear la compensación como otra operación, con su propio identificador de intención, estado, intentos, evidencia y política de aprobación.

No crees una función recursiva para «revertir la reversión». Modela el historial como un libro mayor de acciones. Si una compensación provoca un nuevo error, emite otra acción explícita después de revisar el estado actual. El historial será más largo, pero seguirá siendo comprensible durante un incidente.

La idempotencia evita repeticiones, pero no revierte un éxito

La idempotencia protege los reintentos para que no produzcan efectos previstos duplicados. No deshace el primer efecto exitoso. Los equipos confunden estas ideas de forma habitual y descubren la diferencia después de un tiempo de espera.

RFC 9110 define un método de solicitud idempotente por el efecto previsto de que varias solicitudes idénticas sea el mismo que el de una sola. Identifica PUT, DELETE y los métodos seguros como idempotentes a nivel de semántica del protocolo. POST no suele ser idempotente, aunque una API puede añadir ese comportamiento mediante su propio contrato.

La precisión importa. Un DELETE idempotente puede seguir produciendo una nueva entrada de registro, métrica o respuesta cada vez. La implementación de idempotencia de un proveedor también puede hacer caducar registros, limitar identificadores a una cuenta, rechazar parámetros modificados o almacenar en caché solo determinados resultados. Lee el contrato del proveedor en lugar de deducir garantías a partir de un verbo HTTP.

Cada intención de efecto debe recibir un valor de idempotencia estable antes de su primer intento. Los reintentos de esa misma intención lo reutilizan. Una nueva intención empresarial recibe un valor nuevo. Nunca lo derives solo de parámetros mutables como cliente, importe y fecha, porque dos compras legítimas pueden compartirlos.

Un tiempo de espera crea un resultado desconocido, no un fallo. Sigue esta secuencia:

1. Marca el intento como outcome_unknown; no crees una intención de reemplazo.
2. Consulta al proveedor usando el valor de idempotencia o la referencia de operación.
3. Si el proveedor confirma el éxito, registra ese éxito localmente.
4. Si confirma que no hubo operación, reintenta con el mismo valor.
5. Si no puede responder, retén la operación para reconciliación o revisión humana.

Esta forma de respuesta da al agente suficiente información para distinguir la aceptación de la incertidumbre de transporte:

{
  "intent_id": "eff_7f31",
  "attempt": 2,
  "idempotency_key": "eff_7f31",
  "transport_status": "timeout",
  "provider_status": "unknown",
  "provider_reference": null,
  "next_action": "reconcile"
}

Un valor de idempotencia debe viajar por registros, mensajes de cola, cabeceras API y metadatos del proveedor cuando sea posible. Si los operadores no pueden buscarlo a ambos lados del límite, adivinarán durante la recuperación.

La aprobación corresponde al límite del efecto

La aprobación debe ocurrir después de que el agente haya formado la acción externa exacta y antes de que la primera solicitud irreversible salga del sistema. Aprobar al comienzo de una tarea amplia da al agente demasiado margen para cambiar después destinatarios, importes, ámbitos o herramientas.

«Gestiona la cuenta de este cliente» no es una aprobación suficiente para cobrar una tarjeta o enviar correo a todos los usuarios. Una aprobación válida describe la operación concreta: destinatario, importe y moneda, resumen del mensaje o carga útil, cuenta de destino, herramienta, vencimiento y cantidad de intentos permitidos. Si cambia cualquier campo aprobado, la aprobación deja de coincidir.

Una política útil ordena los efectos por consecuencia, no por el agente o modelo que los solicitó. El acceso de lectura aún puede exponer datos privados, pero no crea el mismo problema de recuperación que una acción saliente. Redactar un correo es local y reversible. Enviarlo cruza el límite. Crear una propuesta de pago es local. Capturar fondos cruza el límite.

Exige aprobación explícita para acciones que:

• Muevan dinero o creen una obligación financiera
• Envíen información a una persona u organización externa
• Publiquen, eliminen o revelen datos fuera del almacenamiento controlado
• Cambien identidad, acceso, propiedad o configuración de seguridad
• Inicien trabajo físico u otro proceso que no pueda retirarse de forma fiable

Las acciones repetitivas de baja consecuencia pueden usar aprobación permanente limitada. El límite debe indicar un importe máximo, conjunto de destinatarios, herramienta permitida, hora de vencimiento, frecuencia y número total de operaciones. «Aprobado para facturación» no tiene un límite aplicable.

La aprobación también necesita protección contra la repetición. Vincúlala a un resumen inmutable de la operación y márcala como consumida cuando la política permita una sola ejecución. Si la ejecución devuelve un resultado desconocido, no pidas una aprobación nueva ni crees una segunda intención. Reconcilia primero la intención aprobada.

La pantalla de aprobación debe explicar en lenguaje común la realidad de la recuperación. «Este mensaje no se puede retirar tras la entrega» es útil. «Esta operación es reversible» resulta engañoso cuando la recuperación real es un reembolso que puede tardar y seguir apareciendo en los extractos financieros.

Los contratos de herramientas deben mostrar todo el ciclo de vida del efecto

Un contrato de herramienta para agentes debe describir intención, ejecución, observación y compensación como operaciones separadas. Una única función que produce un efecto y devuelve success: true deja muy poca evidencia para reintentos, aprobaciones o respuesta ante incidentes.

El siguiente fragmento de política es lo bastante pequeño para aplicarlo y lo bastante específico para revisarlo:

tools:
  send_email:
    effect: irreversible
    approval: required
    idempotency_field: intent_id
    evidence_field: provider_message_id
    compensation: null

  capture_payment:
    effect: compensatable
    approval: required
    idempotency_field: intent_id
    evidence_field: provider_payment_id
    compensation: refund_payment

  update_draft:
    effect: local_reversible
    approval: none
    compensation: restore_version

effect indica al planificador qué clase de recuperación corresponde. approval bloquea la ejecución hasta que se autoricen los argumentos exactos. El campo de idempotencia hace que los reintentos reutilicen una identidad. El campo de evidencia indica a los operadores qué debe conservarse. El campo de compensación apunta a una herramienta separada, en vez de fingir que la llamada original puede ejecutarse hacia atrás.

La ejecución debe aceptar un sobre inmutable:

{
  "intent_id": "eff_7f31",
  "operation": "capture_payment",
  "arguments": {
    "invoice_id": "inv_2048",
    "amount_minor": 12900,
    "currency": "USD"
  },
  "approval": {
    "approval_id": "apr_662",
    "scope_hash": "sha256:8b4f...",
    "expires_at": "2026-07-27T18:00:00Z"
  }
}

El ejecutor calcula el resumen de la operación, lo compara con scope_hash, comprueba el vencimiento, reserva la intención y solo entonces contacta con el proveedor. Guarda los metadatos de la solicitud antes de la llamada y la respuesta después. Si falla entre esas escrituras, la intención duradera sigue disponible para la reconciliación.

El ejecutor debe rechazar cuatro condiciones sin improvisar: argumentos modificados, aprobación vencida, reutilización de una intención para otra operación e intento de compensar un efecto cuyo éxito aún no se ha confirmado. Los agentes son buenos encontrando continuaciones plausibles. Los controles financieros y de comunicación deben preferir una detención visible a una suposición plausible.

Da a la observación su propia herramienta, como get_payment_status(intent_id). La observación no debe crear un efecto. Mantenerla separada permite al agente resolver resultados ambiguos sin recibir permiso para reintentar la acción original.

Una sola ejecución fallida puede cruzar todos los límites de recuperación

Una sola ejecución de agente puede dejar código, registros de base de datos y sistemas externos en momentos distintos. Recorrer ese fallo antes del lanzamiento revela huecos que oculta un control de reversión genérico.

Supongamos que un agente crea una aplicación de membresías, despliega un cambio, importa una lista de clientes, cobra cuotas anuales y envía correos de bienvenida. La tarea parece unificada, pero cruza al menos cuatro límites de recuperación.

A las 14:00, el agente despliega código que calcula la cuota anual a partir de la columna equivocada. A las 14:02, escribe 40 intenciones de pago y borradores de correo en la base de datos. A las 14:03, un trabajador captura varios pagos. A las 14:04, el proveedor de correo acepta mensajes de bienvenida que contienen la cuota incorrecta. A las 14:05, la monitorización detiene al trabajador. Algunas llamadas de pago agotaron el tiempo de espera tras llegar al procesador, de modo que el estado local no revela si tuvieron éxito.

Restaurar la instantánea de código de las 13:59 detiene el cálculo defectuoso en futuras ejecuciones. No cambia la cuota copiada en las intenciones existentes. Revertir el commit de Git documenta la corrección de código fuente, pero tiene el mismo límite.

Restaurar la base de datos a las 13:59 eliminaría los registros de intención locales que contienen referencias del proveedor y valores de idempotencia. Eso empeora el desajuste externo. La mejor acción sobre la base de datos es una corrección lógica: conservar las intenciones, marcar las operaciones inciertas para reconciliación y corregir las filas solo después de cotejar el estado del proveedor.

El equipo de respuesta debe continuar según la clase de efecto. Consulta cada pago incierto con su identidad de operación estable. Las capturas confirmadas pasan a revisión de reembolso, los intentos fallidos se cierran sin reintento y los intentos sin resolver siguen bloqueados. Los correos entregados reciben una corrección cuidadosamente aprobada. Se cancelan los mensajes en cola que aún no han llegado al proveedor. Cada compensación recibe una nueva intención vinculada a la original.

Este ejemplo también muestra por qué la compensación automática puede ser peligrosa. Si el sistema reembolsa inmediatamente cada registro local payment_unknown, puede emitir reembolsos por cargos que nunca existieron o llamar a un endpoint de reembolso con la referencia equivocada. Si reenvía cada correo ausente tras recuperar la base de datos, los destinatarios pueden recibir duplicados. La reconciliación debe preceder a la compensación siempre que el estado local y el del proveedor no coincidan.

La ejecución termina solo cuando cada intención alcanza un estado terminal como succeeded, confirmed_failed, compensated o manual_exception. «La aplicación se revirtió» describe solo la primera parte del incidente.

La recuperación solo funciona si sobrevive la evidencia

Los controles de recuperación fallan cuando una reversión elimina los registros necesarios para decidir qué ocurrió. Guarda un libro mayor de efectos de solo anexado fuera del estado de la aplicación que puedan reemplazar las instantáneas o restauraciones rutinarias, y conserva suficiente evidencia del proveedor para reconciliar cada operación.

El libro mayor debe registrar la creación de intención, el resumen de argumentos, la aprobación, el arrendamiento de ejecución, el intento, el resultado de transporte, la referencia del proveedor, el estado observado del proveedor y los vínculos de compensación. Limita los cambios a transiciones de estado en lugar de permitir que los agentes sobrescriban entradas antiguas. Las correcciones deben añadir eventos en vez de editar el historial.

Supervisa los estados sin resolver, no solo los errores explícitos. Un outcome_unknown que permanece diez minutos puede ser más peligroso que un rechazo claro, porque un operador puede reintentarlo manualmente. También alerta cuando una aprobación vence durante la ejecución, aparece un valor de idempotencia con un resumen de argumentos distinto o falla una compensación.

Haz simulacros de recuperación con puntos de fallo deliberadamente incómodos. Finaliza un trabajador después de que el proveedor acepte una solicitud pero antes de que se escriba el éxito local. Restaura los datos de la aplicación desde una instantánea anterior preservando el libro mayor de efectos. Deja vencer la aprobación entre la planificación y la ejecución. Haz que la API de observación no esté disponible. El simulacro tiene éxito cuando el sistema se detiene, reconcilia y expone la decisión sin resolver sin duplicar el efecto.

Cuando uses Koder.ai, trata sus instantáneas y su reversión como la capa de recuperación de la aplicación. Después diseña controles separados para el historial de la base de datos y cada acción externa que la aplicación pueda activar. La exportación de código fuente, los controles de despliegue y la reversión ayudan a restaurar el software, mientras los contratos de herramientas de la aplicación siguen controlando aprobaciones y compensación.

Un botón de reversión debe indicar su límite junto al botón: código, configuración, datos gestionados o efectos externos. Si la interfaz no puede expresar esa frase con precisión, no debe prometer una reversión. El control honesto puede parecer menos mágico, pero da al equipo de incidentes lo que necesita a las 2 de la mañana: un relato fiable de qué cambió, qué se escapó y qué acción es segura a continuación.