Claude Code: custo por subagente de uma execução de $0.17

Uma execução do Claude Code via gateway, dividida por agente: a primeira chamada de cada um dos três agentes somou 72% dos $0.17. Bastam duas variáveis de ambiente.

11 de outubro de 2026

O Claude Code informa o custo de uma sessão, mas não mostra quais partes consumiram esse valor. Quando uma equipe passa a usá-lo, também fica difícil saber a qual repositório ou desenvolvedor cada cobrança pertence. Usar o Claude Code por um gateway (um proxy entre o Claude Code e o provedor do modelo) resolve os dois problemas sem plugin nem wrapper: o gateway já recebe todas as requisições, e o Claude Code já envia um id de sessão e um id de agente em cada uma. Neste guia, executamos uma tarefa pequena pelo gateway da Synthorai e analisamos o resultado: $0.1728 por 11 requisições, com 72% do custo concentrado na primeira chamada de cada um dos três agentes.

TL;DR

• Uma execução do Claude Code com Claude Sonnet 5.5 e dois subagentes custou $0.1728 via gateway, e $0.0812 ao ser repetida meio minuto depois.
• As gravações em cache representaram 77% da primeira execução, e a primeira chamada de cada um dos três agentes, 72%.
• Os dois subagentes responderam por 39% do custo da sessão.
• Duas variáveis de ambiente direcionam o Claude Code para um gateway; uma terceira identifica o tipo de cada subagente.

O código está em github.com/synthorai-io/use-cases, no diretório coding-agent-spend/. Você precisa de Python 3.10 ou superior e do comando claude na versão 2.1.280 ou superior, exigida por esse modelo.

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

O script inicia o Claude Code em uma cópia de um pequeno repositório de exemplo com um teste falhando. Ele define o endereço do gateway e a chave apenas no ambiente desse processo e usa um diretório de configuração vazio. Assim, não lê nem altera sua configuração do Claude Code. Cada execução leva cerca de meio minuto. O script limita o custo de cada execução a $0.60 com --max-budget-usd e não inicia uma execução que possa elevar o total acima de $2.

Os números desta página vêm de execuções feitas em 10 de outubro de 2026, com Claude Code 2.1.296 e Claude Sonnet 5.5.

Como usar o Claude Code por um gateway?

Basta definir duas variáveis de ambiente. O Claude Code usa a Messages API da Anthropic, e o gateway disponibiliza a mesma API em seu próprio endereço:

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

Nada mais muda. A página de integração com o Claude Code explica os detalhes. A partir daí, todas as chamadas ao modelo de todas as sessões aparecem no log de requisições do gateway, agrupadas no console.

O que o gateway vê sem configuração adicional?

Ele vê a sessão, seus traces, o cliente e cada subagente. O Claude Code envia seu próprio id de sessão em todas as requisições. Por isso, uma execução de claude corresponde a uma sessão no console, cuja página identifica o cliente como “Claude Code 2.1.296”. As requisições também exibem um id de trace no console, e a sessão lista esses traces: nesta execução, foram dois, com 6 e 5 chamadas. A tabela “Agentes nesta sessão” já separa as chamadas entre a conversa principal e uma linha para cada subagente.

Um subagente é um segundo agente que o Claude Code inicia para executar parte de uma tarefa, com instruções e contexto próprios. A tarefa da demonstração pede dois: o subagente Explore, integrado ao Claude Code, para localizar uma regra, e um subagente personalizado, test-runner, para executar os testes.

Por padrão, um subagente aparece com um id como a05e467acd14b25e6. Isso permite saber que havia dois subagentes, mas não distinguir qual era qual. Mais uma variável resolve isso:

export CLAUDE_CODE_GATEWAY_HINT_HEADERS=1

Com essa variável, a tabela identifica cada subagente pelo tipo. Ao abrir uma chamada em Logs, você vê seu tipo (subagent:Explore) e a lista “Ferramentas antes desta chamada”, com o nome e o tempo de execução de cada ferramenta, como Read 7 ms. O gateway armazena o tipo do agente, não o nome que você deu a ele. Por isso, test-runner aparece como custom. Os nomes das ferramentas e seus tempos de execução são armazenados; o conteúdo que elas leram ou escreveram, não.

Para onde foram os $0.17?

O custo foi dividido entre três agentes e se concentrou na primeira chamada de cada um.

Os dois subagentes custaram $0.0676, ou 39% da sessão, para executar as duas menores partes da tarefa: encontrar uma regra em uma biblioteca de três arquivos-fonte e rodar cinco testes. A correção em si foi de um caractere, de > para >=.

