工作階段預算

工作階段預算（session budget）是您在建立工作階段時可選擇設定的硬性支出上限。平台會持續以公開定價計算工作階段所消耗的一切資源（即工作階段的 list cost（定價成本）），並在該成本達到預算時停止發出新的模型請求。在超過上限當下正在進行中的請求仍會完成，因此最終的定價成本可能會略為超出預算。達到預算的工作階段會暫停並進入閒置狀態，而不會終止；變更或移除預算即可恢復因預算而暫停的工作。部署（deployment）也接受相同的預算，並將其套用至其啟動的每個工作階段；請參閱部署上的預算。

在建立工作階段時設定預算

在建立工作階段時傳入可選的 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 物件有兩個欄位：

• type 一律為 "limit"。
• max_list_cost 即為上限本身：amount 是以美分為單位的整數，以不含前導零的字串表示（"125" 為 $1.25 美元，"50" 為 50 美分），且必須大於零。"25.00" 之類的小數形式會被拒絕。金額使用字串而非數字，因此永遠不會套用浮點數捨入。currency 是大寫的 ISO-4217 貨幣代碼；USD 是唯一支援的貨幣。

預算只能在建立工作階段時附加。為原本沒有預算的既有工作階段新增預算會被拒絕並回傳 400 錯誤。已設定預算的工作階段，其上限可隨時變更或移除。

定價成本的計算方式

平台會持續以公開定價費率為工作階段所消耗的項目計價：

• 模型 token，依各個實際服務模型的定價
• 網頁搜尋，每 1,000 次搜尋 $10 美元
• 工作階段執行時間，每小時 $0.08 美元

這個累計的美元總額即為工作階段的 list cost（定價成本），也是預算所比對的對象。定價成本並非您的合約價格：如果您的組織已協商折扣，工作階段會在定價總額達到上限時達到上限，而您實際計費的支出可能低於該上限。

強制執行使用的是精確、未經捨入的定價成本。工作階段及其事件上回報的 list_cost 數值為整數美分，四捨五入至最接近的美分，因此回報的數值與強制執行所用的精確金額之間，可能相差最多半美分。

當工作階段達到預算時

上限是在模型請求之間強制執行，而非在請求進行中。在每次模型請求之前，平台會檢查工作階段已消耗的定價成本，一旦總額達到上限，每個執行緒都會在下一次請求前暫停。使總額超過上限的那個請求，是在工作階段仍低於上限時被允許的，因此會執行至完成。因此，已暫停工作階段所記錄的 list_cost 會等於或略為超過 max_list_cost。例如，上限為 "50"（50 美分）的工作階段，可能在 list_cost 為 "53" 時暫停。這是預期行為，並非計費錯誤。超過上限的模型支出，最多為每個執行緒一次模型請求的成本。該請求回應中的工具呼叫仍會執行，其網頁搜尋與執行時間也會計入定價成本。請將預算視為對新工作的限制，而非精確的停止點，並在設定上限時考量此餘裕。

達到預算的工作階段會進入閒置狀態，其 stop_reason 為 budget_reached；它不會被終止，其歷史記錄與沙箱會像其他閒置工作階段一樣被保留。在事件串流上，您會依序看到：

1. 每個執行緒暫停時，一個 stop_reason 為 budget_reached 的 session.thread_status_idle 事件。
2. 一個 session.usage 事件，包含工作階段的累計用量與定價成本。
3. 一個 stop_reason 為 budget_reached 的 session.status_idle 事件。用量事件一律緊接在此閒置事件之前。

如果有開啟中的工作流程執行，每個尚未閒置的執行也會收到一個 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。由於工作階段暫停時，已消耗的成本通常會略微超過舊上限，請以工作階段回報的 usage.list_cost 為基準設定新值，而非舊的 max_list_cost。請將其設定為比該數值高出一美分或更多：回報的數值經過捨入，可能略低於檢查所使用的精確已消耗成本。

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 對並行執行緒的重疊活動只計算一次。執行緒擷取回應會在執行緒自己的 usage 上帶有相同的兩個欄位，並依每個執行緒計價。每個執行緒的數值會獨立捨入，且不包含工作階段的執行時間成本，因此加總不會恰好等於工作階段的 list_cost；預算是以工作階段的數值為準來強制執行。

session.usage 事件是工作階段累計用量與所追蹤定價成本的快照。它帶有工作階段的 token 總數、list_cost、active_seconds、server_tool_use 請求次數（web_search_requests，按每次請求計入定價成本；以及 web_fetch_requests，其值為 0，因為網頁擷取請求不收取每次請求費用，也不會被計量），以及工作階段的 budget（若工作階段有設定）。它會出現在事件清單與工作階段串流中。無論停止原因為何，工作階段都會在進入閒置前立即發出一個此事件，因此達到預算的工作階段一律會在預算已達的閒置事件之前立即發出一個此事件。

若要從串流和工作階段物件讀取用量，請參閱追蹤用量。

多代理工作階段中的預算

多代理工作階段有單一預算，由其所有執行緒共用；沒有個別執行緒的上限。每個執行緒的消耗按其實際服務的模型計價，而當共用上限達到時，各執行緒會獨立暫停。顧問諮詢也計入同一預算，並按顧問模型的費率計價。一個執行緒可能在 budget_reached 時暫停，而另一個執行緒則完成其進行中的請求。

待處理的詢問優先於上限：若工作階段有一個執行緒正在等待 requires_action，而另一個執行緒在 budget_reached 暫停，則工作階段層級會回報 requires_action。待處理的請求仍需要回答，而回答它屬於預算不會阻擋的結算事件。

部署上的預算

部署在您建立或更新它時接受相同的 budget 物件：

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

上限會被複製到部署所啟動的每個工作階段上，因此它分別限制每次執行，而非部署的累計支出。變更部署的預算會套用至部署之後啟動的工作階段，而不會套用至已在執行中的工作階段。與工作階段不同，部署的預算可以用 budget=None 清除，之後再重新設定。請參閱為每次執行設定預算。

沒有定價的模型

預算只能追蹤平台能夠計價的消耗。若以下任一項目使用沒有公開定價的模型，建立設有預算的工作階段會以 400 錯誤被拒絕：

• 工作階段的代理
• 列在 subagents 或 workflows 的 predefined_agents 清單中的任何代理
• 在代理的多代理設定中設定的顧問

錯誤訊息會指出該模型沒有可用的定價。

如果已設定預算的工作階段的用量開始包含沒有定價的模型，預算將無法再衡量工作階段的支出：工作階段可能會以 budget_reached 的 stop_reason 暫停，且變更預算會被拒絕。請移除預算以恢復工作階段。

錯誤參考

與預算相關的請求在下列情況下會被拒絕：

可用性