Trocar ferramenta no meio da conversa sem zerar o cache: o que mudou na API da Claude

Quem constrói agente de verdade, não um chatbot de FAQ, esbarra cedo ou tarde no mesmo problema: a lista de ferramentas que você declara pro modelo raramente é fixa a conversa inteira. Um agente de suporte ganha acesso a "cancelar pedido" só depois que o cliente confirma identidade. Um agente de código só deveria enxergar "deletar arquivo" depois que o usuário liga um modo mais permissivo. Até agora, mudar isso no meio da conversa tinha um preço técnico que pouca gente calculava direito.

O problema que ninguém via no preço da fatura

No prompt caching da API da Claude, o pedido é lido nesta ordem fixa: tools, depois system, depois messages. Um cache hit exige que o prefixo bata byte a byte com um pedido recente, até o ponto de corte.

Isso coloca o array tools antes do próprio system prompt no prefixo. Então, se seu agente precisa liberar uma ferramenta nova no meio de uma sessão longa e a única forma de fazer isso é editando o array tools, o cache inteiro da conversa invalida, do começo ao fim. Numa sessão agêntica de dezenas de turnos já cacheados, isso não é detalhe: é reprocessar tudo de novo a preço cheio, só porque uma ferramenta mudou de disponível pra indisponível.

O que a Anthropic entregou, em três lançamentos

A correção veio em etapas, todas documentadas nas release notes oficiais:

A peça que resolve o problema do parágrafo anterior é o tool_addition/tool_removal, hoje em beta no Claude Fable 5, Claude Fable 5.1, Claude Mythos 5, Claude Mythos 5.1, Claude Opus 4.8 e Claude Opus 5 (API, Amazon Bedrock e Google Cloud). Não está disponível no Claude Sonnet 5.

Como funciona, sem reescrever o array

A ideia central: você declara todo o conjunto de ferramentas em tools logo no primeiro pedido, e esse array nunca muda depois. O que muda é quais dessas ferramentas o modelo enxerga em cada ponto da conversa.

• Toda ferramenta declarada em tools fica visível desde o início, a menos que você marque defer_loading: true, que a mantém escondida até você liberá-la.
• Pra liberar ou tirar uma ferramenta a partir de um ponto da conversa, você anexa um bloco tool_addition ou tool_removal dentro de uma mensagem role: "system", referenciando o nome da ferramenta já declarada (tool_reference, ou mcp_tool_reference/mcp_toolset_reference pra ferramenta de um MCP connector).
• Como o array tools em si nunca é editado, o prefixo que a API já tinha em cache continua batendo. Só a partir da mensagem de troca é que o pedido processa conteúdo novo, o resto da conversa anterior segue vindo do cache.

Na prática, pra um fluxo de suporte: você declara cancelar_pedido com defer_loading: true desde o primeiro turno, e só manda o tool_addition liberando ela depois que outra etapa do seu fluxo confirma a identidade do cliente. Nenhum turno anterior é reprocessado.

O complemento: lembrete que não acumula

Junto veio o clear_at: "next_user_message", pensado pra outro problema comum em loop de agente: o lembrete que você reinjeta a cada rodada de ferramenta ("peça leituras independentes na mesma resposta", "o orçamento de tokens está baixo") e que, se você não tomar cuidado, vai empilhando cópia sobre cópia no histórico.

Com clear_at, a mensagem de sistema renderiza só enquanto nenhuma mensagem de usuário mais recente existir depois dela. Assim que o próximo turno de usuário chega, ela some do que o modelo lê, mas continua no array, sem custo de token e sem invalidar cache. É texto puro (sem tool_addition, tool_removal ou cache_control), então ela serve só pra lembrete, não pra troca de ferramenta.

Onde isso baixa custo de automação de verdade

Isso importa em qualquer fluxo com dois traços: sessão longa (muitos turnos cacheados) e ferramentas que mudam de disponibilidade por causa de estado, não por causa do prompt.

• Permissão escalonada. Agente começa com ferramentas de leitura, ganha ferramentas de escrita só depois de uma confirmação explícita, igual ao padrão de "modo autônomo" que já existe em harness de código.
• Handoff entre etapas de um pipeline. Se a automação usa a mesma conversa pra pesquisar, depois decidir, depois executar, cada etapa pode ter seu próprio conjunto de ferramentas sem forçar o modelo a reprocessar as etapas anteriores.
• Multi-tenant com ferramentas por cliente. Um agente que atende clientes diferentes numa mesma sessão longa (ex.: revezando contexto) pode ligar e desligar integrações específicas de cada cliente sem pagar cache miss geral a cada troca.

A ressalva que vale escrever com todas as letras: a mensagem que carrega o tool_addition/tool_removal ainda é conteúdo novo, então ela e tudo que vier depois dela nesse pedido específico não sai do cache. O ganho não é "grátis", é "só paga o que realmente mudou", em vez de pagar a conversa inteira de novo. Pra sessão curta isso não faz diferença. Pra sessão agêntica que já vinha acumulando turnos cacheados, é a diferença entre um ajuste pontual e reprocessar a conversa toda a cada vez que o estado muda.