Volver al blog

Notificaciones push con aprobación humana: aprueba un agente de IA desde tu teléfono

Notificaciones push con aprobación humana: aprueba un agente de IA desde tu teléfono

Un agente que puede desplegar, reembolsar, borrar o enviar correos por su cuenta es útil hasta el momento en que hace una de esas cosas mal. La solución no es impedir que actúe. Es hacer que pregunte primero, y que preguntar sea lo bastante barato como para que de verdad respondas.

Human-in-the-loop significa exactamente eso: el agente se detiene en un punto de control, una persona aprueba o rechaza, y el agente continúa con la respuesta. Lo difícil no es la lógica. Es hacer que la pregunta te llegue cuando no estás frente al escritorio, y que tu respuesta vuelva sin necesidad de un portátil.

Esta guía lo resuelve con una notificación push que incluye un botón Approve. El agente la envía, espera y lee tu decisión desde un pequeño endpoint al que llama el botón.

Cómo funciona el bucle

Cuatro piezas, todas pequeñas:

  1. El agente llega a un paso arriesgado y crea una solicitud con un ID aleatorio.
  2. Envía una notificación push de Pocket Alert con dos botones de acción. Cada botón es una petición HTTP a tu endpoint de aprobación, con ese ID.
  3. Tocas la notificación, lees lo que el agente quiere hacer y pulsas Approve o Decline. Tu teléfono llama directamente al endpoint.
  4. El agente consulta el endpoint, ve la decisión y continúa o se detiene.

Si nadie responde antes del tiempo límite, el agente lo trata como un no. Un paso de aprobación que por defecto dice "sí" es una notificación, no una salvaguarda.

Lo que necesitas

  • Una cuenta de Pocket Alert con un plan de pago. Los botones de acción se eliminan de los mensajes en el plan gratuito, así que la push llegaría sin ellos. Starter cuesta $6 al mes.
  • Una clave de API desde Claves de API, idealmente una distinta para el agente.
  • Un lugar donde ejecutar un pequeño endpoint HTTPS al que tu teléfono pueda acceder. El ejemplo usa un Cloudflare Worker, que es gratuito con este volumen; cualquier servidor sirve.

Paso 1. El endpoint de aprobación

El endpoint hace dos cosas: registra una decisión cuando la llama el teléfono, y la devuelve cuando el agente la pide. Este Worker guarda las decisiones en Workers KV durante una hora:

export default {
  async fetch(request, env) {
    if (request.headers.get('X-Approval-Secret') !== env.SECRET) {
      return new Response('forbidden', { status: 403 });
    }

    const [, action, id] = new URL(request.url).pathname.split('/');
    if (!/^[a-f0-9]{32}$/.test(id ?? '')) {
      return new Response('bad id', { status: 400 });
    }

    if (request.method === 'POST' && (action === 'approve' || action === 'decline')) {
      const existing = await env.DECISIONS.get(id);
      if (!existing) await env.DECISIONS.put(id, action, { expirationTtl: 3600 });
      return new Response(existing ?? action);
    }

    if (request.method === 'GET' && action === 'status') {
      return new Response((await env.DECISIONS.get(id)) ?? 'pending');
    }

    return new Response('not found', { status: 404 });
  },
};

Enlaza un namespace de KV como DECISIONS, añade un SECRET largo y aleatorio como secreto del Worker, y despliega. Tres detalles son intencionados:

  • La primera respuesta gana. Un segundo toque, o un toque en el otro botón, no puede cambiar una decisión ya registrada. Pocket Alert no bloquea los toques repetidos en un botón http, así que el endpoint tiene que hacerlo.
  • El secreto viaja en una cabecera, configurada dentro del propio botón. El teléfono la envía, el agente la envía, y nadie más la tiene.
  • Las decisiones caducan. Una aprobación de ayer no debería desbloquear nada hoy.

Workers KV es de consistencia eventual, así que el agente puede no ver una decisión hasta 60 segundos o más después de que la toques. Para un paso de aprobación es suficiente; si necesitas que sea instantáneo, cualquier servidor con una base de datos o un Durable Object hace el mismo trabajo.

Paso 2. Preguntar desde el agente

El siguiente helper envía la push, consulta si hay una decisión y devuelve True solo ante una aprobación explícita. Funciona con cualquier agente en Python: una herramienta de LangChain, una función del OpenAI Agents SDK, un bucle simple.

import json
import os
import time
import uuid

import requests

PUSH_API = "https://api.pocketalert.app/v1/messages"
APPROVALS = "https://approvals.YOUR_SUBDOMAIN.workers.dev"
SECRET = os.environ["APPROVAL_SECRET"]


def ask_human(title: str, details: str, timeout: int = 900) -> bool:
    request_id = uuid.uuid4().hex

    def button(label: str, action: str) -> dict:
        return {
            "type": "http",
            "label": label,
            "value": json.dumps({
                "url": f"{APPROVALS}/{action}/{request_id}",
                "method": "POST",
                "headers": {"X-Approval-Secret": SECRET},
            }),
        }

    requests.post(
        PUSH_API,
        headers={"Token": os.environ["POCKETALERT_API_KEY"]},
        json={
            "title": title,
            "message": details,
            "level": "high",
            "actions": [button("Approve", "approve"), button("Decline", "decline")],
        },
        timeout=10,
    ).raise_for_status()

    deadline = time.time() + timeout
    while time.time() < deadline:
        status = requests.get(
            f"{APPROVALS}/status/{request_id}",
            headers={"X-Approval-Secret": SECRET},
            timeout=10,
        ).text
        if status in ("approve", "decline"):
            return status == "approve"
        time.sleep(5)
    return False

