Orçamentos de sessão

Um orçamento de sessão é um teto rígido opcional de gastos que você define ao criar uma sessão. A plataforma precifica continuamente tudo o que a sessão consome com base nas tarifas públicas de tabela (o custo de tabela da sessão) e para de emitir novas solicitações ao modelo assim que esse custo atinge o orçamento. A solicitação em andamento quando o limite é ultrapassado ainda é concluída, então o custo de tabela final pode ficar uma fração acima do orçamento. Uma sessão que atinge seu orçamento é pausada e fica ociosa em vez de ser encerrada; alterar ou remover o orçamento retoma o trabalho automaticamente. Deployments aceitam o mesmo orçamento e o aplicam a cada sessão que iniciam; consulte Orçamentos em deployments.



Definir um orçamento na criação da sessão

Passe o campo opcional budget ao criar a sessão:

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")

O objeto budget tem dois campos:

• type é sempre "limit".
• max_list_cost é o limite em si: amount é um número inteiro de centavos de dólar americano escrito como uma string sem zeros à esquerda ("2500" é US$ 25,00 e "50" é 50 centavos) e deve ser maior que zero. Formas decimais como "25.00" são rejeitadas. O valor é uma string em vez de um número para que nenhum arredondamento de ponto flutuante seja aplicado a ele. currency é um código de moeda ISO-4217 em maiúsculas; USD é a única moeda suportada.

Um orçamento só pode ser anexado quando a sessão é criada. Adicionar um orçamento a uma sessão existente que não tem um é rejeitado com um erro 400. O limite de uma sessão com orçamento pode ser alterado ou removido a qualquer momento.



Como o custo de tabela é medido

A plataforma precifica o que a sessão consome, continuamente, com base nas tarifas públicas de tabela:

• Tokens de modelo, ao preço de tabela de cada modelo servido
• Buscas na web, a US$ 10 por 1.000 buscas
• Tempo de execução da sessão, a US$ 0,08 por hora

Esse total acumulado em dólares é o custo de tabela da sessão, e é com ele que o orçamento é comparado. O custo de tabela não é o seu preço contratado: se a sua organização negociou descontos, a sessão atinge seu limite quando o total ao preço de tabela o atinge, e o valor cobrado pode ser menor que o limite.

A aplicação do limite usa o custo de tabela exato, sem arredondamento. Os valores de list_cost reportados na sessão e em seus eventos são centavos inteiros, arredondados para o centavo mais próximo, então um valor reportado pode estar até meio centavo acima ou abaixo do valor exato que a aplicação do limite usa.



Quando uma sessão atinge seu orçamento

O limite é aplicado entre solicitações ao modelo, não no meio de uma solicitação. Antes de cada solicitação ao modelo, a plataforma verifica o custo de tabela consumido pela sessão e, assim que esse total atinge o limite, cada thread é pausada antes de sua próxima solicitação. A solicitação que levou o total além do limite foi admitida enquanto a sessão ainda estava abaixo dele e é executada até o fim, então o list_cost registrado de uma sessão pausada fica igual ou uma fração acima de max_list_cost: uma sessão limitada a "50" (50 centavos) pode pausar com um list_cost de "53". Isso é esperado, não um erro de cobrança, e o excedente é limitado a uma solicitação ao modelo por thread. Trate o orçamento como um limite para novo trabalho em vez de um ponto de parada exato, e dimensione o limite levando em conta essa margem de uma solicitação.

Uma sessão que atinge seu orçamento fica ociosa com um stop_reason de budget_reached; ela não é encerrada, e seu histórico e sandbox são preservados como os de qualquer outra sessão ociosa. No stream de eventos você verá, em ordem:

1. Um evento session.thread_status_idle com um stop_reason de budget_reached à medida que cada thread é pausada.
2. Um evento session.usage com o uso cumulativo e o custo de tabela da sessão.
3. Um evento session.status_idle com um stop_reason de budget_reached. O evento de uso sempre precede imediatamente esse evento de ociosidade.

Uma thread cuja solicitação final tanto ultrapassa o limite quanto completa seu turno reporta end_turn em seu próprio evento session.thread_status_idle, enquanto a sessão ainda reporta budget_reached; trate o stop_reason no nível da sessão como o sinal de que a sessão pausou ao atingir seu orçamento.



Eventos aceitos no limite

Enquanto a sessão está no limite ou acima dele, ela aceita apenas eventos que finalizam trabalho já em andamento:

• user.tool_confirmation
• user.tool_result
• user.custom_tool_result
• user.interrupt

Qualquer evento que iniciaria novo trabalho, como user.message, é rejeitado com um erro 400 que lista esses eventos aceitos. Resultados finalizados são registrados sem disparar uma nova solicitação ao modelo; a sessão permanece pausada em seu orçamento.

Um user.interrupt enviado enquanto a sessão está pausada em seu orçamento (todas as threads pausadas no limite) é aceito e ignorado: ele não aparece na lista de eventos e não altera nada. Altere ou remova o orçamento para continuar.



Retomar uma sessão que atingiu seu orçamento

Altere ou remova o orçamento com uma atualização de sessão. Uma atualização aceita retoma automaticamente o trabalho pausado da sessão; nenhuma ação adicional do cliente é necessária.



Alterar o orçamento

Atualize a sessão com um novo max_list_cost. O novo valor pode ser maior ou menor que o limite atual, mas deve ser estritamente maior que o custo de tabela consumido pela sessão; caso contrário, a atualização é rejeitada com um erro 400: budget.max_list_cost must be greater than the session's consumed list cost. Como o custo consumido geralmente fica uma fração acima do limite antigo quando a sessão pausa, baseie o novo valor no usage.list_cost reportado pela sessão, não no max_list_cost antigo. Defina-o um centavo ou mais acima desse valor: o valor reportado é arredondado e pode estar uma fração abaixo do custo consumido exato que a verificação usa.

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



Remover o orçamento

Defina budget como null para remover o limite completamente. O trabalho pausado da sessão é retomado, e o evento session.updated resultante carrega budget definido como 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}'



Monitorar gastos

O objeto de sessão carrega seu budget e um objeto usage com o gasto rastreado: usage.list_cost é o custo de tabela consumido pela sessão, e usage.active_seconds é o tempo de execução sobre o qual seu custo de runtime é precificado. Em uma sessão pausada em budget_reached, espere que usage.list_cost esteja igual ou uma fração acima de max_list_cost: a solicitação que ultrapassou o limite foi concluída antes da pausa. O active_seconds no nível da sessão conta a atividade sobreposta de threads concorrentes apenas uma vez. As respostas de recuperação de thread carregam os mesmos dois campos no usage da própria thread, precificados por thread. Os valores por thread são arredondados independentemente e excluem o custo de tempo de execução da sessão, então não somam exatamente o list_cost da sessão; o valor da sessão é aquele contra o qual o orçamento é aplicado.

O evento session.usage é um instantâneo do uso cumulativo e do custo de tabela rastreado da sessão. Ele carrega os totais de tokens da sessão, list_cost, active_seconds, contagens de solicitações de server_tool_use (web_search_requests, precificadas no custo de tabela por solicitação, e web_fetch_requests, que lê 0 porque solicitações de web fetch não têm cobrança por solicitação e não são medidas), e um eco do budget da sessão, ou null quando a sessão não tem nenhum. Ele aparece na lista de eventos e no stream da sessão. A sessão emite um imediatamente antes de ficar ociosa, qualquer que seja o motivo de parada, então uma sessão que atinge seu orçamento sempre emite um imediatamente antes do evento de ociosidade por orçamento atingido.

Para ler o uso a partir do stream e do objeto de sessão, consulte Rastreamento de uso.



Orçamentos em sessões multiagente

Uma sessão multiagente tem um único orçamento compartilhado entre todas as suas threads; não há limites por thread. O consumo de cada thread é precificado com base em seu próprio modelo servido, e as threads pausam independentemente à medida que o limite compartilhado é atingido. Consultas ao advisor contam para o mesmo orçamento, precificadas às tarifas do modelo do advisor. Uma thread pode pausar em budget_reached enquanto outra finaliza sua solicitação em andamento.

Uma solicitação pendente tem prioridade sobre o limite: uma sessão com uma thread aguardando em requires_action e outra pausada em budget_reached reporta requires_action no nível da sessão. A solicitação pendente ainda precisa de uma resposta, e respondê-la é um evento de finalização que o orçamento não bloqueia.



Orçamentos em deployments

Um deployment aceita o mesmo objeto budget quando você o cria ou atualiza:

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

O limite é copiado para cada sessão que o deployment inicia, então ele limita cada execução separadamente em vez do gasto cumulativo do deployment. Alterar o orçamento do deployment se aplica às sessões que o deployment iniciar depois, não às sessões já em execução. Diferentemente de uma sessão, o orçamento de um deployment pode ser removido com null e definido novamente depois. Consulte Definir um orçamento em cada execução.



Modelos sem preço de tabela

Um orçamento só pode rastrear consumo que a plataforma consegue precificar. Criar uma sessão com orçamento cujo agente, ou qualquer agente ou advisor em sua lista multiagente, usa um modelo sem preço público de tabela é rejeitado com um erro 400 informando que nenhum preço de tabela está disponível para o modelo.

Se o uso de uma sessão com orçamento passar a incluir um modelo sem preço de tabela, o orçamento não pode mais medir o gasto da sessão: a sessão pode pausar com um stop_reason de budget_reached, e alterar o orçamento é rejeitado. Remova o orçamento para retomar a sessão.



Referência de erros

Solicitações relacionadas a orçamento são rejeitadas nos seguintes casos: