1

Agente com tool use (API do Claude) gasta muitos tokens ao gerar documentos técnicos grandes: como reaproveitar blocos prontos em vez de gerar do zero

Tenho um aplicativo desktop em C#/.NET (WPF) que desenha esquemas elétricos de painéis industriais. Ele tem um assistente de IA que usa a API do Claude (Messages API com tool use) pra montar projetos inteiros. A IA chama ferramentas do programa, como inserir_componente, ligar, ler_folha, verificar_projeto e ver_pagina (que devolve uma imagem da página), e o próprio programa confere as ligações em código.

Um projeto típico tem de 20 a 60 páginas e segue um padrão de desenho rígido. Os documentos do cliente entram como anexos PDF no primeiro pedido.

Como funciona hoje:

Um agente “coordenador” planeja e divide o trabalho. Os “executores” desenham grupos de páginas, cada um numa conversa separada, e um “revisor” confere.

Cada chamada reenvia o prompt do sistema, as regras de desenho (~5 mil tokens), as definições das ferramentas, os PDFs e o histórico. Uso prompt caching com cache_control no prompt do sistema e no fim da conversa.

O que medi num projeto grande (um pedido, 240 chamadas):

Parte Tokens % do custo

Gravação no cache 2,2 milhões 46%

Saída (incluindo raciocínio) 421 mil 35%

Leitura do cache 24,3 milhões 20%

Cada chamada carregava em média ~100 mil tokens de contexto.

O que já corrigi:

O cache vencia, porque tem 5 minutos de vida, enquanto o coordenador esperava um executor terminar. Agora reenvio a última requisição com max_tokens: 0 a cada 4 minutos pra manter o cache vivo.

O limite de contexto contava o prompt inteiro. Com os PDFs no começo da conversa, o agente “resumia e recomeçava” quase toda hora. Agora o limite conta só o que o pedido acrescentou.

Passei a registrar o uso de cada chamada num CSV.

O problema que continua:

Boa parte dos circuitos se repete de projeto pra projeto (alimentação geral, partida de motor, comando local/remoto, inversor). Mesmo assim, o modelo tende a desenhar componente por componente: são dezenas de chamadas, e cada uma relê o contexto. Criei “macros” (blocos prontos inseridos por uma ferramenta inserir_macro) e um catálogo de peças padrão. Ainda não sei qual é a melhor forma de fazer o modelo preferir esses blocos de forma confiável sem perder qualidade.

Minha pergunta: num agente com tool use que gera documentos grandes e estruturados, que técnicas funcionam na prática pra que o modelo reaproveite blocos prontos em vez de gerar do zero, reduzindo o número de chamadas e o contexto relido? Por exemplo:

descrever as macros nas definições das ferramentas, ou num catálogo consultado sob demanda;

uma ferramenta de “plano” que já devolve a lista de blocos a inserir;

ou separar o planejamento (feito uma vez) da execução (com contexto mínimo).

Se alguém já mediu o efeito disso no custo, gostaria de saber a ordem de grandeza.Tenho um aplicativo desktop em C#/.NET (WPF) que desenha esquemas elétricos de painéis industriais. Ele tem um assistente de IA que usa a API do Claude (Messages API com tool use) pra montar projetos inteiros. A IA chama ferramentas do programa, como inserir_componente, ligar, ler_folha, verificar_projeto e ver_pagina (que devolve uma imagem da página), e o próprio programa confere as ligações em código.

Um projeto típico tem de 20 a 60 páginas e segue um padrão de desenho rígido. Os documentos do cliente entram como anexos PDF no primeiro pedido.

Como funciona hoje:

Um agente “coordenador” planeja e divide o trabalho. Os “executores” desenham grupos de páginas, cada um numa conversa separada, e um “revisor” confere.

Cada chamada reenvia o prompt do sistema, as regras de desenho (~5 mil tokens), as definições das ferramentas, os PDFs e o histórico. Uso prompt caching com cache_control no prompt do sistema e no fim da conversa.

O que medi num projeto grande (um pedido, 240 chamadas):

Parte Tokens % do custo

Gravação no cache 2,2 milhões 46%

Saída (incluindo raciocínio) 421 mil 35%

Leitura do cache 24,3 milhões 20%

Cada chamada carregava em média ~100 mil tokens de contexto.

O que já corrigi:

O cache vencia, porque tem 5 minutos de vida, enquanto o coordenador esperava um executor terminar. Agora reenvio a última requisição com max_tokens: 0 a cada 4 minutos pra manter o cache vivo.

O limite de contexto contava o prompt inteiro. Com os PDFs no começo da conversa, o agente “resumia e recomeçava” quase toda hora. Agora o limite conta só o que o pedido acrescentou.

