Os Claude API Message Threads permitem que a Messages API mantenha uma conversa de curta duração no servidor, para que cada turno seguinte envie apenas as novas mensagens em vez de reenviar todo o histórico. Anunciado em beta público no início de novembro de 2026, o recurso reduz o tamanho das solicitações e o tempo até o primeiro token em execuções longas de agentes, embora o uso de tokens cobrado permaneça exatamente igual.
Se você já criou um assistente de programação ou um ciclo de ferramentas com várias etapas, conhece o problema do turno 40. Sempre que o modelo executa um comando ou examina uma captura de tela, seu cliente reúne todos os prompts, respostas e resultados de ferramentas anteriores e envia o pacote inteiro novamente pela rede. Message Threads é a solução da Anthropic para esse gargalo de transporte e validação, com algumas regras rígidas sobre expiração após cinco minutos, prompt caching e retenção de dados que você precisa considerar no projeto antes de ativá-lo.
O que são Claude API Message Threads?
Message Threads são um cache de conversas no servidor para a Claude Messages API, ativado em beta com o cabeçalho message-threads-2026-08-12. Em vez de tratar cada chamada à API como uma página em branco que exige todo o histórico do chat, o servidor mantém a conversa na memória entre os turnos, para que seu cliente transmita apenas o que mudou desde a última resposta.
Segundo as notas de lançamento e a documentação da Anthropic de 2 de novembro de 2026, isso é separado dos threads de sessão no Claude Managed Agents. Funciona diretamente em /v1/messages com todos os modelos em beta e está disponível na Claude API direta, Claude Platform on AWS, Claude Models on Google Cloud (gerenciado pela Anthropic) e Claude in Microsoft Foundry.
Entre os turnos, a Anthropic mantém o thread na memória do servidor, criptografado com uma chave gerenciada pelo servidor, e nunca o grava em armazenamento persistente em disco.
O que Message Threads economiza e o que não economiza?
Message Threads reduz o volume de upload na rede e o tempo até o primeiro token (TTFT) em conversas longas, mas não reduz a quantidade de tokens cobrados nem altera seus limites de taxa.
Quando uma sessão de agente cresce para centenas de milhares de tokens, algo comum quando um ciclo de programação lê arquivos grandes ou um agente que usa o computador troca capturas de tela, reenviar e validar essa carga a cada turno acrescenta um atraso perceptível antes mesmo de o modelo começar a gerar. A Anthropic afirma que Message Threads está ativado por padrão para a maioria dos usuários do Claude Code e que solicitações com 500k a 1M tokens apresentam queda de cerca de 35% na mediana do TTFT.
A conta não muda. Mesmo que sua solicitação HTTP contenha apenas a mensagem mais recente do usuário ou a saída de uma ferramenta, o Claude ainda lê a conversa inteira em cada turno. Aplicam-se as tarifas padrão de tokens: em novembro de 2026, o Claude Opus 5.5 custa na tabela $4 por milhão de tokens de entrada ($0.20 em cache) e $20 por milhão de tokens de saída, enquanto o Sonnet 5.5 custa $2 de entrada ($0.10 em cache) e $10 de saída (consulte nossa comparação de preços de APIs de IA e nosso guia Claude Opus 5.5 vs. Sonnet 5.5 para comparar essas faixas de preço).
| O que muda com Message Threads | O que continua igual |
|---|---|
| Cargas menores nas solicitações HTTP dos turnos seguintes | Tokens de toda a conversa lidos e cobrados em cada turno |
| Menor tempo até o primeiro token (segundo a Anthropic, queda mediana de ~35% no TTFT em solicitações de 500k–1M tokens no Claude Code) | Preços padrão de tokens da API e limites de taxa existentes |
system e tools enviados uma vez na criação do thread |
Seu aplicativo continua sendo a fonte de referência do histórico de mensagens |
Como criar e continuar um thread?
Você inicia um thread enviando uma solicitação normal a /v1/messages com "thread": {"type": "create"} e o cabeçalho beta message-threads-2026-08-12. No turno seguinte, continua o thread passando o id da resposta como previous_message_id. Se usar os SDKs da Anthropic, o auxiliar client.beta.messages.thread(...) gerencia o fluxo de criação e continuação e anexa automaticamente o cabeçalho beta.
Na chamada inicial create, inclua toda a conversa até aquele momento junto com system e tools:
{
"model": "claude-sonnet-5-5",
"max_tokens": 2048,
"system": "You are a careful repository refactoring assistant.",
"tools": [
{
"name": "run_tests",
"description": "Run the project test suite",
"input_schema": { "type": "object", "properties": {} }
}
],
"thread": {
"type": "create"
},
"messages": [
{ "role": "user", "content": "Check why the auth test is failing." }
]
}
A API retorna uma resposta de mensagem padrão com um id (por exemplo, msg_01XYZ...) que representa a conversa armazenada, incluindo a resposta do Claude. No turno seguinte, você envia somente as novas mensagens, como um tool_result ou o próximo prompt do usuário, e faz referência a esse id:
{
"model": "claude-sonnet-5-5",
"max_tokens": 2048,
"thread": {
"type": "continue",
"previous_message_id": "msg_01XYZ..."
},
"messages": [
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01ABC...",
"content": "FAIL src/auth.test.ts: expected 200, got 401"
}
]
}
]
}
Regras que podem causar problemas se você não ler a documentação
A Anthropic exige consistência rigorosa durante toda a vida de um thread:
- Campos apenas na criação: Você deve omitir
systemetoolsem toda solicitaçãocontinue. Enviá-los novamente retorna um erro400. - Campos fixos: Seu
model,tool_choice,thinking,mcp_servers(exceto o token de autenticação de cada servidor),context_management,output_config, as skills de contêiner,cache_controlde nível superior e o conjunto exato de valores do cabeçalhoanthropic-betadevem corresponder à chamada inicialcreate. Alterar qualquer um deles gera um erro400thread_fingerprint_mismatch. - Campos por turno: Você continua livre para alterar
max_tokens,stop_sequences,stream,metadataeservice_tierde um turno para outro. - Histórico somente para acréscimo: Cada
idde resposta só pode ser continuado uma vez, e você deve sempre continuar a partir doidda resposta mais recente. Se precisar editar uma mensagem anterior ou criar uma ramificação da conversa, terá de iniciar um novo thread comcreate.
Quanto tempo dura um Message Thread?
Um Message Thread expira 5 minutos após sua última solicitação e é excluído permanentemente da memória do servidor em até 1 hora após seu último uso. Cada resposta armazenada com sucesso reinicia o temporizador de 5 minutos.
Como os threads ficam em memória volátil como um cache de melhor esforço, a resposta da API nunca informa antecipadamente se um turno específico foi armazenado com sucesso. Você só descobre na próxima chamada continue. Se a janela de 5 minutos tiver passado ou o servidor tiver removido o thread antes, a API retornará um erro 404.
Quando seu cliente recebe um 404, a recuperação é simples: reenvie todo o histórico da conversa (junto com system e tools) em uma nova solicitação "thread": {"type": "create"}. Seu aplicativo deve continuar sendo a fonte de referência e manter sua própria cópia completa de cada mensagem e resultado de ferramenta.
Como Message Threads funciona com prompt caching?
Message Threads e prompt caching resolvem partes diferentes do problema de contextos longos, e prompt caching não é ativado automaticamente quando você habilita threads. Message Threads reduz os bytes que você envia e valida pela rede; prompt caching reduz o valor pago por tokens de entrada repetidos (por exemplo, diminuindo os tokens de entrada do Sonnet 5.5 de $2 para $0.10 por milhão, conforme detalhado em nossa comparação de preços de APIs de IA).
Se quiser tanto um TTFT mais rápido quanto custos menores de tokens de entrada, você precisa ativar os dois. Para armazenar em cache cada turno de um thread, inclua cache_control de nível superior na solicitação inicial create e continue enviando o mesmo cache_control de nível superior em cada solicitação continue (lembre-se de que cache_control de nível superior é um dos campos fixos que precisam corresponder em todo o thread). A Anthropic permite no máximo 4 pontos de interrupção cache_control quando thread está definido.
Quem deve ativar Message Threads?
Equipes que executam ciclos longos de programação, fluxos de uso do computador ou agentes com vários turnos e muitos documentos terão o benefício mais claro, enquanto equipes com requisitos rígidos de conformidade ou pipelines em lote talvez precisem abrir mão do recurso. Se você ainda não conhece a diferença entre ciclos que usam ferramentas e chatbots comuns, nosso guia sobre o que é um agente de IA aborda os fundamentos.
Onde Message Threads se encaixa melhor:
- Agentes de programação: Ciclos que leem arquivos, executam compiladores e iteram por dezenas de turnos rápidos dentro da janela ativa de 5 minutos. (A Anthropic já o ativou por padrão para a maioria dos usuários do Claude Code.)
- Agentes que usam o computador: Fluxos em que cada turno anexa uma nova captura da área de trabalho ou do navegador; manter as capturas anteriores no servidor evita reenviar megabytes de dados de imagem em base64 a cada etapa.
- Chats com muitos documentos e imagens: Sessões interativas em que um usuário envia PDFs grandes ou conjuntos de imagens e faz perguntas de acompanhamento rapidamente. Mesmo que seu agente orquestre pipelines de mídia externos, por exemplo, escrevendo roteiros e iniciando renderizações em uma ferramenta como AI Studio, manter o contexto volumoso de planejamento e as imagens de referência em um thread no servidor mantém o ciclo de coordenação ágil.
Onde está bloqueado ou não é compatível em novembro de 2026:
- Organizações com Zero Data Retention (ZDR) e HIPAA: Message Threads não são elegíveis para ZDR, e organizações com prontidão para HIPAA ativada não podem usá-los.
- Recursos da API sem suporte: Você não pode usar
threadcom Message Batches, solicitações de contagem de tokens que incluamthread, compactação sob demanda, a maioria das estratégias de edição de contexto (excetoclear_thinking_20251015comkeep: "all") ou organizações que tenham Inference hooks ativados.
O que eu faria na prática
Se você mantém uma infraestrutura de agentes na Claude Messages API, eu ativaria Message Threads onde uma única tarefa ultrapassa regularmente 100k tokens e os turnos ocorrem com menos de cinco minutos de intervalo, desde que suas exigências de conformidade permitam. Esta é a lista de implantação que eu seguiria:
- Mantenha intacto seu armazenamento local de conversas. Trate os threads mantidos no servidor estritamente como um acelerador de transporte, nunca como seu banco de dados. Acrescente localmente cada turno do usuário, resposta do assistente e resultado de ferramenta como faz hoje.
- Envolva
continueem uma alternativa automática para404. Quando uma chamadacontinueretornar404(seja por uma pausa ociosa de 5 minutos ou por uma remoção de melhor esforço), capture o erro e reenvie imediatamente todo o histórico local com"thread": {"type": "create"},systemetools. - Combine com
cache_controlde nível superior. Nunca ative Message Threads esperando que sua conta diminua. Coloquecache_controlde nível superior nas chamadascreateecontinuepara obter o desconto de 90%+ na entrada em cache junto com a melhora do TTFT. Consulte nossa comparação de preços de APIs de IA para estimar os custos de entrada com e sem cache em 500k tokens. - Fixe a configuração do thread na criação. Verifique seu ciclo de agente para garantir que ele não altere dinamicamente
tools,system,thinkingou cabeçalhosanthropic-betadurante uma tarefa, caso contrário você receberá erros400thread_fingerprint_mismatch. - Confira primeiro as configurações de ZDR e HIPAA. Se seu espaço de trabalho depende de Zero Data Retention ou prontidão para HIPAA, mantenha Message Threads desativado: o beta não é elegível para nenhum dos dois.
Perguntas frequentes
Message Threads reduz meu custo de tokens da Claude API?
Não. Embora cada solicitação HTTP seguinte carregue apenas as novas mensagens, o Claude ainda lê todo o histórico da conversa em cada turno. Todos os tokens de entrada e saída são cobrados pelas tarifas padrão do Claude, e os limites de taxa existentes continuam valendo. Para reduzir sua conta de tokens de entrada em contextos repetidos, combine Message Threads com prompt caching.
Ainda preciso de prompt caching se usar Message Threads?
Sim. Message Threads apenas mantém a conversa na memória do servidor para que você não precise reenviar e revalidar mensagens anteriores pela rede. Ele não ativa prompt caching automaticamente. Para obter o preço de entrada em cache a cada turno, envie cache_control de nível superior na solicitação inicial create e em cada solicitação continue posterior (até 4 pontos de interrupção no total).
O que acontece após 5 minutos de inatividade?
Um Message Thread expira 5 minutos após a última solicitação (e é excluído da memória em até 1 hora após o último uso). Se você enviar uma solicitação continue após a expiração do thread, a API retornará o código de status 404. Seu cliente deve capturar esse 404 e reenviar toda a conversa com "thread": {"type": "create"} para iniciar um novo thread.
Message Threads está disponível na AWS, Azure e Google Cloud?
Sim. Segundo as notas de lançamento da Anthropic de 2 de novembro de 2026, o beta público (message-threads-2026-08-12) está disponível na Claude API direta, Claude Platform on AWS, Claude Models on Google Cloud (gerenciado pela Anthropic) e Claude in Microsoft Foundry.
O Claude Code já usa Message Threads?
Sim. A Anthropic afirma que Message Threads está ativado por padrão para a maioria dos usuários do Claude Code, onde solicitações entre 500k e 1M tokens apresentam redução mediana de cerca de 35% no tempo até o primeiro token.
Detalhes do recurso verificados pela última vez em 3 de novembro de 2026. Próxima revisão: 3 de dezembro de 2026.
Fontes
- Anthropic, Notas de lançamento da Claude Platform (2 de novembro de 2026), consultadas em 3 de novembro de 2026
- Anthropic, Acelere agentes de longa duração com Message Threads, consultado em 3 de novembro de 2026
- Documentação da Anthropic, Message Threads (
message-threads-2026-08-12), consultada em 3 de novembro de 2026 - LoTook, Comparação de preços de APIs de IA, consultada em 3 de novembro de 2026



