Faça seu agente perguntar antes de gastar dinheiro: aprovações por link

Agentes não deveriam aprovar os próprios reembolsos

Quando um agente consegue fazer reembolsos, comprar coisas ou conceder acessos, alguém vai perguntar “quem disse sim?”. A resposta não pode ser “o modelo decidiu”. Você quer que uma pessoa aprove, quer saber qual pessoa, e quer que o agente espere, e não chute, quando ninguém responde.

As pessoas que deveriam aprovar muitas vezes não estão na sua ferramenta de chat: um responsável financeiro no celular, o gestor de um cliente, o dono de um pequeno negócio. Elas precisam de um link que possam abrir de qualquer lugar, não de uma licença no seu software.

Uma solicitação, vários aprovadores

Uma aprovação é um createRequest com mode: "approval", um motivo e as pessoas que decidem. Cada pessoa recebe o próprio link, então cada decisão é atribuída a ela:

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

As opções que importam

• policy define quantas aprovações são necessárias: "any", "all", "majority" ou um número. O veredito chega assim que é decidido, sem esperar por todos.
• verify: "email" faz cada pessoa confirmar um código de 6 dígitos enviado ao próprio endereço antes de os botões funcionarem. Um link encaminhado não decide por ela. Use para dinheiro, acesso ou exclusão.
• showOthers deixa cada aprovador ver como os outros estão votando, por nome ou em contagens.
• options troca Aprovar e Recusar por até quatro rótulos, como “Aprovar com alterações”. O primeiro conta como aprovação.
• allowComment deixa as pessoas explicarem a decisão; os comentários voltam junto com ela.

Aja pelo veredito, nunca pelo silêncio

Quando a regra é cumprida, seu webhook recebe request.completed com um veredito: "approved", "declined" ou "expired" (getStatus devolve o mesmo). Se ninguém decidir antes de a solicitação expirar, o veredito é expired. Não existe caminho em que a falta de resposta vire um sim. No Builder e no Pro, um agente conectado por MCP não precisa do webhook: ele assina a solicitação, é avisado quando o veredito chega e faz o reembolso na mesma sessão.

// 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)
}

Sempre verifique a assinatura do webhook antes de agir com base nele: é um HMAC-SHA256 do corpo bruto com o segredo de assinatura da sua conta. A documentação traz uma verificação pronta.

Boas práticas

• Coloque o valor e o pedido em reason. É o que as pessoas leem primeiro, numa tela pequena.
• Defina um expiresIn que combine com a decisão. Um reembolso pode esperar um dia; a aprovação de um deploy provavelmente não.
• Use metadata para levar seus próprios IDs, para que o handler do webhook saiba o que fazer sem precisar consultar nada.
• Chame remind se um prazo estiver perto. Ele envia e-mail de novo às pessoas pendentes, no máximo uma vez por dia para cada uma.

Está comparando isso com aprovações no Slack ou caixas de revisão? Veja Run it by vs ferramentas de aprovação.