Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Un budget di sessione è un tetto massimo di spesa 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 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 quando il limite viene superato viene comunque completata, quindi il costo di listino finale può risultare leggermente superiore al budget. Una sessione che raggiunge il suo budget si mette in pausa e diventa inattiva anziché terminare; modificare o rimuovere il budget ne riprende automaticamente il lavoro. I deployment accettano lo stesso budget e lo applicano a ogni sessione che avviano; consulta Budget sui deployment.
Passa il campo opzionale budget quando crei la sessione:
session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d @- <<EOF
{
"agent": "$AGENT_ID",
"environment_id": "$ENVIRONMENT_ID",
"budget": {
"type": "limit",
"max_list_cost": {"amount": "2500", "currency": "USD"}
}
}
EOF
)
SESSION_ID=$(jq -r '.id' <<< "$session")L'oggetto budget ha due campi:
type è sempre "limit".max_list_cost è il limite stesso: amount è un numero intero di centesimi di dollaro USA scritto come stringa senza zeri iniziali ("2500" equivale a $25,00 e "50" equivale a 50 centesimi) e deve essere maggiore di zero. 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 quando la sessione viene creata. L'aggiunta di un budget a una sessione esistente che non ne ha uno viene rifiutata con un errore 400. Il limite di una sessione con budget può essere modificato o rimosso in qualsiasi momento.
La piattaforma calcola il prezzo di ciò che la sessione consuma, continuamente, alle tariffe di listino pubbliche:
Questo totale progressivo in dollari è il costo di listino della sessione, ed è ciò con cui il budget viene confrontato. Il costo di listino non è il tuo prezzo contrattuale: se la tua organizzazione ha negoziato sconti, la sessione raggiunge il suo limite quando lo fa il totale al prezzo di listino, e la spesa fatturata potrebbe essere inferiore al limite.
L'applicazione del limite utilizza il costo di listino esatto, non arrotondato. I valori list_cost riportati sulla sessione e sui suoi eventi sono in 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.
Il limite viene applicato tra le richieste al modello, non durante una richiesta. Prima di ogni richiesta al modello, la piattaforma verifica il costo di listino consumato dalla sessione, e una volta che tale totale raggiunge il limite ogni thread si mette in pausa prima della sua richiesta successiva. La richiesta che ha portato il totale oltre il limite è stata ammessa mentre la sessione era ancora 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 limitata a "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 sul nuovo lavoro piuttosto che un punto di arresto esatto, e dimensiona il limite tenendo conto di quel margine di una richiesta.
Una sessione che raggiunge il suo budget diventa inattiva con uno stop_reason di budget_reached; non viene terminata, e la sua cronologia e sandbox vengono preservate come quelle di qualsiasi altra sessione inattiva. Sullo stream di eventi vedrai, nell'ordine:
session.thread_status_idle con uno stop_reason di budget_reached man mano che ogni thread si mette in pausa.session.usage con l'utilizzo cumulativo e il costo di listino della sessione.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 limite e completa il suo 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.
Mentre la sessione è al limite o oltre il suo budget, accetta solo eventi che concludono lavoro già in corso:
user.tool_confirmationuser.tool_resultuser.custom_tool_resultuser.interruptQualsiasi evento che avvierebbe nuovo lavoro, come user.message, viene rifiutato con un errore 400 che elenca questi eventi accettati. I risultati conclusi vengono registrati senza attivare una nuova richiesta al modello; la sessione rimane in pausa al suo budget.
Un user.interrupt inviato mentre la sessione è in pausa al suo budget (tutti i thread in pausa al limite) viene accettato e ignorato: non appare nell'elenco degli eventi e non cambia nulla. Modifica o rimuovi il budget per continuare.
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.
Aggiorna la sessione con un nuovo max_list_cost. Il nuovo valore può essere superiore o inferiore al limite attuale, ma deve essere strettamente maggiore del costo di listino consumato dalla sessione; altrimenti 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 limite 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 a un centesimo o più sopra quel valore: il valore riportato è arrotondato e può trovarsi leggermente al di sotto del costo consumato esatto utilizzato dal controllo.
curl -sS --fail-with-body "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d @- <<'EOF'
{
"budget": {
"type": "limit",
"max_list_cost": {"amount": "4000", "currency": "USD"}
}
}
EOFImposta budget su null per rimuovere completamente il limite. Il lavoro in pausa della sessione riprende, e l'evento session.updated risultante riporta budget impostato su null.
curl -sS --fail-with-body "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d '{"budget": null}'L'oggetto sessione contiene il suo 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 limite è 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 contengono gli stessi due campi nel usage del thread stesso, calcolati per thread. I valori per thread sono arrotondati indipendentemente ed escludono il costo del tempo di esecuzione della sessione, quindi non sommano 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. Contiene i totali dei token della sessione, list_cost, active_seconds, i conteggi delle richieste server_tool_use (web_search_requests, incluso nel costo di listino per richiesta, e web_fetch_requests, che riporta 0 perché le richieste di web fetch non comportano alcun addebito per richiesta e non vengono misurate), e una copia del budget della sessione, o null quando la sessione non ne ha uno. Appare nell'elenco degli eventi e nello stream della sessione. La sessione ne emette uno immediatamente prima di diventare inattiva, qualunque sia il motivo di arresto, quindi una sessione che raggiunge il suo budget ne emette sempre uno immediatamente prima dell'evento di inattività per budget raggiunto.
Per leggere l'utilizzo dallo stream e dall'oggetto sessione, consulta Tracciamento dell'utilizzo.
Una sessione multiagente ha un singolo budget condiviso tra tutti i suoi thread; non esistono limiti per thread. Il consumo di ogni thread viene calcolato al prezzo del proprio modello servito, e i thread si mettono in pausa indipendentemente man mano che il limite 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 sua richiesta in corso.
Una richiesta in sospeso ha priorità sul limite: 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 ad essa è un evento di conclusione che il budget non blocca.
Un deployment accetta lo stesso oggetto budget quando lo crei o lo aggiorni:
{
"budget": {
"type": "limit",
"max_list_cost": { "amount": "2000", "currency": "USD" }
}
}Il limite viene copiato su ogni sessione che il deployment avvia, 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 rimosso con null e impostato nuovamente in seguito. Consulta Impostare un budget su ogni esecuzione.
Un budget può tracciare solo il consumo che la piattaforma può prezzare. 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.
Le richieste relative al budget vengono rifiutate nei seguenti casi:
| Condizione | Stato |
|---|---|
Un evento che avvia lavoro (ad esempio, user.message) viene inviato mentre la sessione è al limite o oltre il suo budget; l'errore elenca gli eventi di conclusione accettati | 400 |
| Il budget viene impostato a un valore pari o inferiore al costo di listino consumato dalla sessione | 400 |
| Un budget viene aggiunto a una sessione creata senza, o riaggiunto dopo la rimozione | 400 |
amount non è un numero intero di centesimi (ad esempio, "25.00"), è zero o negativo, oppure currency non è USD | 400 |
| Una creazione con budget fa riferimento a un modello senza prezzo di listino pubblico | 400 |
Was this page helpful?