Managed Agents セッション予算

上級

What you'll learn

1つの Managed Agents セッションが使える金額を、開始前に米セント単位で上限設定する
セッションが budget_reached で一時停止するときに発火する4段階のイベントシーケンスを読む
1リクエスト分のオーバーシュートを理解する — なぜ $0.50 の上限が $0.53 で一時停止しうるのか、そしてそれを見越したサイズ設定
上限を引き上げるか撤去して一時停止したセッションを再開する — そして撤去が一方向である理由を知る
スケジュールされたデプロイメントに1実行あたりの上限を付けて、繰り返し実行が暴走支出に流れないようにする
セッション予算を Messages API のタスク予算（助言的、トークン建て、単一ループ）と区別する

自律的な Managed Agents セッションは午前3時に目覚め、厄介なツール結果を見つめ、ループを回し始めることがあります。上限がなければ、唯一のバックストップは組織のレート制限か、コーヒーの後に誰かが読む監視アラートだけです。セッション予算は Anthropic のファーストパーティの解決策です：セッション作成時に設定するハードな金額の天井で、プラットフォームがモデルリクエスト間で強制します。

これまで作ってきたあらゆる「コストアラート」と2つの点で違います：

上限はプラットフォーム側で各モデルリクエストの前に強制されます — あなたの webhook が事後に強制するのではありません。予算付きのセッションは自ら一時停止します。
上限は米セント整数で、Anthropic のパブリックリスト料金で価格計算されます — あなたの契約料金ではありません。組織に割引があれば、セッションはリスト価格ドルで上限に達し、請求される支出はそれより低くなります。

セッション予算 vs タスク予算 — 混同しない

Claude プラットフォームには「予算」プリミティブが2つ出荷されています。それぞれ異なる問題を解決します。

	セッション予算（このページ）	タスク予算（Messages API）
対象	Managed Agents セッション / デプロイメント	Messages API の単一エージェンティックループ
単位	米ドル、セント整数	トークン
強制	ハード — プラットフォームがセッションを一時停止	助言的 — モデルが自己調整
誰が読むか	プラットフォームのコスト会計	モデル（ガイダンスとして）
上限到達時	`stop_reason: "budget_reached"`、セッションはアイドルに	モデルがまとめて明け渡す

無人実行をハード停止させたいならセッション予算。1つのループ内でモデルにペースを合わせさせたいならタスク予算。両者は組み合わせられます — Managed Agents セッションはセッション予算を持ちつつ、その中で呼び出す入れ子の Messages API ツール呼び出しが独自のタスク予算を持てます。

セッション作成時に予算を設定する

POST /v1/sessions のオプションフィールド budget を渡します：

$25.00 で上限を設定したセッションを作成する

curl -fsSL https://api.anthropic.com/v1/sessions \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d '{
  "agent": "'"$AGENT_ID"'",
  "environment_id": "'"$ENVIRONMENT_ID"'",
  "budget": {
    "type": "limit",
    "max_list_cost": {"amount": "2500", "currency": "USD"}
  }
}'

budget オブジェクトはちょうど2つのフィールドを持ちます：

type は常に "limit"。今日はこれ以外の種類はありません。将来の強制形態が既存クライアントを壊さないためにフィールドがあります。
max_list_cost は上限そのものです。amount は米セントの整数を文字列で指定します — "2500" は $25.00、"50" は50セント、"1" は1セントです。"25.00" のような小数形式は400で拒否されます。文字列形式は意図的です：浮動小数点の丸めが上限に触れることはありません。currency は大文字の ISO-4217 コードで、今日サポートされているのは USD のみです。

Watch out

予算はセッション作成時にのみアタッチできる。予算なしで作成された実行中のセッションに予算を追加すると400が返る — 事前に計画すること。
amount はセント整数の文字列。「25.00」は拒否される。「0」は拒否される。「-1」は拒否される。

リストコストの測り方

プラットフォームはセッションが消費するものをパブリックリスト料金で連続的に価格計算し、その走行合計をセッションのリストコストと呼びます。3つの要素が入ります：

モデルトークン — 各配信モデルのリスト価格で。マルチエージェントセッションでは、各スレッドのトークンはそのスレッド自身のモデルで価格計算されます。
Web 検索 — 1,000リクエストあたり $10（つまり検索1回あたり1セント）。
セッション実行時間 — アクティブなセッション時間1時間あたり $0.08。

