Todas las guías

Cómo añadir aprobación humana al flujo de un agente de IA

Por Nodrail · 7 min de lectura

Para añadir aprobación humana a un agente de IA, pausa la llamada propuesta a una herramienta, guarda su alcance exacto, solicita la decisión de una persona autorizada y permite que el entorno del cliente continúe solo después de verificarla. La aprobación debe corresponder a la acción que va a ejecutarse, seguir vigente y estar protegida frente a reutilizaciones.

Enviar una notificación es una parte del proceso. La vía de ejecución debe impedir la llamada mientras la solicitud siga pendiente, haya sido denegada o haya caducado.

Esta guía utiliza un flujo ilustrativo de publicación de versiones. El modelo de estados y el pseudocódigo son ejemplos de diseño, no código de producción ni una integración de Nodrail disponible. Para definir la política que lo acompaña, empieza por cómo gestionar los permisos de agentes de IA.

Decide qué operaciones requieren revisión

Un agente puede leer notas de una versión automáticamente y necesitar aprobación antes de publicarla en un repositorio de producción. Define esa diferencia mediante una política antes de crear la interfaz de aprobación.

Una solicitud ajena a la organización o al conjunto de recursos permitido puede necesitar una denegación, en lugar de una revisión. Una persona no debe poder aprobar operaciones para las que carece de autoridad. En este modelo, una prohibición explícita conserva su prioridad.

La revisión también necesita un volumen razonable. Si cada operación habitual exige un clic, el equipo puede dejar de examinar las solicitudes con atención. Utiliza permisos permanentes acotados cuando tenga sentido y reserva la revisión individual para acciones cuyo efecto concreto deba valorar una persona.

Muestra la acción que se va a autorizar

En el ejemplo, release-agent propone publicar v1.4.0 en acme/website. La solicitud podría presentar estos datos:

Obtén la identidad, la pertenencia del repositorio y el commit efectivo de un estado de aplicación confiable. Una etiqueta o una rama pueden cambiar de destino: mostrar únicamente el nombre de la versión puede no describir el artefacto que se publicará.

La interfaz puede empezar por un resumen, pero los parámetros relevantes deben poder revisarse. Trata el contenido del agente como datos no confiables, no como instrucciones para el aprobador ni como HTML ejecutable. Un campo user_confirmed: true no constituye un registro de autorización.

La guía de seguridad de agentes de OWASP incluye la vinculación de aprobaciones a acciones y su validación en la vía de ejecución. Este ejemplo concreta esos requisitos para una solicitud de publicación.

Guarda la solicitud antes de notificar

Conserva la acción efectiva y su estado de revisión antes de intentar enviar una notificación por web, correo o chat. Si la entrega falla, la operación sigue pendiente; enviar un aviso no concede permiso para continuar.

Un modelo sencillo de estados sería:

La aplicación debe resolver cambios simultáneos, por ejemplo cuando llega una aprobación justo al caducar la solicitud. Usa una actualización condicional y atómica sobre el estado persistido para que solo gane una transición válida. Los clics duplicados deben devolver el estado existente, sin crear aprobaciones independientes.

Autentica a la persona y comprueba su autoridad

La persona que abre una notificación necesita una sesión válida y permiso para consultar la solicitud. Al recibir su decisión, comprueba si puede aprobar esa organización, entorno y operación concretos.

Separa las credenciales del agente de la autoridad humana de aprobación. Conocer el identificador de una solicitud no debe permitir aprobarla. Un enlace «Aprobar» debería abrir el flujo de revisión, en lugar de cambiar el estado por el simple hecho de que lo visite un escáner de enlaces.

Slack puede servir como interfaz, pero un mensaje entregado no demuestra quién autorizó una operación. La implementación necesita verificar la interacción entrante y relacionar el espacio de trabajo y el usuario con una persona autorizada. Todos los canales compatibles deben actualizar la misma solicitud central.

Verifica de nuevo antes de ejecutar

Una persona puede tardar varios minutos en revisar. Mientras tanto, la acción puede cambiar, la solicitud puede caducar o la política puede revocarse. Comprueba la operación efectiva cuando el entorno del cliente esté listo para continuar.

Pseudocódigo ilustrativo:

solicitud = cargar_para_entorno_autenticado(id_solicitud)
accion = resolver_accion_efectiva_desde_contexto_confiable()

si accion_no_coincide_con_lo_revisado(accion, solicitud):
    detener_y_pedir_otra_revision()

politica = evaluar_politica_actual(accion)
si politica no esta disponible, no es valida o es DENEGAR:
    detener_sin_invocar_herramienta()

consumo = consumir_atomicamente_si_aprobada_vigente_y_sin_usar(solicitud, accion)
si consumo no es valido:
    detener_sin_invocar_herramienta()

resultado = entorno_cliente.invocar_herramienta_registrada(accion)
registrar_resultado_por_separado(consumo, resultado)

Estas funciones representan contratos que cada aplicación debe implementar. Define cómo normalizar la acción, qué versiones de recursos importan, qué vigencia tiene la decisión de política y en qué punto el consumo de autorización resulta vinculante. Un hash ayuda a detectar cambios cuando se calcula sobre una representación confiable y se compara con la operación efectiva.

El SDK de agentes de OpenAI ofrece un patrón de interrupción y continuación con revisión humana. Su documentación también señala responsabilidades de producción relacionadas con autenticación, autorización, almacenamiento y recuperación. El mecanismo de pausa del entorno es una pieza útil; la aplicación sigue siendo responsable del contrato de autorización que lo rodea.

Separa los reintentos de la reutilización de aprobaciones

Un consumo atómico puede impedir que dos procesos utilicen la misma aprobación. Por sí solo no consigue que una operación en un proveedor remoto se ejecute exactamente una vez.

Cuando el proveedor lo permita, utiliza una clave de idempotencia adecuada para la misma operación lógica. Si se pierde la conexión después de que el proveedor haya podido aceptar la llamada, registra un resultado incierto y comprueba qué ocurrió antes de reintentar. La falta de respuesta no demuestra que no haya sucedido nada; tampoco justifica devolver automáticamente la aprobación al estado approved.

Si el reintento puede producir un efecto nuevo, necesita una nueva autorización cuando la política lo exija. Si existe una regla permanente aplicable, evalúa la nueva solicitud según esa regla. La revisión única y el permiso permanente siguen siendo mecanismos diferentes.

Comprueba lo que una demo satisfactoria no muestra

Estos son criterios de aceptación propuestos para el ejemplo:

Al implementar las pruebas, cuenta las invocaciones reales de una herramienta simulada. Estas filas no afirman que Nodrail ya haya superado esos casos. Revisa además las credenciales o rutas de red que puedan evitar el punto de control: añadir aprobación a un SDK no aísla todo el entorno del agente.

Haz visible el flujo para el equipo

Muestra quién solicita, qué efecto propone, quién revisa, cuál es la decisión, cuándo caduca y qué se sabe de la ejecución, indicando la procedencia de los datos. «Aprobado» y «Completado» deben ser estados diferentes en la interfaz. El equipo debe poder encontrar tanto solicitudes sin notificación entregada como operaciones con resultado desconocido.

Nodrail está desarrollando una capa headless de permisos y aprobaciones para este tipo de flujo. Tu equipo conserva su entorno y las credenciales de sus herramientas; publicaremos las integraciones compatibles cuando estén probadas. Apúntate a la lista de espera de Nodrail, o utiliza la guía de permisos para definir tus primeras reglas.