Documentación: Nodo Herramienta de Confirmación Humana (Human Confirmation Tool)¶

Descripción General¶

El Nodo Herramienta de Confirmación Humana (Human Confirmation Tool) es una herramienta (tool) para Agentes de IA que pausa la ejecución de la automatización y solicita la aprobación de una persona mediante una notificación en el dashboard, antes de permitir que se ejecuten las herramientas/acciones protegidas que vienen a continuación.

Es un mecanismo de seguridad y gobernanza para flujos con IA: garantiza que un humano valide explícitamente las acciones sensibles (abrir una barrera, desarmar una alarma, ejecutar un comando crítico) antes de que el agente las realice de forma autónoma.

¿Cuándo usar este nodo?¶

Utiliza este nodo cuando necesites:

Exigir aprobación humana antes de que un Agente ejecute una acción crítica.
Implementar un punto de control (human-in-the-loop) en flujos automatizados con IA.
Cumplir requisitos de gobernanza/seguridad que prohíben acciones totalmente autónomas en operaciones sensibles.

Arquitectura: herramienta del Agente¶

Este nodo se conecta como herramienta (Tool) de un Agente. Cuando el agente intenta usar una capacidad protegida, este nodo intercepta el flujo, envía una notificación de aprobación y espera la respuesta humana (o el vencimiento del tiempo de espera) antes de continuar.

Configuración del Nodo¶

Configuración vacía del nodo Herramienta de Confirmación Humana

Vista Formulario¶

Un mensaje informativo recuerda la función del nodo: "This node pauses execution and sends a dashboard notification to request human approval" (Este nodo pausa la ejecución y envía una notificación al dashboard para solicitar aprobación humana).

1. Título (Title)¶

El título de la solicitud de aprobación que verá el usuario (por ejemplo, Confirm vehicle barrier opening). Este campo soporta el modo IA (el ícono junto a la etiqueta permite que el valor lo decida la IA según el contexto).

2. Destinatarios de la Notificación (Notification Targets)¶

Los usuarios que recibirán la solicitud de aprobación. Haz clic en Add Users as Targets para seleccionarlos.

3. Tiempo de Espera (Timeout, segundos)¶

El tiempo máximo (en segundos) que el nodo esperará la respuesta humana antes de expirar (por defecto 300). Rango válido: de 1 a 86400 segundos.

Formulario configurado del nodo Herramienta de Confirmación Humana

Estructura JSON (Parámetros de entrada)¶

{
  "title": "Confirm vehicle barrier opening",
  "session_id": "{{trigger.session_id}}",
  "targets": [],
  "timeout_seconds": 300
}

Campos del JSON¶

Campo	Tipo	Descripción
`title`	string	Título de la solicitud de aprobación mostrada al usuario.
`session_id`	string	Identificador de la sesión (relaciona la confirmación con la conversación del agente).
`targets`	array (string)	Usuarios que reciben la notificación de aprobación.
`timeout_seconds`	number	Tiempo máximo de espera de la respuesta humana (por defecto `300`).

Output: Dónde viene la data del nodo¶

El resultado del nodo refleja la decisión humana (aprobado / rechazado) o el vencimiento del tiempo de espera. El Agente utiliza este resultado para decidir si ejecuta o no las acciones protegidas. Si no hay aprobación (rechazo o timeout), las acciones sensibles no se ejecutan.

Ejemplos de uso¶

Ejemplo 1: Aprobación antes de abrir una barrera vehicular¶

Caso de uso: Un agente que gestiona accesos puede abrir una barrera, pero solo tras la aprobación del supervisor de turno.

Title: Confirm vehicle barrier opening
Notification Targets: Supervisor de turno.
Timeout: 300 segundos.

(ver estructura JSON anterior)

Ejemplo 2: Validar desarmado de alarma¶

Caso de uso: Antes de que un agente desarme un panel de alarma, se exige la confirmación de un responsable de seguridad.

Validación y errores¶

Condición	Causa / Solución habitual
Nadie recibe la solicitud	Agrega al menos un usuario en Notification Targets y verifica que tenga sesión activa.
La acción no se ejecuta	Es el comportamiento esperado si no hubo aprobación (rechazo o vencimiento del timeout).
Expira demasiado rápido/lento	Ajusta `timeout_seconds` según el tiempo razonable de respuesta del responsable.

Buenas prácticas¶

Proteger solo lo crítico: Usa esta herramienta para acciones realmente sensibles, para no entorpecer el flujo con aprobaciones innecesarias.
Títulos claros: Redacta el título de forma que el aprobador entienda exactamente qué está autorizando.
Destinatarios adecuados: Dirige la solicitud a quien tiene la autoridad para aprobar la acción.
Timeout sensato: Define un tiempo de espera acorde a la urgencia y a la disponibilidad del personal.