O caso: uma equipe roda um agente de revisão de código no Claude Sonnet 5.5 com o SDK em TypeScript. O agente usava a compactação do próprio SDK para resumir a conversa quando ela crescia. Com os SDKs lançados em 21 de outubro de 2026, essa opção sumiu e a compactação passa a rodar no servidor da API. A equipe quer saber o que quebra e quanto isso muda na conta.
Resposta curta: a versão 2026-10-21 da API rejeita temperature, top_p e top_k, e a compactação do lado do cliente saiu do executor de ferramentas dos SDKs de TypeScript e Ruby. Numa sessão de exemplo de 40 passos com cache, que custa US$ 1,162, compactar a 100.000 tokens leva a conta para US$ 1,063 a US$ 1,253: quase nada muda. Sem cache, a mesma compactação economiza US$ 2,82 por sessão.
O que mudou em 21 de outubro
A Anthropic lançou a versão 2026-10-21 da API em 21 de outubro de 2026, segundo as notas de versão da Claude Platform. Junto vieram novas versões principais de todos os SDKs e da linha de comando ant, que já enviam a versão nova por padrão: Python 2.0.0, TypeScript 1.0.0, C# 13.0.0, Go 2.0.0, Java 3.0.0, PHP 1.0.0, Ruby 2.0.0 e ant 2.0.0.
O guia de migração oficial compara a versão nova com a anterior, 2023-06-01. Ele diz que um pedido que depende de um valor fora do padrão pode continuar na versão antiga. Quem atualiza o SDK muda de versão sem perceber, porque ele passa a enviar 2026-10-21 sozinho.
As licenças dos SDKs também mudaram, de MIT para Apache 2.0.
O que quebra na API
As mudanças valem para a Messages API, para a contagem de tokens e para cada pedido de um lote criado com a versão nova.
| Mudança | O que acontece na versão 2026-10-21 | O que fazer |
|---|---|---|
temperature, top_p e top_k |
Erro 400, mesmo com o valor padrão | Tirar os três parâmetros do pedido |
Bloco document dentro de mensagem assistant |
Erro 400 | Mandar documentos em mensagens user |
citations em blocos de texto de mensagem user |
Erro 400 | Tirar citations desses blocos |
workspace_id das chaves (Admin API) |
Campo removido | Ler scope.workspace_id |
O guia faz uma ressalva sobre a temperatura. Os modelos Claude 4.7 e posteriores já só aceitavam os valores padrão, então eles respondem como antes. Num modelo que aceitava outros valores, como o Claude Sonnet 4.6, quem baixava a temperatura para ter respostas mais estáveis perde esse efeito. Nada substitui o parâmetro.
O que quebra nos SDKs
Algumas mudanças não dependem da versão da API, só da versão do SDK:
- Chave no cabeçalho
Authorization. A chave de API passa a ir comoAuthorization: Bearer, e não mais emX-Api-Key, nos clientes principais. Um proxy ou gateway que liaX-Api-Keyprecisa de ajuste. - Uma credencial por cliente. O cliente não manda mais chave e token juntos.
- Text Completions saiu. A API antiga de completar texto foi removida dos SDKs de TypeScript, Go, Java e Ruby e da linha de comando.
- Compactação do cliente saiu. No TypeScript e no Ruby, a opção de compactação do executor de ferramentas foi removida em favor da compactação no servidor.
A última mudança é a que mexe na conta.
Como a compactação no servidor é cobrada
A compactação troca os turnos antigos da conversa por um resumo que o próprio Claude escreve no servidor. Na versão por limite de tokens, a API resume a conversa quando a entrada chega ao gatilho que você define. Pela documentação, o gatilho padrão é de 150 mil tokens e o mínimo é de 50 mil. O exemplo de migração do guia usa 100.000. O recurso está em beta, com o cabeçalho compact-2026-01-12.
A documentação é clara sobre o custo: o resumo é uma etapa extra de geração, que conta para os limites de uso e para a fatura. A resposta traz o consumo dessa etapa numa lista separada, usage.iterations.
O ponto de atenção está aqui. Os campos usage.input_tokens e usage.output_tokens do topo da resposta não incluem a etapa de compactação. Para saber o total cobrado, é preciso somar todas as entradas de usage.iterations. Quem mede custo só pelos campos do topo vai subestimar a fatura.
Reaplicar um bloco de compactação que já existe não custa nada a mais, segundo a mesma página.
A conta de uma sessão
Premissas de exemplo, não medidas de uma equipe real:
- 40 passos por sessão no Sonnet 5.5;
- 20.000 tokens fixos de sistema e ferramentas, sempre lidos do cache;
- 4.000 tokens novos de conversa a cada passo (resultado de ferramenta e resposta anterior), gravados no cache;
- 800 tokens de saída por passo;
- gatilho de compactação em 100.000 tokens e resumo de 3.500 tokens, o tamanho do exemplo da documentação.
Sem compactação, a conversa cresce até 176.000 tokens no último passo. Com compactação, o resumo entra depois de 20 passos, e a sessão termina com 99.500 tokens. Há uma compactação só.
A documentação não diz se a etapa de resumo aproveita o cache. Por isso, a conta mostra dois casos. No pior, os 100.000 tokens lidos pelo resumo pagam o preço cheio de entrada. No melhor, pagam o preço de leitura do cache.
| Cenário | Custo por sessão | Mês com 660 sessões | Em reais por mês |
|---|---|---|---|
| Com cache, sem compactação | US$ 1,162 | US$ 766,92 | R$ 3.841,96 |
| Com cache e compactação (melhor caso) | US$ 1,063 | US$ 701,42 | R$ 3.513,81 |
| Com cache e compactação (pior caso) | US$ 1,253 | US$ 826,81 | R$ 4.142,01 |
| Sem cache, sem compactação | US$ 8,160 | US$ 5.385,60 | R$ 26.979,70 |
| Sem cache, com compactação | US$ 5,335 | US$ 3.521,10 | R$ 17.639,30 |
O mês supõe 30 sessões por dia em 22 dias úteis. Preços do Sonnet 5.5 pela tabela do site, atualizada em outubro de 2026.
O que a conta mostra
Com cache, a compactação quase não muda a conta. No pior caso, a sessão fica US$ 0,091 mais cara. A leitura do cache no Sonnet 5.5 custa US$ 0,10 por milhão de tokens, contra US$ 2,00 da entrada normal. Encurtar a conversa economiza pouco quando reler o histórico já é barato. A etapa de resumo, cobrada à parte, come essa economia.
Sem cache, a história é outra. Reler o histórico inteiro a cada passo pelo preço cheio pesa muito. Aí, a compactação corta US$ 2,82 por sessão, ou US$ 1.864,50 no mês do exemplo, cerca de R$ 9.340,40.
A documentação dá outro motivo para compactar: manter a tarefa dentro da janela de contexto, porque a qualidade da resposta cai quando a conversa cresce. Para quem já usa cache, esse é o ganho principal.
Há um cuidado com o cache. Quando o resumo entra, ele é conteúdo novo e precisa ser gravado. Sem um ponto de cache no fim do prompt de sistema, a troca invalida também o sistema guardado. A documentação recomenda pôr um cache_control no fim do prompt de sistema, para que só o resumo seja gravado de novo.
O custo que o painel não mostra
No pior caso do exemplo, a etapa de compactação custa US$ 0,244 por sessão. Isso é 19,5% do custo total da sessão. Um painel interno que soma só os campos do topo de usage deixa esse valor de fora. No mês do exemplo, a diferença chega a US$ 160,88.
Checklist para migrar
- Procure
temperature,top_petop_kno código. Tire os três ou mantenha esse pedido na versão2023-06-01. - Revise o proxy. Se ele lê ou troca
X-Api-Key, ajuste paraAuthorization. - Troque a compactação do cliente. No TypeScript e no Ruby, use
context_managementcom a estratégiacompact_20260112e o cabeçalho beta. O gatilho precisa ter pelo menos 50 mil tokens. - Some
usage.iterations. Atualize o cálculo de custo antes de ligar a compactação. - Ponha cache no fim do sistema. Assim, a compactação só regrava o resumo.
- Teste com a sua carga. Os números acima são de exemplo. Rode uma amostra das suas sessões e compare.
Perguntas frequentes
A versão 2023-06-01 parou de funcionar?
Não. O guia de migração diz que um pedido que depende de um valor fora do padrão pode continuar na 2023-06-01. Mas o SDK novo envia 2026-10-21 por padrão.
A compactação no servidor é de graça?
Não. A etapa de resumo é cobrada. No exemplo, ela custa entre US$ 0,054 e US$ 0,244 por vez no Sonnet 5.5, conforme o resumo leia ou não do cache.
Compactar barateia um agente?
Depende do cache. Com cache, a sessão de exemplo vai de US$ 1,162 para US$ 1,063 a US$ 1,253. Sem cache, fica US$ 2,82 mais barata.
Por que o meu painel de custo mostra menos que a fatura?
Se a compactação estiver ligada, os campos do topo de usage deixam a etapa de resumo de fora. É preciso somar usage.iterations. No pior caso do exemplo, a diferença é de 19,5% por sessão.
Qual é o menor gatilho de compactação?
50 mil tokens. Abaixo disso, a API recusa. O padrão é de 150 mil.
Quer refazer a conta com o seu agente? Use a calculadora de agentes de código.
