Come controllare i costi di un agente AI su VPS

Come evitare che un agente AI sempre attivo faccia aumentare i costi

Il controllo dei costi di un agente AI su un VPS (virtual private server) si basa su limiti impostati prima dell'avvio dell'agente, perché durante l'esecuzione nessuno controlla il contatore dei consumi. Limita ogni risposta con max_tokens, imposta nel tuo codice un numero massimo di iterazioni del ciclo, memorizza nella cache la parte del prompt che non cambia mai e registra i dati di utilizzo di ogni risposta per individuare quale attività genera la spesa. Il noleggio del server ha un prezzo mensile fisso. L'API del modello applica invece una tariffa in base ai token, e un ciclo non supervisionato può consumare token rapidamente senza attirare attenzione.

Si presuppone che l'agente sia già disponibile e chiami la Messages API da un server che controlli. Creare un agente AI con Claude su un VPS descrive la configurazione dell'agente.

Perché un agente non presidiato ha una struttura dei costi diversa

In una sessione interattiva è presente una persona. Se il modello segue una direzione errata o legge un log di 40,000 righe, la persona che lo controlla lo interrompe. Un agente non presidiato non ha questo meccanismo di arresto: continua a funzionare fino al termine del ciclo, quindi un timer lo avvia di nuovo.

La frequenza è il moltiplicatore che spesso viene trascurato. Un job pianificato ogni cinque minuti viene eseguito 288 volte al giorno e circa 8,640 volte al mese. Qualunque sia il costo di una singola esecuzione, questo è il valore da moltiplicare. Molti agenti "always-on" non devono essere attivi continuamente. Devono rispondere entro un determinato numero di minuti. Questo è un requisito di pianificazione.

Un agente sostiene inoltre costi che una finestra di chat non ha.

• Le definizioni degli strumenti vengono incluse in ogni richiesta. Il system prompt per l'utilizzo degli strumenti costa 290 token su Claude Opus 4.8 con tool_choice di auto o none, e 410 con any o tool. Lo strumento bash aggiunge altri 325 token. Ogni server MCP collegato aggiunge i relativi schemi a questo peso; MCP è il model context protocol.
• I risultati degli strumenti sono token di input. Un comando che stampa 8,000 righe inserisce 8,000 righe nella richiesta successiva e in ogni richiesta successiva dello stesso turno.
• Le pagine recuperate sono token di input. Una pagina web media di 10 kB corrisponde a circa 2,500 token, mentre un PDF di ricerca di 500 kB corrisponde a circa 125,000 token. max_content_tokens tronca solo i contenuti testuali, perché "si applica ai contenuti testuali, non ai contenuti binari come i PDF". Per limitare un PDF, usare invece max_uses e allowed_domains.
• La ricerca web ha un costo per ricerca, pari a $10 ogni 1,000 ricerche, indipendentemente dal numero di risultati restituiti. Una ricerca che restituisce un errore non viene addebitata.

Nessuno di questi costi è elevato per una singola esecuzione. Tutti diventano elevati quando si ripetono 8,640 volte.

I limiti rigidi e i limiti flessibili risolvono problemi diversi

max_tokens viene applicato. È un limite rigido sull'output totale di una richiesta, includendo ragionamento e testo della risposta. Claude non lo supera mai e il modello non può vedere questo valore. Quando viene raggiunto, si ottengono stop_reason: "max_tokens" e una risposta troncata. Per gli agenti esiste però una conseguenza: ogni richiesta in un ciclo di utilizzo degli strumenti ha il proprio max_tokens, quindi il limite riguarda una singola risposta e non l'intera attività. Dieci chiamate agli strumenti da 4,000 token ciascuna producono un limite di 40,000 token per il turno.

Il budget dell'attività è indicativo. task_budget rientra in output_config e comunica al modello quanti token ha a disposizione per l'intero ciclo agentico, includendo ragionamento, chiamate agli strumenti, risultati degli strumenti e output.

resp = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    betas=["task-budgets-2026-03-13"],
    output_config={"task_budget": {"type": "tokens", "total": 64000}},
    messages=messages,
)

"I budget delle attività sono un'indicazione flessibile, non un limite rigido." Claude può superarne uno durante un'azione, mentre il limite applicato all'output resta max_tokens. "Il conto alla rovescia è visibile soltanto al modello" e le risposte non includono alcun campo con il budget rimanente. Il valore minimo accettato per task_budget.total è di 20,000 token; un valore inferiore restituisce un errore 400. Un budget troppo ridotto rispetto al lavoro richiesto produce un comportamento simile a un rifiuto: il modello riduce l'ambito dell'attività oppure si interrompe in anticipo.

Un dettaglio comporta un costo invece di ridurlo. Se il client decrementa task_budget.remaining a ogni richiesta successiva, il valore modificato invalida qualsiasi prefisso memorizzato nella cache che lo contenga. Impostalo una sola volta, nella prima richiesta.

I budget delle attività sono in beta su Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5.5 e Claude Haiku 5.5. Claude Sonnet 5 e Claude Haiku 4.5 sono indicati come Not supported e i budget delle attività non si applicano a Claude Code. Di conseguenza, una sessione di Claude Code scollegata in tmux dipende invece dalla corretta gestione della sessione.

Il terzo limite si trova nella Claude Console: assegna all'agente un workspace dedicato, quindi imposta un limite mensile di spesa e limiti di frequenza al minuto per quel workspace. "Non puoi impostare limiti sul Default Workspace" e "i limiti a livello di organizzazione si applicano sempre, anche se la somma dei limiti dei workspace è superiore". Aggiungi notifiche di spesa, così una soglia ti avvisa prima che venga raggiunto il limite.

Scelta del modello per job e impatto effettivo del livello di sforzo

La scelta del modello è una decisione specifica per ogni job. A ottobre 2026, il costo per un milione di token, prima input e poi output, è il seguente: Claude Fable 5.1 e Fable 5 costano $10 e $50, Claude Opus 5.5 $4 e $20, Claude Opus 5, Opus 4.8 e Opus 4.7 $5 e $25, Claude Sonnet 5.5 e Sonnet 5 $2 e $10, Claude Haiku 5.5 $0.10 e $0.50 per prompt fino a 100,000 token ($0.50 e $2.50 oltre tale soglia, con i token memorizzati nella cache inclusi nel conteggio) e Claude Haiku 4.5 $1 e $5. Anthropic ha inizialmente venduto Sonnet 5 a quel prezzo come tariffa introduttiva, poi lo ha reso il prezzo standard e ha annullato l'aumento previsto a $3 e $15. Un passaggio che classifica soltanto le righe di log non ha bisogno di Opus.

Non fare affidamento neppure sull'utilizzo gratuito per assorbire un carico elevato. Oltre a il piccolo credito che Claude API assegna alla registrazione, l'unica disponibilità ricorrente è il credito API mensile incluso nei piani Claude Max e Team: $100 su Max 5x, $200 su Max 20x e fino a $500 condivisi su Team, rinnovati a ogni ciclo di fatturazione. Puoi richiederlo dopo 7 giorni con un piano idoneo e non è necessario alcun metodo di pagamento. Copre Claude API, Managed Agents, Agent SDK e playground, ma non Claude Code, e scade alla fine di ogni ciclo senza essere trasferito al ciclo successivo. Il suo utilizzo viene conteggiato nel limite di spesa e, quando si esaurisce, le richieste vengono interrotte a meno che l'organizzazione non disponga anche di crediti acquistati.

Il livello di sforzo è la seconda leva. output_config.effort accetta low, medium, high, xhigh e max, anche se non tutti i modelli supportano ogni livello. Il valore predefinito è high sulla maggior parte dei modelli e medium su Claude Opus 5.5 e Claude Haiku 5.5; impostare esplicitamente il valore predefinito di un modello equivale a ometterlo. Un livello di sforzo inferiore riduce più della lunghezza del ragionamento: la documentazione indica che induce Claude a effettuare meno chiamate agli strumenti e a combinare più operazioni in un numero inferiore di chiamate. In un agente, questo comporta un risparmio maggiore, perché evitare una chiamata a uno strumento significa evitare completamente un'intera richiesta.

Il problema è che il livello di sforzo entra in conflitto con la cache. Modificare il valore di primo livello tra una richiesta e l'altra invalida il prompt caching. Nell'esempio documentato su Claude Opus 5.5, la richiesta 2 ha riportato cache_read_input_tokens: 3546. La richiesta 3 ha modificato il livello di sforzo da medium, il valore predefinito di quel modello, a low e ha riportato cache_creation_input_tokens su 3546 e cache_read_input_tokens su 0. Pertanto, varia il livello di sforzo di primo livello tra workload diversi, mai all'interno della stessa conversazione memorizzata nella cache. Esistono due modalità per modificare la profondità senza interrompere la cache. Su Claude Fable 5.1, Opus 5.5, Opus 5, Sonnet 5.5 e Haiku 5.5, una modifica del livello di sforzo per messaggio (beta, header mid-conversation-output-config-2026-07-01) imposta un nuovo livello e lascia invariato il prefisso memorizzato nella cache. Su qualsiasi modello puoi invece indicare l'impostazione nel prompt: una riga come "Rispondi direttamente senza fare ragionamenti." nell'ultimo messaggio dell'utente lascia intatti i breakpoint precedenti. Su Claude Haiku 5.5, però, questa frase non riduce il ragionamento in modo affidabile.

