Claude Code: dove vanno $0.17, suddivisi per sotto-agente

Una sessione Claude Code via gateway: le prime chiamate dei tre agenti valgono il 72% dei $0.17 spesi. Bastano due variabili d'ambiente per configurarlo.

11 ottobre 2026

Claude Code mostra il costo di una sessione, ma non dice quali parti hanno generato la spesa. Quando lo usa un team, manca anche un modo per attribuire il conto a un repository o a uno sviluppatore. Far passare Claude Code da un gateway, cioè un proxy tra Claude Code e il provider del modello, risolve entrambi i problemi senza plugin o wrapper. Il gateway vede già tutte le richieste e Claude Code le contrassegna già con un ID di sessione e un ID di agente. In questa guida eseguiamo un piccolo task attraverso il gateway Synthorai e analizziamo il risultato: $0.1728 per 11 richieste, con il 72% del costo concentrato nella prima chiamata di ciascuno dei tre agenti.

TL;DR

• Un’esecuzione di Claude Code su Claude Sonnet 5.5 con due sotto-agenti è costata $0.1728 attraverso un gateway, e $0.0812 ripetendola mezzo minuto dopo.
• Le scritture in cache hanno rappresentato il 77% della prima esecuzione; le prime chiamate dei tre agenti, il 72%.
• I due sotto-agenti hanno generato il 39% del costo della sessione.
• Due variabili d’ambiente instradano Claude Code attraverso un gateway; una terza permette di identificare il tipo di ciascun sotto-agente.

Il codice si trova su github.com/synthorai-io/use-cases, nella directory coding-agent-spend/. Servono Python 3.10 o successivo e il comando claude alla versione 2.1.280 o successiva, richiesta da questo modello.

git clone https://github.com/synthorai-io/use-cases
cd use-cases
cp .env.example .env    # put your API key in it
cd coding-agent-spend
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python run.py --hints --label repo=shipping --label _user=dev_1

Lo script avvia Claude Code su una copia di un piccolo repository di esempio con un test che fallisce. Imposta l’indirizzo del gateway e la chiave solo nell’ambiente di quel processo e usa una directory di configurazione vuota: non legge né modifica la tua configurazione di Claude Code. Un’esecuzione dura circa mezzo minuto. Lo script limita ogni esecuzione a $0.60 tramite --max-budget-usd e non ne avvia una che potrebbe portare la spesa totale oltre $2.

I dati di questa pagina provengono da esecuzioni del 10 ottobre 2026, con Claude Code 2.1.296 su Claude Sonnet 5.5.

Come si instrada Claude Code attraverso un gateway?

Basta impostare due variabili d’ambiente. Claude Code usa la Messages API di Anthropic e il gateway espone la stessa API al proprio indirizzo:

export ANTHROPIC_BASE_URL="https://synthorai.io"   # no /v1: Claude Code adds /v1/messages itself
export ANTHROPIC_API_KEY="<your gateway key>"

Non cambia altro. La pagina di integrazione di Claude Code descrive i dettagli. Da quel momento ogni chiamata al modello, in ogni sessione, finisce nel log delle richieste del gateway e viene raggruppata nella console.

Cosa vede il gateway senza altre configurazioni?

Vede la sessione, le sue trace, il client e ogni sotto-agente. Claude Code invia il proprio ID di sessione con ogni richiesta: un’esecuzione di claude corrisponde quindi a una sessione nella console, dove il client è indicato come “Claude Code 2.1.296”. Nella console le richieste mostrano anche un ID di trace, e la sessione elenca le relative trace: in questa esecuzione sono due, da 6 e 5 chiamate. La tabella “Agents in this session” separa già le chiamate della conversazione principale da quelle dei sotto-agenti, con una riga per ciascuno.

Un sotto-agente è un secondo agente che Claude Code avvia per una parte del task, con istruzioni e contesto propri. Il task della demo ne richiede due: il sotto-agente integrato Explore per trovare dove è definita una regola e un sotto-agente personalizzato, test-runner, per eseguire i test.

Per impostazione predefinita, un sotto-agente compare con un ID come a05e467acd14b25e6. Si vede che ce ne sono due, ma non si distingue quale sia l’uno e quale l’altro. Un’altra variabile risolve il problema:

export CLAUDE_CODE_GATEWAY_HINT_HEADERS=1

Con questa variabile, la tabella identifica ogni sotto-agente per tipo. Aprendo una chiamata in Logs si vedono il tipo (subagent:Explore) e l’elenco “Tools before this call”, con nome e tempo di esecuzione di ogni strumento, per esempio Read 7 ms. Il gateway conserva il tipo dell’agente, non il nome che gli hai assegnato: test-runner compare quindi come custom. Vengono conservati i nomi degli strumenti e i tempi di esecuzione, non ciò che hanno letto o scritto.

Dove sono finiti i $0.17?

Sono stati spesi da tre agenti, soprattutto nella prima chiamata di ciascuno.

I due sotto-agenti sono costati $0.0676, il 39% della sessione, per le due attività più piccole del task: trovare una regola in una libreria di tre file sorgente ed eseguire cinque test. La correzione consisteva in un solo carattere, da > a >=.

La spiegazione sta nei conteggi dei token che Claude Code stampa a fine esecuzione:

claude-sonnet-5-5                20 in   158612 cache read   53058 cache write   2425 out  $0.1728

Applicando le tariffe del modello ($2 per milione di token di input, $10 per l’output, $0.10 per una lettura dalla cache e $2.50 per una scrittura in cache), i quattro conteggi danno questi importi:

Le scritture in cache rappresentano il 77% del conto. La scrittura avviene al primo invio di un prefisso del prompt e costa 1.25 volte la tariffa di input. Su questo modello, le richieste successive lo leggono a un ventesimo della tariffa di input. Il prompt di un agente di programmazione è lungo ancora prima che tu scriva qualcosa: contiene il prompt di sistema e la definizione di ogni strumento. Per questo la prima chiamata di un agente è la più costosa.

Ogni agente parte con un prompt proprio e paga quindi la propria prima chiamata:

Queste tre chiamate costano $0.1240, il 72% dell’esecuzione. Le successive costano poco: la seconda e la terza chiamata del sotto-agente Explore leggono dalla cache il 94% dell’input e costano $0.0052 e $0.0132.

Il costo di avvio a cache fredda di un sotto-agente si giustifica quando evita di caricare nella conversazione principale una grande quantità di contenuti letti. È ciò a cui serve Explore in una codebase reale. Per un’attività da una o due chiamate, eseguirla nella conversazione principale evita un’altra scrittura in cache. Qui il repository è piccolo: controlla la ripartizione nelle tue sessioni prima di cambiare modo di lavorare.

Quanto costa una seconda esecuzione?

Circa la metà, se parte mentre la cache è ancora calda. Abbiamo ripetuto la stessa esecuzione mezzo minuto dopo. Ha effettuato le stesse 11 chiamate, letto dalla cache il 93.1% dell’input contro il 74.9% della prima esecuzione e speso $0.0812 invece di $0.1728. Le prime chiamate dei tre agenti hanno letto dalla cache l’82%, l’81% e il 71% dell’input, perché i prompt iniziali erano già presenti dall’esecuzione precedente.

La cache di Anthropic conserva una voce per cinque minuti per impostazione predefinita e ne rinnova la durata a ogni lettura. Uno sviluppatore che lavora con continuità nello stesso repository paga soprattutto il costo a cache calda. Un job pianificato che gira una volta all’ora paga ogni volta quello a cache fredda.

Il costo indicato da Claude Code coincide con il conto?

Con la versione 2.1.296 coincideva fino alla quarta cifra decimale: $0.1728 a cache fredda e $0.0812 a cache calda da entrambe le parti. Dipende dalla versione. Claude Code calcola il costo usando una propria tabella delle tariffe. La versione 2.1.278, che l’8 ottobre eseguiva ancora questo modello, applicava $5 e $25 per milione di token di input e output, mentre il conto usava $2 e $10. Stampava quindi un importo pari a circa 2.7 volte quello addebitato. I conteggi dei token coincidevano sempre da entrambe le parti.

Questo incide su un’impostazione: --max-budget-usd interrompe l’esecuzione quando il conteggio di Claude Code raggiunge il limite. Con la vecchia versione, un’esecuzione veniva fermata a $0.60 secondo Claude Code, ma l’addebito era circa un terzo. Dopo un aggiornamento, confronta una volta l’importo con la pagina della sessione. Imposta il limite su cui fai affidamento dove viene conteggiato l’addebito: un limite di spesa sulla chiave API.

Come si divide la spesa per sviluppatore o repository?

Si aggiunge un’etichetta a ogni richiesta usando una variabile che Claude Code supporta già per gli header personalizzati:

export ANTHROPIC_CUSTOM_HEADERS='X-Synthorai-Metadata: {"repo":"shipping","_user":"dev_1"}'

X-Synthorai-Metadata è l’header del gateway per le etichette: un oggetto JSON piatto con un massimo di 10 stringhe brevi. La chiave _user identifica la persona per cui è stata effettuata la richiesta. Le opzioni --label della demo impostano esattamente questo header e la pagina della sessione mostrata sopra visualizza entrambe le etichette come tag.

Imposta la variabile per ciascuno sviluppatore nel suo profilo della shell e per ciascun repository nel sistema che carica le variabili d’ambiente del progetto. Avrai due viste a disposizione:

• In Traces, la casella di ricerca accetta metadata.repo = shipping ed elenca le sessioni di quel repository.
• Nella scheda Breakdown di Analytics, il riquadro Cost by metadata somma richieste e costi per ogni valore di una chiave: repo mostra il conto per repository e _user quello per sviluppatore.

Funziona anche con un’unica chiave condivisa. Chiavi separate per sviluppatore permettono la stessa ripartizione dei costi e aggiungono limiti di spesa individuali, ma richiedono di gestire più chiavi.

Come si vedono i costi degli agenti su più sessioni?

Usa il riquadro Cost by agent nella scheda Breakdown di Analytics. La pagina della sessione suddivide una singola sessione; questo riquadro aggrega tutte le sessioni dell’intervallo selezionato per tipo di agente:

Explore × 2 e custom × 2 corrispondono alle esecuzioni a cache fredda e calda descritte sopra: un totale per tipo di agente su entrambe le sessioni. La colonna Share indica la quota di ogni riga rispetto alla spesa complessiva nell’intervallo, che comprendeva anche altre sessioni. Senza la variabile hint, i sotto-agenti non comunicano il proprio tipo e vengono raggruppati in una riga chiamata “Sub-agent”. Un agente nel tuo programma che imposta direttamente X-Agent-Id, come quello in Tracciare un agente LLM, compare in una riga con il nome che ha inviato.

Su una settimana di sessioni del team, questa vista mostra se i sotto-agenti pesano poco o molto sul conto e quali tipi incidono di più.

Cosa non offre questa configurazione?

Non offre ID di span, nomi per gli agenti personalizzati, una scorciatoia per l’isolamento o una vista del lavoro svolto.

• Nessun ID di span. Le richieste di Claude Code 2.1.296 mostrano un ID di sessione e un ID di trace, ma nessun ID di span. Il campo span di una chiamata riporta quindi “not sent”. Le unità disponibili sono la sessione, le sue trace e i suoi agenti.
• Nessun nome per gli agenti personalizzati. Ogni sotto-agente personalizzato è custom. Se ne usi diversi tipi e devi distinguerli, l’unico riferimento è l’ID dell’agente nella pagina della sessione.
• Nessuna scorciatoia per l’isolamento. --bare sembra il modo per eseguire Claude Code senza i tuoi plugin e le tue impostazioni. Disattiva però anche i sotto-agenti: la sessione ha un solo agente e non c’è nulla da suddividere. La demo isola invece l’esecuzione con una directory CLAUDE_CONFIG_DIR vuota.
• Nessuna vista del lavoro svolto. Il gateway registra le chiamate al modello, i nomi degli strumenti e i tempi di esecuzione. Non registra contenuti dei file, diff o output dei comandi.

FAQ

Quanto costa una sessione di Claude Code?

Dipende dal modello, dalle dimensioni del repository, dal numero di agenti coinvolti e dallo stato della cache. L’esecuzione descritta qui, 11 richieste su Claude Sonnet 5.5 per correggere un bug di un carattere con due sotto-agenti, è costata $0.1728 a cache fredda e $0.0812 ripetendola mezzo minuto dopo.

Come si monitorano i costi di Claude Code per un team?

Configura Claude Code di ogni sviluppatore affinché usi un gateway tramite ANTHROPIC_BASE_URL, poi aggiungi le etichette per sviluppatore e repository con ANTHROPIC_CUSTOM_HEADERS. Il gateway aggrega i costi per sessione, valore dell’etichetta e tipo di agente, senza installare nulla in Claude Code.

I sotto-agenti di Claude Code aumentano i costi?

Ogni sotto-agente parte con un prompt proprio e paga una propria scrittura in cache. Nella demo su Claude Sonnet 5.5, la prima chiamata del sotto-agente Explore è costata $0.0391 e le due successive $0.0052 e $0.0132. Insieme, i due sotto-agenti hanno generato il 39% del costo della sessione. Quel costo serve ad avere un contesto separato, utile per esplorazioni ampie ma non per attività da una sola chiamata.

Il costo stampato da Claude Code è corretto?

Verificalo una volta per ogni versione. Claude Code 2.1.296 stampava $0.1728, lo stesso importo addebitato. Claude Code 2.1.278 applicava a Claude Sonnet 5.5 tariffe di $5 e $25 per milione di token, mentre il conto usava $2 e $10: stampava circa 2.7 volte l’importo addebitato. I conteggi dei token coincidevano in entrambe le versioni.

A cosa serve CLAUDE_CODE_GATEWAY_HINT_HEADERS?

Fa inviare a Claude Code tre informazioni aggiuntive con ogni richiesta: il tipo di agente, il tipo di chiamata, e i nomi e i tempi di esecuzione degli strumenti eseguiti prima della chiamata. Senza questa variabile, il gateway vede comunque la sessione e ogni sotto-agente, ma li distingue solo per ID.

Letture correlate

• Tracciare un agente LLM: le stesse viste della console per un agente scritto da te.
• Perché il mio agente LLM costa tanto?: cache miss, crescita del contesto e cicli di retry, riprodotti e risolti.
• Perché il mio agente LLM è lento? e Debug di un agente LLM: le stesse viste usate per analizzare latenza ed errori.
• Chiedi a Claude di analizzare i log del tuo LLM: risposte a domande su sessioni come queste tramite il server MCP del gateway.
• Dai al tuo agente strumenti per leggere i log: gli stessi log letti da un tuo programma e il costo dei token del modello.
• Integrazione di Claude Code: le due variabili e i nomi dei modelli.
• Riferimento degli header delle richieste: quali header di Claude Code e degli altri agenti vengono letti dal gateway.

← Casi d'uso