El human-in-the-loop es el patrón que deja a una persona dentro del bucle de decisión de un agente de IA para aprobar, corregir o detener sus acciones antes de que ocurran. En esta guía verás qué significa exactamente, qué acciones deben pasar por un punto de aprobación, cómo se interrumpe y se reanuda un agente sin perder el estado con LangGraph y el Agents SDK de OpenAI, cómo diseñar la interfaz de confirmación y cuándo conviene exigir supervisión. Es un patrón de fiabilidad, no un freno: se trata de ajustar el control al riesgo de cada tarea. La misma explicación está disponible en inglés.

Puntos clave

  • El human-in-the-loop (HITL) inserta una decisión humana en el bucle del agente: el agente propone una acción, se detiene y solo continúa cuando una persona la aprueba, la edita o la rechaza.
  • Se reserva para acciones irreversibles o de alto riesgo: enviar dinero, borrar datos, publicar contenido o escribir en sistemas de producción. Las tareas de bajo riesgo corren solas.
  • Técnicamente son dos cosas: una interrupción que pausa la ejecución y una persistencia de estado que permite reanudar justo donde se quedó, incluso días después.
  • LangGraph lo resuelve con la función interrupt() y un checkpointer; el Agents SDK de OpenAI con needs_approval y la lista RunResult.interruptions.
  • El objetivo no es frenar al agente, sino ajustar la supervisión al riesgo: cuanto más peligrosa o difícil de deshacer sea la acción, más justificado está el punto de aprobación.

¿Qué es el human-in-the-loop en un agente?

Un agente de IA trabaja en un bucle: el modelo razona, elige una herramienta, la ejecuta, observa el resultado y decide el siguiente paso. El human-in-the-loop introduce un tercer actor en ese bucle, una persona, con capacidad de veto. En lugar de ejecutar cada acción de forma automática, el agente marca ciertos pasos como sujetos a revisión: se detiene, muestra lo que pretende hacer y espera una respuesta antes de continuar.

La guía de referencia sobre el tema es Building Effective Agents de Anthropic, publicada en diciembre de 2024. En ella se recomienda diseñar el sistema para que, en sus palabras, "los agentes puedan detenerse a esperar una respuesta humana en puntos de control o cuando encuentran un obstáculo". La misma guía insiste en incluir "condiciones de parada (como un número máximo de iteraciones) para mantener el control". La idea central es que la autonomía es lo que hace útil a un agente, pero el humano conserva el control sobre cómo se persiguen sus objetivos, sobre todo antes de una decisión de alto impacto.

Conviene distinguir el HITL de otras salvaguardas. Un guardrail filtra entradas o salidas de forma automática; la observabilidad registra lo que pasó para revisarlo después. El human-in-the-loop es distinto: bloquea la acción en tiempo real y cede la decisión a una persona antes de que el efecto se produzca.

¿Qué acciones deben pasar por un punto de aprobación?

No todo merece una interrupción. Si el agente pide aprobación para cada búsqueda o cada lectura de un archivo, la supervisión se vuelve insufrible y la persona acaba aprobando sin mirar. La regla práctica es sencilla: exige confirmación cuando la acción sea difícil o imposible de deshacer, y deja correr el resto.

Estos son los candidatos habituales a un punto de aprobación:

  • Movimientos de dinero: pagos, transferencias, reembolsos o cualquier transacción financiera.
  • Escrituras destructivas: borrar registros, sobrescribir archivos, ejecutar un DROP TABLE o desplegar en producción.
  • Comunicación externa: enviar un correo, publicar en redes o abrir una incidencia a nombre de tu empresa.
  • Acciones caras o irreversibles: aprovisionar infraestructura, comprar recursos o llamar a una API con coste por uso elevado.

Las operaciones de solo lectura (consultar una base de datos, buscar en la web, resumir un documento) rara vez necesitan aprobación. Anthropic lo resume bien: la meta no es ralentizar por ralentizar, sino ajustar el nivel de supervisión al riesgo de la tarea. Las de bajo riesgo se ejecutan solas; las de alto riesgo esperan una aprobación manual.

¿Cómo se interrumpe y se reanuda un agente sin perder el estado?

Aquí está el reto técnico. Pausar un programa es fácil; pausarlo y poder retomarlo horas o días después, en el punto exacto y con todo su estado, no lo es. Por eso el human-in-the-loop necesita dos piezas: una interrupción y un almacenamiento de estado persistente (un checkpointer).

En LangGraph, la función interrupt() pausa el grafo dentro de un nodo y devuelve al cliente el valor que quieras mostrar para la revisión. La versión estable en PyPI es la 1.2.9 (2026). Necesita un checkpointer que guarde el estado y un thread_id que identifique la conversación:

from langgraph.types import interrupt, Command

def revisar_envio(state):
    decision = interrupt({
        "accion": "enviar_email",
        "para": state["destinatario"],
        "asunto": state["asunto"],
    })
    if decision == "aprobar":
        return {"estado": "enviado"}
    return {"estado": "cancelado"}

Cuando el nodo llama a interrupt(), LangGraph lanza una excepción controlada, guarda la instantánea completa del estado y detiene la ejecución. Para reanudar, el cliente vuelve a invocar el grafo con Command(resume=...), y ese valor se convierte en lo que devuelve interrupt() dentro del nodo:

grafo.invoke(
    Command(resume="aprobar"),
    config={"configurable": {"thread_id": "hilo-42"}},
)

El detalle importante es que el nodo se re-ejecuta desde el principio al reanudar, así que conviene no poner efectos secundarios antes del interrupt(). Este mecanismo sustituyó a los antiguos breakpoints interrupt_before e interrupt_after, que solo permitían pausar entre nodos.

El Agents SDK de OpenAI lo aborda desde la herramienta. Marcas una función con needs_approval=True (o una función asíncrona que decide caso por caso) y, cuando el agente quiere invocarla, la ejecución se pausa y la llamada pendiente aparece en RunResult.interruptions como un ToolApprovalItem:

from agents import Agent, Runner, function_tool

@function_tool(needs_approval=True)
def borrar_registro(id: int) -> str:
    return f"registro {id} borrado"

result = await Runner.run(agente, "borra el registro 42")
for item in result.interruptions:
    state = result.to_state()
    state.approve(item)   # o state.reject(item)
result = await Runner.run(agente, state)

La opción needs_approval está disponible en cinco tipos de herramienta: function_tool, Agent.as_tool, ShellTool, ApplyPatchTool y las herramientas MCP, tanto locales como remotas. Capturas el estado con to_state(), apruebas o rechazas cada elemento y reanudas pasando ese estado a Runner.run(). Un detalle a tener en cuenta: los runs pausados esperan de forma indefinida, sin timeout, escalado ni auditoría integrados. Eso lo pones tú.

¿Cómo se diseña la interfaz de aprobación?

La interrupción es la mitad del trabajo; la otra mitad es qué ve la persona que aprueba. Una buena pantalla de aprobación tiene que responder tres preguntas de un vistazo: qué va a hacer el agente, con qué datos y por qué. Mostrar solo "¿Aprobar la acción?" obliga a confiar a ciegas.

Algunas prácticas que funcionan:

  • Enseña la acción concreta y sus argumentos: no "enviar correo", sino el destinatario, el asunto y el cuerpo exactos que se enviarán.
  • Ofrece más de dos salidas: además de aprobar y rechazar, permite editar la propuesta (corregir el importe, cambiar el destinatario) antes de continuar. LangGraph devuelve el valor editado como resultado del interrupt().
  • Da contexto del porqué: incluye el razonamiento del agente o los pasos previos, para que la persona juzgue con información.
  • Registra la decisión: guarda quién aprobó qué y cuándo. Es la base de una auditoría y de la mejora del agente con el tiempo.

Como los runs pueden quedar pausados mucho tiempo, la aprobación suele ser asíncrona: el estado se persiste, la persona recibe un aviso (un mensaje, un correo, una tarjeta en una cola de revisión) y la reanudación ocurre cuando responde, quizá desde otro dispositivo. Ese patrón encaja de forma natural con un agente desplegado en producción, donde las peticiones de aprobación van a una cola y un operador las resuelve a su ritmo.

¿Cuándo conviene exigir supervisión humana?

La respuesta corta: siempre que el coste de un error supere el coste de la espera. La respuesta larga depende de tres factores.

El primero es la reversibilidad. Una acción que puedes deshacer con un clic (renombrar un borrador) tolera la autonomía; una que no (cursar un pago, borrar una cuenta) pide aprobación. El segundo es la madurez del agente: un sistema nuevo, sin historial de fiabilidad, merece más puntos de control que uno que lleva meses acertando en un dominio acotado. Puedes empezar con supervisión estricta e ir relajándola a medida que mides los resultados. El tercero es el marco regulatorio: en sanidad, banca o decisiones legales, la supervisión humana no es opcional.

También existe la vía intermedia de las condiciones de parada automáticas que menciona Anthropic: limitar el número de iteraciones, el gasto máximo o el tiempo total, de modo que el agente se detenga y pida ayuda al superar un umbral aunque nadie lo estuviera vigilando. Combinar puntos de aprobación explícitos con estos límites da un control razonable sin convertir a la persona en un cuello de botella permanente. Frameworks de flujos como LangGraph integran ambos mecanismos en el mismo grafo.

Preguntas frecuentes

¿Human-in-the-loop es lo mismo que un guardrail?

No. Un guardrail es una comprobación automática que filtra entradas o salidas (bloquea un prompt malicioso o una respuesta tóxica) sin intervención humana. El human-in-the-loop cede la decisión a una persona en tiempo real antes de ejecutar una acción concreta. Se complementan: el guardrail atrapa lo evidente de forma automática y el HITL reserva el criterio humano para lo ambiguo o irreversible.

¿No hace esto que el agente sea inútilmente lento?

Solo si abusas de los puntos de aprobación. Si pides confirmación para cada lectura, sí; si la reservas para las acciones irreversibles, el coste es mínimo frente al de un error grave. La clave es ajustar la supervisión al riesgo: dejar correr las tareas de bajo impacto y detener solo las peligrosas. Un agente bien diseñado pide aprobación pocas veces, pero en los momentos que importan.

¿Puedo aprobar acciones horas después de que el agente las proponga?

Sí, si el framework persiste el estado. Tanto LangGraph (con su checkpointer y thread_id) como el Agents SDK de OpenAI (con to_state()) guardan la ejecución para reanudarla más tarde. El agente no consume recursos mientras espera. Eso sí, tú debes añadir el aviso, el timeout y el escalado: las herramientas pausan el run, pero no avisan a nadie por su cuenta.

Conclusión

El human-in-the-loop es lo que convierte a un agente autónomo en un sistema en el que puedes confiar para tareas serias. La receta es clara: identifica las acciones irreversibles, márcalas para revisión con interrupt() en LangGraph o needs_approval en el Agents SDK, persiste el estado para poder reanudar, y diseña una pantalla de aprobación que muestre la acción, sus datos y su porqué. Ajusta la supervisión al riesgo y relájala a medida que el agente demuestra fiabilidad. El siguiente paso es añadir un único punto de aprobación a tu agente sobre su acción más peligrosa y comprobar el flujo de interrupción y reanudación de principio a fin.

Fuentes: [1] Interrupts en la documentación de LangGraph[1], [2] Human-in-the-loop en el Agents SDK de OpenAI[2], [3] Building Effective Agents de Anthropic[3], [4] Paquete langgraph en PyPI[4].

Visitas: 0

Fuentes

  1. Interrupts en la documentación de LangGraph
  2. Human-in-the-loop en el Agents SDK de OpenAI
  3. Building Effective Agents de Anthropic
  4. Paquete langgraph en PyPI

Ruta: Fundamentos de los agentes de IA