A explicação está na contagem de tokens que o Claude Code imprime ao fim da execução:

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

Com os preços do modelo ($2 por milhão de tokens de entrada, $10 para saída, $0.10 para leitura de cache e $2.50 para gravação em cache), essas quatro contagens resultam em:

As gravações em cache representam 77% da conta. A gravação ocorre quando um prefixo de prompt é enviado pela primeira vez: custa 1.25 vezes o preço de entrada. Nesse modelo, as requisições seguintes leem esse conteúdo por um vigésimo do preço de entrada. O prompt de um agente de programação já é longo antes de você digitar qualquer coisa, pois inclui o prompt de sistema e a definição de todas as ferramentas. Por isso, a primeira chamada de um agente é a mais cara.

Cada agente começa com seu próprio prompt e paga por essa primeira chamada:

Essas três chamadas somam $0.1240, ou 72% da execução. As chamadas seguintes são baratas: a segunda e a terceira chamadas do subagente Explore leem 94% da entrada do cache e custam $0.0052 e $0.0132.

O custo de iniciar um subagente com cache frio compensa quando ele evita levar um grande volume de leitura para o contexto da conversa principal. É para isso que o Explore serve em uma base de código real. Se o trabalho exige apenas uma ou duas chamadas, executá-lo na conversa principal evita outra gravação em cache. Este exemplo usa um repositório pequeno; confira a distribuição dos custos nas suas próprias sessões antes de mudar sua forma de trabalhar.

Quanto custa uma segunda execução?

Custa cerca de metade se começar enquanto o cache ainda estiver quente. Repetimos a mesma execução meio minuto depois. Ela fez as mesmas 11 chamadas, leu 93.1% da entrada do cache, contra 74.9% na primeira execução, e custou $0.0812, contra $0.1728. As primeiras chamadas dos três agentes leram 82%, 81% e 71% do cache, porque seus prompts iniciais já estavam armazenados pela execução anterior.

Por padrão, o cache da Anthropic mantém cada entrada por cinco minutos e renova esse prazo a cada leitura. Um desenvolvedor trabalhando continuamente no mesmo repositório paga, na maior parte do tempo, o preço com cache quente. Um job agendado que roda uma vez por hora paga o preço com cache frio em todas as execuções.

O custo informado pelo Claude Code confere com a cobrança?

Na versão 2.1.296, conferiu até a quarta casa decimal: $0.1728 com cache frio e $0.0812 com cache quente nos dois lados. Isso depende da versão. O Claude Code calcula o custo usando sua própria tabela de preços. A versão 2.1.278, que ainda executava esse modelo em 8 de outubro, usava $5 e $25 por milhão de tokens de entrada e saída, enquanto a cobrança era de $2 e $10. Por isso, imprimia cerca de 2.7 vezes o valor cobrado. As contagens de tokens foram idênticas nos dois lados em todas as execuções.

Isso afeta uma configuração: --max-budget-usd interrompe a execução quando o valor calculado pelo próprio Claude Code atinge o limite. Na versão antiga, uma execução foi interrompida ao chegar a $0.60 na contagem do Claude Code, com uma cobrança de cerca de um terço desse valor. Após uma atualização, compare o valor com a página da sessão uma vez. Configure o limite do qual você depende onde a cobrança é contabilizada: no limite de gastos da chave de API.

Como separar os gastos por desenvolvedor ou repositório?

Adicione uma label a cada requisição. O Claude Code pode enviá-la por uma variável que já oferece suporte a headers personalizados:

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

X-Synthorai-Metadata é o header do gateway para labels: um objeto JSON sem aninhamento com até 10 strings curtas, no qual _user identifica a pessoa para quem a requisição foi feita. As opções --label da demonstração definem exatamente esse header, e a página da sessão acima mostra as duas labels como tags.

Defina a variável de cada desenvolvedor no perfil do shell e a de cada repositório no mecanismo que carrega as variáveis de ambiente do projeto. Isso permite consultar os dados de duas formas:

• Em Traces, a busca aceita metadata.repo = shipping e lista as sessões desse repositório.
• Na aba Breakdown de Analytics, o card Cost by metadata soma as requisições e o custo de cada valor de uma chave. Assim, repo mostra a conta por repositório, e _user, por desenvolvedor.

Isso funciona com uma única chave compartilhada. Usar uma chave por desenvolvedor permite a mesma divisão da cobrança e acrescenta limites de gastos individuais, mas exige gerenciar mais chaves.

Como consultar o custo dos agentes entre sessões?

Use o card Cost by agent na aba Breakdown de Analytics. A página da sessão detalha uma única sessão. Esse card soma todas as sessões do período por tipo de agente:

Explore × 2 e custom × 2 correspondem às execuções com cache frio e quente acima, com um total por tipo de agente nas duas sessões. A coluna Share mostra a participação de cada linha no gasto total do período, que também incluía outras sessões. Sem a variável de hints, os subagentes não informam seu tipo e são agrupados em uma linha chamada “Subagente”. Um agente no seu próprio programa que define X-Agent-Id, como o de Rastreie um agente de LLM, aparece em uma linha com o nome que enviou.

Ao analisar uma semana de sessões da equipe, essa visão mostra se os subagentes representam uma parcela pequena ou grande da conta e quais tipos respondem por ela.

O que essa configuração não oferece?

Ela não oferece ids de span, nomes de agentes personalizados, um atalho para isolamento nem uma visão do trabalho executado.

• Sem ids de span. As requisições do Claude Code 2.1.296 mostram um id de sessão e um id de trace, mas nenhum id de span. Por isso, o campo span de uma chamada aparece como “não enviado”. As unidades disponíveis para análise são a sessão, seus traces e seus agentes.
• Sem nomes de agentes personalizados. Todo subagente personalizado aparece como custom. Se você usa vários tipos e precisa distingui-los, o id do agente na página da sessão é a única referência.
• Sem atalho para isolamento. --bare parece ser a opção para executar o Claude Code sem seus plugins e configurações. Mas ela também desativa os subagentes, deixando a sessão com um único agente e nada para separar. A demonstração isola a execução usando um CLAUDE_CONFIG_DIR vazio.
• Sem visão do trabalho executado. O gateway registra chamadas ao modelo, nomes de ferramentas e tempos de execução. Ele não registra o conteúdo dos arquivos, diffs nem a saída dos comandos.

Perguntas frequentes

Quanto custa uma sessão do Claude Code?

Depende do modelo, do tamanho do repositório, de quantos agentes participam e de o cache estar quente ou frio. A execução desta página fez 11 requisições com Claude Sonnet 5.5 para corrigir um bug de um caractere usando dois subagentes. Ela custou $0.1728 com cache frio e $0.0812 ao ser repetida meio minuto depois.

Como acompanhar os custos do Claude Code de uma equipe?

Direcione o Claude Code de cada desenvolvedor para um gateway com ANTHROPIC_BASE_URL e adicione labels para o desenvolvedor e o repositório via ANTHROPIC_CUSTOM_HEADERS. O gateway soma os custos por sessão, valor de label e tipo de agente, sem instalar nada no Claude Code.

Os subagentes do Claude Code aumentam o custo?

Cada subagente começa com seu próprio prompt e paga sua própria gravação em cache. Na demonstração com Claude Sonnet 5.5, a primeira chamada do subagente Explore custou $0.0391, e as duas seguintes, $0.0052 e $0.0132. Os dois subagentes juntos representaram 39% da sessão. Esse custo dá ao subagente um contexto separado, o que compensa em explorações grandes, mas não em tarefas de uma chamada.

O custo que o Claude Code imprime é preciso?

Confira uma vez por versão. O Claude Code 2.1.296 imprimiu os mesmos $0.1728 que foram cobrados. O Claude Code 2.1.278 usava preços de $5 e $25 por milhão de tokens para o Claude Sonnet 5.5, enquanto a cobrança era de $2 e $10, e imprimia cerca de 2.7 vezes o valor cobrado. As contagens de tokens conferiram nas duas versões.

O que CLAUDE_CODE_GATEWAY_HINT_HEADERS faz?

Faz o Claude Code enviar três informações adicionais em cada requisição: o tipo do agente, o tipo da chamada e os nomes e tempos de execução das ferramentas executadas antes dela. Sem essa variável, o gateway ainda vê a sessão e cada subagente, mas apenas pelo id.

Leituras relacionadas

• Rastreie um agente de LLM: as mesmas visualizações do console para um agente que você desenvolve.
• Por que meu agente de LLM custa caro?: falhas de cache, crescimento do contexto e loops de tentativas, reproduzidos e corrigidos.
• Por que meu agente de LLM é lento? e Depure um agente de LLM: as mesmas visualizações usadas para analisar latência e falhas.
• Pergunte ao Claude sobre seus logs de LLM: perguntas sobre sessões como estas, respondidas pelo servidor MCP do gateway.
• Dê ao seu agente ferramentas para consultar logs: o mesmo log consultado por um programa seu e o custo dos tokens do modelo.
• Integração com o Claude Code: as duas variáveis e os nomes dos modelos.
• Referência de headers de requisição: quais headers do Claude Code e de outros agentes o gateway lê.

← Casos de uso