GuidesOneMux

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.

AI

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:

  1. Reintentar solo los errores que probablemente sean transitorios.
  2. Detenerse tras un número reducido y explícito de intentos.
  3. Pasar el trabajo agotado o ambiguo a un estado de recuperación.
  4. 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. InMemorySaver es adecuado para pruebas; la documentación de LangGraph recomienda un checkpointer persistente, como AsyncPostgresSaver o MongoDBSaver, para producción.
  • Un thread_id estable 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 falloAcción automáticaAcción de recuperación
Tiempo de espera agotado por una interrupción temporal de redReintentar dentro del límiteEscalar con el ID de la operación
Límite de solicitudesReintentar según las indicaciones del proveedorPoner en cola o aplazar el flujo de trabajo
Argumentos no válidosNo reintentarDevolver un error de validación al agente
Fallo de permisosNo reintentarSolicitar autorización o detenerse
Resultado desconocido tras agotarse el tiempo de esperaNo repetir a ciegasConsultar 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:

  1. El modelo propone una llamada a una herramienta.
  2. La política comprueba si hace falta una revisión.
  3. Una persona revisora aprueba, edita o rechaza la llamada.
  4. La herramienta se ejecuta con su propia política de reintentos limitados.
  5. 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 when basados 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