
Ejecución durable para agentes de IA: arquitectura y manejo de fallos
Un agente de IA que funciona en una demo suele fallar en producción por una razón poco glamorosa: el proceso que lo ejecuta muere a mitad de camino. Un deploy reinicia el contenedor, la API del modelo da timeout, una llamada a una herramienta se cuelga o una persona tarda dos días en aprobar un reembolso. Si el progreso del agente vive solo en memoria, pierdes la ejecución o, peor, la reintentas y repites efectos secundarios. La ejecución durable para agentes de IA es la respuesta de ingeniería a ese problema: cada paso del ciclo del agente queda registrado para que una ejecución pueda reanudarse exactamente donde se detuvo. Este artículo explica cómo diseñarla: el modelo de datos, el ciclo de pasos, los efectos secundarios, las aprobaciones humanas y las ventajas y desventajas de construirla tú mismo, usar el checkpointer de un framework o adoptar un motor de workflows.
Si todavía estás definiendo qué deberían hacer los agentes en tu empresa y cómo implementarlos, empieza por nuestra guía de 7 pasos sobre agentes de IA para empresas. Este texto da esa decisión por tomada y se enfoca en el sistema que hay debajo.
Por qué las ejecuciones de un agente fallan distinto a una petición normal
Una petición web típica es corta, casi determinista y fácil de reintentar. Una ejecución de agente no es nada de eso:
- Es larga. Una ejecución puede incluir varias llamadas al modelo y a herramientas, y pausarse minutos o días esperando a una persona.
- No es determinista. Llamar al modelo otra vez con la misma entrada puede producir un plan distinto. No puedes simplemente volver a empezar y esperar el mismo camino.
- Tiene efectos secundarios. Las herramientas envían correos, crean facturas, actualizan un registro del CRM o emiten reembolsos. Repetirlos es un problema de negocio, no solo técnico.
- Depende de servicios inestables. Los proveedores de modelos limitan la tasa de peticiones y dan timeout, y las APIs internas se caen.
El propio planteamiento de Temporal es útil aquí: al anunciar su integración con el OpenAI Agents SDK, afirma sin rodeos que "AI agents are distributed systems" (los agentes de IA son sistemas distribuidos). Trátalos como tales: asume que cualquier paso puede fallar y diseña para que un fallo cueste un reintento, no una ejecución perdida.
Qué significa realmente la ejecución durable para agentes de IA
La idea central es dividir el agente en dos tipos de código:
- Orquestación: el ciclo que decide qué sigue (llamar al modelo, ejecutar una herramienta, esperar una aprobación, terminar). Este código debe poder repetirse (replay).
- Pasos: el trabajo con mucha E/S, como peticiones al modelo, llamadas a herramientas y APIs externas. El resultado de cada paso se guarda en cuanto termina.
Cuando el proceso se cae, un nuevo worker carga el historial de la ejecución, repite la orquestación usando los resultados registrados en lugar de volver a llamar al modelo y continúa desde el primer paso que nunca terminó. La documentación de Pydantic AI describe la misma división en su integración con Temporal: las peticiones al modelo, las llamadas a herramientas que requieren E/S y la comunicación con servidores MCP se delegan a activities de Temporal, mientras la lógica que coordina al agente corre en el workflow.
Esa regla, "nunca rehacer un paso cuyo resultado ya está registrado", es lo que evita que un modelo no determinista tome otro camino después de un reinicio.
El modelo de datos si lo construyes tú
No necesitas un motor de workflows para obtener la mayor parte del beneficio. Una base de datos relacional y un ciclo de pasos estricto llegan lejos. Un esquema mínimo:
CREATE TABLE agent_runs (
id UUID PRIMARY KEY,
agent_name TEXT NOT NULL,
status TEXT NOT NULL, -- running | waiting_approval | completed | failed | cancelled
input JSONB NOT NULL,
lease_owner TEXT, -- worker que ejecuta la corrida en este momento
lease_expires TIMESTAMPTZ,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE TABLE agent_steps (
run_id UUID NOT NULL REFERENCES agent_runs(id),
step_index INT NOT NULL,
kind TEXT NOT NULL, -- model_call | tool_call | approval | final
request JSONB NOT NULL, -- prompt o nombre de herramienta + argumentos validados
result JSONB, -- null hasta que el paso termina
status TEXT NOT NULL, -- pending | completed | failed
attempts INT NOT NULL DEFAULT 0,
idempotency_key TEXT NOT NULL UNIQUE,
PRIMARY KEY (run_id, step_index)
);
CREATE TABLE agent_approvals (
run_id UUID NOT NULL,
step_index INT NOT NULL,
decision TEXT, -- approved | rejected | edited
edited_args JSONB,
decided_by TEXT,
decided_at TIMESTAMPTZ,
PRIMARY KEY (run_id, step_index)
);
Tres decisiones de diseño importan más que las columnas exactas:
- Los pasos son solo de inserción y están ordenados. El par
(run_id, step_index)es la identidad del paso. Repetir una ejecución significa recorrer esas filas en orden. - La clave de idempotencia se deriva, no es aleatoria. Usa algo como
run_id:step_index. Si un worker se cae después de llamar a una herramienta pero antes de guardar el resultado, el reintento envía la misma clave y una API bien diseñada puede descartar el duplicado. - Un lease impide que dos workers ejecuten la misma corrida. Un worker reclama la ejecución fijando
lease_ownerylease_expirescon un update condicional, y renueva el lease mientras trabaja. Si muere, el lease expira y otro worker la retoma.
El ciclo de pasos
En el ciclo de orquestación es donde vive la corrección. En pseudocódigo:
def execute_run(run_id, worker_id):
if not claim_lease(run_id, worker_id):
return # otro worker es dueño de la ejecución
history = load_completed_steps(run_id) # lista ordenada
messages = rebuild_messages(history)
step_index = len(history)
while True:
# 1. Preguntar al modelo qué hacer (paso registrado)
decision = run_step(run_id, step_index, "model_call",
request={"messages": messages},
fn=lambda: call_model(messages, tools=ALLOWED_TOOLS))
step_index += 1
if decision.type == "final":
mark_run(run_id, "completed", output=decision.content)
return
# 2. Validar argumentos antes de ejecutar nada
tool = TOOLS[decision.tool_name]
args = tool.schema.validate(decision.arguments)
# 3. Pausar para una persona si la herramienta es sensible
if tool.requires_approval:
approval = get_approval(run_id, step_index)
if approval is None:
request_approval(run_id, step_index, tool.name, args)
mark_run(run_id, "waiting_approval")
release_lease(run_id)
return # el proceso termina; nada queda en memoria
if approval.decision == "rejected":
messages.append(tool_rejected_message(tool.name))
step_index += 1
continue
args = approval.edited_args or args
# 4. Ejecutar la herramienta una sola vez por paso (paso registrado)
result = run_step(run_id, step_index, "tool_call",
request={"tool": tool.name, "args": args},
fn=lambda: tool.execute(args,
idempotency_key=f"{run_id}:{step_index}"))
messages.append(tool_result_message(tool.name, result))
step_index += 1
def run_step(run_id, step_index, kind, request, fn):
existing = get_step(run_id, step_index)
if existing and existing.status == "completed":
return existing.result # replay: nunca volver a llamar al modelo o la herramienta
upsert_pending_step(run_id, step_index, kind, request)
result = with_retries(fn, max_attempts=3, backoff="exponential")
complete_step(run_id, step_index, result)
return result
Fíjate en lo que el ciclo nunca hace: nunca guarda estado que exista solo en memoria y nunca vuelve a ejecutar un paso terminado. Esperar a una persona no es un hilo dormido; es un estado en la base de datos. Cuando llega la aprobación, un webhook o un mensaje en cola vuelve a disparar execute_run y el ciclo se repite hasta llegar al mismo punto.
Efectos secundarios: la parte que de verdad duele
La ejecución durable garantiza que tu orquestación se reanude correctamente. No puede garantizar que un sistema externo no haya recibido una petición cuya respuesta nunca guardaste. Ese hueco es el origen de los correos duplicados y los reembolsos dobles. Ciérralo con tres patrones:
- Claves de idempotencia en cada herramienta de escritura. Pasa la clave derivada a las APIs que la soporten. En tus propios servicios, guarda las claves procesadas y devuelve el resultado original cuando una clave se repite.
- Outbox transaccional para efectos internos. Cuando una herramienta escribe en tu base de datos y publica un evento, guarda el registro y el mensaje saliente en la misma transacción, y deja que un proceso aparte entregue el mensaje.
- Compensación para lo que no puede ser idempotente. Si una herramienta no deduplica, diseña una acción inversa (cancelar el pedido, anular la factura) y registra qué pasos la necesitan si la ejecución se abandona.
Clasifica cada herramienta como solo lectura, escritura idempotente o escritura no idempotente antes de dársela a un agente. Las de solo lectura pueden reintentarse libremente. Las escrituras no idempotentes normalmente deberían requerir aprobación o estar envueltas en un servicio que controles.
Aprobaciones humanas como esperas durables
Las aprobaciones son la razón más clara por la que la persistencia es obligatoria y no opcional. La documentación de LangChain sobre su middleware de human-in-the-loop indica que debes configurar un checkpointer para persistir el estado del grafo entre interrupciones, y recomienda un checkpointer persistente como AsyncPostgresSaver o MongoDBSaver en producción, dejando InMemorySaver para pruebas.
Sea cual sea tu stack, diseña el registro de aprobación con cuidado:
- Muestra a quien revisa los argumentos exactos ya validados, no la prosa del modelo sobre ellos.
- Permite tres resultados: aprobar, rechazar con un motivo que el agente pueda leer o editar los argumentos.
- Registra quién decidió y cuándo. Esa es tu pista de auditoría.
- Define una expiración. Una ejecución que esperó demasiado debe fallar limpiamente en lugar de actuar sobre datos viejos.
Construir, framework o motor de workflows: las ventajas y desventajas
Hay tres enfoques realistas, y el correcto depende de cuánto duran tus ejecuciones y cuánta infraestructura quieres operar.
1. Hacerlo tú mismo sobre Postgres
Conviene para: pocos agentes, ejecuciones cortas o medianas, equipos que ya operan Postgres y una cola. Ventajas: control total, sin infraestructura nueva, el modelo de datos se ajusta a tu dominio. Desventajas: eres responsable de leases, reintentos, temporizadores y lógica de replay, y los errores sutiles ahí son difíciles de encontrar.
2. Checkpointers de framework (por ejemplo, LangGraph)
Conviene para: equipos que ya construyen sobre ese framework. La documentación de LangGraph explica que los checkpointers guardan el estado para que una persona pueda inspeccionar, interrumpir y aprobar pasos del grafo y el grafo pueda reanudarse después. También ofrecen modos de durabilidad; en el modo "exit", los cambios se persisten solo cuando la ejecución del grafo termina, ya sea con éxito, con error o en una interrupción. Es más barato, pero una caída a mitad de la ejecución puede perder el progreso desde la última salida, así que elige el modo según la carga de trabajo. Desventajas: la durabilidad se limita al grafo del framework; los efectos secundarios dentro de las herramientas siguen siendo tu responsabilidad.
3. Un motor de ejecución durable (por ejemplo, Temporal)
Conviene para: workflows largos, de alto valor o con varios agentes. El tutorial de Temporal sobre agentes durables señala que los workflows preservan el contexto ante interrupciones del sistema y que la duración de la ejecución del workflow es irrelevante. Temporal ofrece integraciones con el OpenAI Agents SDK (anunciada en vista previa pública) y con el AI SDK de Vercel. Desventajas: otro sistema que operar o pagar, y el código del workflow debe seguir las reglas de determinismo del motor, lo que requiere acostumbrarse.
Un camino pragmático: empieza con el enfoque 1 o 2 para un solo agente bien acotado y pasa a un motor cuando tengas esperas largas, muchas ejecuciones concurrentes o workflows entre varios servicios.
Controles de seguridad y costo que pertenecen a la arquitectura
La durabilidad hace a los agentes resistentes; también los hace persistentes, lo que sube el costo de una mala acción. Integra estos controles en el ciclo, no en el prompt:
- Lista de herramientas permitidas por agente y por ejecución. El modelo solo puede llamar lo que contiene
ALLOWED_TOOLS. - Valida argumentos con un esquema antes de ejecutar y antes de pedir aprobación. Rechaza, no corrijas a la fuerza.
- Usa credenciales acotadas. Cada herramienta corre con los permisos mínimos que necesita, nunca con un token de administrador compartido.
- Define presupuestos. Limita el número de pasos, tokens del modelo y tiempo total por ejecución, y haz fallar la ejecución cuando los supere.
- Mantén los payloads grandes fuera de la tabla de pasos. Guarda documentos y salidas largas de herramientas en almacenamiento de objetos y registra una referencia, para que el replay sea rápido y los checkpoints pequeños.
Errores comunes
- Mantener el estado de la conversación en la memoria del proceso "por ahora".
- Reintentar toda la ejecución desde el inicio tras un fallo, lo que vuelve a llamar al modelo y puede tomar otro camino.
- Generar una clave de idempotencia aleatoria en cada intento, lo que anula su propósito.
- Tratar la aprobación como una llamada bloqueante dentro de una petición web.
- Dejar que las herramientas decidan sus propios permisos en lugar de imponerlos desde el orquestador.
- Registrar solo la respuesta final, de modo que no puedes explicar cómo llegó a ella una ejecución.
Checklist de implementación
- Cada ejecución tiene un ID persistente y un estado.
- Cada llamada al modelo y a herramientas es un paso registrado y ordenado.
- Los pasos terminados nunca se vuelven a ejecutar en el replay.
- Las claves de idempotencia se derivan de la ejecución y el paso, y se envían a los sistemas externos.
- Cada herramienta está clasificada como solo lectura, escritura idempotente o escritura no idempotente.
- Las herramientas sensibles requieren aprobación, con expiración y registro de auditoría.
- Un lease o un motor garantiza un solo worker activo por ejecución.
- Los reintentos usan backoff y un número máximo de intentos.
- Los presupuestos de pasos, tokens y tiempo se imponen en código.
- Los payloads grandes viven fuera del almacén de checkpoints.
Si necesitas esta base dentro de tu propio producto, con tu modelo de datos y tus sistemas, ese es el trabajo que hace nuestro equipo de desarrollo de software a la medida.
Preguntas frecuentes
¿Necesito Temporal para que un agente de IA sea durable?
No. Una base de datos con una tabla de pasos ordenada, claves de idempotencia derivadas y un lease por ejecución cubre muchos casos. Un motor vale la pena cuando las ejecuciones son largas, numerosas o abarcan varios servicios.
¿Un checkpointer de framework es lo mismo que ejecución durable?
Cubre una parte: guardar y reanudar el estado del agente, que es lo que necesitan las aprobaciones humanas. No hace seguros los efectos secundarios dentro de tus herramientas; la idempotencia y la compensación siguen siendo tu trabajo.
¿Cómo evito que un agente reanudado repita una acción?
Nunca vuelvas a ejecutar un paso terminado y envía una clave de idempotencia determinista con cada escritura, para que el sistema externo pueda ignorar duplicados cuando la caída ocurrió entre la llamada y el guardado.
Comentarios
Todavía no hay comentarios. Sé el primero en compartir lo que piensas.


