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, 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 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ò 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à.

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 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 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 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.

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

Imposta budget su null per rimuovere completamente il tetto. Il lavoro messo in pausa dal budget 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 è terminata prima della pausa. Il valore