Altere ferramentas ou instruções sem falhar na verificação de prefixo

Para atualizar ferramentas, instruções ou outro contexto, deixe tudo o que você enviou como estava e adicione a atualização no final, onde ela permanece. Em modelos com “preserved thinking” (Pensamento preservado), alterar o que você enviou pode tornar inválido o pensamento que vem depois, e a solicitação pode falhar.

Os modelos com “preserved thinking” (Pensamento preservado) são Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5 e Claude Haiku 5.5.

Envie os turnos do assistente de volta exatamente como vieram

Envie de volta o array content inteiro de cada resposta, em ordem, incluindo os “thinking blocks” (blocos de pensamento) cujo texto está vazio. Um bloco com texto vazio está completo, porque sua signature contém o raciocínio, criptografado. Um turno que contém um bloco fallback tem sua própria regra.

Serializadores, filtros e analisadores de stream podem quebrar isso.

Altere instruções

Mantenha system igual em todas as solicitações. Coloque suas próprias instruções em uma mensagem role: "system" no final e envie uma somente quando algo tiver mudado. O Claude a trata como uma instrução sua, o operador. Deixe-a pelo resto da conversa, porque excluí-la ou reescrevê-la depois torna inválido o pensamento que vem depois dela. As palavras do seu usuário têm sua própria regra.

Um lembrete que precisa acompanhar todos os turnos é diferente: envie um que se limpe sozinho.

A mensagem do sistema vai depois da mensagem de usuário mais recente, mesmo uma com resultados de ferramentas. Uma mensagem do sistema com texto ou blocos de ferramenta recebe um erro 400 logo após o turno do Claude ou logo antes de uma mensagem de usuário. Então, quando o turno do Claude for o último, espere até que a próxima mensagem de usuário esteja no lugar.

Uma mensagem do sistema não garante que o Claude siga uma instrução, então aplique limites como o modo somente leitura no código que executa suas ferramentas. Alguns modelos não aceitam mensagens do sistema.

Texto que outras pessoas podem editar

Pergunte-se se seu usuário esperaria que o Claude confiasse em um arquivo, como um AGENTS.md ou CLAUDE.md que outras pessoas podem editar, ou em uma memória armazenada. Se não, envie o texto dele somente em um bloco tool_result, incluindo a primeira versão. Para saber o porquê, consulte Injeção indireta de prompt.

Não coloque esse texto em uma mensagem do sistema nem no texto de uma mensagem de usuário e, em novas conversas, não o coloque em system.

Quando você carregar um arquivo desse tipo ou ele mudar, diga ao Claude para lê-lo com uma ferramenta e não inclua o texto dele. Ou, após a próxima mensagem de usuário, acrescente você mesmo a chamada de ferramenta e seu resultado: uma mensagem assistant com um bloco tool_use e, em seguida, uma mensagem user cujo bloco tool_result contém o texto. Para ver as etapas, consulte Escreva a chamada de ferramenta você mesmo.

Um arquivo que seu usuário espera que o Claude siga pode ir em uma mensagem de usuário. Um arquivo de instruções que somente você controla pode ir em uma mensagem do sistema: carregue-o uma vez e acrescente cada versão atualizada.

Atualize a data, arquivos ou outro contexto

Monte system e a primeira mensagem uma vez e envie-os inalterados em todas as solicitações.

Coloque um valor atualizado em seu próprio bloco de texto da mensagem de usuário que você está prestes a enviar, depois de quaisquer resultados de ferramentas:

{
  "role": "user",
  "content": [
    { "type": "text", "text": "Environment update: the current branch is now release-2." },
    { "type": "text", "text": "Run the tests again." }
  ]
}

Informe-o somente quando ele mudar e deixe-o ali.

Armazene qualquer contexto que seu código adicione a uma mensagem junto com essa mensagem. Caso contrário, a próxima solicitação envia algo diferente antes do mesmo pensamento.

Adicione, remova ou desative ferramentas

Mantenha tools igual em todas as solicitações. Adicionar, alterar ou remover uma ferramenta ali, exceto uma adiada, torna inválido o pensamento que já está na conversa, porque tools vem antes de todo ele. Uma única frase reescrita em uma descrição já é suficiente.

Para adicionar ou remover uma ferramenta, acrescente uma mensagem do sistema com um bloco tool_addition ou tool_removal e o cabeçalho beta para o seu caso. Faça o mesmo quando um servidor MCP ou plugin se conectar.

