Budget di sessione

Un budget di sessione è un tetto di spesa rigido opzionale che imposti quando crei una sessione. La piattaforma calcola continuamente il prezzo di tutto ciò che la sessione consuma alle tariffe di listino pubbliche (il list cost, o costo di listino, della sessione) e smette di emettere nuove richieste al modello una volta che tale costo raggiunge il budget. La richiesta in corso nel momento in cui il tetto viene superato viene comunque completata, quindi il costo di listino finale può attestarsi leggermente oltre il budget. Una sessione che ha raggiunto il proprio budget si mette in pausa e diventa idle (inattiva) anziché terminare; modificare o rimuovere il budget riprende automaticamente il suo lavoro. I deployment accettano lo stesso budget e lo applicano a ogni sessione che avviano; consulta Budget sui deployment.

Imposta un budget alla creazione della sessione

Passa il campo opzionale budget quando crei la sessione:

# Mantieni l'importo tra virgolette così viene inviato come stringa, non come numero.
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)

L'oggetto budget ha due campi:

• type è sempre "limit".
• max_list_cost è il tetto stesso: amount è un numero intero di centesimi di dollaro USA scritto come stringa senza zeri iniziali ("125" corrisponde a $1,25 e "50" a 50 centesimi) e deve essere maggiore di zero. Le forme decimali come "25.00" vengono rifiutate. L'importo è una stringa anziché un numero, in modo che non venga mai applicato alcun arrotondamento in virgola mobile. currency è un codice valuta ISO-4217 in maiuscolo; USD è l'unica valuta supportata.

Un budget può essere associato solo al momento della creazione della sessione. L'aggiunta di un budget a una sessione esistente che non ne ha uno viene rifiutata con un errore 400. Il tetto di una sessione con budget può essere modificato o rimosso in qualsiasi momento.

Come viene misurato il costo di listino

La piattaforma calcola il prezzo di ciò che la sessione consuma, in modo continuo, alle tariffe di listino pubbliche:

• Token del modello, al prezzo di listino di ciascun modello servito
• Ricerche web, a $10 per 1.000 ricerche
• Tempo di esecuzione della sessione, a $0,08 all'ora

Questo totale progressivo in dollari è il costo di listino della sessione, ed è il valore con cui viene confrontato il budget. Il costo di listino non è il tuo prezzo contrattuale: se la tua organizzazione ha negoziato sconti, la sessione raggiunge il proprio tetto quando lo raggiunge il totale a prezzo di listino, e la tua spesa fatturata potrebbe essere inferiore al tetto.

L'applicazione del limite utilizza il costo di listino esatto, non arrotondato. I valori list_cost riportati sulla sessione e sui suoi eventi sono centesimi interi, arrotondati al centesimo più vicino, quindi un valore riportato può discostarsi fino a mezzo centesimo in più o in meno rispetto all'importo esatto utilizzato per l'applicazione del limite.

Quando una sessione raggiunge il proprio budget

Il tetto viene applicato tra una richiesta al modello e l'altra, non a metà richiesta. Prima di ogni richiesta al modello, la piattaforma controlla il costo di listino consumato dalla sessione e, una volta che tale totale raggiunge il tetto, ogni thread si mette in pausa prima della richiesta successiva. La richiesta che ha portato il totale oltre il tetto è stata ammessa mentre la sessione era ancora al di sotto di esso e viene eseguita fino al completamento, quindi il list_cost registrato di una sessione in pausa risulta pari o leggermente superiore a max_list_cost: una sessione con tetto "50" (50 centesimi) può mettersi in pausa con un list_cost di "53". Questo è previsto, non è un errore di fatturazione, e lo sforamento è limitato a una richiesta al modello per thread. Considera il budget come un limite al nuovo lavoro piuttosto che come un punto di arresto esatto, e dimensiona il tetto tenendo presente questo margine di una richiesta.

Una sessione che raggiunge il proprio budget diventa inattiva con uno stop_reason di budget_reached; non viene terminata, e la sua cronologia e la sua sandbox vengono conservate come quelle di qualsiasi altra sessione inattiva. Sul flusso di eventi vedrai, in ordine:

1. Un evento session.thread_status_idle con uno stop_reason di budget_reached man mano che ogni thread si mette in pausa.
2. Un evento session.usage con l'utilizzo cumulativo e il costo di listino della sessione.
3. Un evento session.status_idle con uno stop_reason di budget_reached. L'evento di utilizzo precede sempre immediatamente questo evento di inattività.

Un thread la cui richiesta finale supera il tetto e al tempo stesso completa il proprio turno riporta end_turn sul proprio evento session.thread_status_idle, mentre la sessione riporta comunque budget_reached; considera lo stop_reason a livello di sessione come il segnale che la sessione si è messa in pausa al raggiungimento del budget.

Eventi accettati al raggiungimento del tetto

Mentre la sessione è pari o superiore al proprio budget, accetta solo eventi che concludono il lavoro già in corso:

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

Qualsiasi evento che avvierebbe nuovo lavoro, come user.message, viene rifiutato con un errore 400 che elenca questa lista. I risultati conclusi vengono registrati senza attivare una nuova richiesta al modello; la sessione rimane in pausa al proprio budget.

