Orçamentos de sessão

Um "session budget" (orçamento de sessão) é um teto rígido de gasto opcional que você define ao criar uma sessão. A plataforma precifica continuamente tudo o que a sessão consome às tarifas públicas de lista (o "list cost", ou custo de lista, da sessão) e para de emitir novas requisições ao modelo quando esse custo atinge o orçamento. A requisição em andamento quando o teto é ultrapassado ainda é concluída, portanto o custo de lista final pode ficar uma fração acima do orçamento. Uma sessão que atinge seu orçamento pausa e fica ociosa em vez de ser encerrada; alterar ou remover o orçamento retoma seu trabalho automaticamente. Implantações aceitam o mesmo orçamento e o aplicam a cada sessão que iniciam; consulte Orçamentos em implantações.

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

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

# Mantenha o valor entre aspas para que seja enviado como string, não como número.
SESSION_ID=$(ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID" \
  --budget '{type: limit, max_list_cost: {amount: "125", currency: USD}}' \
  --transform id --raw-output)

O objeto budget tem dois campos:

• type é sempre "limit".
• max_list_cost é o teto em si: amount é um número inteiro de centavos de dólar americano escrito como string sem zeros à esquerda ("125" é $1,25 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 teto de uma sessão com orçamento pode ser alterado ou removido a qualquer momento.

Como o custo de lista é medido

A plataforma precifica o que a sessão consome, continuamente, às tarifas públicas de lista:

• Tokens do modelo, ao preço de lista de cada modelo servido
• Pesquisas na web, a $10 por 1.000 pesquisas
• Tempo de execução da sessão, a $0,08 por hora

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

A aplicação usa o custo de lista 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, portanto um valor reportado pode ficar até meio centavo acima ou abaixo do valor exato que a aplicação usa.

Quando uma sessão atinge seu orçamento

O teto é aplicado entre requisições ao modelo, não no meio de uma requisição. Antes de cada requisição ao modelo, a plataforma verifica o custo de lista consumido pela sessão e, quando esse total atinge o teto, cada thread pausa antes de sua próxima requisição. A requisição que levou o total além do teto foi admitida enquanto a sessão ainda estava abaixo dele e é executada até a conclusão, portanto o list_cost registrado de uma sessão pausada fica igual ou uma fração acima de max_list_cost: uma sessão com teto de "50" (50 centavos) pode pausar com um list_cost de "53". Isso é esperado, não um erro de faturamento, e o excedente é limitado a uma requisição ao modelo por thread. Trate o orçamento como um limite para novos trabalhos em vez de um ponto de parada exato, e dimensione o teto tendo em mente essa margem de uma requisiçã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 fluxo de eventos você verá, em ordem:

1. Um evento session.thread_status_idle com um stop_reason de budget_reached à medida que cada thread pausa.
2. Um evento session.usage com o uso acumulado e o custo de lista 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 requisição final tanto ultrapassa o teto quanto conclui 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 em seu orçamento.

Eventos aceitos no teto

Enquanto a sessão está no orçamento ou acima dele, ela aceita apenas eventos que resolvem 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 nomeia essa lista. Resultados resolvidos são registrados sem disparar uma nova requisiçã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 teto) é 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 em seu orçamento

Altere ou remova o orçamento com uma atualização da 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 teto atual, mas deve ser estritamente maior que o custo de lista 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 teto 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 ficar uma fração abaixo do custo consumido exato que a verificação usa.

ant beta:sessions update \
  --session-id "$SESSION_ID" \
  --budget '{type: limit, max_list_cost: {amount: "500", currency: USD}}'

Remover o orçamento

Defina budget como null para remover o teto completamente. O trabalho pausado da sessão é retomado, e o evento session.updated resultante traz budget definido como null.

ant beta:sessions update --session-id "$SESSION_ID" --budget null

Monitorar o gasto

O objeto da sessão traz seu budget e um objeto usage com o gasto rastreado: usage.list_cost é o custo de lista consumido pela sessão, e usage.active_seconds é o tempo de execução sobre o qual seu custo de tempo de execução é precificado. Em uma sessão pausada em budget_reached, espere que usage.list_cost fique igual ou uma fração acima de max_list_cost: a requisição que ultrapassou o teto terminou antes da pausa. O active_seconds no nível da sessão conta uma única vez a atividade sobreposta de threads concorrentes. As respostas de recuperação de thread trazem os mesmos dois campos no próprio usage da thread, precificados por thread. Os valores por thread são arredondados independentemente e excluem o custo de tempo de execução da sessão, portanto 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 acumulado e do custo de lista rastreado da sessão. Ele traz os totais de tokens da sessão, list_cost, active_seconds, contagens de requisições server_tool_use (web_search_requests, precificadas no custo de lista por requisição, e web_fetch_requests, que mostra 0 porque requisições de web fetch não têm cobrança por requisição e não são medidas), e um eco do budget da sessão, ou null quando a sessão não tem um. 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, portanto 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 da sessão, consulte Rastreando o 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á tetos por thread. O consumo de cada thread é precificado em seu próprio modelo servido, e as threads pausam independentemente à medida que o teto compartilhado é atingido. Consultas ao advisor contam contra o mesmo orçamento, precificadas às tarifas do modelo advisor. Uma thread pode pausar em budget_reached enquanto outra termina sua requisição em andamento.

Uma solicitação pendente tem precedência sobre o teto: 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 requisição pendente ainda precisa de uma resposta, e respondê-la é um evento de resolução que o orçamento não bloqueia.

Orçamentos em implantações

Uma "deployment" (implantação) aceita o mesmo objeto budget quando você a cria ou atualiza:

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

O teto é copiado para cada sessão que a implantação inicia, portanto ele limita cada execução separadamente em vez do gasto acumulado da implantação. Alterar o orçamento da implantação se aplica às sessões que a implantação inicia depois disso, não às sessões já em execução. Diferentemente de uma sessão, o orçamento de uma implantação pode ser limpo com null e definido novamente mais tarde. Consulte Definir um orçamento em cada execução.

Modelos sem preço de lista

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

Se o uso de uma sessão com orçamento passar a incluir um modelo sem preço de lista, 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

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