コンテンツにスキップ

AI エージェントの予算

要点:支出の上限が効くのは、エージェントの手が届かない場所にあるときだけです。上限はプロンプトにもエージェント自身のコードにも置かず、エージェントが HTTP で話しかける別のプロセスに置き、次の 5 つの問いに答えさせます。1 回の呼び出しでいくらまでか、1 日や 1 か月でいくらまでか、誰に払ってよいか、上限に達したらどうなるか、どんな記録が残るか。spendctl では、これが YAML ファイル 1 つとサイドカー 1 つになります。

問い ポリシーのキー 例
1 回の呼び出しでいくらまで払ってよいか budget.perRequest "0.05"
一定の期間でいくらまでか budget.hourly / daily / weekly / monthly daily: "5.00"
エージェントは誰に払ってよいか allow、deny、payTo ホスト 1 つ、受取アドレス 1 つ
上限に達したらどうなるか onBudgetExceeded、requireApprovalAbove 拒否する、または人間の判断を待って保留する
どんな記録が残るか 台帳 支払ったものも拒否したものも、試行ごとに 1 行

1 回あたりの支払いの上限が答えるのは、最初の問いだけです。エージェントが実際にお金を失うのは、残りの問いのところです。少額の支払いの積み重ね、タスクに必要のなかった売り手、二重に払ってしまう再試行、じわじわ上がる価格がそれにあたります。

npx spendctl init が書き出すのが次のファイルです(コメントは短くしてあります)。中身はすべて、エージェントとは別のプロセスであるサイドカーが強制します。

version: 1
signer:
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 init
npx 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 OK
x-spendctl-amount: $0.01
x-spendctl-attempt: pay_mwefbsts9e649h
x-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 に届くリンクから判断します。エージェントにはできません。どの判断にも、エージェントが目にすることのない管理トークンが必要だからです。詳しくは承認フローにあります。

エージェントの予算は、そのエージェントが合計でいくら使ってよいかを決めます。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

誰が支払いを受け取るかは 402 が決めます。これを固定しておけば、売り手も、売り手の代わりに応答できる誰かも、アドレス・チェーン・トークンを差し替えられません。

payTo:
"api.weather.dev":
addresses: ["0x209693Bc6afc0C5328bA36FaF03C514EF312287C"]
networks: ["eip155:8453"]
assets: ["USDC"]

エージェントに mode: dry-run を設定するか、サイドカーを spendctl start --dry-run で起動して、実際のトラフィックを流します。何も署名されず、台帳には、支払われたはずのものと拒否されたはずのものが残ります。意図どおりの拒否だけになるまでポリシーを絞り込み、それから enforce に切り替えてください。

上限はほかにもある。それでも残るもの

Section titled “上限はほかにもある。それでも残るもの”

お使いのツールがすでに持っている上限は、そのまま使ってください。それぞれが一部を受け持ちます。

  • @x402/core の spendControls は、エージェントのプロセス内で 1 回あたりの支払い(既定 $1)に上限をかけます。
  • CDP SDK の x402 spend controls はローリング上限を加えますが、こちらもプロセス内で動き、既定の保存先はメモリです。
  • ウォレットのポリシーエンジンが見るのは自社が持つ鍵で、ホスト型のエージェント決済基盤が管理するのは自社が預かるウォレットです。

残るのは、エージェントがどのウォレット・どのプロトコルに出会ってもその手前に立つ、1 つのポリシー、1 つの承認フロー、1 つの台帳です。それを、エージェントが書き換えられない場所に置きます。支出管理の置き場所で並べて比べています。