langchain-ai/langgraph-human-in-the-loop

¿Qué hace langgraph-human-in-the-loop?

INVOCA ESTA HABILIDAD al implementar patrones de intervención humana, pausas para aprobación o manejo de errores en LangGraph. Cubre interrupt(), Command(resume=...), flujos de aprobación/validación y la estrategia de manejo de errores en 4 niveles.

Visión General

Los patrones de humano en el bucle (HITL) permiten que un humano revise, apruebe, modifique o rechace la salida de un nodo del grafo antes de que esta continúe su ejecución. Esto es crítico para aplicaciones donde la corrección, seguridad o cumplimiento normativo son prioritarios.

Funciones Clave

interrupt()

La función interrupt() se usa dentro de un nodo de LangGraph para pausar el grafo en un punto específico. Espera un valor que será presentado al humano (por ejemplo, un mensaje de revisión). El grafo se detiene hasta que se proporcione una reanudación.

from langgraph.types import interrupt

def nodo_revision_por_humano(state):
    # Pausa para que el humano revise el estado actual
    respuesta = interrupt({
        "pregunta": "¿Estás de acuerdo con este paso?",
        "datos": state["datos_propuestos"]
    })
    # respuesta contiene lo que el humano decida
    return {"aprobado": respuesta["aprobado"]}

Command(resume=...)

Command es una clase que permite reanudar un grafo pausado, proporcionando los datos necesarios. Se usa desde fuera del grafo (por ejemplo, desde una API o interfaz de usuario).

from langgraph.types import Command

# Reanuda el grafo con aprobación
command = Command(resume={"aprobado": True})
# Luego se pasa al método apropiado del grafo (ej. `graph.invoke` con command)

Flujos de Aprobación y Validación

• Aprobación Simple: Pausa con interrupt(), espera una respuesta booleana o un conjunto de opciones, y reanuda con Command(resume=...).
• Validación Compleja: El humano puede modificar los datos antes de reanudar. El grafo recibe los datos modificados y continúa con la versión aprobada.
• Rechazo con Retroalimentación: El humano proporciona retroalimentación sobre por qué se rechazó un paso, que el grafo puede usar para corregir el enfoque.

Estrategia de Manejo de Errores en 4 Niveles

1. Reintento Automático: Si un nodo falla, se reintenta automáticamente un número configurable de veces antes de escalar.
2. Degradación Elegante: El nodo puede devolver un valor predeterminado o un estado de error conocido, permitiendo que el grafo continúe con datos incompletos pero seguros.
3. Pausa para Revisión Humana: Si el reintento falla, el grafo pausa usando interrupt() y espera instrucciones del humano (por ejemplo, aprobar un valor alternativo, proporcionar datos correctos o abortar).
4. Aborto con Registro: Si el humano no responde o elige abortar, el grafo se detiene y registra el error para depuración posterior.

Plataformas Soportadas

• LangGraph (Python y JavaScript/TypeScript) - Las funciones interrupt() y Command están disponibles en ambas versiones.
• LangGraph Cloud - Soporte nativo para HITL mediante endpoints de API.
• LangGraph Studio - Interfaz visual para depurar y probar flujos HITL.

Ejemplos de Uso

Ejemplo 1: Aprobación de Transacción Financiera

from langgraph.graph import StateGraph
from langgraph.types import interrupt, Command

def nodo_verificacion(state):
    # Simula verificación automática (ej. detección de fraude)
    if state["monto"] > 1000:
        respuesta = interrupt({
            "tipo": "aprobacion_transaccion",
            "monto": state["monto"],
            "destinatario": state["destinatario"]
        })
        return {"aprobado": respuesta["aprobado"]}
    return {"aprobado": True}

graph = StateGraph(estado_aprobacion)
graph.add_node("verificar", nodo_verificacion)
# ... configurar aristas y compilar

Ejemplo 2: Corrección de Datos por Humano

# Supongamos que el grafo detectó una dirección inválida
def nodo_correccion_direccion(state):
    respuesta = interrupt({
        "tipo": "correccion_direccion",
        "direccion_original": state["direccion"],
        "sugerencias": ["Calle Falsa 123", "Av. Siempre Viva 742"]
    })
    # El humano puede elegir una sugerencia o escribir una nueva
    return {"direccion_corregida": respuesta.get("direccion", state["direccion"])}

Mejores Prácticas

• Mensajes Claros: Proporciona suficiente contexto en interrupt() para que el humano tome decisiones informadas.
• Tiempo de Espera: Considera implementar un tiempo de espera en el lado de la aplicación para evitar grafos pausados indefinidamente.
• Registro: Siempre registra la decisión del humano (aprobación, rechazo, modificación) para auditoría.
• Validación de Entrada: Valida los datos recibidos en resume para evitar datos maliciosos o corruptos.

Recursos Adicionales

• Documentación oficial de LangGraph: Human-in-the-loop
• Guía de uso: Cómo usar HITL en LangGraph
• Ejemplos en el repositorio de LangChain: langgraph/examples/human_in_the_loop