Passei a registrar o uso de cada chamada num CSV.

O problema que continua:

Boa parte dos circuitos se repete de projeto pra projeto (alimentação geral, partida de motor, comando local/remoto, inversor). Mesmo assim, o modelo tende a desenhar componente por componente: são dezenas de chamadas, e cada uma relê o contexto. Criei “macros” (blocos prontos inseridos por uma ferramenta inserir_macro) e um catálogo de peças padrão. Ainda não sei qual é a melhor forma de fazer o modelo preferir esses blocos de forma confiável sem perder qualidade.

Minha pergunta: num agente com tool use que gera documentos grandes e estruturados, que técnicas funcionam na prática pra que o modelo reaproveite blocos prontos em vez de gerar do zero, reduzindo o número de chamadas e o contexto relido? Por exemplo:

descrever as macros nas definições das ferramentas, ou num catálogo consultado sob demanda;

uma ferramenta de “plano” que já devolve a lista de blocos a inserir;

ou separar o planejamento (feito uma vez) da execução (com contexto mínimo).

Se alguém já mediu o efeito disso no custo, gostaria de saber a ordem de grandeza.

Carregando publicação patrocinada...
1

Pela sua tabela, o que pesa é a gravação no cache (46% com só 2,2 mi de tokens), não a leitura. Então eu atacaria primeiro o número de prefixos diferentes que você grava, e só depois o número de chamadas.

1. Um prefixo único para todos os executores. O cache é por prefixo, na ordem tools → system → messages. Se cada executor recebe um prompt de sistema um pouco diferente (nome do grupo de páginas, data, ordem das ferramentas), cada um grava o próprio cache dos PDFs. Deixe ferramentas + sistema + regras + PDFs byte a byte idênticos para todos, com um cache_control logo depois dos PDFs, e coloque o que muda (quais páginas desenhar) só depois desse ponto. Aí os PDFs são gravados uma vez e os outros executores só leem. Vale conferir em usage.cache_creation_input_tokens da segunda conversa: se ainda aparecem os ~100 mil, o prefixo está mudando em algum lugar.

2. Executor sem os PDFs. O coordenador lê os PDFs uma vez e devolve uma especificação estruturada (lista de cargas, motores, tensões, I/O) via saída estruturada. Os executores recebem só essa especificação, que deve ficar em poucos milhares de tokens. Na sua conta, 240 chamadas × ~100 mil = os 24 mi de leitura; se o contexto de cada executor cair para algo como 15 mil, a leitura cai na mesma proporção.

3. Macro inserida pelo código, não pelo modelo. Em vez de torcer para o modelo preferir inserir_macro, separe as etapas: uma ferramenta planejar_paginas devolve, para cada página, {macro, parâmetros} ou "personalizado". As páginas com macro o seu C# monta sozinho, sem nenhuma chamada ao modelo. O modelo só desenha componente por componente o que o plano marcou como personalizado, e o revisor confere tudo no fim. Isso troca "dezenas de chamadas por circuito padrão" por zero.

4. Menos idas e voltas no que sobra. Uma ferramenta que aceita uma lista (inserir_componentes([...]), ligar([...])) e chamadas paralelas na mesma resposta reduzem o número de vezes que o contexto é relido. Na descrição da ferramenta de componente, diga quando ela é a escolha certa ("use só para o que nenhuma macro do catálogo cobre") e peça um campo motivo obrigatório; isso costuma bastar para o modelo não pular o catálogo.

5. Conjunto de ferramentas fixo por papel. Tirar e pôr ferramentas no meio da conversa invalida o cache inteiro (elas vêm primeiro no prefixo). Melhor ter dois conjuntos estáveis, um do coordenador e um do executor, cada um com seu cache.

Sobre ordem de grandeza: não tenho um número medido de um caso igual ao seu, então não vou inventar. Mas o item 3 é o único que zera chamadas; os outros só barateiam cada uma. Com o seu CSV por chamada dá para medir antes e depois num projeto só.

1

O modelo tende a ler o histórico inteiro para validar uma conexão, o que escala linearmente com o número de páginas. Isso sugere mudar o mecanismo de validação: em vez de reenviar o histórico, crie uma ferramenta que exponha apenas o estado local atual (conexões ativas no nó específico). O modelo valida a nova inserção contra esse snapshot leve, reduzindo drasticamente o contexto necessário por passo. A validação mecânica global (como verificar se todos os circuitos estão fechados) deve continuar sendo feita pelo seu código C#, mantendo a qualidade. O modelo foca na inserção do bloco, enquanto o código garante a integridade. Para o planejamento, você mantém o coordenador com contexto total ou usa um modelo menor apenas para a divisão de tarefas, acionando o Claude só na execução dos blocos?