Acciones fiables de agentes: tiempos de espera, reintentos y recuperación
Sigue un reembolso de comercio electrónico desde la intención autorizada hasta el resultado conciliado. Aprende a separar estado durable, idempotencia y presupuesto de reintentos con una implementación local ejecutable.
Fuentes y versiones
En este artículo
1. El reembolso puede completarse después del timeout
Un cliente solicita devolver 25 dólares del pedido 7. El modelo propone la acción, una política la autoriza y el proveedor la acepta. La respuesta se pierde antes de guardar el éxito. Un agente ingenuo declara el fallo y crea otro reembolso. Ambos razonamientos pueden ser correctos y aun así producir un error empresarial. El objetivo es conservar una intención aprobada a través de una entrega incierta, no aparentar éxito en el chat.
Un efecto modifica un sistema externo; un acuse comunica evidencia al cliente. La ausencia del segundo no demuestra ausencia del primero. Idempotencia es el contrato que evita un efecto adicional al repetir la misma intención identificada. Durabilidad significa sobrevivir a un modelo de fallos explícito. Un registro durable puede conservar perfectamente dos pagos duplicados. Se requieren nociones de transacciones, comunicación petición/respuesta y autorización: una transacción local no incluye automáticamente una llamada HTTP remota.
Este tutorial sirve para agentes que crean incidencias, reservan inventario o inician reembolsos autorizados. La búsqueda de solo lectura necesita frescura y presupuestos, pero normalmente no conciliación de efectos financieros. Una acción irreversible sin idempotencia ni consulta de estado exige intervención o rediseño. El sistema es un diseño de referencia original; el programa usa dos bases locales, sin modelos ni pagos reales.
2. Separar la planificación de la ejecución
El planificador propone herramienta y argumentos. Una puerta determinista valida esquema, inquilino, propiedad del pedido, importe y caducidad de aprobación. Normaliza el dinero a unidades menores enteras antes de aprobar: 2500 centavos son 25 dólares; una integración real también registra moneda. Vincula aprobación, ID de operación, resumen de argumentos canónicos y versión de política. Cambiar el importe crea una intención nueva; repetir la misma conserva su ID.
El ejecutor guarda la intención antes de enviarla. El proveedor posee el registro autoritativo del efecto. Un conciliador consulta ese registro y actualiza el estado local solo con evidencia validada. La interfaz distingue pendiente, confirmado, incierto y rechazado. La salida de una herramienta no concede permisos para la siguiente compra. Cada nueva mutación debe revisar su autorización; consultar una operación anterior requiere una capacidad de lectura separada.
La arquitectura tiene dos transacciones independientes: local y remota, separadas por la red. Un outbox guarda intención y trabajo pendiente atómicamente en la base local y permite entrega al menos una vez; no incluye el efecto remoto en esa transacción. Toda mutación pasa por la puerta de ejecución. La conciliación lee estado y conserva evidencia; no inicia compensaciones ocultas.
3. La incertidumbre es un estado
Guarda PREPARED antes de enviar. SUBMITTED significa que la petición puede haber salido, no que haya sido aceptada. Una confirmación con intención coincidente permite SUCCEEDED. Un acuse perdido o un fallo posterior al envío deja UNKNOWN o SUBMITTED pendiente de conciliación. REJECTED requiere un rechazo definitivo; un timeout no lo demuestra. Un resultado «no encontrado» puede deberse a visibilidad retrasada o a una petición en vuelo. Repetir la misma clave solo es seguro bajo un contrato explícito de idempotencia.
Hay tres ventanas de fallo. Antes del commit local, no se permite enviar. Después del commit de intención y antes del envío, se retoma la misma operación. Después del commit remoto y antes del éxito local, se consulta al proveedor o se repite la operación deduplicada. Crear otro UUID en cada reintento destruye esa continuidad. Deriva la clave de una identidad empresarial durable o guarda una clave generada en un paso durable anterior al efecto.
Cancelar detiene trabajo futuro cuando es posible; no revierte efectos completados. Si cancelación y reembolso compiten, muestra el resultado conciliado y trata cualquier remedio como otra operación autorizada. Compensar no es rollback atómico. La documentación actual de LangGraph distingue reejecución de nodos y efectos externos, y considera desconocido un acuse ausente. Fija versiones del framework; el ejemplo no depende de ellas.
4. Propietario, ámbito y retención de la idempotencia
El registro del proveedor puede usar una clave única por inquilino e ID de operación y conservar resumen de intención, resultado y retención. Deduplicación y efecto deben ser atómicos dentro de ese sistema. Consultar desde el cliente y luego escribir sin protección no basta: dos workers pueden observar ausencia y actuar. La referencia utiliza clave única y transacción; un proveedor real debe publicar un contrato equivalente.
No uses el hash del prompt ni únicamente un ID de herramienta inventado por el modelo como identidad empresarial. Un espacio puede cambiar el hash, mientras dos reembolsos deliberadamente iguales deben distinguirse. Canonicaliza argumentos validados y separa identidad de resumen. El ejemplo resume pedido y centavos; producción debe incluir moneda, cuenta, acción y versión de esquema. Una clave con otro resumen es un conflicto, no permiso para sobrescribir historia.
La retención limita la garantía. Stripe API v1 documenta respuestas repetidas, comprobación de parámetros y eliminación de claves después de al menos 24 horas; API v2 trata los fallos de otra manera. No generalices ese contrato. Si la recuperación dura más que la deduplicación, detén mutaciones automáticas hasta conciliar mediante una identidad durable. Puede ser necesario conservar una marca histórica compacta o libro empresarial. No incluyas datos personales sensibles en las claves.
5. Plazos y presupuestos de reintento
Un timeout limita una espera; un deadline limita toda la operación. El presupuesto restante R es D menos t. Reserva F segundos para guardar estado y responder. Una espera b y un intento de timeout T caben solo si b+T+F no supera R. Ejemplo original: presupuesto de 30 segundos, 18 consumidos, F=2 y T=4. Esperar 8 requiere 14 segundos y no cabe; esperar 2 requiere 8 y sí cabe en los 12 restantes. Usa reloj monotónico dentro del proceso y propaga tiempo restante acotado entre servicios.
Clasifica antes de repetir. Argumentos inválidos, permisos denegados y rechazos empresariales definitivos no son fallos transitorios. Para fallos temporales usa intentos limitados, backoff exponencial con jitter, presupuesto compartido y límites de concurrencia por dependencia. La fórmula de full jitter usa índice i desde cero y base/cap en segundos; el retraso se distribuye uniformemente entre cero y el límite del intento. Jitter distribuye la carga, pero no reduce cuántos intentos se permiten.
Tres capas con tres intentos cada una pueden generar 27 llamadas finales. Asigna un propietario de reintentos o presupuesta todo el árbol. Con probabilidad independiente de fallo 0,2 y tres intentos máximos, la esperanza es 1+0,2+0,04=1,24. La sobrecarga correlacionada invalida la independencia. El presupuesto sigue siendo necesario aunque falle esa estimación. gRPC propaga deadlines, pero las tareas que lanza la aplicación deben cooperar con la cancelación.
En las ecuaciones b_0 es el retraso base, b_max su límite, i el índice desde cero, A el número de intentos, m el máximo y p la probabilidad independiente de fallo. A y m son conteos; p es adimensional. La esperanza incluye el primer intento.
6. Persistencia y observabilidad no son intercambiables
Un checkpoint conserva control; el libro de herramientas conserva efectos identificados; la auditoría vincula autoridad y evidencia; la traza mide intentos, colas y latencia. LangGraph diferencia checkpoints de hilo y stores entre hilos. Los ejemplos en memoria no establecen durabilidad frente a caídas. Guarda decisiones o salidas del modelo en los límites de replay para que un planificador estocástico no invente otra operación dentro de la misma intención aprobada.
Registra operación, inquilino, resumen, versión de aprobación, intento, deadline, referencia remota, transición y error redactado. Una operación empresarial puede tener muchos intentos de red. Mide cantidad y antigüedad de UNKNOWN, efectos por intención, conflictos, amplificación y tiempo de conciliación. No cuentes un timeout como reembolso fallido si luego se confirma. Protege registros y retención: los argumentos pueden contener datos personales.
Varios ejecutores requieren propiedad mediante leases y, cuando el destino lo admita, generaciones de fencing. Caducar un lease no mata al worker anterior. Sin fencing o idempotencia todavía puede actuar. Un mutex local no es exclusión distribuida. El código usa un ejecutor y un proveedor transaccional simulado; no implementa leases distribuidos, failover regional ni autorización real.
7. Elegir el mecanismo mínimo suficiente
Para lectura, reintenta dentro del plazo e identifica datos obsoletos. Para mutación idempotente con consulta, concilia primero y repite la misma clave con autorización vigente. Sin consulta, recuperar una respuesta mediante repetición depende de retención y semántica de errores. Sin idempotencia ni estado fiable, detén el proceso y pide investigación humana. Reintentar no crea un contrato inexistente.
Un motor de workflows ayuda con pasos largos, temporizadores y aprobaciones; resulta excesivo para un cálculo puro local. Outbox resuelve despacho local fiable; saga define compensaciones empresariales. Ninguno convierte cualquier API externa en exactly-once. En el ejemplo, un conciliador de solo lectura es más seguro que inferir éxito desde un correo o iniciar automáticamente un pago inverso.
Persisten problemas de expiración, caídas del proveedor durante la consulta, migraciones de esquema, callbacks tardíos, eventos desordenados y propiedad multirregional. Versiona intenciones, conserva evidencia terminal y asigna responsables a la cola manual. La aceptación productiva exige una conducta segura en cada ventana de incertidumbre, no prometer ausencia de fallos. La práctica verifica un subconjunto; no certifica una integración de pagos.
| Mecanismo | Protege | No garantiza |
|---|---|---|
| Checkpoint | Estado del flujo | Efectos externos exactly-once |
| Outbox | Intención y despacho local | Commit atómico entre proveedores |
| Clave idempotente | Deduplicación de intención | Retención infinita o autorización |
| Conciliación | Evidencia remota | Disponibilidad del proveedor |
Práctica y validación
Python 3.11+, solo biblioteca estándar. Ejecuta python3 agent-action-recovery.py. Sin claves, red, efectos reales ni aleatoriedad. Dos archivos SQLite temporales separan agente y proveedor simulado; deduplicación y reembolso se confirman juntos solo en el proveedor. Resultado: PASS y effects=3; duplicate-effects=0. Son dos operaciones distintas de shop y una de otro inquilino. Las aserciones cubren acuse perdido, reapertura, conflicto, permiso de escritura caducado, caída tras commit remoto y entrega duplicada. No prueban IAM real, kill de procesos, red ni límites financieros. Compara con una variante que genere otra clave después de perder el acuse: aparece un efecto extra. Mantén intención y punto de fallo iguales. Antes de producción añade visibilidad retrasada, fallos del proveedor, agotamiento de presupuesto y ejecutores concurrentes.
agent-action-recovery.pypython3 agent-action-recovery.pyPython 3.11+
"""Python 3.11+, standard library. Local teaching model; never contacts a provider."""
import hashlib
import json
import sqlite3
import tempfile
from pathlib import Path
def connect(path):
db = sqlite3.connect(path)
db.execute('PRAGMA synchronous=FULL')
return db
def fingerprint(order, cents):
if type(cents) is not int or cents <= 0:
raise ValueError('positive integer cents required')
return hashlib.sha256(json.dumps([order, cents], separators=(',', ':')).encode()).hexdigest()
class Provider:
"""One transactional SQLite database models the external system's contract."""
def __init__(self, path):
self.db = connect(path)
self.db.executescript('''
CREATE TABLE IF NOT EXISTS refunds (
tenant TEXT, op TEXT, digest TEXT, cents INTEGER,
PRIMARY KEY (tenant, op));
''')
def submit(self, tenant, op, digest, cents):
# Atomic deduplication + effect, not a client-side check-then-act.
with self.db:
self.db.execute('BEGIN IMMEDIATE')
old = self.db.execute('SELECT digest FROM refunds WHERE tenant=? AND op=?',
(tenant, op)).fetchone()
if old and old[0] != digest:
raise ValueError('provider key conflict')
if not old:
self.db.execute('INSERT INTO refunds VALUES (?,?,?,?)',
(tenant, op, digest, cents))
return {'state': 'succeeded', 'digest': digest}
def status(self, tenant, op):
row = self.db.execute('SELECT digest FROM refunds WHERE tenant=? AND op=?',
(tenant, op)).fetchone()
return None if row is None else {'state': 'succeeded', 'digest': row[0]}
def count(self):
return self.db.execute('SELECT COUNT(*) FROM refunds').fetchone()[0]
class AgentExecutor:
def __init__(self, path, provider):
self.db, self.provider = connect(path), provider
self.db.execute('''CREATE TABLE IF NOT EXISTS operations (
tenant TEXT, op TEXT, digest TEXT, order_id TEXT, cents INTEGER,
state TEXT, PRIMARY KEY(tenant,op))''')
self.db.commit()
def state(self, tenant, op):
row = self.db.execute('SELECT state FROM operations WHERE tenant=? AND op=?',
(tenant, op)).fetchone()
return row[0] if row else None
def mark(self, tenant, op, state):
with self.db:
self.db.execute('UPDATE operations SET state=? WHERE tenant=? AND op=?',
(state, tenant, op))
def execute(self, tenant, op, order, cents, *, authorized, lose_ack=False,
crash_after_provider=False):
digest = fingerprint(order, cents)
row = self.db.execute('SELECT digest,state FROM operations WHERE tenant=? AND op=?',
(tenant, op)).fetchone()
if row and row[0] != digest:
raise ValueError('same operation ID with different intent')
if row and row[1] == 'succeeded':
return 'succeeded'
if not row:
if not authorized:
return 'blocked'
with self.db:
self.db.execute('INSERT INTO operations VALUES (?,?,?,?,?,?)',
(tenant, op, digest, order, cents, 'prepared'))
# Reconcile first, even if permission to create a new effect has expired.
# This demo assumes a separate permission to inspect this tenant's status.
result = self.provider.status(tenant, op)
if result:
if result['digest'] != digest:
raise ValueError('status intent mismatch')
self.mark(tenant, op, 'succeeded')
return 'succeeded'
if not authorized:
return 'blocked'
# A missing status alone is NOT proof of no effect. Safe repeat here depends
# on Provider.submit's durable atomic idempotency contract, with no expiry.
self.mark(tenant, op, 'submitted')
self.provider.submit(tenant, op, digest, cents)
if crash_after_provider:
raise RuntimeError('injected crash after provider commit')
if lose_ack:
self.mark(tenant, op, 'unknown')
return 'unknown'
self.mark(tenant, op, 'succeeded')
return 'succeeded'
def run():
with tempfile.TemporaryDirectory() as folder:
root = Path(folder)
provider = Provider(root / 'provider.sqlite')
client = AgentExecutor(root / 'agent.sqlite', provider)
assert client.execute('shop', 'refund-1', 'order-7', 2500,
authorized=True, lose_ack=True) == 'unknown'
assert provider.count() == 1
client.db.close()
client = AgentExecutor(root / 'agent.sqlite', provider)
assert client.execute('shop', 'refund-1', 'order-7', 2500,
authorized=False) == 'succeeded'
assert provider.count() == 1
try:
client.execute('shop', 'refund-1', 'order-7', 3000, authorized=True)
raise AssertionError('changed intent accepted')
except ValueError:
pass
assert client.execute('shop', 'refund-2', 'order-8', 500,
authorized=False) == 'blocked'
try:
client.execute('shop', 'refund-3', 'order-9', 700,
authorized=True, crash_after_provider=True)
except RuntimeError:
pass
assert client.state('shop', 'refund-3') == 'submitted'
client.db.close()
client = AgentExecutor(root / 'agent.sqlite', provider)
assert client.execute('shop', 'refund-3', 'order-9', 700,
authorized=True) == 'succeeded'
# Direct duplicate delivery exercises provider-side atomic deduplication.
d = fingerprint('order-9', 700)
provider.submit('shop', 'refund-3', d, 700)
assert provider.count() == 2
# Distinct tenant namespace: same op is a different operation.
assert client.execute('shop-2', 'refund-3', 'order-9', 700,
authorized=True) == 'succeeded'
assert provider.count() == 3
client.db.close()
provider.db.close()
print('PASS: lost acknowledgement, restart, conflict, expired permission, crash window, duplicate delivery, tenant namespace')
print('effects=3; duplicate-effects=0; no network; deterministic; no random seed needed')
if __name__ == '__main__':
run()
Preguntas originales, no de entrevistas empresariales
¿Por qué un timeout no demuestra fracaso?
Pista
Separa commit y entrega.
Respuesta y análisis
El efecto puede existir sin respuesta. Conserva incertidumbre y consulta; no generes otra intención.
¿Un checkpoint garantiza pagos exactly-once?
Pista
Ubica las dos transacciones.
Respuesta y análisis
No. El nodo puede repetirse tras el efecto. Hace falta contrato de idempotencia atómica o conciliación fiable.
¿La aprobación caducada impide consultar?
Pista
Separa lectura y escritura.
Respuesta y análisis
Impide nuevas mutaciones; la consulta puede continuar con permiso separado válido, supuesto explícito del ejemplo. No renueva aprobación.
¿Cuándo vuelve a ser insegura la repetición?
Pista
Revisa retención, argumentos y ámbito.
Respuesta y análisis
Al caducar deduplicación, cambiar clave o intención, o salir del ámbito contratado. Detén y concilia.
Puntuación: 1—define conceptos; 2—identifica incertidumbre; 3—ejecuta y explica; 4—diseña controles; 5—especifica retención, autoridad y concurrencia.
Predecir, comprobar y conservar evidencia
Antes de revelar la respuesta, predice un resultado. Después registra diferencias y una prueba de transferencia. Se guarda localmente y se comparte entre idiomas.
Abrir cuaderno / exportar / borrar →El alcance de revisión matemática se registra por lección. No certifica reproducción empírica del artículo; anota posibles errores. Alcance de revisión
Referencias y aprendizaje adicional
- AWS · Making retries safe with idempotent APIshttps://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/
- AWS · Timeouts, retries and backoff with jitterhttps://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/
- AWS · Transactional outboxhttps://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/transactional-outbox.html
- LangGraph · Fault tolerancehttps://docs.langchain.com/oss/python/langgraph/fault-tolerance
- LangGraph · Persistencehttps://docs.langchain.com/oss/python/langgraph/persistence
- Stripe · Idempotent requestshttps://docs.stripe.com/api/idempotent_requests
- gRPC · Deadlineshttps://grpc.io/docs/guides/deadlines/