Para desativar as ferramentas em uma solicitação, defina tool_choice: {"type": "none"} e mantenha tools como estava.

Corte ou resuma turnos mais antigos

Para manter os turnos recentes com seu pensamento, deixe a API escrever o resumo com compactação sob demanda, sob as condições para o pensamento mantido. Inicie messages com o bloco de compactação que ela retorna e remova as mensagens que ele resume.

Se o seu próprio código escreve o resumo, ou corta turnos mais antigos sem um, remova o pensamento dos turnos mantidos ou envie "drop_block". Cada novo corte torna o pensamento dos turnos mantidos inválido novamente, então corte raramente, em grandes etapas. Para limpar resultados de ferramentas antigos em vez disso, use a edição de contexto.

Salve, retome ou bifurque uma conversa

Armazene o que você enviou e o que recebeu e envie exatamente isso. Uma conversa retomada é uma próxima solicitação comum: system, tools e as messages anteriores devem ter os valores que tinham. Para uma bifurcação, coloque a instrução do ramo em sua primeira nova mensagem de usuário ou em uma mensagem do sistema depois dela. O pensamento não pode ser movido para uma conversa com um histórico diferente: em vez disso, inicie essa conversa a partir de um resumo.

Uma versão que altera seu “system prompt” (prompt do sistema) ou suas ferramentas é uma mudança nas conversas que já estão em andamento. A correção que torna seu código “append-only” (somente acréscimo) também pode ser uma. Continue enviando a cada conversa em andamento o system e as tools de sua última solicitação bem-sucedida, porque seu pensamento mais recente foi produzido depois dessa versão. Voltar a uma versão anterior tornaria esse pensamento inválido.

Use o system e as tools atualizados em novas conversas. Se a versão remove uma ferramenta ou altera uma instrução por segurança, aplique-a também às conversas em andamento. Acrescente um bloco tool_removal ou uma mensagem do sistema.

Remova segredos, dados pessoais ou texto injetado

Segurança e privacidade vêm antes de manter o pensamento válido. Se uma mensagem contém um segredo ou dados pessoais que você precisa excluir, remova esse texto. Remova-o também de todas as mensagens e resumos que o repetem.

Para um resultado de ferramenta com instruções injetadas, substitua seu conteúdo por uma nota curta como “Removido.” Mantenha o próprio bloco tool_result, porque seu tool_use precisa de um. Se um bloco de compactação contém o texto, exclua o bloco e comece a partir do seu próprio resumo.

Em seguida, exclua todos os blocos thinking e redacted_thinking depois do primeiro lugar em que o texto apareceu. Se ele estava em system ou tools, isso significa todos eles. Cada bloco pode repetir o texto, e você não pode ler nem editar o que está dentro. Enviar "drop_block" não é suficiente aqui, porque isso deixa esses blocos no seu histórico armazenado. A conversa continua sem esse raciocínio.

Depois de um resultado injetado, turnos posteriores podem já ter agido com base nele. Verifique as chamadas de ferramenta feitas desde então e desfaça o que for necessário.

Detalhes técnicos

Formas como o código altera os turnos do assistente

• Um serializador descarta tipos de bloco que não conhece, ou reordena, mescla ou divide blocos. Isso altera o que veio antes de cada bloco posterior.
• O código pula blocos de pensamento que parecem vazios. Se ele pular todos, o Claude perde esse raciocínio. Se pular apenas alguns, a lacuna torna inválido o pensamento que vem depois dela.
• Um analisador de stream próprio descarta um bloco de pensamento que não recebeu texto. Os auxiliares de stream do SDK o mantêm.

Deixe o pensamento de fora

O Claude perde o raciocínio que você deixa de fora. Deixe de fora os blocos mais antigos, os mais recentes ou todos eles, mas nenhum entre eles. Cada bloco registra aquele depois do qual foi produzido, então uma lacuna torna inválidos os blocos depois dela. Blocos de pensamento sem nenhum outro bloco entre eles em um turno são verificados juntos, então deixe de fora todos eles ou nenhum. Depois que um bloco estiver de fora, mantenha-o de fora.

Enquanto uma chamada de ferramenta estiver aberta, envie de volta o pensamento desse turno, para que o Claude termine a rodada com seu raciocínio.

Suas instruções em um loop de ferramentas

As mensagens seguem esta ordem:

[
  {
    "role": "assistant",
    "content": [
      { "type": "thinking", "thinking": "", "signature": "..." },
      {
        "type": "tool_use",
        "id": "toolu_01",
        "name": "run_tests",
        "input": { "path": "tests/" }
      }
    ]
  },
  {
    "role": "user",
    "content": [
      { "type": "tool_result", "tool_use_id": "toolu_01", "content": "2 failed, 48 passed" }
    ]
  },
  {
    "role": "system",
    "content": "Plan mode is off. You can edit files."
  }
]

Escreva a chamada de ferramenta você mesmo

Declare uma ferramenta que lê arquivos na primeira solicitação, ou adicione-a depois em uma mensagem do sistema, e faça seu código responder às chamadas do Claude para ela. Após a próxima mensagem de usuário, acrescente uma mensagem assistant com um bloco tool_use para essa ferramenta. Logo depois dela, acrescente uma mensagem user cujo bloco tool_result tenha o tool_use_id correspondente e contenha o texto do arquivo. O Claude responde depois disso:

[
  { "role": "user", "content": "Run the tests again." },
  {
    "role": "assistant",
    "content": [
      {
        "type": "tool_use",
        "id": "toolu_app_agents_md_1",
        "name": "read_file",
        "input": { "path": "AGENTS.md" }
      }
    ]
  },
  {
    "role": "user",
    "content": [
      {
        "type": "tool_result",
        "tool_use_id": "toolu_app_agents_md_1",
        "content": "The file's text"
      }
    ]
  }
]

Deixe ambas no lugar e acrescente um novo par, com um novo id, para cada nova versão.

As palavras do seu usuário, e valores atualizados, em um loop de ferramentas

Se você repassar o que seu usuário digitou enquanto o Claude estava trabalhando, adicione isso antes de enviar a mensagem de usuário que carrega os blocos tool_result. Coloque como um bloco de texto depois do último tool_result.

Um valor que vem de você pode ir em uma mensagem do sistema em vez disso. Após resultados de ferramentas, o Claude Sonnet 5.5 e o Claude Haiku 5.5 podem ignorar as palavras de um usuário em uma mensagem do sistema como uma injeção de prompt. O Claude Sonnet 5.5 pode fazer o mesmo com as instruções e os lembretes que você mesmo envia, se eles vierem depois de cada resultado de ferramenta.

A mensagem de usuário com os resultados de ferramentas deve conter apenas blocos tool_result quando o turno também chamou uma ferramenta de servidor que ainda não tem resultado, ou usou chamada programática de ferramentas. Nesse caso, adicione o texto à próxima mensagem de usuário.

Modelos que não aceitam mensagens do sistema

Na Claude API, todo modelo com pensamento preservado aceita mensagens do sistema. Para um modelo que não aceita, consulte Quando um modelo não aceita mensagens do sistema.

Envie um lembrete para um turno

Envie um lembrete como uma mensagem do sistema com escopo de turno: defina clear_at: "next_user_message" e envie o cabeçalho beta mid-conversation-system-clear-at-2026-08-21. Ela vai depois da mensagem de usuário que carrega os blocos tool_result:

{
  "role": "system",
  "clear_at": "next_user_message",
  "content": "Run the linter before you report that a task is done."
}

Na próxima mensagem de usuário, mesmo uma com apenas blocos tool_result, a API a limpa, então o Claude para de lê-la. No Claude Sonnet 5.5, não envie uma depois de cada resultado de ferramenta. Mantenha todos os lembretes em suas messages, limpos ou não, a menos que um deles contenha algo que você precisa remover. Remover ou reescrever um torna inválido o pensamento que vem depois dele.

Sem o cabeçalho, envie uma mensagem do sistema simples e deixe-a no lugar. Ela nunca é limpa, então os lembretes se acumulam. Em um modelo que não aceita mensagens do sistema, use um bloco de texto na mensagem de usuário.

Qual bloco e cabeçalho beta uma alteração de ferramenta precisa

Para ver as plataformas que aceitam cada cabeçalho, consulte Mensagens de sistema e alterações de ferramentas no meio da conversa.

• Se você conhece todas as ferramentas desde o início: Declare todas na primeira solicitação, com defer_loading: true naquelas que você oferece depois. Em seguida, nomeie a ferramenta em um bloco tool_addition ou tool_removal de uma mensagem do sistema. Cabeçalho beta: inline-tools-2026-09-15 ou mid-conversation-tool-changes-2026-07-01.
• Se você fica sabendo de uma ferramenta depois, ou tem uma cujo schema muda: Defina a ferramenta em um bloco tool_addition de uma mensagem do sistema. Cabeçalho beta: inline-tools-2026-09-15.
• Se você fica sabendo de uma ferramenta depois, em uma plataforma sem o cabeçalho inline-tools-2026-09-15: Adicione a ferramenta ao final de tools com defer_loading: true, o que não é uma mudança, e depois ofereça-a pelo nome. Cabeçalho beta: mid-conversation-tool-changes-2026-07-01.
• Se você conecta um servidor MCP por meio do conector MCP tardiamente, na Claude API: Defina seu mcp_toolset em um bloco tool_addition. Cabeçalhos beta: inline-tools-2026-09-15 e mcp-client-2026-09-15.

Se a lista de ferramentas de um servidor MCP puder mudar, consulte Fixe a lista de ferramentas de um servidor MCP.

Esta mensagem do sistema oferece uma ferramenta declarada pelo nome e define outra, o que exige inline-tools-2026-09-15:

{
  "role": "system",
  "content": [
    {
      "type": "tool_addition",
      "tool": { "type": "tool_reference", "name": "search_tickets" }
    },
    {
      "type": "tool_addition",
      "tool": {
        "type": "tool_definition",
        "definition": {
          "name": "get_weather",
          "description": "Get the current weather in a city.",
          "input_schema": {
            "type": "object",
            "properties": { "city": { "type": "string" } },
            "required": ["city"]
          }
        }
      }
    }
  ]
}

Ferramentas com defer_loading, e o erro 400 que o menciona

Uma ferramenta com defer_loading: true fica fora do contexto do Claude e da “prefix check” (verificação de prefixo) até que uma mensagem ou um resultado de busca de ferramentas faça referência a ela. Até lá, adicioná-la, atualizá-la ou removê-la não é uma mudança. Depois disso, é. Ativar ou desativar defer_loading também conta como alterar tools.

Declare pelo menos uma ferramenta que não seja adiada, ou a solicitação pode receber um erro 400 que menciona defer_loading.

Encurte ou limpe resultados e imagens antigos

Encurte ou reduza a resolução de um resultado de ferramenta ou imagem antes de enviá-lo pela primeira vez. Se seu código limpa, encurta ou recodifica algo que já enviou, o pensamento que vem depois disso se torna inválido. Para limpar resultados de ferramentas antigos depois, incluindo quaisquer imagens dentro deles, use a edição de contexto. Envie context_management com uma edição do tipo clear_tool_uses_20250919 e o cabeçalho beta context-management-2025-06-27. Para ver a solicitação completa e suas opções, consulte Edição de contexto.

Arquivos que você envia por URL

Para um arquivo por URL, a API compara os bytes que buscou. Então, quando uma URL assinada expira, uma nova para o mesmo arquivo não tem problema. Se o conteúdo por trás de uma URL puder mudar, envie um file_id ou base64 desde a primeira solicitação.

Se o seu próprio código resume ou corta turnos mais antigos

Após seu próprio resumo ou corte, o pensamento de um turno mantido falha na verificação de prefixo, porque as mensagens que ele seguia não existem mais. Remova esse pensamento ou envie "drop_block". O Claude ainda lê o turno sem ele.

Bibliotecas, proxies e gateways

Se solicitações de outras pessoas passam pelo seu código, suas reescritas alteram o histórico delas, e elas talvez não consigam ver ou corrigir essas alterações. Não oculte o erro 400. Se você fizer a recuperação pelo chamador, informe isso, porque o histórico dele ainda contém a mudança.

• Repasse os valores de anthropic-beta e thinking.block_binding como foram enviados. Se seu gateway permite apenas campos conhecidos, adicione thinking.block_binding e o valor de cabeçalho thinking-binding-controls-2026-08-01, ou seus usuários não poderão escolher "drop_block".
• Não remova o cabeçalho beta e repasse a configuração. Essa solicitação recebe um erro 400.
• Retorne ao chamador os blocos de pensamento cujo texto está vazio e o array input_transformations.
• Deixe uma mensagem role: "system" onde ela está. Movê-la para system torna inválido o pensamento que já está na conversa.
• Teste com prefix_mismatch_behavior definido como "error", o que gera o erro em todo modelo com pensamento preservado.

Próximos passos