Después, colócalo delante de cualquier acción que no quieras que el agente haga sin supervisión:

if ask_human("Deploy to production?", "build #482 · 14 files · all checks green"):
    deploy()
else:
    report("Deploy skipped: not approved")

level: "high" envía la push como urgente, así que atraviesa Concentración en el iPhone y aparece como notificación emergente en Android. Una aprobación que ves una hora después es una aprobación por la que el agente esperó una hora.

Lo que ves en el teléfono

La push llega con el título y los detalles que escribió el agente, y Approve y Decline aparecen directamente en la notificación. Mantén pulsado en el iPhone o despliégala en Android y toca una opción: la solicitud se envía en segundo plano, sin abrir la app, incluso si Pocket Alert está cerrada. Los mismos botones están dentro del mensaje en la app, donde un aviso muestra el código de estado que devolvió tu endpoint.

Dos detalles de cada plataforma conviene conocerlos antes de depender de esto:

  • Si la solicitud falla, porque tu endpoint devolvió un error o el teléfono no tenía red, aparece una nueva notificación con un botón Retry. Una solicitud que puede haber llegado a tu endpoint nunca se reintenta por sí sola, así que un toque no puede aprobar dos veces a tus espaldas.
  • Los botones de notificación del sistema requieren la app de Pocket Alert 2.0.1 o posterior. En versiones anteriores el banner no tiene botones y estos esperan dentro del mensaje. Tus etiquetas se muestran tal como las escribiste en ambas plataformas; si iOS no puede preparar los botones personalizados a tiempo, usa una etiqueta genérica Run para http, y el botón sigue funcionando.

Dónde poner los puntos de control

Si preguntas con demasiada frecuencia, acabarás aprobando sin leer. Los buenos puntos de control son las acciones difíciles de deshacer o que cuestan dinero real:

  • Despliegues y migraciones de bases de datos en producción
  • Enviar correos, publicar en abierto o escribir a clientes
  • Reembolsos, compras y cualquier cosa que llame a una API de pagos
  • Borrar datos, rotar claves, cambiar DNS o permisos
  • Ejecuciones que vayan a gastar más de un presupuesto de tokens o de nube definido

Todo lo demás es mejor como una notificación normal después del hecho. La página de alertas para agentes de IA cubre ese lado: terminado, fallido, bloqueado.

Hacerlo a través de MCP

Si el agente se ejecuta en un cliente MCP, puede enviar la misma push sin el helper de Python. El servidor MCP de Pocket Alert expone create_message con un parámetro actions, así que puedes indicarle al agente que lo llame con los dos botones y que consulte la URL de estado antes de continuar.

Funciona, con una advertencia: ahora el agente es responsable de esperar, y un modelo al que se le dice que espere aprobación puede decidir igualmente no hacerlo. Para lo que importa, aplica el punto de control en código que el modelo no pueda saltarse, como el helper de arriba o un hook de permisos en Claude Code o Codex. Usa la ruta MCP para la pregunta y el código para la puerta.

Variantes

  • Un solo botón. Envía solo Approve y deja que el silencio signifique no. Así no hay nada que pulsar por error en el banner, y rechazar no te cuesta nada.
  • Herramientas de flujos de trabajo. En n8n, un nodo Wait configurado para reanudarse con una llamada webhook te da una URL de reanudación; ponla en el botón Approve y el flujo continúa cuando toques.
  • Contexto en la push. Pon los números en el mensaje: el importe, el entorno, el número de filas. Deberías poder decidir solo con el texto.
  • Un botón de vista. Sustituye Decline por un botón view que abra el diff, la factura o la ejecución, y rechaza simplemente no aprobando.

Preguntas frecuentes

¿Aprobar funciona desde la pantalla de bloqueo?

Sí. Los botones http se ejecutan desde la pantalla de bloqueo sin desbloquear el teléfono, tanto si Pocket Alert está abierta, en segundo plano o cerrada. En Android, eso requiere una pantalla de bloqueo que muestre el contenido de las notificaciones; si la oculta, los botones aparecen después de desbloquear. Si eso es demasiado fácil para una acción arriesgada, pon la decisión detrás de un botón view que abra una página a la que tengas que iniciar sesión; abrir una página obliga antes a desbloquear.

¿Es seguro?

La solicitud del botón va directamente de tu teléfono a tu endpoint; Pocket Alert no la retransmite ni ve la respuesta. Protege el endpoint con una cabecera secreta, usa un ID aleatorio por solicitud, acepta solo la primera respuesta y haz que las decisiones caduquen. Los mensajes, incluida la configuración de los botones, se cifran en reposo.

¿Qué pasa si nunca respondo?

El helper devuelve False cuando se agota el tiempo, 15 minutos por defecto, y el agente debe tratarlo como rechazado. Elige un tiempo límite acorde con lo que la tarea puede esperar de forma razonable.

¿Pueden aprobar varias personas?

Cada dispositivo de la cuenta recibe la push, y gana el primer toque. Para aprobaciones por persona, envía a cada una su propia push con un ID de solicitud separado y decide en el endpoint cuántas aprobaciones necesitas.

¿Funciona en Android y en iPhone?

Sí, en ambos, con tus propias etiquetas en la notificación y dentro del mensaje. Los botones de notificación del sistema requieren la versión 2.0.1 de la app o posterior.

Obtén una clave de API, despliega el endpoint y dale a tu agente una forma de preguntar antes de actuar.

Comparte este artículo