Claude Code agent_summary: meça e reduza o consumo de tokens
Meça as requisições que geram os rótulos de progresso dos agentes em segundo plano do Claude Code. Compare a estimativa de 16.4% de uma equipe com os 2% gerais e 6% no terminal relatados pela equipe do Claude Code. Use um receptor local de OpenTelemetry e avalie a correção de cache da versão 2.1.311+, os controles de agentes e os patches da comunidade.
Conteúdo
Atualize o Claude Code para 2.1.311 ou posterior e meça agent_summary com OpenTelemetry antes de desativar recursos dos agentes. Essas requisições de resumo podem gerar custos enquanto agentes trabalham em segundo plano. Os 16.4% divulgados são a parcela do custo estimado de uma equipe, não um acréscimo universal no consumo de tokens.
O que o agent_summary faz
agent_summary gera rótulos de progresso por meio de requisições separadas ao modelo. No relato de dblumenau sobre o Claude Code 2.1.312, cada requisição enviava o histórico do agente em segundo plano ao próprio modelo dele. O resultado solicitado era um rótulo de três a cinco palavras. A reprodução usou Haiku, portanto o mecanismo não é exclusivo do Opus.
Agentes que trabalham em segundo plano podem acionar essas requisições aproximadamente a cada 30 segundos. A requisição pode ser pulada se o histórico não mudar, como documenta o changelog oficial. Conte as requisições reais, em vez de multiplicar os minutos decorridos por dois.
Por isso, o tamanho do contexto pode pesar mais que o comprimento do rótulo visível. Ao investigar o custo, confira o modelo informado e o uso de cache.
Isso é separado da linha de status que você configura no terminal. A documentação da linha de status personalizada descreve um script local que não consome tokens da API. Remover esse script não impede as requisições de resumo ao modelo.
O que 16.4%, 2% e 6% medem
As três porcentagens de custo descrevem populações diferentes. Em 2026-11-01, os relatos publicados relevantes são:
| Relato | População e período | Parcela do custo atribuída aos resumos | Base de cálculo |
|---|---|---|---|
| Flamerix AI | Uma semana medida por uma equipe | 16.4% | Estimativas cost_usd por requisição do Claude Code |
| edwinarbus, integrante da equipe do Claude Code | Usuários que enviam telemetria, na semana anterior à resposta de 29 de outubro | Cerca de 2% | Custo pelos preços de tabela da API |
| Mesma resposta, recorte do terminal | Uso do terminal dentro dessa amostra de telemetria | Cerca de 6% | Custo pelos preços de tabela da API |
Separadamente, a Flamerix relatou que os resumos representaram 19.7% das requisições à API. A participação nas requisições e a participação nos custos usam denominadores diferentes. Nenhuma delas determina a parcela do limite de uso da sua assinatura consumida pelos resumos.
Use esses relatos como motivo para medir seu próprio cenário de uso. Uma equipe que delega muitas tarefas longas pode ter resultados bem diferentes de quem usa principalmente a conversa principal.
Atualize primeiro, sem presumir uma economia fixa
Segundo a resposta da equipe do Claude Code, a versão 2.1.311+ corrige o caso mais caro: resumos que não aproveitam o cache do prompt. A afirmação se refere a uma correção de cache, não à remoção das requisições de resumo. Ela não estabelece uma economia fixa para suas sessões.
Para uma instalação nativa, execute no Bash:
claude --version
claude update
claude --versionReinicie o Claude Code após atualizar. Se a instalação usar um gerenciador de pacotes, siga o comando de atualização nas instruções oficiais. Confira a versão resultante: o canal de atualização ou uma política da organização pode limitá-la.
Na mesma resposta, a equipe descreve um modo mais barato em desenvolvimento, com notas curtas e um modelo menor. A resposta não informa uma data de lançamento. Em 2026-11-01, não há uma configuração pública documentada para ativar esse modo. Ainda não inclua essa economia no orçamento.
Meça sua sessão com OpenTelemetry
Capture eventos de log claude_code.api_request e agrupe-os por query_source. A referência de monitoramento documenta esse atributo, o model informado e a estimativa cost_usd.
Se sua organização já coleta esses eventos, use o sistema de monitoramento existente. Filtre uma sessão ou um intervalo controlado, conte os eventos de requisição à API e some cost_usd por origem. Ao comparar modelos, acrescente model como segundo agrupamento.
O exemplo local abaixo exige Bash, Python 3 e uma instalação do Claude Code já autenticada. Use uma máquina em que você controla o destino da telemetria. O receptor mantém os totais em memória e exibe metadados sem exigir a captura de prompts ou respostas brutos.
Inicie o receptor local
Execute o código no primeiro terminal. Ele aceita OTLP HTTP JSON na interface de loopback e imprime totais acumulados por origem:
python3 -u - <<'PY'
import gzip, json, math
from collections import defaultdict
from http.server import BaseHTTPRequestHandler, HTTPServer
rows = defaultdict(lambda: [0, 0.0, 0])
models = defaultdict(set)
seen = set()
def scalar(value):
return next((value[k] for k in ("stringValue", "doubleValue", "intValue", "boolValue")
if k in value), None)
def report():
count = sum(row[0] for row in rows.values())
cost = sum(row[1] for row in rows.values())
missing = sum(row[2] for row in rows.values())
print("\nquery_source\trequests\trequest_%\tknown_USD\tcost_%\tmissing_cost\tmodels")
for source, (n, usd, absent) in sorted(rows.items()):
share = f"{100 * usd / cost:.2f}" if cost > 0 and not missing else "n/a"
names = ",".join(sorted(models[source]))
print(f"{source}\t{n}\t{100 * n / count:.2f}\t{usd:.6f}\t{share}\t{absent}\t{names}")
print(f"Total API records: {count}; missing costs: {missing}", flush=True)
class Receiver(BaseHTTPRequestHandler):
def log_message(self, *args):
pass
def do_POST(self):
if self.path != "/v1/logs":
self.send_error(404)
return
raw = self.rfile.read(int(self.headers.get("Content-Length", "0")))
try:
if self.headers.get("Content-Encoding") == "gzip":
raw = gzip.decompress(raw)
data = json.loads(raw)
except (ValueError, OSError):
self.send_error(400)
return
for resource in data.get("resourceLogs", []):
for scope in resource.get("scopeLogs", []):
for record in scope.get("logRecords", []):
a = {item["key"]: scalar(item["value"])
for item in record.get("attributes", [])}
event = a.get("event.name") or scalar(record.get("body", {}))
if event in ("user_prompt", "claude_code.user_prompt"):
print("Received user_prompt event.", flush=True)
if event not in ("api_request", "claude_code.api_request"):
continue
identity = a.get("request_id") or json.dumps(record, sort_keys=True)
if identity in seen:
continue
seen.add(identity)
source = str(a.get("query_source") or "(missing)")
models[source].add(str(a.get("model") or "(missing)"))
row = rows[source]
row[0] += 1
try:
usd = (float(a["cost_usd"]) if a.get("cost_usd") is not None
else float(a["cost_usd_micros"]) / 1_000_000)
if not math.isfinite(usd) or usd < 0:
raise ValueError()
row[1] += usd
except (KeyError, ValueError, TypeError):
row[2] += 1
self.send_response(200)
self.send_header("Content-Type", "application/json")
self.end_headers()
self.wfile.write(b"{}")
report()
server = HTTPServer(("127.0.0.1", 4318), Receiver)
print("Listening on 127.0.0.1:4318. Stop after Claude exits with Ctrl+C.", flush=True)
try:
server.serve_forever()
except KeyboardInterrupt:
pass
finally:
server.server_close()
report()
PYInicie a sessão que será medida
Execute este bloco no segundo terminal. Os parênteses criam um subshell, que restringe essas alterações de ambiente ao processo medido:
(
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=none
export OTEL_TRACES_EXPORTER=none
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=http/json
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://127.0.0.1:4318/v1/logs
export OTEL_LOGS_EXPORT_INTERVAL=1000
claude
)Escolha uma tarefa normal que justifique o trabalho em segundo plano. Por exemplo, peça uma revisão dos testes de autenticação em segundo plano, sem editar arquivos. Continue trabalhando na conversa principal e confirme que o agente em segundo plano realmente iniciou.
Mantenha a sessão interativa, sem redirecionar a saída do Claude por um pipe. Trocar o comando por claude -p muda o modo de execução e pode alterar o comportamento dos resumos.
Após enviar um prompt, o primeiro terminal deve mostrar Received user_prompt event.. As linhas de requisições à API devem aparecer em seguida. Deixe a tarefa terminar e saia do Claude normalmente. Aguarde a última exportação antes de parar o receptor com Ctrl+C. Copie a tabela final do histórico de saída do terminal.
Interprete o resultado e investigue dados ausentes
Leia a linha agent_summary para o intervalo medido. request_% usa todos os eventos de requisição à API capturados como denominador. cost_% usa a soma dos custos estimados de todas as requisições à API capturadas:
summary cost share = 100 × summary estimated USD / all captured estimated USDA coluna models lista os modelos informados para cada origem. Para investigar o cache no sistema de monitoramento existente, examine também input_tokens, cache_read_tokens, cache_creation_tokens e output_tokens.
O receptor mantém requisições sem origem no denominador, identificadas como (missing). Ele mostra n/a nas porcentagens de custo se alguma requisição capturada não tiver um custo válido. Resolva os campos ausentes antes de considerar o detalhamento completo.
Sem uma linha agent_summary, nenhuma dessas requisições foi observada naquela janela. Isso não prova que o recurso está desativado. Primeiro confirme que chegaram eventos de prompt e de requisição à API, e que houve trabalho real em segundo plano.
Se nada chegar, confira se o receptor está ativo, se o protocolo é http/json e se o endpoint termina em /v1/logs. Um destino gerenciado pela organização pode ter prioridade sobre a configuração local. Para continuar a investigação, inicie claude --debug-file ./otel-debug.log dentro do mesmo subshell. Procure erros do exportador marcados com [3P telemetry], conforme o guia de monitoramento.
Por que históricos, /usage e faturas podem divergir
Uma linha ausente no histórico pode ocultar a origem do custo sem alterar o total da sessão. Na issue #104358, rabitlord1324 relata registros ausentes de requisições em segundo plano e descreve a contabilização interna do Claude Code como correta.
A documentação atual de uso descreve totais por sessão e uso por modelo. Ela não fornece a divisão por query_source necessária aqui. Não conclua que todos os resumos estão ausentes de /usage só porque um analisador de históricos não os encontra.
cost_usd continua sendo uma estimativa. O Claude Code normalmente usa os preços de tabela, mas a configuração gerenciada modelPricing pode alterar as tarifas dos relatórios. O consumo do limite da assinatura e as cobranças da API são medidas diferentes. Para uso pago por consumo, confronte o resultado com os registros reais do provedor.
Para usuários do BetterToken, a URL base documentada para o Claude Code é https://bettertoken.ai. O catálogo lista claude-opus-5-5 em 2026-11-01. Compare o intervalo medido com o modelo, o consumo de tokens e as cobranças no painel.
Reduza o consumo sem perder trabalho útil
Comece reduzindo o escopo das tarefas ou o número de agentes em segundo plano, se o custo medido justificar isso. Em 2026-11-01, as referências de variáveis de ambiente e subagentes não documentam um controle que desative apenas os resumos.
| Opção | O que muda | Impacto |
|---|---|---|
| Menos tarefas em segundo plano ou tarefas mais curtas | Reduz as oportunidades de repetir resumos do histórico | Pode reduzir o paralelismo útil; compare o tempo de conclusão |
| Um modelo menor para um subagente com tarefa delimitada | Muda o modelo que executa o trabalho delegado | Confira a qualidade e o modelo realmente informado na telemetria |
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 claude | Desativa de forma ampla a execução em segundo plano pelas ferramentas afetadas | Claude espera os subagentes terminarem antes de continuar |
CLAUDE_CODE_FORK_SUBAGENT=0 claude | Desativa a criação autônoma de ramificações da conversa | Subagentes ainda podem rodar em segundo plano; a supressão de resumos não é garantida |
| Patch da comunidade via preload do Bun | Tenta interceptar o temporizador dos resumos | Executa código de terceiros dentro do Claude Code e pode parar de funcionar após uma atualização |
A variável de tarefas em segundo plano remove run_in_background e impede que as ferramentas afetadas movam tarefas automaticamente para segundo plano. Tarefas MCP, a ferramenta Monitor e sessões separadas em segundo plano têm exceções ou controles próprios. Não é um interruptor para toda atividade em segundo plano.
O controle de ramificações, ou modo fork, é documentado, mas o efeito de interromper resumos não é garantido. Na versão 2.1.312, chrisvaillancourt relatou a supressão no macOS. dblumenau continuou observando requisições no Linux. As configurações e o modo de execução diferem entre esses relatos.
Defina o controle antes de iniciar uma nova sessão. Confira entradas env conflitantes em ~/.claude/settings.json e nas configurações do projeto; elas podem substituir valores herdados do shell.
Trate o preload da Flamerix como uma solução alternativa experimental da comunidade. Examine o código de uma revisão fixada antes de considerar seu uso. Verifique a contagem de requisições após cada atualização do cliente; um rótulo congelado não prova que as requisições pararam.
Para pesquisas com escopo delimitado, siga o guia de verificação do modelo de subagentes com acesso somente de leitura. Se definições extensas de ferramentas aumentarem o contexto, use a comparação de custo do contexto MCP para testar um conjunto menor de ferramentas.
Mude uma variável de cada vez. Use a mesma tarefa, modelo e condições de contexto na comparação. Considere o resultado aceito e o tempo gasto junto do custo por origem. Restaure o trabalho em segundo plano se perder paralelismo útil custar mais que a economia medida.
