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 o trabalho que o orçamento pausou. 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:

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

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" equivale a $1,25 e "50" equivale a 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 USD por 1.000 pesquisas
• Tempo de execução da sessão, a $0,08 USD 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 do teto usa o custo de lista exato, sem arredondamento. Os valores de list_cost informados na sessão e em seus eventos são centavos inteiros, arredondados para o centavo mais próximo, então um valor informado pode diferir em até meio centavo, para mais ou para menos, do valor exato usado na aplicação do teto.

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, assim que esse total atinge o teto, cada thread é pausada 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é 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 com teto de "50" (50 centavos) pode ser pausada com um list_cost de "53". Isso é esperado, não um erro de cobrança. O gasto com o modelo além do teto é, no máximo, o custo de uma requisição ao modelo para cada thread. As chamadas de ferramentas na resposta dessa requisição ainda são executadas, e suas pesquisas na web e seu tempo de execução também contam para o custo de lista. Trate o orçamento como um limite para novos trabalhos, e não como um ponto de parada exato, e dimensione o teto levando essa margem em consideraçã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á, nesta 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 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.

Se houver execuções de workflow abertas, cada uma que ainda não esteja ociosa também recebe um evento workflow_run.status_idle.

Uma thread cuja requisição final tanto ultrapassa o teto quanto conclui seu turno informa end_turn em seu próprio evento session.thread_status_idle, enquanto a sessão ainda informa budget_reached; trate o stop_reason no nível da sessão como o sinal de que a sessão foi pausada 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 não aparece na lista de eventos. Ele não para nenhuma thread, porque todas as threads já estão pausadas. Altere ou remova o orçamento para continuar.

Se a sessão tiver execuções de workflow abertas, a interrupção pode pausá-las, como uma interrupção em qualquer outro momento também pode. Uma execução que uma interrupção pausou não é retomada quando você altera ou remove o orçamento. Para continuá-la, altere ou remova o orçamento e, em seguida, envie uma user.message pedindo ao agente que continue suas execuções.

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 que o orçamento pausou; nenhuma ação adicional do cliente é necessária.

Cada execução de workflow que o orçamento pausou também recebe um evento workflow_run.status_running. Uma execução que uma interrupção pausou, mesmo uma interrupção enviada enquanto a sessão estava em seu orçamento, permanece pausada e não recebe nenhum evento workflow_run.status_running como resultado da atualização. Para continuá-la, envie uma user.message pedindo ao agente que continue suas execuções. Consulte Interromper uma sessão com execuções abertas.

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 é pausada, baseie o novo valor no usage.list_cost informado pela sessão, e não no max_list_cost antigo. Defina-o um centavo ou mais acima desse valor: o valor informado é arredondado e pode ficar uma fração abaixo do custo consumido exato que a verificação usa.

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

Remover o orçamento

Passe budget=None para remover o teto completamente. O trabalho que o orçamento pausou é retomado, e o evento session.updated resultante traz budget definido como null.

unbudgeted_session = client.beta.sessions.update(session.id, budget=None)
print(unbudgeted_session.budget)  # None

Monitorar o gasto

O objeto da sessão traz seu budget e um objeto usage com os gastos rastreados: 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 foi concluída 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 threads trazem os mesmos dois campos no próprio usage da thread, precificados por thread. Os valores por thread são arredondados de forma independente 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 com base no qual o orçamento é aplicado.

O evento session.usage é um snapshot 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, as contagens de requisições de server_tool_use (web_search_requests, precificado 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 o budget da sessão, se a sessão tiver 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 da 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 da sessão, consulte Acompanhar 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, então ele limita cada execução separadamente, e não o gasto acumulado da implantação. Alterar o orçamento da implantação se aplica às sessões que a implantação iniciar depois, não às sessões já em execução. Diferentemente de uma sessão, o orçamento de uma implantação pode ser removido com budget=None 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 listado na lista predefined_agents de subagents ou workflows, ou o advisor definido em sua configuração multiagente, use 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 consegue mais medir os gastos da sessão: a sessão pode ser pausada com um stop_reason de budget_reached, e a alteração do orçamento é rejeitada. 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: