AIREITERA Anthropic lançou o Message Threads em beta público em 2 de novembro de 2026. O ganho principal é fácil de interpretar errado: em requisições de 500 mil a 1 milhão de tokens, o tempo mediano até o primeiro token cai cerca de 35%, mas a cobrança de tokens continua exatamente igual. Para quem mantém agentes em loops longos, trata-se de uma otimização de transporte com um limite rígido de 5 minutos de inatividade.
Requisições mais rápidas, mesma cobrança: o que os threads mudam — e o que não mudam
Message threads são um estado temporário de conversa mantido no servidor para a Messages API, lançado em beta público em 2 de novembro de 2026. Você envia todo o histórico uma vez usando thread: { "type": "create" } e, nas chamadas seguintes, manda apenas as mensagens novas junto de previous_message_id, usando thread: { "type": "continue" }. Segundo o anúncio da Anthropic e a documentação da plataforma, o estado fica na memória criptografada, nunca é gravado em disco, expira após 5 minutos de inatividade e é apagado no máximo 1 hora depois do último uso.
Toda requisição dentro de um thread precisa incluir o cabeçalho beta anthropic-beta: message-threads-2026-08-12. Preços e limites de uso não mudam: o Claude continua lendo a conversa inteira a cada turno. A economia está no volume de dados enviados, não na quantidade de tokens processados ou cobrados.
"Legal, mas isso não reduz o custo dos tokens :( O Claude continua lendo a conversa inteira em cada turno e o consumo de tokens permanece inalterado" — @_navicstein, em resposta ao thread oficial de lançamento
O anúncio oficial informa uma redução de aproximadamente 35% no TTFT mediano para requisições de 500 mil a 1 milhão de tokens, sem qualquer desconto nos tokens.
Threads e prompt caching em um parágrafo
Threads reduzem o que você envia; o prompt caching reduz o que você paga pelo preço cheio. Threads não fazem cache automaticamente: você ainda precisa definir pontos de interrupção com cache_control. A interação detalhada com o cache abaixo segue o detalhamento da implementação: mantenha um cache_control no nível superior em toda continuação, com leituras de cache a 0,1x do preço-base de entrada (0,05x no Claude Opus 5.5 e no Sonnet 5.5).
Threads e threads de sessão de agentes gerenciados
Os resultados de busca misturam dois recursos diferentes chamados “threads”. Os message threads da Messages API — assunto deste artigo — são uma otimização efêmera do tamanho das requisições e não têm API para listar, ler ou excluir dados. Já os threads de sessão de agentes gerenciados (GET /v1/sessions/{session_id}/threads/{thread_id}) são threads de execução dentro da API de managed agents da Anthropic, com endpoints para listar, recuperar e arquivar. Se a documentação mencionar threads filhos, fluxos de eventos ou arquivamento, você está olhando para a API errada. Consulte a referência da API para session threads para confirmar qual recurso precisa usar.
Como um thread funciona na prática: criar, continuar e expirar
Na prática, um thread funciona de forma incremental: você cria com o contexto completo, continua enviando apenas as diferenças e faz replay quando o estado é perdido. Não há API para ramificar, editar, voltar atrás ou inspecionar a conversa. Cada resposta retorna um novo id, e cada id só pode ser continuado uma vez. As regras de campos e erros desta seção seguem a documentação da plataforma, conforme detalhado no detalhamento da implementação.
A criação leva tudo: messages, system e tools completos, além de:
{
"model": "claude-opus-5-5",
"system": "You are a support agent for Acme. Keep replies short.",
"messages": [{ "role": "user", "content": "Hi! I have a question about an order." }],
"thread": { "type": "create" }
}A continuação leva apenas o que é novo — normalmente uma mensagem do usuário ou blocos tool_result:
{
"model": "claude-opus-5-5",
"messages": [{ "role": "user", "content": "How long does standard shipping usually take?" }],
"thread": { "type": "continue", "previous_message_id": "msg_xxx_from_create" }
}Não envie system nem tools em uma continuação — até "system": null resulta em erro 400. Em streams, espere pelo evento message_stop antes de continuar; o ID que pode ser usado na continuação chega em message_start.
Quais campos podem mudar no meio do thread
A Anthropic cria uma impressão digital de parte da requisição inicial. Se um valor incluído nessa impressão mudar, a API retorna thread_fingerprint_mismatch e exige um novo thread.
| Grupo | Exemplos | Regra na continuação |
|---|---|---|
| Apenas na criação | system, tools | Nunca reenvie; null também falha |
| Fixos | model, tool_choice, thinking, mcp_servers, context_management, output_config, habilidades do container, tratamento do cache_control no nível superior | Devem permanecer idênticos |
| Livres | max_tokens, stop_sequences, stream, metadata, service_tier | Podem mudar a cada turno |
| Sempre reenviar | URLs / tokens de autenticação dos servidores MCP, ID do container | Não ficam armazenados no servidor; inclua-os sempre que forem usados |
Modelos com extended thinking exigem atenção extra: alterar system ou tools pode invalidar blocos anteriores de thinking / redacted_thinking. Se um replay completo após a expiração retornar 400, remova os blocos de thinking antigos do histórico reenviado em vez de repetir a requisição sem alterações.
A regra dos 5 minutos e o replay que você precisa implementar
Trate os threads como um recurso de melhor esforço: mantenha localmente o histórico completo, o system prompt, as ferramentas e as referências a arquivos, porque o armazenamento só é confirmado quando a próxima continuação é concluída com sucesso. Os arquivos são mantidos por referência — se um arquivo for excluído no meio do thread, a continuação falhará.
O relógio de expiração é reiniciado a cada resposta armazenada. Depois de 5 minutos sem atividade, a próxima continuação retorna 404, e você precisa reenviar toda a conversa como uma nova create. Os dados são apagados no máximo 1 hora após o último uso.
| HTTP | Código | O que aconteceu | O que fazer |
|---|---|---|---|
| 404 | thread_not_found | Expirou, não foi armazenado, a chave ou workspace está incorreto, a primeira imagem foi adicionada a um thread somente de texto, um modelo de fallback recebeu a requisição ou a resposta ainda está sendo gerada | Verifique a chave, o workspace e a configuração; depois faça replay de todo o histórico como um novo create |
| 400 | thread_fingerprint_mismatch | Um campo fixo foi alterado | Restaure o valor original ou inicie um novo thread |
| 400 | thread_already_continued | O previous_message_id já foi usado | Continue a partir do id mais recente |
| 400 | thread_continue_in_flight | Houve uma continuação concorrente usando o mesmo ID | Espere a operação terminar e use o novo ID; caso contrário, faça replay |
| 400 | thread_unsupported_request | Configuração não suportada (por exemplo, mais de 4 pontos de cache ou batches) | Remova a configuração ou envie a requisição sem thread |
Segundo o resumo da documentação, requisições de thread que falham são interrompidas antes da execução do modelo. Portanto, não consomem tokens nem reiniciam o temporizador de expiração. Salve atomicamente o ID da última resposta bem-sucedida antes de aceitar o turno seguinte e proteja os replays contra duplicidade quando as ações de ferramentas tiverem efeitos colaterais.
Estrutura de replay em Python (trate apenas thread_not_found confirmado; erros de fingerprint, concorrência e requisição não suportada precisam de ramificações próprias):
try:
resp = client.beta.messages.create(
model="claude-opus-5-5",
messages=[new_msg], # delta only
thread={"type": "continue", "previous_message_id": last_id},
extra_headers={"anthropic-beta": "message-threads-2026-08-12"},
)
except NotFoundError: # thread_not_found after checking identity/config
resp = client.beta.messages.create(
model="claude-opus-5-5",
system=SYSTEM, tools=TOOLS,
messages=full_history + [new_msg], # you stored this
thread={"type": "create"},
extra_headers={"anthropic-beta": "message-threads-2026-08-12"},
)A armadilha do erro 404 com proxy e rotação de chaves
Este comportamento foi relatado por operadores, mas ainda não aparece na documentação oficial: um thread fica vinculado à organização, ao workspace e à credencial que o criou. Um relay que alterna as chaves de API a cada requisição pode criar o thread com a chave A e tentar continuá-lo com a chave B. O resultado se parece exatamente com uma expiração: uma sequência interminável de 404, seguida de replay completo e sem qualquer ganho de latência.
"O thread fica vinculado à chave e ao workspace usados na criação; trocar a chave gera 404 thread_not_found. Um intermediário que alterna chaves primeiro recebe 404 e depois reenvia tudo." — @ak12kpoot (nota de um desenvolvedor chinês sobre o comportamento de proxies)
Prenda cada thread a uma única chave ou desative threads em rotas que usam pools.
Onde os threads funcionam, o que fica de fora e se já vale migrar
Message threads estão disponíveis na Claude API, na Claude Platform na AWS, no Anthropic-managed Google Cloud Claude Models e no Claude in Microsoft Foundry. Todos os modelos em beta estão incluídos; não existe uma lista de modelos separada nem uma fila de espera informada.
Para o planejamento do lançamento, as limitações são ainda mais importantes:
| Área | Status |
|---|---|
| Amazon Bedrock | Não suportado |
| Message Batches | Não suportado — itens de threads em batches falham |
| Endpoint de contagem de tokens | Não suportado — conte o histórico completo por conta própria |
| Compactação / edição de contexto | Não suportado (exceto clear_thinking com keep all) |
| Zero data retention, compatibilidade com HIPAA e inference hooks | Não elegíveis |
| API de gerenciamento de threads | Não existe — não é possível listar, ler ou excluir threads |
Checklist para decidir
- Use threads agora: agentes de programação ativos, loops de uso do computador com capturas de tela ou fluxos pesados em documentos que fazem dezenas de turnos com intervalos menores que 5 minutos. Combine com prompt caching e uma rotina de replay.
- Espere por enquanto: chats conduzidos no ritmo de pessoas, fluxos pausados, pipelines em batch, cargas com ZDR/HIPAA ou implantações no Bedrock.
- Combine quando fizer sentido: um
cache_controlno nível superior em cada requisição conta para o limite de 4 pontos de interrupção; os pontos definidos emsystem/toolsna criação também contam novamente em cada continuação. Ultrapassar esse limite retornathread_unsupported_request, então consolide os pontos de cache antes de ativar os dois recursos.
Veja também: guia de preços da Claude API 2026, guia da Claude Skills API.
Perguntas frequentes
Qual cabeçalho beta e qual parâmetro preciso usar?
Envie anthropic-beta: message-threads-2026-08-12 em toda requisição do thread, além de thread: { "type": "create" } na primeira chamada e thread: { "type": "continue", "previous_message_id": "<last response id>" } nas seguintes.
O que acontece quando um thread expira?
A próxima continuação retorna 404 thread_not_found. Reenvie o messages completo junto do system/tools original como uma nova create. A expiração ocorre após 5 minutos de inatividade, e a exclusão acontece no máximo 1 hora depois do último uso.
Posso listar, inspecionar ou excluir threads?
Não. A Messages API não oferece uma API de gerenciamento para esses threads. Seu histórico local é o único registro persistente.
Isso funciona no Amazon Bedrock?
Não. As superfícies compatíveis são Claude API, AWS Claude Platform, Microsoft Foundry e Anthropic-managed Google Cloud. Requisições para o Bedrock devem continuar enviando o histórico completo.
Posso mudar o system prompt ou as ferramentas no meio do thread?
Não. Crie um novo thread com o system/tools atualizado. Enviar valores diferentes durante a continuação dispara thread_fingerprint_mismatch. A mesma regra vale para model, tool_choice e a configuração de thinking.
Funciona com streaming, ferramentas e MCP?
Sim, mas há regras: espere o message_stop antes de continuar, reenvie as URLs/tokens do MCP e os IDs do container em cada turno e envie fallbacks em todas as requisições ou em nenhuma. Uma resposta gerada por um modelo de fallback não é armazenada e precisa passar por replay.