会话预算

"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 错误。已设置预算的会话可以随时更改或移除其上限。



标价成本的计量方式

平台会持续按公开标价对会话消耗的内容进行计价：

• 模型令牌，按每个所用模型的标价计算
• 网络搜索，每 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 事件。使用量事件始终紧接在此空闲事件之前。

如果某个线程的最后一个请求既超过了上限又完成了其轮次，则该线程自己的 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 事件中 budget 会被设置为 null。

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 事件是会话累计使用量和已跟踪标价成本的快照。它包含会话的令牌总数、list_cost、active_seconds、server_tool_use 请求计数（web_search_requests 按每次请求计入标价成本；web_fetch_requests 读数为 0，因为网络抓取请求不收取每次请求费用且不计量），以及会话 budget 的回显（当会话没有预算时为 null）。它会出现在事件列表和会话流中。无论停止原因为何，会话都会在进入空闲状态之前立即发出一个此类事件，因此达到预算的会话总会在因达到预算而产生的空闲事件之前立即发出一个。

有关从流和会话对象读取使用量的信息，请参阅跟踪使用量。



多智能体会话中的预算

多智能体（multiagent）会话在其所有线程之间共享单一预算；没有每线程上限。每个线程的消耗按其自己所用的模型计价，当达到共享上限时，各线程独立暂停。顾问（advisor）咨询计入同一预算，按顾问模型的费率计价。一个线程可能在 budget_reached 处暂停，而另一个线程正在完成其进行中的请求。

待处理的询问优先于上限：如果会话中一个线程正在等待 requires_action，而另一个线程在 budget_reached 处暂停，则会话级别报告 requires_action。待处理的请求仍需要回应，而回应它属于预算不会阻止的结算事件。



部署上的预算

部署（deployment）在创建或更新时接受相同的 budget 对象：

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

该上限会被复制到部署启动的每个会话上，因此它分别限制每次运行，而非部署的累计支出。更改部署的预算会应用于部署此后启动的会话，而不会应用于已在运行的会话。与会话不同，部署的预算可以用 null 清除，之后可以再次设置。请参阅为每次运行设置预算。



没有标价的模型

预算只能跟踪平台能够计价的消耗。如果创建的带预算会话的智能体，或其多智能体名单上的任何智能体或顾问，使用了没有公开标价的模型，则创建请求会被拒绝，并返回说明该模型没有可用标价的 400 错误。

如果带预算会话的使用量开始包含没有标价的模型，预算将无法再衡量会话的支出：会话可能会以 stop_reason 为 budget_reached 暂停，且更改预算会被拒绝。请移除预算以恢复会话。



错误参考

在以下情况下，与预算相关的请求会被拒绝：