Fai chiedere al tuo agente prima di spendere: approvazioni tramite link

Gli agenti non dovrebbero approvarsi i rimborsi da soli

Quando un agente può emettere rimborsi, fare acquisti o concedere accessi, prima o poi qualcuno chiederà «chi ha detto di sì?». La risposta non può essere «l’ha deciso il modello». Vuoi che sia una persona ad approvare, vuoi sapere quale persona, e vuoi che l’agente aspetti, non tiri a indovinare, quando nessuno risponde.

Chi dovrebbe approvare spesso non è nel tuo strumento di chat: un responsabile finanziario dal telefono, il manager di un cliente, il titolare di una piccola attività. Serve un link apribile ovunque, non un posto nel tuo software.

Una richiesta, più approvatori

Un’approvazione è un createRequest con mode: "approval", un motivo e le persone che decidono. Ogni persona riceve il proprio link, così ogni decisione le è attribuita:

{
  "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" }
}

Le opzioni che contano

• policy stabilisce quante approvazioni servono: "any", "all", "majority" o un numero. L’esito arriva appena è deciso, senza aspettare tutti.
• verify: "email" fa confermare a ogni persona un codice di 6 cifre inviato al proprio indirizzo prima che i pulsanti funzionino. Un link inoltrato non può decidere al suo posto. Usalo per denaro, accessi o cancellazioni.
• showOthers permette a ogni approvatore di vedere a che punto sono gli altri, per nome o come conteggi.
• options sostituisce Approva e Rifiuta con un massimo di quattro etichette, come «Approva con modifiche». La prima conta come approvazione.
• allowComment permette alle persone di spiegare la propria decisione; i commenti tornano insieme a essa.

Agisci sull’esito, mai sul silenzio

Quando la regola è soddisfatta, il tuo webhook riceve request.completed con un esito: "approved", "declined" o "expired" (getStatus restituisce lo stesso). Se nessuno decide prima della scadenza della richiesta, l’esito è expired. Non esiste alcun percorso in cui una mancata risposta diventi un sì. Su Builder e Pro, un agente collegato via MCP non ha bisogno del webhook: si iscrive alla richiesta, viene avvisato quando arriva l’esito ed emette il rimborso nella stessa sessione.

// 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 sempre la firma del webhook prima di agire: è un HMAC-SHA256 del corpo grezzo con il segreto di firma del tuo account. La documentazione include un controllo già pronto.

Buone abitudini

• Metti l’importo e l’ordine in reason. È ciò che le persone leggono per primo, su uno schermo piccolo.
• Imposta un expiresIn adatto alla decisione. Un rimborso può aspettare un giorno; l’approvazione di un deploy probabilmente no.
• Usa metadata per portare i tuoi ID, così il gestore del webhook sa cosa fare senza fare ricerche.
• Chiama remind se la scadenza è vicina. Riscrive a chi è ancora in attesa, al massimo una volta al giorno ciascuno.

Stai confrontando tutto questo con le approvazioni su Slack o le caselle di revisione? Vedi Run it by e gli strumenti di approvazione.