Claude message threads: o que são e como usar

O que são os message threads

Sem uma thread, cada turno do loop de um agente envia a conversa completa de novo, e a API valida e tokeniza tudo outra vez. Um agente de programação faz centenas de requisições em uma sessão; quando a conversa chega a centenas de milhares de tokens, esse reenvio atrasa o início da resposta do Claude. Com uma thread, a API guarda a conversa entre os turnos e a maior parte desse trabalho cobre só o turno novo.

• Primeiro token mais rápido: a Anthropic mediu uma queda da mediana de cerca de 35% em requisições do Claude Code de 500 mil a 1 milhão de tokens. Quanto mais longa a conversa, maior o ganho.
• Requisições menores: cada turno leva só mensagens novas, resultados de ferramentas ou capturas de tela.
• Mesmos tokens e mesmo preço: o Claude continua lendo a conversa completa a cada turno, e preços e limites de uso não mudam.
• De curta duração: uma thread expira 5 minutos depois da última requisição e fica na memória, criptografada, sem nunca ser gravada em disco.
• Onde: a API do Claude, o Claude Platform na AWS, o Claude Models no Google Cloud (gerenciado pela Anthropic) e o Microsoft Foundry, em todos os modelos.

Com e sem thread

Como usar os message threads no seu próprio agente

O Claude Code já faz isso por você. Para usar threads em um agente que você constrói sobre a Messages API, o helper de threads do SDK é o caminho mais curto.

1. Crie um helper de thread

   Passe os mesmos campos de uma requisição da Messages. O helper adiciona o cabeçalho beta message-threads-2026-08-12, cria a thread no primeiro turno, envia só mensagens novas depois e mantém a conversa completa na memória.

   import anthropic
   
   client = anthropic.Anthropic()
   
   # Cria o helper. Esta chamada não envia nenhuma requisição.
   thread = client.beta.messages.thread(
       model="claude-opus-5-5",
       max_tokens=1024,
       cache_control={"type": "ephemeral"},
       system="You are a coding agent. Keep replies short.",
   )
   
   # O turno 1 cria a thread e envia a conversa completa
   thread.send({"role": "user", "content": "Read the failing test and explain it."})
   
   # O turno 2 envia só a mensagem nova
   reply = thread.send({"role": "user", "content": "Now fix it."})

2. Ou envie você mesmo o campo thread

   Com cURL ou uma chamada create comum, adicione thread a cada requisição e envie o cabeçalho beta em todas. Continue sempre a partir do id da resposta mais recente; cada id só pode ser continuado uma vez.

   # Turno 1: a conversa completa, mais
   "thread": {"type": "create"}
   
   # Todos os turnos seguintes: só as mensagens novas, sem system nem tools, mais
   "thread": {"type": "continue", "previous_message_id": "<id of the last response>"}
   
   # Em toda requisição da thread
   anthropic-beta: message-threads-2026-08-12

3. Mantenha modelo e configurações fixos

   system e tools vão só na primeira requisição. model, thinking, tool_choice, o cache_control de nível superior e os cabeçalhos beta devem ser os mesmos em todos os turnos; qualquer mudança retorna um erro 400 com thread_fingerprint_mismatch. Para mudá-los, comece uma nova thread.

4. Guarde sua própria cópia e reenvie em caso de 404

   As threads funcionam em regime de melhor esforço (best-effort). Quando uma requisição de continuação retorna 404 com thread_not_found (a thread expirou, o último turno não foi armazenado ou um modelo de fallback o escreveu), envie a conversa completa de novo em uma nova requisição create. O helper do SDK faz isso uma vez sozinho.

5. Ative o prompt caching

   Uma thread não coloca seu prompt em cache por você. Envie um cache_control de nível superior em toda requisição para que cada turno leia a conversa anterior do cache; uma requisição com thread pode ter no máximo 4 pontos de corte (breakpoints).

Fonte: a documentação de message threads da Anthropic

Limites e o que as threads não suportam

• Não funcionam com Message Batches, contagem de tokens, compactação sob demanda nem edição de contexto (exceto clear_thinking_20251015 com keep: "all").
• Não estão disponíveis para organizações com HIPAA readiness ou Inference hooks; essas requisições retornam um erro 400 com thread_unsupported_request.
• Não são elegíveis à retenção zero de dados: a API guarda a thread na memória e a exclui no máximo 1 hora após o último uso.
• Não existe API para listar, ler ou excluir uma thread, e uma thread só aceita acréscimos. Para compactar, comece uma nova thread a partir do seu próprio resumo.
• Depois de uma recusa (refusal), não continue a thread: comece uma nova sem o turno que a causou.
• Use a mesma chave de API e o mesmo workspace em todas as requisições de uma thread, ou ela não poderá ser continuada.

O que isso significa para quem usa o Claude Code

Você não precisa mudar nada: a Anthropic diz que as threads vêm ativadas por padrão para a maioria dos usuários do Claude Code. O ganho aparece nas sessões longas, em que um turno avançado de uma conversa grande começa a responder mais cedo. Seu consumo não diminui, porque o Claude continua lendo a conversa inteira a cada turno.

Segundo a documentação da API, uma thread expira 5 minutos depois da última requisição. Quando você volta a uma sessão depois de uma pausa maior, a primeira requisição envia a conversa completa de novo e os turnos seguintes são rápidos. É também o que acontece com uma sessão proativa do Claude Code que acorda em um horário agendado.

Faça as sessões longas do Claude Code trabalharem sozinhas

Os message threads deixam as sessões longas mais rápidas; o Crewmark as deixa proativas. Ele dá a uma sessão do Claude Code, Codex, DeepSeek Harness ou OpenCode um cargo, uma meta e um horário de trabalho, e a acorda com um heartbeat na mesma conversa, de modo que ela mantém o contexto e pega a próxima issue de um quadro.

1. Transforme uma sessão em funcionário

   Escolha um cargo, como engenheiro de software ou especialista em SEO, escreva a meta dele como um número e rode o comando de configuração no Claude Code.

2. Deixe o heartbeat iniciar o trabalho

   Durante o horário de trabalho, o funcionário acorda a cada 15, 30 ou 60 minutos na mesma conversa; veja como tornar o Claude Code proativo. Vários podem rodar lado a lado, como em vários agentes do Claude Code.

3. Atribua issues e responda às mensagens dele

   Coloque trabalho no quadro; o funcionário pega a tarefa, comenta ao longo do caminho e manda mensagem quando precisa de uma decisão. Leia o que é um funcionário de IA.

Perguntas frequentes sobre Claude message threads