Human Approval para agentes de IA: cómo controlar de forma segura las acciones write

Idea en 30 segundos

Human approval es un runtime-gate para acciones write de riesgo: antes de ejecutar, el agente recibe approval_required y espera confirmación humana.

Cuándo se necesita: cuando el agente puede modificar datos, enviar mensajes a clientes o lanzar acciones irreversibles en producción.

Problema

Sin approval, las acciones write se ejecutan de inmediato si la policy las permite. En demo esto es cómodo. En producción, un solo error del agente se convierte en incidente real.

El problema no es solo un modelo "malo". Incluso un buen modelo se equivoca a veces en solicitudes atípicas. Si no hay un gate humano entre el agente y la herramienta write, el error se convierte al instante en side effect dentro de sistemas reales.

Analogía: es como un pago sin 3D Secure. Mientras todo va bien, no hay retraso. Cuando algo sale mal, las consecuencias se vuelven costosas en segundos.

Solución

La solución es agregar en la policy layer un flow de approval específico para acciones write de riesgo. La policy devuelve una de estas decisiones: allow, deny o approval_required.

approval_required no ejecuta la acción de inmediato: runtime crea una approval request, espera una decisión humana y solo después de approval_granted ejecuta el tool call. Esta decisión se toma en cada paso, no solo al final del run.

Human Approval != Manual Mode

Son modelos diferentes:

Manual mode: una persona ejecuta casi cada acción en lugar del agente.
Human approval: el agente trabaja de forma autónoma, y la persona confirma solo acciones write de riesgo.

Uno sin el otro no alcanza:

sin approval, acciones riesgosas pasan sin control adicional
si se usa manual mode para todo, el sistema pierde velocidad y escalabilidad

Ejemplo:

sin approval: ticket.close_bulk se ejecuta de inmediato
con approval: policy devuelve approval_required y la acción espera confirmación

Métricas de control de approval

Estas métricas y señales trabajan juntas en cada paso del agente.

Métrica	Qué controla	Mecánicas clave	Para qué sirve
Approval scope	Para qué acciones se requiere confirmación	write policy risk tiers	Reduce el riesgo en acciones irreversibles
Approval request context	Qué ve exactamente la persona antes de decidir	preview + args hash reason + policy context	Permite tomar una decisión fundamentada
TTL y cancelación	Ciclo de vida de la approval request	approval TTL cancel flow	Evita que el run quede bloqueado indefinidamente
Execution gate	Ejecución real de la acción write	approval token gateway enforcement	Garantiza que write no se ejecute sin confirmación
Approval observability	Visibilidad de decisiones de approval	audit logs alerts on timeout spikes	No limita la acción directamente, pero ayuda a detectar cuellos de botella del proceso de approval

Cómo se ve en la arquitectura

La policy layer (tool gateway) se ubica entre runtime y tools y es el único punto de control de acceso antes de cada paso. Cada decisión (allow, deny, approval_required) se registra en audit log.

Cada paso del agente pasa por este flow antes de ejecutarse: runtime no ejecuta acciones write directamente — primero chequeo de policy -> approval gate -> ejecución.

Resumen del flow:

Runtime forma un tool call
Policy layer valida riesgo y puede devolver approval_required
con approval_granted, se ejecuta write
con approval_denied o approval_timeout, el run recibe stop reason
cada decisión se escribe en audit log

En runtime, deny también se convierte en stop reason explícito, visible en logs y respuesta del run.

Una approval request normalmente contiene:

tool
preview breve de la acción
args hash
reason / risk tier
TTL

Ejemplo

Un agente de soporte quiere ejecutar email.send para un cliente. La policy define que este tool requiere confirmación humana.

Resultado:

sin approval token, write no se ejecuta
después de approval_granted, el llamado se permite
con timeout, el agente devuelve stop("approval_timeout")

Human approval detiene la acción riesgosa antes del side effect, no después del incidente.

En código se ve así

En el esquema simplificado de arriba se muestra el control flow principal. En la práctica, validación y ejecución deben pasar por un único policy/tool gateway.

Ejemplo de configuración de approval:

YAML

approvals:
  required_for:
    - email.send
    - ticket.close_bulk
    - db.write
  ttl_seconds: 300
  fallback_when_not_approved: stop

PYTHON

decision = policy.evaluate(tool, user_context, mode="normal")

if decision.outcome == "approval_required":
    request = approvals.create_request(
        run_id=run_id,
        tool=tool,
        args_hash=hash_args(args),
        ttl_seconds=300,
    )
    audit.log(run_id, decision.outcome, reason="pending_human_review", tool=tool, pending_id=request.id)
    return stop("approval_required", pending_id=request.id)