I token di ragionamento vengono fatturati alle tariffe di output e conteggiati ai fini di max_tokens; per questo una risposta troncata spesso indica che il ragionamento ha consumato il budget. Leggi usage.output_tokens_details.thinking_tokens per conoscere il numero. Cosa riempie effettivamente una fattura dei token Claude analizza nel dettaglio il contatore.

Memorizza il prefisso stabile e non invalidarlo accidentalmente

Una scrittura nella cache costa 1.25 volte il prezzo base dell'input nella cache di cinque minuti e 2 volte nella cache di un'ora. Nella maggior parte dei modelli, una lettura dalla cache costa 0.1 volte, quindi «la memorizzazione nella cache diventa conveniente dopo una lettura dalla cache per la durata di 5 minuti (scrittura a 1.25x) o dopo due letture dalla cache per la durata di 1 ora (scrittura a 2x)». Nei modelli più recenti le letture costano ancora meno: 0.05 volte su Claude Opus 5.5 e Claude Sonnet 5.5 e 0.025 volte su Claude Fable 5.1.

Una riga spiega perché questa funzione è adatta a un agente sempre attivo: «La cache viene aggiornata senza costi aggiuntivi ogni volta che il contenuto memorizzato nella cache viene utilizzato». Un job eseguito ogni due minuti sulla cache di cinque minuti mantiene caldo il prefisso per tutta la giornata con una sola scrittura.

Tre modi per perdere la cache senza accorgersene.

Un prefisso che cambia. «I prefissi della cache vengono creati nel seguente ordine: tools, system, quindi messages.» Qualsiasi modifica a un byte precedente in questo ordine invalida tutto ciò che segue e la modifica delle definizioni degli strumenti invalida l'intera cache. L'errore classico consiste nell'inserire un timestamp o un run id nel prompt di sistema: ogni richiesta contiene quindi un prefisso diverso, scrive una nuova voce a 1.25x e non riutilizza nulla dalla cache. Il segnale è usage.cache_read_input_tokens a 0 in chiamate apparentemente identiche. Sposta il testo variabile nel messaggio utente più recente.

Un prefisso troppo breve. Ogni modello ha una lunghezza minima memorizzabile nella cache. Al di sotto di questa soglia, la richiesta viene elaborata senza caching e «non viene restituito alcun errore». I valori sono 512 token su Claude Fable 5.1, Fable 5, Opus 5.5, Opus 5, Sonnet 5.5 e Haiku 5.5, 1,024 su Claude Opus 4.8 e Claude Sonnet 5 e 4,096 su Claude Haiku 4.5. Di conseguenza, spostare un job da Sonnet 5 a Haiku 4.5 può disattivare il caching senza alcun avviso.

Una conversazione che supera la finestra di lookback. «La finestra di lookback è di 20 blocchi.» Il sistema controlla al massimo 20 posizioni per ogni breakpoint, quindi interrompe la ricerca. Nell'esempio documentato, un turno che contiene 35 blocchi e ha un breakpoint sul blocco 35 controlla i blocchi dal 35 al 16. La voce del turno precedente, al blocco 15, è fuori dalla finestra e quindi non viene trovata. Un'applicazione agente che aggiunge diversi blocchi di utilizzo degli strumenti e di risultati degli strumenti a ogni turno supera 20 blocchi in due o tre turni. Sono disponibili quattro breakpoint per richiesta: utilizzane uno per i messaggi recenti.

Invia alla Batches API tutto ciò che può attendere

"Ogni utilizzo viene addebitato al 50% dei prezzi standard dell'API", sia per l'input sia per l'output. L'elaborazione batch è asincrona, "e la maggior parte dei batch termina in meno di 1 ora", con risultati disponibili quando tutte le richieste sono terminate o dopo 24 ore, a seconda di quale evento si verifichi per primo. Si tratta di un comportamento tipico, non garantito.

Esegui il polling di processing_status finché non restituisce ended. Le richieste che restituiscono errored, canceled o expired non vengono addebitate. Se utilizzi un limite massimo di spesa, considera questa eccezione: "i batch possono superare leggermente il limite di spesa configurato per il tuo Workspace".

