Managed Agentsのセッション予算(budget)でコストを上限管理する

Managed Agentsのセッション予算とは何か

Managed Agentsのセッション予算(budget)は、セッション単位でドルの上限を設定するハード制限です。プラットフォームはセッションが消費するモデルトークン・Web検索・稼働時間を常にlist価格(公開料金)で積算し、この合計(list cost)が上限に達すると新規のモデルリクエストを止めます。トークン数やターン数ではなく、金額で止める点が要点です。

上限に達してもセッションは終了しません。idle(待機)状態になり、履歴とサンドボックスはそのまま残ります。予算を変更または解除すれば、作業は自動的に再開します。トークンと稼働時間それぞれの単価はManaged Agentsの料金体系にあります。

Web検索と稼働時間も課金対象に入るため、トークン数だけを見ていても総額は読めません。予算が金額建てなのは、この3つの費目をまとめて受け止めるためです。

budgetを付けてセッションを作成する

budget はセッション作成時にしか付けられません。予算なしで作ったセッションに後から足そうとすると、400エラーになります。

session=$(curl -sS --fail-with-body 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 @- <<EOF
{
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID",
  "budget": {
    "type": "limit",
    "max_list_cost": {"amount": "125", "currency": "USD"}
  }
}
EOF
)
SESSION_ID=$(jq -r '.id' <<< "$session")

ant CLIなら、同じ内容を --budget で渡します。金額を引用符で囲み、数値ではなく文字列として送るのがコツです。

ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID" \
  --budget '{type: limit, max_list_cost: {amount: "125", currency: USD}}'

budget オブジェクトのフィールドは2つだけです。type は常に "limit" で、上限そのものが max_list_cost です。

• amount は米ドルのセントを整数で数え、先頭に0を付けない文字列で渡します。"125" は1.25ドル、"50" は50セントで、ゼロより大きい値が必要です。
• "25.00" のような小数表記は拒否されます。文字列なのは、浮動小数点の丸めを一切かけないためです。
• currency は大文字のISO-4217コードで、サポートされているのは USD だけです。

組織で割引を契約していても、上限はlist価格の合計で判定されます。そのため、実際の請求額は上限より低くなることがあります。

上限の判定に使われるのは、丸める前の正確な金額です。セッションやイベントに出る list_cost は1セント単位に丸めた値なので、判定に使われた値と最大0.5セントずれて見えることがあります。

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

上限のチェックはモデルリクエストの合間に行われ、リクエストの途中では止まりません。リクエストを送る前にその時点の消費額を確かめ、上限に達していれば全スレッドが次のリクエストの手前で停止します。上限をまたいだリクエストは、受理された時点ではまだ上限の下にいたので、最後まで走ります。

結果として、一時停止したセッションの list_cost は上限ぴったりか、わずかに上回った値になります。"50" で上限を切ったセッションが list_cost: "53" で止まるのは正常で、課金エラーではありません。超過幅はスレッドごとに最大1リクエスト分です。予算は「新しい作業を止める枠」として扱い、上限を決めるときはこの1リクエスト分の余白を織り込みます。

停止したセッションのイベントストリームには、次の順に3つのイベントが流れます。

最後のリクエストが上限をまたぐと同時にターンも終わらせた場合、そのスレッドの session.thread_status_idle は end_turn を報告します。それでもセッション全体の stop_reason は budget_reached のままなので、予算停止かどうかの判定にはセッション側の値を使います。

停止中に受け付けるイベント

上限に達しているセッションが受理するのは、進行中の作業を決着させるものだけです。

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

新しい作業を始める user.message などは、受け付けるイベントの一覧つきの400エラーで拒否されます。決着イベントで届いた結果は記録されるだけで、新しいモデルリクエストは走りません。セッションは停止したまま、予算の変更を待ちます。

停止中に送った user.interrupt は受理されたうえで無視されます。イベント一覧にも残らず、何も変わりません。作業を進めるには、予算を変更するか解除します。

予算を変更・解除して再開する

セッションの更新で max_list_cost を書き換えると、作業は自動的に再開します。追加のアクションは要りません。

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": "500", "currency": "USD"}
    }
  }'

新しい値は現在の上限より大きくても小さくても構いませんが、セッションの消費額より厳密に大きいことが条件です。満たさない更新は、budget.max_list_cost must be greater than the session's consumed list cost という400エラーで拒否されます。

停止直後の消費額は古い上限をわずかに超えているのが通常です。そのため、古い max_list_cost ではなく、セッションが報告する usage.list_cost を基準にします。報告値は丸められていて、判定に使う正確な消費額より小さく見えることがあります。そこから1セント以上の余裕を持たせて設定します。

上限を外して走らせ続けたいときは、budget に null を渡します。再開後に届く session.updated イベントは budget が null になっています。

ant beta:sessions update --session-id "$SESSION_ID" --budget null

マルチエージェントセッションとdeploymentでの適用範囲

マルチエージェントセッションの予算は、スレッドごとではなくセッション全体で1つです。スレッド単位の上限はありません。各スレッドは自分が使うモデルのlist価格で消費を積み上げ、共有の上限に達すると、スレッドごとに独立して止まります。ほかのスレッドが送信済みのリクエストを終えるあいだに、1つのスレッドだけが budget_reached で止まっている状態も起こります。

advisorツールの相談も同じ予算に計上され、advisorモデルのlist価格で課金されます。承認待ち(requires_action)と予算停止(budget_reached)が別々のスレッドで重なったときは、セッション全体として requires_action が優先されます。承認への応答は決着イベントなので、予算が止めることはありません。

スケジュールデプロイも、作成・更新時に同じ budget オブジェクトを受け付けます。単発のセッションとの違いは次のとおりです。

deploymentの予算を変更すると、その後に起動するセッションから新しい値が使われます。すでに走っているセッションには影響しません。

消費額をどこで監視するか

セッションオブジェクトは budget と usage を常に持っています。usage.list_cost が消費済みのlist cost、usage.active_seconds が稼働時間課金の基になる秒数です。複数スレッドが同時に走るセッションでは、重なった稼働時間を1回だけ数えます。

スレッドを取得すると、そのスレッド自身の usage も返ります。スレッドごとの値はそれぞれ独立に丸められ、セッションの稼働時間コストを含みません。そのため、足し合わせてもセッション全体の list_cost とは一致しません。予算の判定に使われるのは、常にセッション側の数値です。

session.usage イベントは、累積使用量のスナップショットです。含まれるのは次の項目です。

• トークンの合計と内訳
• list_cost と active_seconds
• server_tool_use の回数。課金対象のWeb検索は web_search_requests、Web fetchは web_fetch_requests で、後者は課金も計測もされないため常に0
• 予算の写し。予算のないセッションでは null

セッションが idle になる直前には、停止理由を問わず必ず1件発行されます。予算停止のログも、このイベントで追えます。

Messages APIのtask budgetとは別物

Messages APIにはtask budgetという似た名前の機能があります。セッション予算はUSD建てで、プラットフォームが強制するハード停止です。task budgetはトークン建てで、1回のエージェントループの中でモデル自身が消費を自己調整するための助言的な仕組みです。止めるのがプラットフォームか、モデルの自制かが違いです。

エラーになる条件

単発の作業と定期実行で、上限の置き方はどう変わるか

単発の調査や対話型のセッションなら、作成時に上限を決め、足りなければ変更して再開します。上限の見当は費目から付けられます。"50" の上限なら、Web検索だけで50件分に相当します。モデルトークンの分は、エージェントとモデルの組み合わせごとに実測を取ってから足します。

定期実行では、上限の意味が変わります。deploymentの上限は実行ごとにコピーされ、"2000" なら1回の実行で最大およそ20ドルまで使えます。過去の実行の消費が次の実行の枠を削ることはありません。裏を返せば、月の総額は上限に実行回数をかけた額が天井になります。毎日1回の実行なら、30回分です。

すでに走っているセッションは、起動した時点の上限を保ちます。deploymentの予算を変えても、そのセッションには届きません。走行中のセッションの上限を動かすときは、セッション自身を更新します。

list価格を持たないモデルは、予算と併用できません。エージェント、またはマルチエージェント構成のいずれかのエージェントやadvisorがそのモデルだと、予算付きセッションの作成が400エラーで拒否されます。稼働後にそのモデルが使用に加わった場合は、予算を測れなくなり、budget_reached で止まることがあります。予算の変更も拒否されるため、再開には解除が必要です。

まとめ

予算は新しい作業を止めるだけで、履歴は残ります。単発のセッションは作成時に1本分の上限を決め、定期実行は実行ごとの上限に回数をかけた額を月の天井として見積もります。