Que tu agente pregunte antes de gastar dinero: aprobaciones por enlace

Los agentes no deberían aprobar sus propios reembolsos

Cuando un agente puede emitir reembolsos, comprar cosas o dar accesos, alguien preguntará “¿quién dijo que sí?”. La respuesta no puede ser “lo decidió el modelo”. Quieres que una persona apruebe, quieres saber qué persona, y quieres que el agente espere, no que adivine, cuando nadie responde.

Las personas que deberían aprobar muchas veces no están en tu herramienta de chat: un responsable de finanzas desde su móvil, el gerente de un cliente, el dueño de un negocio pequeño. Necesitan un enlace que puedan abrir en cualquier sitio, no un puesto en tu software.

Una solicitud, varios aprobadores

Una aprobación es un createRequest con mode: "approval", un motivo y las personas que deciden. Cada persona recibe su propio enlace, así que cada decisión queda atribuida a ella:

{
  "mode": "approval",
  "title": "Refund #4821",
  "requester": "Ava (the Acme refunds agent)",
  "audience": { "kind": "named", "recipients": [
    { "name": "John Smith", "email": "john@acme.com" },
    { "name": "Martin Carpenter", "email": "martin@acme.com" },
    { "name": "Emily Lee", "email": "emily@acme.com" }
  ] },
  "approval": {
    "reason": "Refund order #4821, $1,200",
    "detail": "Customer reported a damaged item. Photos in ticket T-1042.",
    "policy": "majority",
    "showOthers": "names",
    "verify": "email"
  },
  "expiresIn": "24h",
  "webhookUrl": "https://example.com/hooks/runitby",
  "metadata": { "orderId": "4821" }
}

Las opciones que importan

• policy decide cuántas aprobaciones hacen falta: "any", "all", "majority" o un número. El veredicto llega en cuanto queda decidido, sin esperar a todos.
• verify: "email" hace que cada persona confirme un código de 6 dígitos enviado a su propia dirección antes de que funcionen los botones. Un enlace reenviado no puede decidir por ella. Úsalo para dinero, accesos o eliminaciones.
• showOthers deja que cada aprobador vea cómo van los demás, por nombre o como recuentos.
• options reemplaza Aprobar y Rechazar por hasta cuatro etiquetas, como “Aprobar con cambios”. La primera cuenta como aprobación.
• allowComment permite que las personas expliquen su decisión; los comentarios vuelven con ella.

Actúa según el veredicto, nunca según el silencio

Cuando se cumple la regla, tu webhook recibe request.completed con un veredicto: "approved", "declined" o "expired" (getStatus devuelve lo mismo). Si nadie decide antes de que caduque la solicitud, el veredicto es expired. No hay ningún camino en el que la falta de respuesta se convierta en un sí. En Builder y Pro, un agente conectado por MCP no necesita el webhook: se suscribe a la solicitud, se entera cuando llega el veredicto y emite el reembolso en la misma sesión.

// Your webhook handler, after checking the X-Runitby-Signature header
if (event.event === 'request.completed') {
  if (event.verdict === 'approved') await refund(event.metadata.orderId)
  else await tellCustomer(event.metadata.orderId, event.verdict)
}

Verifica siempre la firma del webhook antes de actuar: es un HMAC-SHA256 del cuerpo sin procesar con el secreto de firma de tu cuenta. La documentación tiene una comprobación lista para usar.

Buenas costumbres

• Pon el importe y el pedido en reason. Es lo primero que lee la gente, en una pantalla pequeña.
• Define un expiresIn acorde con la decisión. Un reembolso puede esperar un día; la aprobación de un despliegue probablemente no.
• Usa metadata para llevar tus propios ID, de modo que el manejador del webhook sepa qué hacer sin consultar nada.
• Llama a remind si se acerca un plazo. Vuelve a escribir a las personas pendientes, como máximo una vez al día a cada una.

¿Lo comparas con las aprobaciones de Slack o con las bandejas de revisión? Mira Run it by frente a las herramientas de aprobación.