工作階段預算

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



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

建立工作階段時傳入選用的 budget 欄位：

session=$(curl -fsSL 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": "2500", "currency": "USD"}
  }
}
EOF
)
SESSION_ID=$(jq -r '.id' <<< "$session")

budget 物件有兩個欄位：

• type 一律為 "limit"。
• max_list_cost 是上限本身：amount 是以字串表示的美分整數，不含前導零（"2500" 代表 $25.00，"50" 代表 50 美分），且必須大於零。諸如 "25.00" 之類的小數形式會被拒絕。金額採用字串而非數字，以確保不會對其套用任何浮點數捨入。currency 是大寫的 ISO-4217 貨幣代碼；USD 是唯一支援的貨幣。

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



牌價成本的計算方式

平台會持續以公開牌價計算工作階段所消耗的費用：

• 模型 token，依每個所使用模型的牌價計算
• 網頁搜尋，每 1,000 次搜尋 $10
• 工作階段執行時間，每小時 $0.08

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

強制執行時使用的是精確、未捨入的牌價成本。工作階段及其事件上回報的 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 事件。使用量事件一律緊接在此閒置事件之前。

若某執行緒的最後一個請求同時超過上限並完成其回合，該執行緒自身的 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。請將其設定為比該數值高出一美分或更多：回報的值經過捨入，可能略低於檢查所使用的精確已消耗成本。

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 @- <<'EOF'
{
  "budget": {
    "type": "limit",
    "max_list_cost": {"amount": "4000", "currency": "USD"}
  }
}
EOF



移除預算

將 budget 設為 null 以完全移除上限。工作階段已暫停的工作會恢復，而產生的 session.updated 事件會帶有設為 null 的 budget。

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": null}'



監控支出

工作階段物件帶有其 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。它會出現在事件清單和工作階段串流中。工作階段在進入閒置狀態前會立即發出一個此事件，無論停止原因為何，因此達到預算的工作階段一律會在 budget-reached 閒置事件前立即發出一個。

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



多代理工作階段中的預算

多代理工作階段具有單一預算，由其所有執行緒共用；沒有個別執行緒的上限。每個執行緒的消耗依其自身所使用的模型計價，且執行緒會在達到共用上限時各自獨立暫停。Advisor（顧問）諮詢會計入同一預算，依顧問模型的費率計價。一個執行緒可能在 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 暫停，且變更預算會被拒絕。請移除預算以恢復工作階段。



錯誤參考

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