Un user.interrupt inviato mentre la sessione è in pausa al proprio budget (tutti i thread in pausa al tetto) viene accettato e ignorato: non compare nell'elenco degli eventi e non cambia nulla. Modifica o rimuovi il budget per continuare.

Riprendi una sessione che ha raggiunto il budget

Modifica o rimuovi il budget con un aggiornamento della sessione. Un aggiornamento accettato riprende automaticamente il lavoro in pausa della sessione; non è necessaria alcuna ulteriore azione da parte del client.

Modifica il budget

Aggiorna la sessione con un nuovo max_list_cost. Il nuovo valore può essere superiore o inferiore al tetto attuale, ma deve essere strettamente maggiore del costo di listino consumato dalla sessione; in caso contrario l'aggiornamento viene rifiutato con un errore 400: budget.max_list_cost must be greater than the session's consumed list cost. Poiché il costo consumato si trova solitamente leggermente oltre il vecchio tetto quando la sessione si mette in pausa, basa il nuovo valore sul usage.list_cost riportato dalla sessione, non sul vecchio max_list_cost. Impostalo almeno un centesimo al di sopra di tale valore: il valore riportato è arrotondato e può trovarsi leggermente al di sotto del costo consumato esatto utilizzato dal controllo.

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

Rimuovi il budget

Imposta budget su null per rimuovere completamente il tetto. Il lavoro in pausa della sessione riprende e l'evento session.updated risultante riporta budget impostato su null.

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

Monitora la spesa

L'oggetto sessione riporta il proprio budget e un oggetto usage con la spesa tracciata: usage.list_cost è il costo di listino consumato dalla sessione e usage.active_seconds è il tempo di esecuzione su cui viene calcolato il costo di runtime. Su una sessione in pausa con budget_reached, aspettati che usage.list_cost risulti pari o leggermente superiore a max_list_cost: la richiesta che ha superato il tetto è terminata prima della pausa. Il valore active_seconds a livello di sessione conta una sola volta l'attività sovrapposta di thread concorrenti. Le risposte di recupero dei thread riportano gli stessi due campi nel usage del thread stesso, calcolati per thread. I valori per thread sono arrotondati in modo indipendente ed escludono il costo del tempo di esecuzione della sessione, quindi la loro somma non corrisponde esattamente al list_cost della sessione; il valore della sessione è quello rispetto al quale viene applicato il budget.

L'evento session.usage è un'istantanea dell'utilizzo cumulativo e del costo di listino tracciato della sessione. Riporta i totali dei token della sessione, list_cost, active_seconds, i conteggi delle richieste server_tool_use (web_search_requests, incluse nel costo di listino per richiesta, e web_fetch_requests, che risulta 0 perché le richieste di web fetch non comportano alcun addebito per richiesta e non vengono misurate) e una copia del budget della sessione, oppure null quando la sessione non ne ha uno. Compare nell'elenco degli eventi e nel flusso della sessione. La sessione ne emette uno immediatamente prima di diventare inattiva, qualunque sia il motivo di arresto, quindi una sessione che raggiunge il proprio budget ne emette sempre uno immediatamente prima dell'evento di inattività per budget raggiunto.

Per leggere l'utilizzo dal flusso e dall'oggetto sessione, consulta Tracciamento dell'utilizzo.

Budget nelle sessioni multiagente

Una sessione multiagente ha un unico budget condiviso tra tutti i suoi thread; non esistono tetti per thread. Il consumo di ciascun thread viene calcolato in base al proprio modello servito e i thread si mettono in pausa in modo indipendente man mano che il tetto condiviso viene raggiunto. Le consultazioni dell'advisor vengono conteggiate sullo stesso budget, calcolate alle tariffe del modello advisor. Un thread può mettersi in pausa con budget_reached mentre un altro completa la propria richiesta in corso.

Una richiesta in sospeso ha la precedenza sul tetto: una sessione con un thread in attesa su requires_action e un altro in pausa con budget_reached riporta requires_action a livello di sessione. La richiesta in sospeso necessita comunque di una risposta, e rispondere è un evento di conclusione che il budget non blocca.

Budget sui deployment

Un deployment accetta lo stesso oggetto budget quando lo crei o lo aggiorni:

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

Il tetto viene copiato su ogni sessione avviata dal deployment, quindi limita ogni esecuzione separatamente anziché la spesa cumulativa del deployment. La modifica del budget del deployment si applica alle sessioni che il deployment avvia successivamente, non alle sessioni già in esecuzione. A differenza di una sessione, il budget di un deployment può essere azzerato con null e impostato nuovamente in seguito. Consulta Imposta un budget su ogni esecuzione.

Modelli senza prezzo di listino

Un budget può tracciare solo il consumo di cui la piattaforma può calcolare il prezzo. La creazione di una sessione con budget il cui agente, o qualsiasi agente o advisor nel suo roster multiagente, utilizza un modello senza prezzo di listino pubblico viene rifiutata con un errore 400 che indica che non è disponibile alcun prezzo di listino per il modello.

Se l'utilizzo di una sessione con budget arriva a includere un modello senza prezzo di listino, il budget non può più misurare la spesa della sessione: la sessione può mettersi in pausa con uno stop_reason di budget_reached e la modifica del budget viene rifiutata. Rimuovi il budget per riprendere la sessione.

Riferimento errori

Le richieste relative al budget vengono rifiutate nei seguenti casi: