セッション予算

セッション予算（session budget）は、セッションを作成する際に設定できる、オプションの厳格な支出上限です。プラットフォームは、セッションが消費するすべてのものを公開リスト料金で継続的に価格計算し（これがセッションのリストコスト（list cost）です）、そのコストが予算に達すると新しいモデルリクエストの発行を停止します。上限を超えた時点で処理中だったリクエストは完了まで実行されるため、最終的なリストコストは予算をわずかに超えることがあります。予算に達したセッションは終了するのではなく、一時停止してアイドル状態になります。予算を変更または削除すると、作業は自動的に再開されます。デプロイメントも同じ予算を受け付け、開始する各セッションにそれを適用します。デプロイメントの予算を参照してください。

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

セッションを作成する際に、オプションの budget フィールドを渡します。

# 金額は数値ではなく文字列として送信されるよう、引用符で囲んだままにします。
SESSION_ID=$(ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID" \
  --budget '{type: limit, max_list_cost: {amount: "125", currency: USD}}' \
  --transform id --raw-output)

budget オブジェクトには2つのフィールドがあります。

• type は常に "limit" です。
• max_list_cost は上限そのものです。amount は米国セント単位の整数を先頭ゼロなしの文字列として記述したもので（"125" は1.25ドル、"50" は50セント）、ゼロより大きくなければなりません。"25.00" のような小数形式は拒否されます。金額が数値ではなく文字列であるのは、浮動小数点の丸めが一切適用されないようにするためです。currency は大文字のISO-4217通貨コードで、サポートされている通貨は USD のみです。

予算はセッションの作成時にのみ付与できます。予算のない既存のセッションに予算を追加しようとすると、400エラーで拒否されます。予算付きセッションの上限は、いつでも変更または削除できます。

リストコストの測定方法

プラットフォームは、セッションが消費するものを公開リスト料金で継続的に価格計算します。

• モデルトークン：提供された各モデルのリスト価格
• ウェブ検索：1,000回の検索あたり10ドル
• セッション実行時間：1時間あたり0.08ドル

この累計ドル合計がセッションのリストコストであり、予算はこれと比較されます。リストコストは契約価格ではありません。組織が割引を交渉している場合、セッションはリスト価格の合計が上限に達した時点で上限に達するため、実際の請求額は上限より低くなる可能性があります。

適用には、丸められていない正確なリストコストが使用されます。セッションおよびそのイベントで報告される list_cost の数値は、最も近いセントに丸められた整数セントであるため、報告される数値は、適用に使用される正確な金額から最大で半セント上下にずれることがあります。

セッションが予算に達したとき

上限はリクエストの途中ではなく、モデルリクエストの間で適用されます。各モデルリクエストの前に、プラットフォームはセッションの消費済みリストコストを確認し、その合計が上限に達すると、すべてのスレッドが次のリクエストの前に一時停止します。合計を上限超えに押し上げたリクエストは、セッションがまだ上限未満だった時点で受け付けられたものであり、完了まで実行されます。そのため、一時停止したセッションに記録される list_cost は max_list_cost と同じか、それをわずかに超えた値になります。たとえば、上限が "50"（50セント）のセッションは、list_cost が "53" の状態で一時停止することがあります。これは想定された動作であり、請求エラーではありません。超過分はスレッドごとにモデルリクエスト1回分に制限されます。予算は正確な停止点ではなく新しい作業に対する上限として扱い、このリクエスト1回分のマージンを考慮して上限を設定してください。

予算に達したセッションは、stop_reason が budget_reached のアイドル状態になります。終了はされず、その履歴とサンドボックスは他のアイドルセッションと同様に保持されます。イベントストリームでは、次の順序でイベントが表示されます。

1. 各スレッドが一時停止する際の、stop_reason が budget_reached の session.thread_status_idle イベント。
2. セッションの累積使用量とリストコストを含む session.usage イベント。
3. stop_reason が budget_reached の session.status_idle イベント。usageイベントは常にこのアイドルイベントの直前に発生します。

最後のリクエストが上限を超え、かつターンを完了したスレッドは、自身の session.thread_status_idle イベントで end_turn を報告しますが、セッションは引き続き budget_reached を報告します。セッションが予算で一時停止したことを示すシグナルとしては、セッションレベルの stop_reason を使用してください。

上限到達時に受け付けられるイベント

セッションが予算に達しているか超過している間は、すでに進行中の作業を完結させるイベントのみを受け付けます。

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

user.message など、新しい作業を開始するイベントは、このリストを示す400エラーで拒否されます。完結された結果は新しいモデルリクエストをトリガーすることなく記録され、セッションは予算で一時停止したままになります。

セッションが予算で一時停止している間（すべてのスレッドが上限で一時停止している状態）に送信された user.interrupt は受け付けられますが無視されます。イベントリストには表示されず、何も変更しません。続行するには、予算を変更または削除してください。

予算に達したセッションを再開する

セッションの更新によって予算を変更または削除します。更新が受け付けられると、セッションの一時停止中の作業は自動的に再開されます。クライアント側でそれ以上の操作は必要ありません。

予算を変更する

新しい max_list_cost でセッションを更新します。新しい値は現在の上限より高くても低くてもかまいませんが、セッションの消費済みリストコストより厳密に大きくなければなりません。そうでない場合、更新は400エラー budget.max_list_cost must be greater than the session's consumed list cost で拒否されます。セッションが一時停止した時点では、消費済みコストは通常以前の上限をわずかに超えているため、新しい値は以前の max_list_cost ではなく、セッションが報告する usage.list_cost に基づいて決めてください。その数値より1セント以上高く設定してください。報告される値は丸められており、チェックに使用される正確な消費済みコストをわずかに下回っている可能性があるためです。

ant beta:sessions update \
  --session-id "$SESSION_ID" \
  --budget '{type: limit, max_list_cost: {amount: "500", currency: USD}}'

予算を削除する

budget を null に設定すると、上限が完全に削除されます。セッションの一時停止中の作業が再開され、結果として発生する session.updated イベントには null に設定された budget が含まれます。

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

支出を監視する

セッションオブジェクトには、budget と、追跡された支出を含む usage オブジェクトが含まれます。usage.list_cost はセッションの消費済みリストコストであり、usage.active_seconds はランタイムコストの価格計算の基準となる実行時間です。budget_reached で一時停止したセッションでは、usage.list_cost が max_list_cost と同じか、それをわずかに超えた値になることが想定されます。上限を超えたリクエストが一時停止前に完了しているためです。セッションレベルの active_seconds は、並行スレッドによる重複するアクティビティを1回だけカウントします。スレッド取得レスポンスには、スレッド自身の usage に同じ2つのフィールドがスレッドごとに価格計算されて含まれます。スレッドごとの数値は個別に丸められ、セッションの実行時間コストを含まないため、合計してもセッションの list_cost と正確には一致しません。予算が適用されるのはセッションの数値です。

session.usage イベントは、セッションの累積使用量と追跡されたリストコストのスナップショットです。セッションのトークン合計、list_cost、active_seconds、server_tool_use のリクエスト数（リクエストごとにリストコストに計上される web_search_requests と、ウェブフェッチリクエストにはリクエストごとの料金がなく計測されないため 0 と表示される web_fetch_requests）、およびセッションの budget のエコー（セッションに予算がない場合は null）が含まれます。このイベントはイベントリストとセッションストリームに表示されます。セッションは、停止理由にかかわらずアイドル状態になる直前にこのイベントを1つ発行するため、予算に達したセッションは常に、予算到達のアイドルイベントの直前にこのイベントを発行します。

ストリームおよびセッションオブジェクトから使用量を読み取る方法については、使用量の追跡を参照してください。

マルチエージェントセッションにおける予算

マルチエージェントセッションには、すべてのスレッドで共有される単一の予算があり、スレッドごとの上限はありません。各スレッドの消費はそれぞれの提供モデルで価格計算され、共有の上限に達するとスレッドは個別に一時停止します。アドバイザーへの相談も同じ予算に計上され、アドバイザーモデルの料金で価格計算されます。あるスレッドが budget_reached で一時停止している間に、別のスレッドが処理中のリクエストを完了することがあります。

保留中の問い合わせは上限より優先されます。あるスレッドが requires_action で待機中で、別のスレッドが budget_reached で一時停止しているセッションは、セッションレベルでは requires_action を報告します。保留中のリクエストには依然として回答が必要であり、それに回答することは予算によってブロックされない完結イベントです。

デプロイメントの予算

デプロイメントは、作成または更新時に同じ budget オブジェクトを受け付けます。

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

上限はデプロイメントが開始する各セッションにコピーされるため、デプロイメントの累積支出ではなく、各実行を個別に制限します。デプロイメントの予算を変更すると、その後にデプロイメントが開始するセッションに適用され、すでに実行中のセッションには適用されません。セッションとは異なり、デプロイメントの予算は null でクリアした後、再度設定することができます。各実行に予算を設定するを参照してください。

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

予算は、プラットフォームが価格計算できる消費のみを追跡できます。エージェント、またはそのマルチエージェントロスター上のいずれかのエージェントやアドバイザーが公開リスト価格のないモデルを使用している予算付きセッションを作成しようとすると、そのモデルのリスト価格が利用できないことを示す400エラーで拒否されます。

予算付きセッションの使用量にリスト価格のないモデルが含まれるようになった場合、予算はセッションの支出を測定できなくなります。セッションは stop_reason が budget_reached の状態で一時停止することがあり、予算の変更は拒否されます。セッションを再開するには、予算を削除してください。

エラーリファレンス

予算関連のリクエストは、次の場合に拒否されます。