工作階段預算

「Session budget」（工作階段預算）是您在建立工作階段時可選擇設定的硬性支出上限。平台會持續以公開定價費率為工作階段所消耗的一切計價（即工作階段的 list cost（定價成本）），並在該成本達到預算時停止發出新的模型請求。跨越上限時正在進行中的請求仍會完成，因此最終的定價成本可能會略微超出預算。達到預算的工作階段會暫停並進入 idle（閒置）狀態，而非終止；變更或移除預算會自動恢復其工作。部署（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 數值為整數美分，四捨五入至最接近的美分，因此回報的數值與強制執行所使用的精確金額之間，可能有最多半美分的上下差距。

當工作階段達到預算時

上限是在模型請求之間強制執行，而非在請求進行中。在每次模型請求之前，平台會檢查工作階段已消耗的定價成本，一旦該總額達到上限，每個執行緒（thread）都會在其下一次請求之前暫停。使總額超過上限的那個請求是在工作階段仍低於上限時被接受的，並會執行至完成，因此已暫停工作階段所記錄的 list_cost 會等於或略微超過 max_list_cost：上限為 "50"（50 美分）的工作階段可能以 "53" 的 list_cost 暫停。這是預期行為，而非計費錯誤，且超出量以每個執行緒一次模型請求為界。請將預算視為對新工作的限制，而非精確的停止點，並在設定上限大小時將這一次請求的餘裕納入考量。

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

1. 每個執行緒暫停時，一個 stop_reason 為 budget_reached 的 session.thread_status_idle 事件。
2. 一個 session.usage 事件，包含工作階段的累計用量與定價成本。
3. 一個 stop_reason 為 budget_reached 的 session.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 會被接受並忽略：它不會出現在事件清單中，也不會改變任何事情。請變更或移除預算以繼續。

恢復達到預算的工作階段

透過工作階段更新來變更或移除預算。被接受的更新會自動恢復工作階段已暫停的工作；用戶端無需採取進一步動作。

變更預算

以新的 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 設為 null 以完全移除上限。工作階段已暫停的工作會恢復，而產生的 session.updated 事件會帶有設為 null 的 budget。

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 的回顯，若工作階段沒有預算則為 null。它會出現在事件清單與工作階段串流中。無論停止原因為何，工作階段都會在進入閒置狀態之前立即發出一個此事件，因此達到預算的工作階段一律會在達到預算的閒置事件之前立即發出一個。

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

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

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

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

部署上的預算

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

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

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

沒有定價的模型

預算只能追蹤平台能夠計價的消耗。若建立已設定預算的工作階段時，其代理、或其多代理名冊上的任何代理或顧問使用了沒有公開定價的模型，則會被拒絕並回傳 400 錯誤，指出該模型沒有可用的定價。

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

錯誤參考

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