セッション予算

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

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

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

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    budget={
        "type": "limit",
        "max_list_cost": {"amount": "125", "currency": "USD"},
    },
)
print(session.id, session.budget.max_list_cost.amount)  # sesn_01... 125

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回のモデルリクエストのコストです。そのリクエストのレスポンスに含まれるツール呼び出しは引き続き実行され、それらのウェブ検索と実行時間もリストコストに加算されます。予算は正確な停止点ではなく新しい作業に対する上限として扱い、その余裕を考慮して上限を設定してください。

予算に達したセッションは、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イベントは常にこのアイドルイベントの直前に発生します。

ワークフロー実行が開いている場合、まだアイドルになっていない各実行にも workflow_run.status_idle イベントが送られます。

最後のリクエストで上限を超え、かつターンを完了したスレッドは、自身の 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 は、受け付けられますが、イベントリストには表示されません。すべてのスレッドがすでに一時停止しているため、どのスレッドも停止しません。続行するには、予算を変更または削除してください。

セッションに開いているワークフロー実行がある場合、他のタイミングでの中断と同様に、この中断によってそれらの実行が一時停止することがあります。中断によって一時停止された実行は、予算を変更または削除しても再開されません。その実行を続行するには、予算を変更または削除してから、実行を続行するようエージェントに依頼する user.message を送信してください。

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

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

予算によって一時停止された各ワークフロー実行にも、workflow_run.status_running イベントが送られます。中断によって一時停止された実行は、セッションが予算に達している間に送信された中断によるものであっても、一時停止したままになり、更新による workflow_run.status_running イベントは送られません。その実行を続行するには、実行を続行するようエージェントに依頼する user.message を送信してください。実行が開いているセッションを中断するを参照してください。

予算を変更する

新しい 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セント以上高く設定してください。報告される値は丸められており、チェックに使用される正確な消費済みコストをわずかに下回る場合があります。

updated_session = client.beta.sessions.update(
    session.id,
    budget={
        "type": "limit",
        "max_list_cost": {"amount": "500", "currency": "USD"},
    },
)
print(updated_session.budget.max_list_cost.amount)  # 500

予算を削除する

上限を完全に削除するには、budget=None を渡します。予算によって一時停止された作業が再開され、結果として発生する session.updated イベントでは budget が null に設定されています。

unbudgeted_session = client.beta.sessions.update(session.id, budget=None)
print(unbudgeted_session.budget)  # None

支出を監視する

セッションオブジェクトには、その 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 が含まれます。このイベントはイベントリストとセッションストリームに表示されます。セッションは停止理由にかかわらず、アイドルになる直前にこのイベントを1つ発行するため、予算に達したセッションは、予算到達のアイドルイベントの直前に必ずこのイベントを発行します。

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

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

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

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

デプロイメントの予算

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

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

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

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

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

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

エラーリファレンス

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