Humano en el bucle

Humano en el bucle es el diseño en el que el agente se detiene en ciertos puntos y espera a que una persona apruebe, corrija o rechace lo que va a hacer. Se usa para las acciones con consecuencias: mover dinero, enviar mensajes en nombre de alguien, borrar datos, cambiar permisos. El modelo propone; la persona decide.

Dónde poner los puntos de aprobación

No todo necesita aprobación. Si pides permiso para cada búsqueda, el usuario aprobará sin leer y el control desaparece. Clasifica cada herramienta por su riesgo:

La política vive en tu código, asociada a cada herramienta. No la dejes en el prompt («pide permiso antes de reembolsar»): el modelo puede saltársela por error o porque un texto inyectado se lo pida. Ver Permisos y mínimo privilegio.

Cómo encaja en el bucle

La aprobación se coloca entre el tool_use del modelo y la ejecución real.

flowchart LR
  M[Modelo] -- tool_use --> P{¿Requiere aprobación?}
  P -- no --> E[Ejecutar]
  P -- sí --> H[Persona]
  H -- aprueba --> E
  H -- rechaza --> R[tool_result con is_error]
  E -- tool_result --> M
  R --> M

Cuando la persona rechaza, no cortes el bucle sin más. Devuelve un tool_result con is_error: True y el motivo. El modelo lo lee y puede proponer otra cosa, preguntar al usuario o terminar explicando que no se hizo.

REQUIERE_APROBACION = {"reembolsar", "enviar_correo"}  # la política vive en el código

def pedir_aprobacion(nombre: str, args: dict) -> tuple[bool, str]:
    """En consola. En una web, esto es un botón y el bucle espera (ver más abajo)."""
    print(f"\nEl agente quiere ejecutar {nombre} con:\n{args}")
    r = input("¿Aprobar? [s/N] o escribe un motivo de rechazo: ").strip()
    return (True, "") if r.lower() == "s" else (False, r or "Sin motivo")

def ejecutar_con_control(bloque, funciones: dict) -> dict:
    if bloque.name in REQUIERE_APROBACION:
        ok, motivo = pedir_aprobacion(bloque.name, bloque.input)
        if not ok:
            return {"type": "tool_result", "tool_use_id": bloque.id, "is_error": True,
                    "content": f"La persona rechazó la acción. Motivo: {motivo}. "
                               "No la reintentes sin preguntar antes al usuario."}
    try:
        salida = funciones[bloque.name](**bloque.input)
        return {"type": "tool_result", "tool_use_id": bloque.id, "content": str(salida)}
    except Exception as e:
        return {"type": "tool_result", "tool_use_id": bloque.id,
                "content": f"Error: {e}", "is_error": True}

import Anthropic from "@anthropic-ai/sdk";

const REQUIERE_APROBACION = new Set(["reembolsar", "enviar_correo"]);
type Aprobador = (nombre: string, args: unknown) => Promise<{ ok: boolean; motivo?: string }>;
type Funciones = Record<string, (args: any) => Promise<unknown>>;

export async function ejecutarConControl(
  b: Anthropic.ToolUseBlock, funciones: Funciones, aprobar: Aprobador,
): Promise<Anthropic.ToolResultBlockParam> {
  if (REQUIERE_APROBACION.has(b.name)) {
    const { ok, motivo } = await aprobar(b.name, b.input);
    if (!ok) {
      return { type: "tool_result", tool_use_id: b.id, is_error: true,
        content: `La persona rechazó la acción. Motivo: ${motivo ?? "sin motivo"}. ` +
                 "No la reintentes sin preguntar antes al usuario." };
    }
  }
  try {
    const salida = await funciones[b.name](b.input);
    return { type: "tool_result", tool_use_id: b.id, content: String(salida) };
  } catch (e) {
    return { type: "tool_result", tool_use_id: b.id, content: `Error: ${e}`, is_error: true };
  }
}

Si el modelo pidió varias herramientas en la misma respuesta y solo una necesita aprobación, ejecuta las demás y devuelve todos los resultados juntos cuando la persona haya decidido. La regla de un tool_result por cada tool_use no cambia.

Aprobaciones que tardan: guardar el estado

En consola, input() bloquea y ya está. En una aplicación real la persona puede tardar minutos u horas, y no puedes tener un proceso esperando. La solución es tratar el bucle como una máquina de estados que se puede guardar:

1. Al llegar a un tool_use que requiere aprobación, guarda en tu base de datos el historial de mensajes completo, los tool_use pendientes y los resultados ya calculados.
2. Termina la petición y notifica a la persona (interfaz, correo, Slack).
3. Cuando decida, carga el estado, construye los tool_result que faltan y continúa el bucle con una llamada nueva.

El historial de mensajes es todo el estado que necesita el modelo. Si lo guardas íntegro (incluidos los bloques thinking si usas razonamiento), retomar horas después funciona igual que seguir en el momento.

Diseñar la pantalla de aprobación

La calidad de la aprobación depende de lo que ve la persona:

• Qué se va a hacer, con los datos exactos y en lenguaje claro.
• Por qué: el razonamiento breve del agente o el mensaje del usuario que lo motivó.
• Qué pasa si aprueba y si la acción se puede deshacer.
• Tres salidas: aprobar, rechazar con motivo y editar los argumentos antes de aprobar.

Si la persona edita los argumentos, ejecuta los editados y díselo al modelo en el tool_result («Se ejecutó con importe 40 € en lugar de 60 €»). Si no, el modelo seguirá razonando con datos falsos. Más ideas de diseño en UX de agentes.

Errores frecuentes

• Fatiga de aprobación: pedir permiso para todo. La gente acaba pulsando «sí» sin mirar.
• Política en el prompt: el control debe estar en el código que ejecuta la herramienta.
• Rechazo silencioso: cortar el bucle sin devolver tool_result. El historial queda inválido y no puedes continuar.
• No registrar quién aprobó: guarda persona, momento y argumentos aprobados. Lo necesitarás para auditar.

Ver también

• Aprobación humana antes de actuar: la receta paso a paso.
• Agente de soporte con aprobación humana: un sistema completo con aprobaciones.
• Humano en el bucle: la forma de trabajar.
• El bucle agéntico: el bucle sobre el que se monta todo esto.