elif decision.outcome == "deny":
    audit.log(run_id, decision.outcome, reason=decision.reason, tool=tool)
    return deny(decision.reason)

# later, in resume flow with pending_id
approval = approvals.get_decision(pending_id)
if approval.outcome != "approved":
    audit.log(run_id, "deny", reason=approval.outcome, tool=tool, pending_id=pending_id)
    return stop(approval.outcome)

audit.log(run_id, "approval_granted", reason="human_approved", tool=tool, approver=approval.approved_by)
result = tool.execute({**args, "approval_token": approval.token})
decision = Decision.allow(reason="policy_ok")
audit.log(run_id, decision.outcome, reason=decision.reason, tool=tool, result=result.status)
return result

En producción, el flow de approval suele ser asíncrono: runtime crea la request, devuelve estado pending/stop sin bloquear worker y reanuda el run después de la decisión humana.

Cómo se ve durante la ejecución

TEXT

Escenario 1: confirmado (approval granted)

1. Runtime forma llamada email.send.
2. Policy devuelve approval_required.
3. Runtime crea approval request y devuelve estado pending/stop.
4. Una persona confirma la acción dentro de TTL.
5. Runtime reanuda el run, ejecuta tool call y registra `approval_granted -> allow`.

---

Escenario 2: timeout de aprobación

1. Runtime forma llamada db.write.
2. Policy devuelve approval_required.
3. Runtime crea approval request y devuelve estado pending/stop.
4. No llega confirmación antes de que termine TTL.
5. Runtime devuelve stop (approval_timeout), acción no ejecutada.

---

Escenario 3: policy deny sin approval

1. Runtime forma llamada write fuera del scope permitido.
2. Policy devuelve deny de inmediato.
3. Runtime devuelve stop reason.
4. Audit: decision=deny, reason=policy_denied.
5. Acción no ejecutada.

Errores típicos

approval solo en UI, pero no en policy/tool gateway
approval sin TTL ni cancelación
mismo enfoque para acciones write low-risk y high-risk
falta de approval token al ejecutar el tool
no loggear approval_required ni approval_granted
bloquear todos los runs esperando approval en vez de devolver estado stop/pending explícito

Como resultado, el sistema o deja pasar acciones inseguras, o queda colgado en colas de approval sin estado transparente.

Autoevaluación

Chequeo rápido de human-approval antes de lanzar en producción:

Existe una lista explícita de acciones write que requieren approval
El flow de approval pasa por policy/tool gateway centralizado
Cada approval request tiene TTL y se puede cancelar
Sin approval token, la acción write no se ejecuta
Cada decisión tiene outcome explícito: allow/deny/approval_required
Todos los outcomes de approval se escriben en audit log
Hay alerting sobre picos de approval_timeout
Las acciones low-risk tienen reglas separadas (sin approval-spam)

Progreso: 0/8

⚠ Faltan controles base de governance

Antes de production necesitas como mínimo control de acceso, límites, audit logs y parada de emergencia.

FAQ

Q: ¿Para qué acciones el approval es obligatorio?
A: Para acciones write irreversibles o visibles para cliente: cambios de datos, cierres masivos, envíos de mensajes, operaciones financieras.

Q: ¿Cómo evitar ahogar al equipo en approval-spam?
A: Divide acciones write por risk tiers. High-risk -> approval obligatorio, low-risk -> policy separada con tighter limits y audit.

Q: ¿Hay que bloquear el worker mientras esperamos approval?
A: Mejor no. Devuelve estado pending/stop y reanuda el run tras la decisión para evitar colas y deadlocks.

Q: ¿Approval puede reemplazar RBAC y budgets?
A: No. Approval es un gate adicional para acciones de riesgo. RBAC, limits y budgets siguen siendo necesarios.

Q: ¿Qué se debe loggear como mínimo?
A: approval_required, approval_granted|approval_denied|approval_timeout, quién aprobó, qué tool, qué reason y el resultado de ejecución.

Dónde encaja Human Approval en el sistema general

Human approval es una de las capas de Agent Governance. Junto con allowlist/RBAC, budgets, limits y audit, forma un sistema unificado de control de ejecución.

Páginas relacionadas

Siguiente en este tema:

Resumen de Agent Governance — modelo general de control de agentes en producción.
Allowlist vs Blocklist — cómo construir acceso a tools con default-deny.
Control de acceso (RBAC) — cómo limitar acceso por roles y tenant scope.
Control de presupuesto — cómo contener costos runaway y bucles.
Audit logs para agentes — cómo explicar decisiones de approval/policy en incidentes.