Threads de mensagens

Com uma “message thread” (thread de mensagens), as requisições são menores, e o “time to first token” (tempo até o primeiro token) permanece mais baixo e mais estável à medida que a conversa cresce. As threads ajudam mais em loops longos de agentes. Sem uma thread, cada turno envia a conversa inteira novamente, e a API valida e tokeniza tudo de novo. Com uma thread, a maior parte desse trabalho cobre apenas o novo turno.

Uma “message thread” (thread de mensagens) mantém uma conversa no servidor por um curto período. Você envia a conversa completa uma vez, com seu prompt do sistema e suas ferramentas. Em cada turno posterior, você envia apenas as novas mensagens e o id da resposta anterior. A API reconstrói a conversa antes de chamar o modelo. Você adiciona um parâmetro, thread, a uma requisição da Messages API. A resposta é a mensagem habitual.

Como as threads de mensagens funcionam

• Criar. Envie sua primeira solicitação como você faz hoje, com a conversa completa, system e tools, e adicione "thread": {"type": "create"}. A API armazena a conversa, incluindo a resposta de Claude, sob o id da resposta.
• Continuar. Envie apenas as mensagens desde a resposta anterior e adicione "thread": {"type": "continue", "previous_message_id": "<previous id>"}. Deixe system e tools fora da solicitação. A thread mantém os valores da solicitação de criação. Use cada novo id de resposta para o próximo turno.
• Reenviar. Uma thread funciona no modelo de melhor esforço. Ela expira 5 minutos após sua última requisição, e a API a exclui no máximo 1 hora após seu último uso. Cada resposta que a API armazena reinicia os 5 minutos. Se a API não puder mais continuar a thread, uma solicitação de continuação retorna um erro 404. Envie a conversa completa novamente em uma nova solicitação de criação e continue a partir do id dessa resposta. O helper de thread do SDK faz esse reenvio para você (consulte Como o helper do SDK se comporta). Após uma resposta de um modelo de fallback, consulte Usar fallbacks com uma thread.

Sua aplicação continua sendo a fonte da verdade para a conversa. Mantenha sua própria cópia de cada mensagem e construa o caminho de reenvio desde o início. Nenhuma resposta, seja a uma solicitação de criação ou de continuação, informa se a API armazenou aquele turno. Você descobre isso na próxima solicitação de continuação. O helper de thread do SDK mantém essa cópia na memória enquanto o objeto helper existir, e não a salva em nenhum outro lugar. Se a conversa precisar sobreviver ao seu processo, mantenha sua própria cópia.

Usar uma thread com um SDK

O SDK tem um helper de thread que monta as solicitações de thread para você. Crie-o com os mesmos campos de uma solicitação da Messages API e, em seguida, envie um turno de cada vez. O helper mantém a conversa completa na memória.

Este exemplo tem dois turnos. O helper cria uma thread no primeiro turno e a continua no segundo, e adiciona o cabeçalho beta para você. O cache_control de nível superior é opcional. Ele solicita cache de prompt em cada turno (consulte Cache de prompt em uma thread). Sem ele, cada turno posterior ainda envia apenas as novas mensagens, mas nada é armazenado em cache, a menos que você mesmo adicione pontos de interrupção de cache.

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 support agent for Acme. Keep replies short.",
)

# Turno 1: o helper cria uma thread e envia a conversa completa
thread.send({"role": "user", "content": "Hi! I have a question about an order."})

# Turno 2: o helper continua a thread e envia apenas a nova mensagem
second = thread.send(
    {"role": "user", "content": "How long does standard shipping usually take?"}
)

for block in second.content:
    if block.type == "text":
        print(block.text)

Enviar o campo thread você mesmo

Para construir as requisições de thread você mesmo, por exemplo com cURL, a CLI ou o método create habitual de um SDK, adicione o campo thread a cada requisição.

Envie o cabeçalho beta message-threads-2026-08-12 em todas as requisições de uma thread.

Este exemplo cria uma thread no primeiro turno e a continua no segundo. O cache_control de nível superior solicita cache de prompt em cada turno. Ele entra em vigor quando a conversa ultrapassa o comprimento mínimo armazenável em cache.

