# AI エージェントの予算

> AI エージェントに、自分では引き上げられない予算を持たせます。1 回あたりの上限、1 日・1 か月の期間予算、売り手ごとの予算、許可リスト、しきい値を超えたときの人間の承認を 1 つのポリシーファイルにまとめ、エージェントの外で強制します。

出典: https://spendctl.dev/ja/docs/agent-budgets/ （spendctl ドキュメント。全体の索引は https://spendctl.dev/llms.txt）

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

## 5 つの問い

| 問い | ポリシーのキー | 例 |
|---|---|---|
| 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` が書き出すのが次のファイルです（コメントは短くしてあります）。中身はすべて、エージェントとは別のプロセスであるサイドカーが強制します。

```yaml
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 セントを両方で使うことはできません。すべてのキーは[ポリシーリファレンス](https://spendctl.dev/ja/docs/policy/)にあります。

## 動かす

```bash
npx spendctl init
npx spendctl mock      # ターミナル 1: モックのファシリテータと有料 API 2 本
npx spendctl start     # ターミナル 2: サイドカー（127.0.0.1:8402）
```

エージェントはリクエストをサイドカー経由で送ります。どの言語からでも、URL の前置きとヘッダ 1 つで済みます。

```bash
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 のクライアントは[組み込み方](https://spendctl.dev/ja/docs/integrations/)にあります。

## 上限でエージェントに見えるもの

拒否は `402` で返り、モデルが読める文と、コードで分岐に使える理由コードが付きます。許可リストにないホストの場合は次のとおりです。

```json
{
  "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 をすぐに受け取ります。

```json
{
  "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 に届くリンクから判断します。エージェントにはできません。どの判断にも、エージェントが目にすることのない管理トークンが必要だからです。詳しくは[承認フロー](https://spendctl.dev/ja/docs/approvals/)にあります。

## 売り手ごとの予算

エージェントの予算は、そのエージェントが合計でいくら使ってよいかを決めます。`endpointBudget` は、そのうち 1 つの売り手がいくらまで受け取れるかを決めるもので、少しずつ上がっていく価格を捕まえます。

```yaml
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 が決めます。これを固定しておけば、売り手も、売り手の代わりに応答できる誰かも、アドレス・チェーン・トークンを差し替えられません。

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

## dry-run から始める

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

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

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

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

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

## 次に読む

- [クイックスタート](https://spendctl.dev/ja/docs/quickstart/)：同じポリシーを 5 分で最初から最後まで動かす
- [ポリシーリファレンス](https://spendctl.dev/ja/docs/policy/)：すべてのキーと、評価される順序
- [台帳と照合](https://spendctl.dev/ja/docs/ledger/)：各行の意味と書き出し方
