Llamadas a herramientas en LangGraph con ejecución limitada y recuperación ante fallos
Crea un agente de operaciones de producción con LangGraph que use llamadas a herramientas, límites de reintentos, aprobación humana y rutas de recuperación explícitas en lugar de una ejecución sin límites.
Resumen · TL;DR
No se debe permitir que un agente de operaciones de producción reintente indefinidamente ni que repita efectos secundarios a ciegas. LangGraph ofrece el modelo de grafos y persistencia para pausar la ejecución, mientras que el flujo de trabajo debe definir límites de reintentos, reglas de idempotencia, vías de escalamiento y estados de recuperación. HumanInTheLoopMiddleware puede controlar llamadas de herramientas de riesgo y reanudarlas desde un punto de control tras una aprobación, edición, rechazo o respuesta directa.
Puntos clave
- Distingue los fallos transitorios de los permanentes antes de decidir si reintentar.
- Limita la ejecución con un presupuesto de reintentos por herramienta y un límite de pasos para el grafo.
- Usa claves de idempotencia en las herramientas que crean, eliminan o modifican recursos de producción.
- Exige aprobación humana para acciones destructivas o visibles externamente.
- Persiste el estado del grafo para que un flujo de trabajo interrumpido pueda reanudarse sin empezar de cero.
En esta página (9)
La decisión de diseño: ¿reintentar automáticamente o recuperarse de forma deliberada?
En las operaciones de flujos de trabajo de producción, la opción predeterminada más segura no es «reintentar ante cualquier fallo». Es:
- Reintentar solo los errores que probablemente sean transitorios.
- Detenerse tras un número reducido y explícito de intentos.
- Pasar el trabajo agotado o ambiguo a un estado de recuperación.
- Exigir aprobación antes de los efectos secundarios que podrían ser costosos o irreversibles.
LangGraph encaja bien porque permite representar estos resultados como estados del grafo, en lugar de ocultarlos en un único bucle extenso del agente. El modelo puede proponer llamadas a herramientas, pero el código determinista decide si una llamada es segura para ejecutar, reintentar, escalar u omitir.
Los ejemplos siguientes son patrones ilustrativos. No constituyen una aplicación probada y las API exactas pueden variar según las versiones instaladas de LangGraph y LangChain.
Requisitos previos
Necesitas:
- Python y paquetes compatibles de LangGraph y LangChain.
- Un modelo de chat que admita llamadas a herramientas mediante la integración elegida.
- Herramientas con esquemas de entrada explícitos y tipos de error predecibles.
- Un checkpointer.
InMemorySaveres adecuado para pruebas; la documentación de LangGraph recomienda un checkpointer persistente, comoAsyncPostgresSaveroMongoDBSaver, para producción. - Un
thread_idestable para cada ejecución del flujo de trabajo.
No des al modelo acceso irrestricto a credenciales de producción. Implementa la autorización, la validación, la idempotencia y las políticas de reintento dentro de las herramientas o del middleware.
Define una herramienta con reintentos limitados
El primer límite debe aplicarse a la propia operación. Este ejemplo solo reintenta los errores transitorios clasificados y devuelve un resultado estructurado cuando se agota el presupuesto.
from dataclasses import dataclass
from typing import Literal
class TransientOperationError(Exception):
pass
class PermanentOperationError(Exception):
pass
@dataclass
class OperationResult:
status: Literal["succeeded", "needs_recovery", "failed"]
attempts: int
message: str
def run_with_budget(operation, *, max_attempts: int) -> OperationResult:
for attempt in range(1, max_attempts + 1):
try:
operation()
return OperationResult("succeeded", attempt, "Operation completed")
except PermanentOperationError as exc:
return OperationResult("failed", attempt, str(exc))
except TransientOperationError as exc:
if attempt == max_attempts:
return OperationResult(
"needs_recovery", attempt,
f"Retry budget exhausted: {exc}",
)
return OperationResult("needs_recovery", max_attempts, "No attempt was made")
En operaciones reales, añade una clave de idempotencia antes de reintentar. Un tiempo de espera agotado tras una solicitud de despliegue no demuestra que el despliegue no se haya realizado. Reintentar sin una clave podría crear un trabajo, ticket, pago o solicitud de cambio duplicados.
Una tabla de políticas útil sería la siguiente:
| Tipo de fallo | Acción automática | Acción de recuperación |
|---|---|---|
| Tiempo de espera agotado por una interrupción temporal de red | Reintentar dentro del límite | Escalar con el ID de la operación |
| Límite de solicitudes | Reintentar según las indicaciones del proveedor | Poner en cola o aplazar el flujo de trabajo |
| Argumentos no válidos | No reintentar | Devolver un error de validación al agente |
| Fallo de permisos | No reintentar | Solicitar autorización o detenerse |
| Resultado desconocido tras agotarse el tiempo de espera | No repetir a ciegas | Consultar el estado mediante la clave de idempotencia |
Añade llamadas a herramientas y aprobación humana
create_agent de LangChain utiliza LangGraph para la ejecución subyacente. La documentación de LangGraph proporcionada describe HumanInTheLoopMiddleware, que puede interrumpir llamadas seleccionadas a herramientas y reanudarlas desde el estado persistido.
from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver
agent = create_agent(
model="provider:model-name",
tools=[inspect_job, restart_job, delete_artifact],
middleware=[
HumanInTheLoopMiddleware(
interrupt_on={
"inspect_job": False,
"restart_job": {
"allowed_decisions": ["approve", "reject"]
},
"delete_artifact": {
"allowed_decisions": ["approve", "edit", "reject"]
},
},
interrupt_mode="per_call",
),
],
checkpointer=InMemorySaver(),
)
En este caso, la inspección se ejecuta sin revisión, mientras que el reinicio y la eliminación se pausan hasta recibir una decisión. approve ejecuta los argumentos originales; edit modifica los argumentos antes de la ejecución; y reject omite la llamada y devuelve al agente comentarios sobre el rechazo. La fuente también documenta respond para actuar como herramienta de «preguntar al usuario»; no debe usarse para denegar una herramienta con efectos secundarios, ya que se trata como un resultado satisfactorio de la herramienta.
En producción, sustituye el checkpointer en memoria por una implementación persistente e invoca el agente con un ID de hilo estable:
config = {
"configurable": {"thread_id": "ops-workflow-1842"}
}
result = agent.invoke(
{
"messages": [
{
"role": "user",
"content": "Inspect the failed job and restart it if safe.",
}
]
},
config=config,
version="v2",
)
Con la versión v2, un resultado interrumpido expone una colección interrupts. Presenta cada acción solicitada a una persona revisora autorizada y, después, reanuda el mismo hilo con el formato de decisión Command documentado.
Mantén los reintentos y la aprobación en el orden correcto
La documentación de la fuente destaca una regla importante sobre el middleware: al utilizar una revisión por llamada, coloca la gestión de intervención humana antes del middleware de reintentos o gestión de errores de herramientas. De lo contrario, un reintento puede hacer que se vuelva a consultar a la persona revisora, o que una respuesta no válida se reintente como si fuera un fallo de la herramienta.
La secuencia prevista es:
- El modelo propone una llamada a una herramienta.
- La política comprueba si hace falta una revisión.
- Una persona revisora aprueba, edita o rechaza la llamada.
- La herramienta se ejecuta con su propia política de reintentos limitados.
- Si tiene éxito, el resultado vuelve al agente; si se agota el límite, pasa a recuperación.
No realices efectos secundarios en middleware que vuelva a ejecutarse al reanudar una interrupción. La documentación advierte específicamente que el middleware situado antes de la capa de revisión humana debe poder ejecutarse de nuevo de forma segura hasta la pausa.
Añade un estado de recuperación en lugar de otro reintento
Cuando se agote el presupuesto de reintentos, registra un evento operativo que incluya el ID del flujo de trabajo, el nombre de la herramienta, el número de intentos, la clave de idempotencia y el último error conocido. A continuación, elige una de estas tres vías:
- Verificar: consulta el sistema externo para determinar si la operación original se realizó correctamente.
- Escalar: pausa el proceso para que una persona operadora, con contexto suficiente, decida el siguiente paso.
- Compensar: ejecuta una operación correctiva distinta, aprobada explícitamente.
No le pidas al modelo que invente una acción compensatoria a partir de un mensaje de error incompleto. Proporciónale datos de estado estructurados y limita las herramientas disponibles.
Un límite de ejecución a nivel del grafo es una segunda barrera de seguridad. Configura el límite compatible con la versión instalada de LangGraph y trata alcanzarlo como un evento de recuperación, en lugar de continuar en silencio. Así se evita que un bucle entre el modelo y las herramientas se convierta en un proceso de producción sin límites.
Lista de comprobación para la resolución de problemas
- El flujo de trabajo vuelve a empezar desde el principio: comprueba que se utilicen un checkpointer persistente y el mismo
thread_id. - La acción rechazada se ejecuta de todos modos: comprueba que la decisión de reanudación sea un rechazo, no
respond. - La persona revisora recibe demasiadas solicitudes: añade predicados
whenbasados en los argumentos para interrumpir solo las llamadas de riesgo. - Un reintento duplica el trabajo: añade idempotencia y una herramienta para consultar el estado antes de reintentar resultados inciertos.
- La misma revisión vuelve a aparecer: revisa el orden del middleware y asegúrate de que la gestión de reintentos no envuelva incorrectamente el límite de aprobación.
- Una llamada editada se comporta de forma inesperada: valida por tu cuenta los argumentos editados; el esquema de respuesta documentado describe la estructura, pero no necesariamente garantiza la seguridad operativa.
Conclusión
Un agente de operaciones fiable con LangGraph es un flujo de trabajo limitado, no un chatbot sin restricciones. Asigna a cada herramienta un presupuesto de reintentos, clasifica los fallos, persiste el estado, controla las llamadas peligrosas y convierte la recuperación en una rama explícita. Así, la aprobación humana se convierte en un punto de control gestionado del flujo de trabajo, en lugar de una solución de emergencia.
Fuentes
FAQ
¿LangGraph reintenta automáticamente todas las llamadas a herramientas que fallan?
No des por hecho que lo hace. Define explícitamente el comportamiento de los reintentos, clasifica los errores y establece un número máximo de intentos. Es posible que el middleware de reintentos de herramientas esté disponible en la pila instalada, pero debes comprobar su configuración y comportamiento en la documentación de la versión correspondiente.
¿Por qué se necesita un punto de control para la aprobación humana?
Una interrupción pausa la ejecución mientras se espera una decisión. Un checkpointer conserva el estado del grafo para que el mismo hilo del flujo de trabajo pueda reanudarse tras una aprobación, edición, rechazo o respuesta directa.
¿Cuándo debería requerir revisión humana una llamada a una herramienta?
Revisa las llamadas que modifican el estado de producción, eliminan datos, envían comunicaciones externas o implican un coste o alcance incierto. La inspección de solo lectura puede ejecutarse a menudo de forma automática si la autorización y los límites de salida están claros.
¿Qué debería ocurrir cuando se agota el presupuesto de reintentos?
Pasa a una vía de recuperación: verifica la operación externa, escala el caso a una persona operadora o ejecuta una acción compensatoria aprobada por separado. Evita repetir a ciegas una operación cuyo resultado se desconoce.
Artículos relacionados
Guides
RAG agéntico con LangGraph: llamadas a herramientas, atribución de fuentes y ejecución acotada
Crea un agente de preguntas y respuestas sobre documentos con LangGraph que decida cuándo recuperar información, evalúe el contexto, reintente búsquedas deficientes y devuelva respuestas con atribución de fuentes sin una ejecución ilimitada.
Guides
Construye un agente de LangGraph con llamadas a herramientas acotadas y revisión humana
Un patrón práctico para evaluar un agente de LangGraph que llama a herramientas con límites de pasos explícitos, aprobación humana para acciones de riesgo y casos de prueba repetibles.
Guides
Gemini 4 Hydrogen vs. Carbon para la operación de flujos de trabajo en producción
Qué indican las pruebas disponibles sobre Gemini 4 Hydrogen y Carbon para programación, tool calling, salida estructurada y flujos de trabajo recuperables en producción.
Guides
Crea un flujo de extracción de datos recuperable en n8n
Diseña un flujo de extracción en n8n que valide registros, reintente fallos transitorios y derive las excepciones a revisión humana sin duplicar escrituras.