Gli sconti sono cumulabili. Poiché un batch può richiedere più di cinque minuti, la documentazione consiglia la cache di un'ora per i batch che condividono lo stesso contesto. Suddividi quindi il lavoro: tutto ciò che deve essere atteso da una persona o da un webhook resta nel percorso live, mentre un riepilogo notturno o la classificazione dei log del giorno precedente viene elaborato in un batch a metà prezzo.

Registrare nel proprio archivio i campi di utilizzo di ogni risposta

Non è possibile attribuire una spesa che non è stata registrata. Ogni risposta indica quanto è costata.

u = resp.usage
row = {
    "job": job_name,
    "model": resp.model,
    "uncached_input": u.input_tokens,
    "cache_write": u.cache_creation_input_tokens,
    "cache_read": u.cache_read_input_tokens,
    "output": u.output_tokens,
    "stop_reason": resp.stop_reason,
}

Aggiungi una riga per ogni chiamata API a un file JSON Lines, associandola al nome del job. Dopo una settimana puoi sapere quale job genera spesa e quale sembra soltanto occupato. Controlla cache_read: una colonna di zeri è il problema di costo più comune in un agente self-hosted.

Un campo può essere interpretato facilmente in modo errato. input_tokens conta soltanto i token successivi all'ultimo punto di cache, quindi la dimensione effettiva del prompt è total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens. Un agente che segnala input_tokens: 400 per un prompt grande non è economico: il resto proviene dalla cache.

Conta i token prima dell'invio. Il conteggio dei token è gratuito e ha limiti di frequenza separati dalla creazione dei messaggi, quindi usa count_tokens per rifiutare un allegato troppo grande invece di pagare per scoprirlo. Il risultato è una stima, quindi esegui una nuova misurazione per ogni modello e non riutilizzare un conteggio ottenuto con il tokenizer di un altro fornitore. I modelli Claude 4.7 e successivi, inclusi Claude Fable 5 e Claude Sonnet 5, usano un tokenizer più recente che "produces approximately 30% more tokens for the same text". Claude Sonnet 4.6 e precedenti, incluso Claude Haiku 4.5, usano quello precedente.

Per la visualizzazione autorevole, Admin API restituisce l'utilizzo all'indirizzo https://api.anthropic.com/v1/organizations/usage_report/messages e il costo all'indirizzo https://api.anthropic.com/v1/organizations/cost_report. Entrambi richiedono una chiave admin (sk-ant-admin01-...) come x-api-key: $ANTHROPIC_ADMIN_KEY con anthropic-version: 2023-06-01. Il report sull'utilizzo accetta bucket_width=1d, group_by[]=model e api_key_ids[]=. Il report sui costi è disponibile soltanto su base giornaliera e raggruppa per workspace_id o description. Una limitazione è la seguente: "The Admin API is unavailable for individual accounts."

Il parametro api_key_ids[] è un metodo semplice per attribuire i costi: assegna a ogni job la propria chiave API, filtra il report sull'utilizzo con api_key_ids[] e suddividilo per chiave con group_by[]=api_key_id. Il filtro è al plurale, mentre la dimensione di raggruppamento è al singolare. Conserva le chiavi nell'ambiente, non nel codice, come fa una prima applicazione Claude API su un VPS per gestirle.

Limita il ciclo, perché non lo farà nient’altro

Qui il numero massimo di iterazioni non è facoltativo. Il ciclo è sotto il tuo controllo, quindi anche il contatore:

for step in range(MAX_STEPS):          # MAX_STEPS = 12, never "while True"
    resp = client.messages.create(...)
    if resp.stop_reason != "tool_use":
        break
else:
    log.warning("job %s hit MAX_STEPS=%d, giving up", job_name, MAX_STEPS)

Nessuno dei due limiti indicati sopra risolve il problema: max_tokens limita una singola risposta, mentre il modello viene soltanto informato di un budget per l’attività. Un prodotto gestito interromperebbe l’esecuzione a questo punto, come il limite di Claude sulle chiamate agli strumenti in un singolo turno termina una sessione che ne ha effettuate troppe. Un ciclo scritto da te, invece, non include alcun meccanismo di arresto finché non ne aggiungi uno.

Aggiungi un secondo meccanismo di protezione all’esterno del processo. Esegui il job tramite un timer di systemd invece di usare un processo permanente e assegna alla relativa unità di servizio un limite di tempo reale. Un job avviato da un timer è in genere Type=oneshot e RuntimeMaxSec= "does not have any effect on Type=oneshot services", quindi imposta TimeoutStartSec=600 in quel punto. Usa RuntimeMaxSec=600 soltanto su un’unità Type=simple. In entrambi i casi, un’esecuzione bloccata viene terminata dopo dieci minuti invece di continuare indefinitamente finché non te ne accorgi. Eseguire un programma come servizio e timer di systemd descrive i file delle unità. Per sapere cosa ha fatto un’esecuzione, usa journalctl -u triage-agent.service --since "1 hour ago".

Limita anche i tentativi, perché un gestore che ritenta all’infinito addebita ogni tentativo. Un errore 429 o 500 giustifica alcuni tentativi con backoff. Un errore 400 non ne giustifica nessuno, perché la stessa richiesta fallirà nello stesso modo.

Il controllo dei costi di un agente AI inizia dalla lettura dei propri numeri

Nessuno può dirti quanto costa un agente sempre attivo, perché il costo è dato dai token per esecuzione moltiplicati per il numero di esecuzioni giornaliere, e puoi controllare entrambe le componenti. Eseguilo una volta, leggi la riga relativa all'utilizzo che hai registrato e moltiplicala per la frequenza pianificata. Due giorni dopo, confronta il report dei costi con questo calcolo. Se i due valori non coincidono, la differenza è quasi sempre dovuta a una cache non funzionante o a un ciclo eseguito più a lungo del previsto.

Questa procedura presuppone una chiave API, perché l'agente è un programma che hai scritto tu e che chiama la Messages API. Per il lavoro interattivo personale, quale piano Claude si adatta al tuo modo di lavorare copre l'aspetto dell'abbonamento. Tutti i prezzi e i limiti riportati qui sono stati verificati sulla documentazione di Anthropic a ottobre 2026; rileggi quindi la pagina dei prezzi prima di preparare un budget.

FAQ

Quanto costa eseguire un agente AI sempre attivo su un VPS?

Ci sono due costi, ma solo uno è prevedibile. Il server ha un prezzo mensile fisso. L'API del modello viene fatturata in base ai token, quindi il costo corrisponde a ciò che consuma una singola esecuzione moltiplicato per la frequenza di esecuzione. Anthropic non pubblica alcun dato relativo a un agente self-hosted sempre attivo, quindi considera qualsiasi cifra indicata come una stima. Registra usage di un'esecuzione reale e moltiplicalo per la pianificazione prevista.

Qual è la differenza tra max_tokens e il budget di un'attività?

max_tokens viene applicato e non è visibile al modello. Limita l'output di una singola richiesta, incluso il ragionamento, e quando viene raggiunto restituisce stop_reason: "max_tokens". Il budget dell'attività funziona al contrario: il modello riceve questo valore e adegua il ciclo agentico di conseguenza, ma "I budget delle attività sono un'indicazione flessibile, non un limite rigido" e il limite effettivo resta max_tokens.

Perché cache_read_input_tokens è sempre pari a zero per il mio agente?

Perché il prefisso cambia tra una chiamata e l'altra oppure è troppo breve per essere memorizzato nella cache. La causa più comune è un timestamp o un run id interpolato nel prompt di sistema: la cache usa il prefisso come chiave, quindi qualsiasi modifica di un byte invalida tutto ciò che segue. Lo stesso accade modificando le definizioni degli strumenti o il valore effort di primo livello. In caso contrario, il problema è la dimensione: i prompt più brevi non vengono memorizzati nella cache e non viene restituito alcun errore.

Come posso impedire a un agente AI di entrare in un ciclo infinito?

Conta le iterazioni nel codice del ciclo e interrompilo al raggiungimento di un massimo fisso, perché max_tokens limita una singola risposta mentre un agente ne esegue molte. Aggiungi un limite basato sul tempo trascorso all'esterno del processo: avvia il job da un timer systemd e imposta TimeoutStartSec= su un'unità oneshot oppure RuntimeMaxSec= su un'unità simple, in modo che un'esecuzione bloccata venga terminata secondo la pianificazione. Limita anche i tentativi, perché un ciclo di retry fattura ogni tentativo.

Posso impostare un limite di spesa per una singola chiave API di Claude?

Il limite di spesa documentato si applica al workspace e non alla singola chiave, quindi assegna all'agente un workspace dedicato e imposta lì il limite di spesa mensile. "Non puoi impostare limiti sul Default Workspace". Aggiungi notifiche di spesa, in modo da ricevere un avviso al superamento di una soglia. Per l'attribuzione, assegna a ogni job una chiave distinta, quindi raggruppa il report di utilizzo con group_by[]=api_key_id.