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 singola richiesta, inclusi ragionamento e testo della risposta. Claude non lo supera e il modello non può visualizzare questo valore. Il raggiungimento del limite restituisce stop_reason: "max_tokens" e una risposta troncata. Per gli agenti c'è un aspetto importante: ogni richiesta in un ciclo di utilizzo degli strumenti ha il proprio max_tokens. Questo valore limita quindi una singola risposta, non l'intera attività. Dieci chiamate agli strumenti con un limite di 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 indica 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,
)

"Il budget dell'attività è un'indicazione flessibile, non un limite rigido." Claude può superarlo durante un'azione e il limite applicato all'output resta comunque max_tokens. "Il conto alla rovescia è visibile solo al modello" e le risposte non includono un 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 basso rispetto al lavoro richiesto produce un comportamento simile a un rifiuto, quindi il modello riduce l'ambito dell'attività o si interrompe prima del completamento.

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 contiene. Impostalo una sola volta, nella prima richiesta.

I budget delle attività sono in beta su Claude Fable 5, Claude Opus 4.8 e Claude Opus 4.7. 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 dalla corretta gestione della sessione.

Il terzo limite si trova in Claude Console: assegna all'agente un workspace dedicato, quindi imposta un limite di spesa mensile 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, in modo da ricevere un avviso al raggiungimento di una soglia prima di arrivare al limite.

Scelta del modello per singolo job e impatto effettivo dell'impegno

La scelta del modello va effettuata per ogni job. A luglio 2026, per milione di token, input e output rispettivamente: Claude Fable 5 a $10 e $50, Claude Opus 4.8 e Opus 4.7 a $5 e $25, Claude Sonnet 5 a $3 e $15, Claude Haiku 4.5 a $1 e $5. Sonnet 5 è attualmente disponibile a un prezzo inferiore a quello indicato, perché è in vigore un «prezzo introduttivo di $2/$10 per milione di token di input/output fino al 31 agosto 2026». Un passaggio che classifica soltanto le righe di log non richiede Opus. Non esiste neppure una quota gratuita sufficiente ad assorbire un carico elevato, perché l'API di Claude non offre un piano gratuito oltre al piccolo credito assegnato alla registrazione.

L'impegno è la seconda leva. output_config.effort accetta low, medium, high, xhigh e max, mentre il valore predefinito è high; impostare esplicitamente high equivale quindi a ometterlo. Un livello di impegno inferiore riduce più della sola lunghezza del ragionamento: la documentazione indica che induce Claude a effettuare meno chiamate agli strumenti e a combinare più operazioni in una sola. In un agent questo comporta un risparmio maggiore, perché una chiamata agli strumenti evitata corrisponde a un'intera richiesta che non viene mai eseguita.

Il problema è che l'impegno entra in conflitto con la cache. Modificare il valore tra una richiesta e l'altra invalida il prompt caching. Nell'esempio documentato, la richiesta 2 riportava cache_read_input_tokens: 3546; la richiesta 3, con l'impegno modificato da alto a medio, riportava cache_creation_input_tokens su 3546 e cache_read_input_tokens su 0. Varia quindi il livello di impegno tra carichi di lavoro diversi, mai all'interno della stessa conversazione memorizzata nella cache. Per controllare la profondità senza invalidare la cache, intervieni nel prompt: una riga come «Rispondi direttamente senza soffermarti sul ragionamento» nell'ultimo messaggio dell'utente lascia invariati i breakpoint precedenti.

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

Memorizzare il prefisso stabile senza invalidarlo accidentalmente

Una scrittura nella cache costa 1.25 volte il prezzo base degli input nella cache di cinque minuti e 2 volte in quella di un'ora. Una lettura dalla cache costa 0.1 volte il prezzo base, quindi «la memorizzazione nella cache diventa conveniente dopo una sola lettura per la durata di 5 minuti (scrittura a 1.25x) oppure dopo due letture per la durata di 1 ora (scrittura a 2x)».

Una riga spiega perché questa funzione è adatta a un agent 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 tutto il giorno 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, mentre la modifica delle definizioni degli strumenti invalida l'intera cache. L'errore classico causato dalla configurazione è inserire un timestamp o un run id nel system prompt: ogni richiesta contiene quindi un prefisso diverso, scrive una nuova voce a 1.25x e non legge nulla dalla cache. L'indicatore è usage.cache_read_input_tokens uguale a 0 in chiamate apparentemente identiche. Spostare il testo variabile nel messaggio user 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 documentati includono 1,024 token per Claude Opus 4.8 e Claude Sonnet 5 e 4,096 per Claude Haiku 4.5. Di conseguenza, spostare un job da Sonnet a Haiku 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 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 sul blocco 15 è fuori dalla finestra, quindi non si verifica alcun hit. Un' applicazione agent che aggiunge diversi blocchi tool-use e tool-result a ogni turno supera 20 blocchi in due o tre turni. Sono disponibili quattro breakpoint per richiesta: è opportuno usarne uno sui 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 composta da zeri è il problema di contabilizzazione dei costi più comune in un agent self-hosted.

Un campo è facile da interpretare male. input_tokens conta soltanto i token successivi all'ultimo punto di cache; la dimensione reale del prompt è quindi total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens. Un agent che segnala input_tokens: 400 con un prompt voluminoso non è economico: il resto proviene dalla cache.

Conta i token prima dell'invio. Il conteggio dei token è gratuito e i relativi limiti di frequenza sono separati da quelli della creazione dei messaggi; usa quindi count_tokens per rifiutare un allegato troppo grande invece di pagare per scoprirlo. Il risultato è una stima, quindi ripeti la misurazione per ogni modello e non riutilizzare un conteggio ottenuto con il tokenizer di un altro vendor. Claude Opus 4.7 e i modelli Opus successivi, 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 versioni precedenti, incluso Claude Haiku 4.5, usano quello precedente.

Per il dato ufficiale, Admin API restituisce l'utilizzo in https://api.anthropic.com/v1/organizations/usage_report/messages e il costo in 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 e accettano bucket_width=1d, group_by[]=model e api_key_ids[]=. Esiste una limitazione: "The Admin API is unavailable for individual accounts."

Quest'ultimo parametro offre un metodo semplice per attribuire i costi: assegna a ogni job una chiave API distinta, applica il filtro con api_key_ids[] e suddividi il report per chiave con group_by[]=api_key_id. Il filtro è plurale, mentre la dimensione di raggruppamento è singolare. Conserva le chiavi nelle variabili d'ambiente, non nel codice, come fa una prima applicazione Claude API su un VPS con queste chiavi.

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

Qui un numero massimo di iterazioni non è facoltativo. Il ciclo è sotto il tuo controllo, quindi lo è 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 superiori lo fa al posto tuo: max_tokens limita una singola risposta e il modello riceve soltanto l'indicazione di un budget per l'attività. Un prodotto ospitato interromperebbe il processo a questo punto, come il limite di Claude per le chiamate agli strumenti in un singolo turno interrompe una sessione che ne ha effettuate troppe, ma un ciclo scritto da te non include alcun meccanismo di sicurezza finché non ne aggiungi uno.

Aggiungi un secondo limite all'esterno del processo. Esegui il job tramite un timer di systemd invece di usare un processo permanente e imposta RuntimeMaxSec= nella relativa unità di servizio. Con RuntimeMaxSec=600, 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 handler che ritenta indefinitamente 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 dati

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 sei tu a determinare entrambi i valori. Eseguilo una volta, leggi la riga sull'utilizzo che hai registrato e moltiplica il risultato per la pianificazione prevista. Dopo due giorni, confronta il report dei costi con questo calcolo. Quando i due valori non coincidono, la causa è quasi sempre una cache non funzionante oppure un loop durato più a lungo del previsto.

Questa procedura presuppone l'uso di una chiave API, perché l'agente è un programma che esegui e che chiama la Messages API. Per il tuo lavoro interattivo, quale piano Claude è più adatto al tuo modo di lavorare descrive l'aspetto relativo all'abbonamento. Tutti i prezzi e i limiti riportati qui sono stati verificati sulla documentazione di Anthropic a luglio 2026; consulta nuovamente la pagina dei prezzi prima di definire il 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 quanto consuma una singola esecuzione moltiplicato per la frequenza di esecuzione. Anthropic non pubblica alcun dato per un agente self-hosted sempre attivo, quindi considera qualsiasi cifra indicata come una stima. Registra usage da un'esecuzione reale e moltiplicalo per la pianificazione.

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 il suo raggiungimento produce stop_reason: "max_tokens". Il budget di un'attività è l'opposto: il modello conosce il valore e adegua a esso il ciclo agentico, ma "I budget delle attività sono un'indicazione flessibile, non un limite rigido" e il limite applicato resta comunque max_tokens.

Perché cache_read_input_tokens è sempre 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 system prompt: la cache usa il prefisso come chiave, quindi qualsiasi modifica a un byte invalida tutto ciò che segue. Anche la modifica delle definizioni degli strumenti o del valore effort produce lo stesso effetto. Altrimenti la causa è 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 produce molte. Aggiungi un limite di tempo reale esterno al processo: avvia il job da un timer systemd con RuntimeMaxSec= impostato, 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 su una singola chiave API di Claude?

Il limite di spesa documentato si applica al workspace e non alla singola chiave. Assegna quindi 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 attribuire i consumi, assegna a ogni job una chiave distinta, quindi raggruppa il report di utilizzo con group_by[]=api_key_id.