AI エージェントの予算
要点:支出の上限が効くのは、エージェントの手が届かない場所にあるときだけです。上限はプロンプトにもエージェント自身のコードにも置かず、エージェントが HTTP で話しかける別のプロセスに置き、次の 5 つの問いに答えさせます。1 回の呼び出しでいくらまでか、1 日や 1 か月でいくらまでか、誰に払ってよいか、上限に達したらどうなるか、どんな記録が残るか。spendctl では、これが YAML ファイル 1 つとサイドカー 1 つになります。
5 つの問い
Section titled “5 つの問い”| 問い | ポリシーのキー | 例 |
|---|---|---|
| 1 回の呼び出しでいくらまで払ってよいか | budget.perRequest |
"0.05" |
| 一定の期間でいくらまでか | budget.hourly / daily / weekly / monthly |
daily: "5.00" |
| エージェントは誰に払ってよいか | allow、deny、payTo |
ホスト 1 つ、受取アドレス 1 つ |
| 上限に達したらどうなるか | onBudgetExceeded、requireApprovalAbove |
拒否する、または人間の判断を待って保留する |
| どんな記録が残るか | 台帳 | 支払ったものも拒否したものも、試行ごとに 1 行 |
1 回あたりの支払いの上限が答えるのは、最初の問いだけです。エージェントが実際にお金を失うのは、残りの問いのところです。少額の支払いの積み重ね、タスクに必要のなかった売り手、二重に払ってしまう再試行、じわじわ上がる価格がそれにあたります。
完全なポリシー
Section titled “完全なポリシー”npx spendctl init が書き出すのが次のファイルです(コメントは短くしてあります)。中身はすべて、エージェントとは別のプロセスであるサイドカーが強制します。
version: 1signer: type: mock # モックの資金。本物のウォレットを使うなら `spendctl init --signer cdp`
approvals: timeout: 10m # 答えのない承認は拒否になる hold: true # 人間が判断する間、エージェントのリクエストを開いたままにする
defaults: networks: ["eip155:84532"] # Base Sepolia のみ assets: ["USDC"] priceJumpFactor: 3 # 前回支払った価格の 3 倍を超えたら人間が確認 firstPaymentMax: "0.05" # 新しい受取先への初回支払いがこれを超えたら人間が確認
agents: researcher: budget: perRequest: "0.05" daily: "0.03" monthly: "20.00" onBudgetExceeded: approve # deny | approve requireApprovalAbove: "0.50" allow: - "localhost:4021" # モックの天気 API - "localhost:4022" # モックの検索 API金額は USD の文字列です。期間はローリング(1 時間、24 時間、7 日、30 日)で、予約済み・決済済み・結果未確認の金額を合計します。そのため、同時に進んでいる 2 つのリクエストが最後の 1 セントを両方で使うことはできません。すべてのキーはポリシーリファレンスにあります。
npx spendctl initnpx spendctl mock # ターミナル 1: モックのファシリテータと有料 API 2 本npx spendctl start # ターミナル 2: サイドカー(127.0.0.1:8402)エージェントはリクエストをサイドカー経由で送ります。どの言語からでも、URL の前置きとヘッダ 1 つで済みます。
curl -H "X-Spendctl-Agent: researcher" "http://127.0.0.1:8402/http://localhost:4021/weather?city=Tokyo"支払いが済んだ呼び出しは、売り手の応答そのものに 3 つのヘッダが加わって返ります。
HTTP/1.1 200 OKx-spendctl-amount: $0.01x-spendctl-attempt: pay_mwefbsts9e649hx-spendctl-decision: settled
{"city":"Tokyo","condition":"sunny","temperatureC":18}TypeScript、Python、MCP のクライアントは組み込み方にあります。
上限でエージェントに見えるもの
Section titled “上限でエージェントに見えるもの”拒否は 402 で返り、モデルが読める文と、コードで分岐に使える理由コードが付きます。許可リストにないホストの場合は次のとおりです。
{ "error": "spendctl_denied", "message": "spendctl refused a payment to localhost:4022/search: localhost:4022 is not on the allowlist for agent researcher.", "attempt": "pay_mwefc8mvqwn3d4", "decision": "deny", "reasons": [ { "code": "domain_not_allowed", "message": "localhost:4022 is not on the allowlist for agent researcher." } ]}onBudgetExceeded: approve にしていると、1 日の予算を超えることになる呼び出しは拒否されません。人間の判断を待って保留され、待っている間は何も署名されません。再送モード(approvals.hold: false)では、エージェントは承認 ID をすぐに受け取ります。
{ "error": "spendctl_approval_required", "message": "spendctl needs a human to approve $0.01 to localhost:4021/weather: $0.01 would exceed the daily budget of $0.02 for agent researcher ($0.02 already spent).", "decision": "approve", "amount": "$0.01", "reasons": [{ "code": "daily_exceeded", "message": "…" }], "approval": "apr_mwefc8s25ehf4t", "approvalExpiresAt": "2026-11-13T03:45:36.818Z", "hint": "Ask a human to run `spendctl approve apr_mwefc8s25ehf4t`, then retry with header X-Spendctl-Approval: apr_mwefc8s25ehf4t."}人間は spendctl approve、ダッシュボード、または Webhook で Slack や Discord に届くリンクから判断します。エージェントにはできません。どの判断にも、エージェントが目にすることのない管理トークンが必要だからです。詳しくは承認フローにあります。
売り手ごとの予算
Section titled “売り手ごとの予算”エージェントの予算は、そのエージェントが合計でいくら使ってよいかを決めます。endpointBudget は、そのうち 1 つの売り手がいくらまで受け取れるかを決めるもので、少しずつ上がっていく価格を捕まえます。
agents: researcher: budget: { perRequest: "0.05", daily: "5.00" } endpointBudget: "api.weather.dev": { daily: "1.00" } "api.search.dev/v1/*": { hourly: "0.50", daily: "2.00" } onBudgetExceeded: approve受取先を固定する
Section titled “受取先を固定する”誰が支払いを受け取るかは 402 が決めます。これを固定しておけば、売り手も、売り手の代わりに応答できる誰かも、アドレス・チェーン・トークンを差し替えられません。
payTo: "api.weather.dev": addresses: ["0x209693Bc6afc0C5328bA36FaF03C514EF312287C"] networks: ["eip155:8453"] assets: ["USDC"]dry-run から始める
Section titled “dry-run から始める”エージェントに mode: dry-run を設定するか、サイドカーを spendctl start --dry-run で起動して、実際のトラフィックを流します。何も署名されず、台帳には、支払われたはずのものと拒否されたはずのものが残ります。意図どおりの拒否だけになるまでポリシーを絞り込み、それから enforce に切り替えてください。
上限はほかにもある。それでも残るもの
Section titled “上限はほかにもある。それでも残るもの”お使いのツールがすでに持っている上限は、そのまま使ってください。それぞれが一部を受け持ちます。
@x402/coreのspendControlsは、エージェントのプロセス内で 1 回あたりの支払い(既定$1)に上限をかけます。- CDP SDK の x402 spend controls はローリング上限を加えますが、こちらもプロセス内で動き、既定の保存先はメモリです。
- ウォレットのポリシーエンジンが見るのは自社が持つ鍵で、ホスト型のエージェント決済基盤が管理するのは自社が預かるウォレットです。
残るのは、エージェントがどのウォレット・どのプロトコルに出会ってもその手前に立つ、1 つのポリシー、1 つの承認フロー、1 つの台帳です。それを、エージェントが書き換えられない場所に置きます。支出管理の置き場所で並べて比べています。
- クイックスタート:同じポリシーを 5 分で最初から最後まで動かす
- ポリシーリファレンス:すべてのキーと、評価される順序
- 台帳と照合:各行の意味と書き出し方