お金を使う前にエージェントに確認させる:リンクで承認

エージェントに、自分で返金を承認させない

エージェントが返金したり、物を買ったり、アクセス権を与えたりできるようになれば、いずれ誰かが「誰がOKを出したの?」と聞いてきます。その答えが「モデルが判断した」では困ります。人に承認してほしいし、それが誰なのかを知りたいし、誰も答えないときは、エージェントは推測せずに待ってほしいはずです。

承認すべき人は、チャットツールにいないことがよくあります。スマートフォンを持った経理の責任者、取引先のマネージャー、小規模事業のオーナーなどです。必要なのは、どこでも開けるリンクであって、あなたのソフトウェアの利用枠ではありません。

1つのリクエストで、複数の承認者に

承認は、mode: "approval"、理由、判断する人を指定した createRequest です。1人1人に専用のリンクが渡されるので、すべての判断が誰のものかわかります。

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

押さえておきたいオプション

• policy は、何件の承認が必要かを決めます。"any"、"all"、"majority"、または数字を指定できます。判定は決まった時点ですぐに届き、全員を待つ必要はありません。
• verify: "email" を指定すると、各自が自分のアドレスに届く6桁のコードを確認して初めてボタンが使えるようになります。転送されたリンクで他の人が代わりに判断することはできません。お金、アクセス、削除に関わるときに使ってください。
• showOthers を指定すると、各承認者は他の人の状況を、名前つき、または件数で確認できます。
• options は、承認・却下のボタンを、最大4つの独自ラベル(たとえば「Approve with changes」)に置き換えます。最初のものが承認として扱われます。
• allowComment を指定すると、判断の理由をコメントで添えられます。コメントは判断と一緒に返ります。

判定に従って動く。沈黙には従わない

ルールが満たされると、Webhookに判定を含む request.completed が届きます。判定は "approved"、"declined"、"expired" のいずれかです(getStatus も同じ内容を返します)。リクエストが期限切れになるまでに誰も判断しなかった場合、判定は expired になります。回答がないことが「はい」になる経路はありません。BuilderとProでは、MCPで接続したエージェントにWebhookは不要です。リクエストを購読しておけば、判定が出た時点で通知が届き、同じセッションの中で返金を実行できます。

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

Webhookに従って動く前に、必ず署名を検証してください。署名は、生のリクエストボディを、アカウントの署名シークレットでHMAC-SHA256にかけたものです。ドキュメントにそのまま使える検証コードがあります。

おすすめの使い方

• 金額と注文を reason に書いてください。小さな画面で、相手が最初に読むのがそこです。
• 判断の内容に合った expiresIn を設定してください。返金なら1日待てますが、デプロイの承認はおそらく待てません。
• metadata に自分のIDを持たせておくと、Webhookのハンドラーが検索なしで何をすべきかわかります。
• 期限が近いときは remind を呼び出してください。回答待ちの人に、1人あたり1日1回までメールで再通知します。

Slackの承認やレビュー用の受信箱と比べたいときは、Run it byと承認ツールの違いをご覧ください。