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 il lavoro messo in pausa dal budget. 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:

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

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, così non gli viene 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 USD per 1.000 ricerche
• Tempo di esecuzione della sessione, a $0,08 USD 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ò differire fino a mezzo centesimo, in più o in meno, dall'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à di una 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 quando la sessione era ancora al di sotto di esso e viene eseguita fino al completamento, quindi il valore 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 comportamento è previsto e non è un errore di fatturazione. La spesa per il modello oltre il tetto è al massimo il costo di una richiesta al modello per ciascun thread. Le chiamate agli strumenti presenti nella risposta a quella richiesta vengono comunque eseguite, e anche le relative ricerche web e il tempo di esecuzione contano ai fini del costo di listino. Considera il budget come un limite al nuovo lavoro piuttosto che come un punto di arresto esatto, e dimensiona il tetto tenendo conto di questo margine.

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

1. Un evento session.thread_status_idle con uno stop_reason pari a budget_reached man mano che ciascun 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 pari a budget_reached. L'evento di utilizzo precede sempre immediatamente questo evento di inattività.

Se sono aperte delle esecuzioni di workflow, ciascuna che non sia già inattiva riceve anche un evento workflow_run.status_idle.

Un thread la cui richiesta finale supera il tetto e al contempo 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 raggiungimento del budget (tutti i thread in pausa al tetto) viene accettato e non compare nell'elenco degli eventi. Non ferma alcun thread, perché ogni thread è già in pausa. Modifica o rimuovi il budget per continuare.

Se la sessione ha esecuzioni di workflow aperte, l'interruzione può metterle in pausa, come può fare un'interruzione in qualsiasi altro momento. Un'esecuzione messa in pausa da un'interruzione non riprende quando modifichi o rimuovi il budget. Per continuarla, modifica o rimuovi il budget, quindi invia un user.message chiedendo all'agente di continuare le sue esecuzioni.

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 messo in pausa dal budget; non è necessaria alcuna ulteriore azione da parte del client.

Ogni esecuzione di workflow messa in pausa dal budget riceve anche un evento workflow_run.status_running. Un'esecuzione messa in pausa da un'interruzione, anche da un'interruzione inviata mentre la sessione era al proprio budget, rimane in pausa e non riceve alcun evento workflow_run.status_running dall'aggiornamento. Per continuarla, invia un user.message chiedendo all'agente di continuare le sue esecuzioni. Consulta Interrompere una sessione con esecuzioni aperte.

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 di solito si trova 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 quel valore: il valore riportato è arrotondato e può trovarsi leggermente al di sotto del costo consumato esatto utilizzato dal controllo.

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

Rimuovi il budget

Passa budget=None per rimuovere completamente il tetto. Il lavoro che il budget aveva messo in pausa riprende, e l'evento session.updated risultante riporta budget impostato su null.

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

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 è stata completata 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, con prezzo calcolato 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, il cui prezzo è incluso nel costo di listino per richiesta, e web_fetch_requests, che riporta 0 perché le richieste di web fetch non hanno alcun addebito per richiesta e non vengono misurate), e il budget della sessione, se la sessione 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 dell'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 Monitorare l'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 vincola ciascuna 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 cancellato con budget=None e reimpostato in seguito. Consulta Impostare un budget per ogni esecuzione.

Modelli senza prezzo di listino

Un budget può tracciare solo il consumo di cui la piattaforma è in grado di calcolare il prezzo. La creazione di una sessione con budget il cui agente, o qualsiasi agente elencato nella lista predefined_agents di subagents o workflows, o l'advisor impostato nella sua configurazione 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 è più in grado di misurare la spesa della sessione: la sessione può mettersi in pausa con uno stop_reason pari a 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: