Contexto de ferramentas e cache de prompts

Duas coisas são verdadeiras em toda requisição que o harness embutido faz: as definições de ferramentas são o maior custo fixo dela, e quase nenhuma delas será usada. Esta página explica o que o Control Center faz a respeito disso e por que a resposta não é simplesmente “enviar menos ferramentas”.

O problema é a atenção, não os bytes

O Control Center registra cerca de 126 ferramentas. Enviadas por inteiro, suas definições custam aproximadamente 23.000 tokens a cada requisição — um custo que nenhuma compactação consegue tocar, porque as definições de ferramentas viajam em uma parte da requisição separada da conversa.

A conta de tokens é a reclamação óbvia e, com o cache de prompts, também é a menor. O custo real é a precisão da seleção. As avaliações publicadas sobre chamadas de ferramentas concordam que os modelos escolhem a ferramenta certa de forma confiável até algo em torno de 30–50 ferramentas no contexto, e pioram progressivamente além disso. A causa apontada não é a contagem de tokens, mas a sobreposição semântica: quando um catálogo contém várias ferramentas cujas descrições soam parecidas, o modelo escolhe entre semelhantes em vez de recordar uma capacidade.

Com 126 ferramentas, um agente está bem além dessa faixa em cada turno — inclusive nos muitos turnos em que só precisava ler um arquivo.

A superfície de dois níveis

Uma execução, portanto, recebe duas coisas:

• um conjunto residente — cerca de duas dúzias de ferramentas, enviadas com os esquemas completos a cada requisição;
• um índice de nomes de todo o resto, agrupado sob títulos como “Tickets and projects” ou “Memory and knowledge”, custando algumas centenas de tokens pelo catálogo inteiro.

Medido no catálogo atual, isso leva o bloco de ferramentas de ~23,1k tokens para ~5,0k, cerca de 78% menor, e coloca o conjunto sempre visível dentro da faixa em que a seleção é confiável.

O conjunto residente são as ferramentas que uma execução usa na maioria das execuções: o vocabulário de arquivos e shell (read, write, edit, search, bash, …), as ferramentas de descoberta, a lista de tarefas, a busca na memória e o verbo que o modo atual precisa chamar para entregar sua saída. O verbo de saída de um modo é sempre residente — uma execução nunca deve ter de sair procurando a única chamada que produz seu entregável.

Diferida não significa indisponível

Esta é a parte que torna o design seguro, e não apenas barato. Uma ferramenta diferida pode ser chamada desde o primeiro turno. Apenas seu esquema é retido.

O agente vê o nome no prompt. Se chamar esse nome diretamente, o harness carrega o esquema e executa a ferramenta no mesmo passo — sem erro, sem ida e volta. O modelo não precisa saber que a ferramenta algum dia esteve “descarregada”.

Quando o agente conhece a tarefa mas não o nome, search_tools recebe uma descrição em linguagem natural (“atribuir um ticket a alguém”), classifica toda a superfície da execução e retorna as correspondências com os esquemas já carregados, de modo que o turno seguinte já possa chamar uma delas. Se uma busca não encontra nada, ela diz isso claramente e sugere outra redação ou uma busca mais ampla — de propósito, porque um agente que lê uma busca vazia como “essa capacidade não existe” vai inventar um substituto em vez de procurar de novo.

search_tools existe apenas no harness embutido. Clientes MCP externos têm search_tool_bm25 em vez disso, que classifica o mesmo índice mas apenas descreve as correspondências — esses clientes já receberam todos os esquemas de tools/list, então não há nada a carregar.

O que o diferimento nunca faz

O diferimento é aplicado depois do filtro de ferramentas do modo, nunca em seu lugar. Ele esconde um esquema; não consegue revelar uma ferramenta que o modo negou. Uma ferramenta ativada ainda passa pelo prompt de aprovação e pelas barreiras de ação exatamente como uma residente passaria, e uma ferramenta não pode carregar um nome que não estivesse na superfície da execução desde o começo.

A superfície MCP que os clientes externos veem não é afetada. tools/list continua retornando o catálogo completo. Uma tentativa anterior de enxugá-la quebrou os agentes por completo: os clientes MCP validam nomes de ferramentas contra a própria lista em cache e recusam qualquer coisa não listada sem nunca perguntar ao servidor, então uma ferramenta “oculta mas chamável” era simplesmente inalcançável. O diferimento mora no harness, onde carregar uma ferramenta no meio da execução é algo que o harness realmente consegue fazer.

Como desativá-lo

--tool-deferral=off (ou CC_SERVER_TOOL_DEFERRAL=off) torna residente novamente toda ferramenta admitida, produzindo exatamente as requisições que o servidor fazia antes de o diferimento existir. Consulte a referência da CLI do cc_server.

Cache de prompts

As cargas de trabalho de agentes são desequilibradas: elas enviam prompts enormes e recebem respostas pequenas, turno após turno, com o mesmo prefixo todas as vezes. Os provedores armazenam esse prefixo em cache, e uma leitura de cache custa cerca de um décimo de uma nova. A taxa de acertos de cache é, portanto, uma propriedade de primeira classe do harness, e não uma otimização — e, na Anthropic, ela também rende throughput, porque tokens em cache não contam para o limite de entrada por minuto.

O cache funciona por correspondência exata de prefixo, o que resulta em uma única regra soberana.

Nunca reescreva o que já foi enviado

Qualquer byte que mude invalida o cache a partir daquele ponto. Por isso o harness apenas acrescenta: novas mensagens no fim, e esquemas de ferramentas recém-ativados depois do bloco de ferramentas em cache, em vez de mesclados nele. Essa ordenação é a razão de a ativação ser barata — o prefixo em cache permanece idêntico e a execução paga apenas pelos esquemas que acabou de carregar.

O loop também poda a saída obsoleta de ferramentas de turnos mais antigos para recuperar contexto. Ele espera até haver o suficiente a recuperar que valha a reescrita, de modo que uma poda é uma reescrita profunda e rara, em vez de uma falha de cache contínua.

Onde ficam os pontos de quebra

Um provedor permite um número limitado de marcadores de cache, e o Control Center os distribui deliberadamente:

Marcador	Abrange	Validade
Última ferramenta residente	O bloco de ferramentas	1 hora
Último bloco de sistema	Ferramentas + prompt de sistema	1 hora
Cauda do turno anterior	Histórico até a última requisição	5 min
Cauda do turno atual	O histórico completo	5 min

Os dois últimos formam um par rotativo, e a razão desse par é sutil: uma consulta ao cache procura para trás, por um número limitado de blocos, algo que uma requisição anterior armazenou. Um único turno que executa muitas ferramentas em paralelo pode emitir mais blocos do que essa janela, e nesse momento um marcador de cauda erra em silêncio e a requisição paga o preço cheio sem que nada na resposta diga isso. Marcar o ponto exato em que a requisição anterior parou torna o acerto estrutural, em vez de uma corrida.

O prefixo de ferramentas e sistema recebe a validade longa porque é constante durante toda a execução, é compartilhado por toda execução e todo subagente com o mesmo formato, e porque o relógio começa quando uma requisição começa — um turno que faz streaming por vários minutos já gastou a maior parte de uma janela curta antes de a próxima requisição se formar.

Subagentes compartilham um prefixo

Subagentes do mesmo tipo produzem prefixos de prompt idênticos byte a byte, então deveriam ler uma única entrada de cache em vez de cada um gravar a sua. Mas uma entrada só se torna legível quando a requisição que a gravou começa a responder, então um fan-out disparado de uma só vez faz cada filho pagar o prêmio por um prefixo que todos compartilham.

O harness deixa o primeiro filho de um dado formato começar e então libera seus irmãos assim que ele começa a fazer streaming. A espera é limitada: um primeiro filho lento custa um acerto de cache, nunca o fan-out em si. Pelo mesmo motivo, todo subagente recebe o mesmo conjunto residente de ferramentas, independentemente do seu perfil — variá-lo por perfil fragmentaria o prefixo compartilhado sem ganho algum, já que o perfil já decidiu o que o filho pode chamar.

Vendo isso em ação

As duas metades são observáveis, e não presumidas:

• O explorador de contexto de uma conversa informa as ferramentas residentes, o índice diferido e quanto cada esquema retido custaria, montado a partir do mesmo caminho de código que uma execução real usa.
• Cada execução registra quais ferramentas diferidas carregou e o que disparou isso, de modo que uma busca que não encontra nada fica visível como uma falha de recuperação, em vez de desaparecer dentro de um agente fazendo em silêncio algo adjacente.
• A Observabilidade informa a Taxa de cache como as leituras de cache sobre todos os tokens de prompt processados, incluídas as gravações de cache — uma execução que não para de reconstruir o próprio prefixo pontua baixo, em vez de pontuar como uma que nunca precisou de cache.