client = anthropic.Anthropic()

# Turno 1: envie a conversa completa e crie uma thread
first = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    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"},
    betas=["message-threads-2026-08-12"],
)

# Turno 2: envie apenas a nova mensagem e o id da resposta do turno 1.
# Omita system e tools: a thread os mantém.
second = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    messages=[
        {"role": "user", "content": "How long does standard shipping usually take?"}
    ],
    thread={"type": "continue", "previous_message_id": first.id},
    betas=["message-threads-2026-08-12"],
)

for block in second.content:
    if block.type == "text":
        print(block.text)

O que enviar em cada requisição

A API não armazena URLs de servidores MCP, tokens de autorização MCP nem o id do container. Envie mcp_servers e container em todas as requisições que os utilizam. Um token de autorização MCP pode mudar entre requisições.

O helper de thread do SDK deixa system e tools fora das solicitações de continuação para você e envia os campos fixos novamente a cada turno.

Se você usa fallback no lado do servidor, envie o campo fallbacks em todas as requisições de uma thread ou em nenhuma. Consulte Usar fallbacks com uma thread.

Para alterar um campo somente de criação ou fixo, inicie uma nova thread: envie a conversa completa em uma requisição de criação com os novos valores.

No Claude Fable 5.1, no Claude Mythos 5.1, no Claude Opus 5.5, no Claude Sonnet 5.5 e no Claude Haiku 5.5, alterar system ou tools torna inválidos os blocos thinking e redacted_thinking que já estão na conversa, e a requisição de criação pode retornar um erro 400. Para evitar isso, deixe todos os blocos thinking e redacted_thinking de fora da conversa que você envia. O modelo então responde sem esse raciocínio anterior. Consulte O que conta como edição, Quando prefix_mismatch_behavior não está definido e O que a API faz com um bloco inválido.

Envie apenas as novas mensagens em uma requisição de continuação. A API não as compara com as mensagens que já possui. Uma mensagem que você envia novamente pode aparecer duas vezes na conversa, ou a requisição pode retornar um erro. Por exemplo, uma requisição de continuação que começa com a resposta anterior retorna um erro.

As novas mensagens geralmente começam com uma mensagem user: seu próximo turno de usuário ou os blocos tool_result que respondem a um tool_use na resposta anterior. Se uma resposta parar com stop_reason: "pause_turn", retome-a com uma solicitação de continuação a partir do id dessa resposta e uma lista messages vazia ("messages": []). Se essa solicitação retornar um erro 404, reenvie a conversa completa, incluindo a resposta pausada, em uma nova solicitação de criação. Não envie uma nova mensagem user enquanto o turno estiver pausado: a API a rejeita. Com o helper de thread do SDK, chame send() sem mensagens: o helper envia essa solicitação e reenvia a conversa em caso de erro 404.

Uma thread é somente de acréscimo, e cada id de resposta pode ser continuado uma vez. Sempre continue a partir do id de resposta mais recente da thread. Para editar ou ramificar uma mensagem anterior, inicie uma nova thread com uma requisição de criação. Para substituir turnos anteriores por um resumo, consulte Compactar uma conversa.

Cache de prompt em uma thread

Uma thread não armazena seu prompt em cache por você. O cache de prompt funciona como funciona sem uma thread: você escolhe onde ficam os pontos de interrupção de cache.

Para armazenar cada turno em cache, envie um cache_control de nível superior em todas as requisições da thread, como no exemplo anterior. A API o aplica ao último bloco de messages de cada requisição que pode ser armazenado em cache. Cada turno então lê a conversa anterior do cache e grava o novo turno nele. O cache_control de nível superior é um campo fixo: envie o mesmo valor em todas as requisições.

Você também pode colocar pontos de interrupção cache_control em blocos você mesmo:

• Os breakpoints que você envia na requisição de criação continuam funcionando em todos os turnos posteriores se estiverem em tools, em system ou em um bloco de mensagem anterior ao último. Um breakpoint no último bloco de messages de uma requisição grava o cache nessa requisição. Para armazenar em cache cada novo turno, envie um breakpoint em todas as requisições. Uma requisição sem breakpoint ainda pode ler parte da conversa do cache.
• Você não pode mover nem remover um breakpoint depois de enviá-lo, porque uma solicitação de continuação não pode enviar novamente uma mensagem anterior.
• Uma solicitação com thread pode conter no máximo 4 breakpoints de cache_control. O cache_control de nível superior conta como um. Os breakpoints em system e tools da solicitação de criação contam novamente em cada solicitação de continuação. Os breakpoints em mensagens armazenadas anteriormente não contam. Um breakpoint a mais retorna um erro 400 com o código thread_unsupported_request.
• Se você mesmo colocar breakpoints em blocos de mensagem, remova-os das mensagens anteriores ao reenviar a conversa em uma nova solicitação de criação e mantenha um no último bloco, para que a solicitação permaneça dentro do limite de 4.

Streaming

As threads funcionam com streaming. O id da resposta chega no evento message_start, mas continue a partir dele somente depois de receber o evento message_stop. Uma requisição de continuação enviada antes disso pode retornar um erro 404.

Se o stream de uma requisição de continuação cair antes de message_stop, envie a mesma requisição de continuação novamente. Se essa requisição retornar um erro thread_already_continued ou thread_continue_in_flight, reenvie a conversa completa em uma nova requisição de criação.

Sua conexão pode ter caído enquanto o servidor ainda estava gerando a resposta, ou depois que o servidor a salvou. É por isso que a API pode rejeitar a nova tentativa. Reenviar é sempre seguro.

O helper de thread do SDK não tenta novamente a solicitação de continuação após um stream interrompido. Consulte Como o helper do SDK se comporta.

Recuperar quando uma thread não pode ser continuada

Uma requisição de continuação retorna um erro 404 com error.details.error_code definido como thread_not_found quando a API não consegue continuar a thread. A resposta não informa o motivo. As causas incluem as seguintes:

• A thread expirou.
• A API atendeu o turno anterior, mas não o armazenou. Por exemplo, a API não armazena uma resposta que termina em uma chamada de ferramenta cortada por max_tokens.
• Um modelo de fallback escreveu a resposta anterior. Consulte Usar fallbacks com uma thread.
• A resposta anterior ainda está sendo gerada.
• A requisição vem de uma organização ou workspace diferente.
• A requisição vem de um usuário ou conta de serviço diferente daquele que criou a thread. Uma thread criada com uma chave de workspace (legado) permanece vinculada a essa chave, então use a mesma chave para a thread inteira.
• As novas mensagens adicionam algo que a conversa armazenada não comporta. Por exemplo, a primeira imagem em uma conversa que não tinha nenhuma pode retornar esse erro.

Para se recuperar, envie a conversa completa a partir da sua própria cópia em uma nova requisição de criação, com system e tools. O helper de thread do SDK envia essa requisição de criação uma vez por conta própria e, ao fazê-lo, deixa de fora os breakpoints cache_control de turnos anteriores. Se mensagens anteriores na sua cópia tiverem breakpoints cache_control, remova-os primeiro (consulte Cache de prompt em uma thread). Em seguida, continue a partir do id da nova resposta. Se um modelo de fallback escreveu a resposta anterior, consulte Usar fallbacks com uma thread. Para descartar as causas relacionadas à propriedade, use a mesma chave de API e o mesmo workspace para cada requisição de uma thread. No Claude Platform on AWS, assine cada requisição de uma thread com credenciais da função do IAM ou do usuário do IAM que a criou.

Uma requisição para um modelo que não existe também retorna um erro 404, então verifique error.details.error_code antes de reenviar.

Se uma requisição de continuação ainda retornar um erro 404 logo após a reprodução, a API pode não conseguir armazenar essa conversa, por exemplo uma muito grande. Envie-a sem thread. O helper de thread do SDK faz isso quando você o cria com unsupported_request_behavior definido como continue_unthreaded. Caso contrário, ele reproduz a conversa a cada turno.

Após uma recusa

Quando uma resposta tiver stop_reason: "refusal", não continue a thread. A API pode já conter o turno recusado, e uma requisição de continuação não pode removê-lo. Inicie uma nova thread com uma requisição de criação que deixe de fora ou reformule o turno que levou à recusa. Consulte Recusas e fallback. O helper de thread do SDK faz isso para você: ele não mantém o turno recusado, e seu próximo turno inicia uma nova thread.

Usar fallbacks com uma thread

O fallback no lado do servidor está disponível com threads na Claude API. Decida ao criar a thread: envie fallbacks em todas as requisições da thread, ou em nenhuma. O valor de fallbacks pode mudar entre requisições. Uma requisição de continuação que adiciona ou remove fallbacks retorna um erro 400 com o código thread_fingerprint_mismatch.

Uma thread mantém um único modelo, então a API não armazena um turno escrito por um modelo de fallback. Você recebe a resposta normalmente, mas não pode continuar a partir do seu id. Após cada resposta, siga estas etapas:

1. Se stop_reason for "refusal", siga Após uma recusa.
2. Caso contrário, procure uma entrada fallback_message em usage.iterations. Em um stream, leia-a a partir do evento message_delta final. Se não houver nenhuma, continue a thread normalmente.
3. Se houver uma, um modelo de fallback escreveu a resposta. Envie a conversa completa, incluindo essa resposta e sua próxima mensagem, em uma nova requisição de criação. Mantenha o cabeçalho beta server-side-fallback-2026-07-01 nela. Escolha uma destas duas requisições:
   • A mesma requisição novamente. Mantenha model, fallbacks e seus outros parâmetros como estavam. Se o modelo que você solicitou responder, a API armazena a nova thread. Se um modelo de fallback responder, a resposta terá novamente uma entrada fallback_message e a API não a armazenará, então repita esta etapa no próximo turno. O roteamento persistente pode enviar essas requisições diretamente ao modelo de fallback, então cada turno pode enviar a conversa completa. O helper de thread do SDK funciona dessa forma.
   • Uma nova thread no modelo de fallback. Defina model como o model nessa entrada fallback_message, deixe fallbacks de fora e use parâmetros que esse modelo aceite. A API armazena essa thread imediatamente, e ela permanece no modelo de fallback. A tentativa de fallback pode ter sido executada com configurações diferentes das que você enviou, então a API pode rejeitar valores copiados da sua primeira requisição.
4. Volte à etapa 1 com a resposta a essa requisição. Quando ela não tiver nenhuma entrada fallback_message, continue a nova thread a partir do id dessa resposta.

O roteamento persistente começa depois que uma requisição recorre ao fallback (uma requisição de criação, ou uma requisição sem thread). Por cerca de uma hora, ele pode enviar requisições de criação posteriores para a mesma conversa que incluam fallbacks diretamente ao modelo de fallback, sem tentar o modelo que você solicitou. A API não armazena nenhum desses turnos, e cada um que recebe resposta reinicia a contagem de uma hora. Uma requisição de continuação nunca inicia esse roteamento e nunca o utiliza. O roteamento persistente não se aplica se sua organização ou workspace usar retenção zero de dados ou chaves de criptografia gerenciadas pelo cliente.

Compactar uma conversa

Uma thread é somente de acréscimo, então você não pode substituir seus turnos anteriores por um resumo. Para compactar uma conversa, inicie uma nova thread a partir do resumo. Escreva o resumo no seu código e envie-o como uma mensagem comum em uma nova requisição de criação, com system e tools. A compactação sob demanda não está disponível com threads (consulte Recursos que as threads não suportam).

Como o helper do SDK se comporta

O que o helper faz por você:

• Adiciona o cabeçalho beta message-threads-2026-08-12 a cada requisição que usa a thread.
• Cria uma thread no primeiro turno e a continua depois disso, enviando apenas as novas mensagens e deixando de fora system e tools.
• Reproduz a conversa completa uma vez em uma nova requisição de criação quando uma requisição de continuação retorna thread_not_found, thread_already_continued ou thread_continue_in_flight.
• Retoma uma resposta pause_turn quando você chama send() sem mensagens.
• Inicia uma nova thread após uma recusa. Você recebe a resposta stop_reason: "refusal" normalmente, mas o helper não mantém esse turno: ele retira as mensagens que você passou para essa chamada. As mensagens que você adicionou com thread.append(...), ou que passou ao criar o helper, permanecem preparadas. Seu próximo turno as envia com a conversa anterior ao turno recusado, em uma nova requisição de criação. Envie uma mensagem reformulada ou, se uma mensagem preparada levou à recusa, inicie uma nova thread a partir dos params sem ela.
• Envia uma nova requisição de criação após uma resposta de um modelo de fallback. Quando uma resposta tem uma entrada fallback_message em usage.iterations, o helper mantém a resposta e envia a conversa completa em uma nova requisição de criação no próximo turno. Ele não espera por um erro 404. Essa requisição mantém o model e os fallbacks que você definiu.
• Deixa de fora os breakpoints cache_control de turnos anteriores sempre que os envia novamente, por exemplo em uma reprodução ou no primeiro turno de um fork. Suas mensagens mais recentes, system, tools e o cache_control de nível superior são enviados como você os forneceu.

O que você mesmo precisa tratar:

• Fallbacks. Enquanto a API continuar respondendo a partir de um modelo de fallback, o helper envia a conversa completa em uma nova requisição de criação a cada turno, porque a API não armazena nenhum desses turnos. Ele volta às requisições de continuação após uma resposta do modelo que você solicitou. Para mover a conversa para o modelo de fallback em vez disso, inicie uma nova thread a partir dos params com esse model e sem fallbacks, como em Usar fallbacks com uma thread.
• Streams interrompidos. Se um stream terminar no meio de uma resposta, o helper mantém os blocos concluídos e qualquer texto que tenha chegado, e o próximo turno envia a conversa completa em uma nova requisição de criação. O helper não tenta novamente por conta própria: para reenviar o turno interrompido, chame send() sem mensagens. Se a parte mantida terminar em chamadas de ferramentas, responda a elas na sua próxima mensagem. Se você parar de ler um stream depois que ele mostrar stop_reason: "refusal", o helper trata esse turno como uma recusa.
• Outros erros. Os erros thread_fingerprint_mismatch e thread_unsupported_request chegam ao seu código. Para prosseguir sem thread após um erro thread_unsupported_request, crie o helper com unsupported_request_behavior definido como continue_unthreaded. Com essa configuração, o helper também para de usar thread quando a primeira requisição de continuação após uma reprodução retorna thread_not_found novamente. A API pode não conseguir armazenar essa conversa. Sem essa configuração, o helper reproduz a conversa a cada turno. Um tool runner que cria sua própria thread usa essa configuração por padrão.

O executor de ferramentas beta do SDK também usa uma thread por padrão, o que você pode desativar ao criar o executor.

Outros métodos do helper

Streaming. O helper registra a resposta quando o stream chega a message_stop, então leia o stream até o fim. Se você parar de ler antes, encerre o stream para que a thread fique livre para o próximo turno:

• Python: saia do bloco with.
• TypeScript: saia do loop ou chame abort().
• Go: chame Close.
• Java e Ruby: chame close().
• C#: descarte o enumerador. Sair de await foreach faz isso.
• PHP: chame close().

Em C#, a requisição é enviada quando você começa a ler o stream.

Em C#, Go, Java e PHP, após uma recusa, thread.LastMessage ainda retorna a resposta do turno anterior, ou nada em um primeiro turno. Leia a recusa a partir dos eventos do stream.

Alterar campos. Uma atualização não envia nada e se aplica a todos os turnos posteriores. Depois que uma thread tem uma resposta, o helper recusa um turno que altere system ou tools, e a API rejeita uma alteração em qualquer outro campo fixo (consulte O que enviar em cada requisição). Para alterar um desses campos, inicie uma nova thread a partir dos params, ou faça um fork da thread e atualize o fork antes do seu primeiro turno.

Fork. Um fork copia a conversa, os campos e as opções de requisição, e não envia nada. Seu primeiro turno envia a conversa completa em uma nova requisição de criação, e as duas threads são independentes depois disso. Um fork sempre começa a partir da conversa inteira, não de uma resposta anterior.

Params. Os params contêm os campos do helper e a conversa completa. Passe-os para o método que cria um helper para iniciar uma nova thread, por exemplo com um system diferente (consulte O que enviar em cada requisição), ou com messages reduzido para descartar turnos posteriores. Uma thread que você inicia a partir dos params envia cada mensagem como você a forneceu, incluindo os breakpoints de cache_control, portanto mantenha-se dentro do limite de 4 (consulte Cache de prompt em uma thread). Exceto em Ruby, os params omitem as opções de requisição, portanto passe-as novamente.

Saída estruturada. Informe o formato de saída ao criar o helper. Um turno posterior não pode alterá-lo. A forma de obter o resultado analisado depende do SDK:

• Python e TypeScript: chame thread.parse(...).
• C#: crie o helper com client.Beta.Messages.Thread<T>(...).
• Go: Send desserializa na struct para a qual Params.OutputConfig.Format.Schema aponta.
• Java: crie o helper com thread(...) e outputConfig(MyClass.class).
• PHP: send() define parsed nos blocos de texto quando outputConfig nomeia uma classe de modelo.
• Ruby: passe output_config: {format: MyModel} para thread(...) e, em seguida, leia reply.parsed_output.

Erros

A API retorna os erros desta tabela antes de o modelo ser executado. A requisição não usa tokens, e a thread e seu tempo de expiração não mudam. error.type é invalid_request_error para os erros 400 e not_found_error para o erro 404.

Alguns erros 400 para requisições de thread não têm error_code, por exemplo uma requisição de continuação sem previous_message_id, ou uma que inclui system ou tools.

O exemplo a seguir mostra um corpo de erro:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "thread: a maximum of 4 blocks with cache_control may be provided when `thread` is set. Found 5.",
    "details": {
      "error_code": "thread_unsupported_request",
      "unsupported": ["cache_control"]
    }
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

Recursos que as threads não suportam

As threads não suportam estes recursos:

• Message Batches. Um item de requisição que inclui thread termina com um invalid_request_error nos resultados do lote.
• Contagem de tokens. Uma requisição de contagem de tokens que inclui thread retorna um erro 400. Em vez disso, conte a conversa completa, com system e tools.
• Compactação. A compactação sob demanda não está disponível com threads. Uma requisição que inclui thread retorna um erro 400 se definir o parâmetro compaction, ou se enviar um bloco compaction com o cabeçalho beta compact-2026-09-04. Consulte Compactar uma conversa.
• Edição de contexto, exceto clear_thinking_20251015 com keep: "all".
• Organizações que têm a prontidão para HIPAA habilitada.
• Organizações que têm Inference hooks ativados.

A API rejeita a maioria das requisições que as threads não suportam com um erro 400 e o código thread_unsupported_request. Quando error.details.unsupported está presente, ele contém um destes valores:

A API pode adicionar valores a esta lista. Se você receber um valor que não reconhece, envie a conversa completa sem thread. Uma requisição que atende a várias dessas condições recebe um erro que nomeia apenas uma.

Limitações

• Não há API para listar, ler ou excluir uma thread.
• As threads estão disponíveis na Claude API, no Claude Platform on AWS, no Claude Models on Google Cloud (Anthropic managed), e no Claude in Microsoft Foundry.

Preços e limites de taxa

As threads não alteram os preços nem os limites de taxa.

Retenção de dados

As threads de mensagens não são elegíveis para ZDR. Usar este recurso não afeta seu uso de outros recursos elegíveis para ZDR. A API mantém uma thread em memória, criptografada com uma chave gerenciada pelo servidor, nunca a grava em armazenamento durável e a exclui no máximo 1 hora após seu último uso.

Uma thread contém a conversa que a API envia ao modelo, o system e as tools da requisição de criação, e uma impressão digital dos campos fixos, que ela usa para verificar requisições posteriores. Ela mantém arquivos por referência, então mantenha disponível cada arquivo que a conversa usa enquanto você usar a thread.

Para a elegibilidade para ZDR em todos os recursos, consulte API e retenção de dados.

Veja também

• Cache de prompt
• Streaming
• Erros

Disponibilidade

Threads de mensagens estão em beta em todos os modelos.

Suporte da API

Os headers beta permitem que você acesse recursos experimentais e novas capacidades de modelos antes que eles se tornem parte da API padrão.