Web fetch リクエストはメーターに影響しません：server_tool_use カウンターには現れますが、リクエストあたりの料金はなく、予算にも入りません。

内面化しておく価値のある会計上の2つの詳細：

強制は正確な、丸められていないリストコストを使います。セッションおよびイベントオブジェクトに 表示される list_cost はセント整数に丸められているので、報告値は強制チェックが読む値から半セントほど上下することがあります。丸められた2つの読み値を比較して、プラットフォームが1セント「忘れた」と結論しないでください。
マルチエージェントセッションでは、セッションレベルの active_seconds は重複するスレッド活動を1回として数えます（並列作業で実行時間が過剰請求されないように）。スレッド単位の active_seconds はスレッド単位で価格計算され、セッションの実行時間コストは除外されるので、スレッドの list_cost を合計してもセッションの list_cost とは一致しません。セッションの値を信頼してください — 上限はそれに対して強制されます。

1リクエストのオーバーシュート

これがセッション予算について最も驚かされる点で、アラートを組み立てる際に念頭に置くべきものです。

上限はモデルリクエストの間でチェックされ、リクエストの途中ではチェックされません。各リクエストの前に、プラットフォームはセッションの消費リストコストを読みます。上限に達すると、すべてのスレッドが次のリクエストの前に一時停止します。合計を上限を越えて運んだリクエストは、セッションがまだ上限以下だったときに受理されており、完了まで走ります。

結果："50"（50セント）で上限設定されたセッションが list_cost "53" で一時停止することがあります。これは請求のバグではありません。オーバーシュートはスレッドあたりモデルリクエスト1回に制限されます — しかし、複数の並行スレッドを持つマルチエージェントロスターでは、その「1回」が掛け算されます。

Pro tip

max_list_cost は新しい仕事の上限として扱い、正確な停止点としては扱わないこと。支出が $X を絶対に超えないことを保証したいなら、上限を X - (max_request_cost * concurrent_threads) に設定します。高価な Opus 呼び出しを行う25スレッドのマルチエージェントセッションでは、この余裕は無視できません。

セッションが予算に達するとどうなるか

予算に達したセッションは死にません — アイドルになり、履歴とサンドボックスは保持されます。イベントストリームでは、以下の順で見えます：

Guided walkthrough1 of 4

各スレッドが進行中のリクエストを完了すると、stop_reason: "budget_reached" の idle イベントを発火する。最終リクエストがそのターンも完了したスレッドは、自身のイベントで stop_reason: "end_turn" を報告する — しかしセッションレベルのイベントは依然として budget_reached を報告する。セッションレベルのシグナルを信頼せよ。

セッションがまだ受け入れるイベント

上限で一時停止中、セッションは進行中の作業を決着させるイベントだけを受け入れます：

user.tool_confirmation
user.tool_result
user.custom_tool_result
user.interrupt

user.message — 新しい作業を開始するもの — は、上のリストを正確に名指しした400エラーで拒否されます。完全に一時停止したセッションに送られた user.interrupt は受理され黙って無視されます（イベントリストにさえ現れません）。進行中のツールを決着させても新しいモデルリクエストは発火しません。セッションは一時停止したままです。

再開：予算を変更または撤去する

正確に2つのレバーがあります。

予算を変更する

新しい max_list_cost を持つ PATCH（または SDK の update）を送ります。新しい値は古い上限より高くても低くても構いません — ただしセッションの消費リストコストより厳密に大きくなければなりません。そうでなければ：

400 budget.max_list_cost must be greater than the session's consumed list cost

Watch out

セッションが一時停止したとき、消費コストは通常古い上限を少しだけ超えています。したがって新しい値は古い max_list_cost ではなく、セッションが報告した usage.list_cost に基づいて設定してください。新しい上限は報告値の少なくとも1セント上に設定します — 報告値は丸められており、チェックが使う正確な消費コストのほんの少し下に位置することがあります。

上限を $40.00 に引き上げる

curl -sS --fail-with-body "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d '{"budget": {"type": "limit", "max_list_cost": {"amount": "4000", "currency": "USD"}}}'

更新が受理されると、一時停止した作業は自動的に再開します。他に何も送る必要はありません。

予算を撤去する

budget を null に設定すれば上限は消えます。セッションは再開し、結果として発生する session.updated イベントは budget: null を運びます。

{"budget": null}

Watch out

撤去は一方向です。 予算が撤去されたセッションに新しい予算を与えることはできません — 「予算は作成時のみ」と同じルールが撤去にも適用されます。セッションに上限を維持したいなら、常に変更してください。組織の通常の支出上限にセッションを意識的に戻すときだけ撤去してください。

デプロイメントの予算 — 累積ではなく1実行あたり

スケジュールされたデプロイメントは同じ budget オブジェクトを受け入れます：

{
  "budget": {
    "type": "limit",
    "max_list_cost": {"amount": "2000", "currency": "USD"}
  }
}

上限はデプロイメントが開始する各セッションにコピーされます。各実行を個別に上限設定するもので、デプロイメントの全実行にわたる累積支出ではありません。したがって、$20 のデプロイメント予算で毎日 cron、月30回実行なら、リストコストで最大〜$600 燃やせます — $20 ではありません。

セッション予算とのさらに2つの違い：

デプロイメントの予算を変更しても、その後にデプロイメントが開始するセッションに適用されます — 既に実行中のセッションは作成時の予算を保ちます。
セッションと異なり、デプロイメントの予算は null でクリアしてから後で再設定できます。一方向の撤去ルールはセッションレベルのルールであり、デプロイメントレベルのルールではありません。

マルチエージェント、アドバイザー、共有される上限

マルチエージェントセッションはすべてのスレッドで単一の共有予算を持ちます — スレッド単位の上限はありません。各スレッドの消費はそれ自身の配信モデルで価格計算され、共有上限に達するにつれてスレッドは独立して一時停止します。あるスレッドが budget_reached で一時停止する一方、別のスレッドはまだ進行中のリクエストを完了中ということもあります。

アドバイザーの相談は同じ予算に対して計上され、アドバイザーモデルの料金で価格計算されます。したがって、$10 の予算のセッションで Sonnet-5 の実行者が相談する Opus-5 のアドバイザーは、同じプールから引き出しています。コスト最適化のためにアドバイザーパターンを使っているなら、実行者だけでなく両方の階層に合わせて上限をサイズ設定してください。

重要な決着ルールが1つあります：保留中の要求は上限より優先されます。あるスレッドが requires_action（例えば user.tool_confirmation）を待っていて、別のスレッドが budget_reached で一時停止している場合、セッションはトップレベルで requires_action を報告します — その要求に答えるのは予算がブロックしない decisive イベントだからです。オペレーター UI は requires-action のプロンプトを先に表示すべきです。

リスト価格のないモデル

予算はプラットフォームが価格計算できる消費しか追跡できません。2つの失敗モード：

作成時： エージェント — またはマルチエージェントロスターのどのエージェントやアドバイザーでも — がパブリックリスト価格のないモデルを使う予算付きセッションを作成すると、no list price is available for the model というメッセージで400が返ります。これには、まだ価格設定されていないプレビュー / リサーチプレビューモデルが含まれます。
作成後： 予算付きセッションの使用に価格のないモデルが含まれるようになると（例えばセッションレベルのオーバーライドがロスターエントリを追加した場合）、予算はもはや支出を測定できません。セッションは依然として stop_reason: "budget_reached" で一時停止できますが、予算を変更しようとする試みは拒否されます。唯一の回復手段は予算を撤去することです — 上のルールに従って一方向です。ロスターを設計してこれが実行中に起こらないようにしてください。

エラーリファレンス

予算関連の400条件の完全なリスト：

条件	ステータス
セッションが予算以上に達した状態で作業開始イベント（例えば `user.message`）が送られる	400（エラーが受理される決着イベントを名指し）
予算がセッションの消費リストコスト以下の値に設定される	400
予算なしで作成されたセッションに予算が追加される、または撤去後に再追加される	400
`amount` がセント整数でない（例えば `"25.00"`）、ゼロや負である、または `currency` が `USD` でない	400
予算付き作成がパブリックリスト価格のないモデルを参照する	400

オペレーションのチェックリスト

セッション予算を有効化する日にランブックに入れる価値のある6項目：

Guided walkthrough1 of 6

1リクエストのオーバーシュートと、通常より長い実行1回分の余裕を持たせる。セント整数のみ — 「25.00」は不可。

クロス AI ノート：他のプラットフォームはこれをどう扱っているか

Anthropic の8月7日リリース前に、主要なホスト型エージェントプラットフォームで同等のプリミティブを出荷したところはありません。2026-08-11時点で他所で近似できるもの：

OpenAI：組織レベルの月次支出上限とプロジェクトごとの使用上限は存在しますが、1実行あたりではなく、実行中の Assistants / Responses API セッションをループ途中で一時停止することはできません。トークンストリームを監視する独自の webhook でバックストップします。
Google Vertex AI（Gemini）：プロジェクトレベルの割り当てと請求予算（Cloud Billing 経由）は非同期です — アラートを出しますが、エージェントをインラインで一時停止しません。
AWS Bedrock：モデル呼び出しの割り当ては秒あたり / 分あたりのハード上限であり、セッション単位の金額上限ではありません。セッションレベルの支出ゲーティングはあなたの責任です。
サードパーティゲートウェイ（LiteLLM、OpenRouter、Portkey）：すべて到達時に HTTP エラーを返すキー単位の予算上限を提供しています — セッション予算に形は近いですが、「一時停止と再開」の挙動はファーストクラスのプリミティブではありません。

コストが Managed Agents 対ゲートウェイ付き自作ループを評価する主な理由なら、優雅な一時停止を伴う1セッション単位のハード上限は、今週の実際の差別化ポイントです。

Key takeaways

セッション予算は Managed Agents セッションに対するハードなプラットフォーム強制の USD 上限で、パブリックリスト料金で価格計算され、セッション作成時にのみ設定される
stop_reason は budget_reached。session.thread_status_idle、次に session.usage、次に session.status_idle の順を期待する — その順序でハンドラを組む
消費コストは上限をわずかに超えて位置する可能性がある（スレッドあたり最大1リクエスト分） — そのオーバーシュートを念頭に上限をサイズ設定する
上限を現在の list_cost より厳密に大きい値に変更して再開する。budget: null で完全に撤去する — ただし撤去は一方向
デプロイメント予算は1実行あたりであり、累積ではない。1実行あたり $20 の上限を持つ日次ジョブは月次 $20 の上限ではない
セッション予算（ハード、USD、プラットフォーム強制）と Messages API のタスク予算（助言的、トークン、モデル強制）を混同しない

自分でチェック

Check yourself

0/4

max_list_cost が「50」（50セント）のセッションを作成します。セッションは usage.list_cost が「53」を示して一時停止しました。何が起きましたか？
予算なしで作成されたセッションが1時間実行されています。上限を設定したいと気づきました。何ができますか？
1実行あたり $20 の予算を持つデプロイメントを日次 cron で持っています。デプロイメントが30日の月にわたって発生させうる最大リストコストはいくらですか？
予算付きセッションが budget_reached で一時停止しています。継続を求める user.message を送ります。何が起きますか？

Managed Agents — この予算がフックするコーディネーター＋セッションのメンタルモデル
Managed Agents Memory Stores — 2026年7月の永続メモリベータ
Effort tuning on Managed Agents — もう1つの大きなコストレバー、エージェント作成時に設定
The advisor tool — Sonnet が作業、Opus が思考（そのコストはセッション予算に計上される）
Why Agents Burn Tokens — $1 のターンを $50 のループに変える設計パターン
What AI Costs Across Providers — クロスモデルのコンテキスト
Hardening Autonomous Runs — コスト上限は3つのガードレールの1つであり、全部ではないから

セッション予算 vs タスク予算 — 混同しない​

セッション作成時に予算を設定する​

$25.00 で上限を設定したセッションを作成する

リストコストの測り方​

1リクエストのオーバーシュート​

セッションが予算に達するとどうなるか​

セッションがまだ受け入れるイベント​

再開：予算を変更または撤去する​

予算を変更する​

上限を $40.00 に引き上げる

予算を撤去する​

デプロイメントの予算 — 累積ではなく1実行あたり​

マルチエージェント、アドバイザー、共有される上限​

リスト価格のないモデル​

エラーリファレンス​

オペレーションのチェックリスト​

クロス AI ノート：他のプラットフォームはこれをどう扱っているか​

自分でチェック​

Check yourself

次へ​

セッション予算 vs タスク予算 — 混同しない

セッション作成時に予算を設定する

リストコストの測り方

1リクエストのオーバーシュート

セッションが予算に達するとどうなるか

セッションがまだ受け入れるイベント

再開：予算を変更または撤去する

予算を変更する

予算を撤去する

デプロイメントの予算 — 累積ではなく1実行あたり

マルチエージェント、アドバイザー、共有される上限

リスト価格のないモデル

エラーリファレンス

オペレーションのチェックリスト

クロス AI ノート：他のプラットフォームはこれをどう扱っているか

自分でチェック

次へ