Intensivo Grátis 21–22/11Intensivo gratuito de 2 dias em Vibecoding (21–22/11 às 16:00 MSK) · Turma 3 começa 23/11Inscrever-se grátis →Turma 3 (23/11)
LançamentoAnálise · No radarHabr AI→ original

Mapa de site para agentes de IA reduziu o texto baixado em 58%, mas o uso de tokens subiu 3,5%

Pergunte a um agente o preço da batata frita e o site entrega o cardápio inteiro. A equipe da Deckard criou o agent-sitemap, um gerador que divide o site em notas Markdown com links, como um índice. Com esse mapa, o Claude Code fez 6 requisições em vez de 9 e baixou 58% menos texto, mas o total de tokens de entrada ficou 3,5% maior. Por isso, a economia deve ser medida em tokens e cache, não pelo tamanho das páginas.

Processado por IA de Habr AI; editado por Hamidun News
Mapa de site para agentes de IA reduziu o texto baixado em 58%, mas o uso de tokens subiu 3,5%
Fonte: Habr AI. Colagem: Hamidun News.
Ouvir artigo
Ficha técnica e números-chave
ParâmetroDados
Fonte originalHabr AI ↗
Editor-chefe
Texto baixado24 627 caracteres contra 58 439 sem o mapa
Tokens de entrada64 987 contra 62 811, e o contador soma também o cache
Código aberto sob licença MITnpx agent-sitemap https://example.com

Quando você pede a um agente de IA que entre no site de um restaurante e descubra o preço da batata frita pequena, uma pessoa simplesmente abriria a seção “Cardápio” e acharia a linha certa. O agente funciona de outro jeito: a ferramenta entrega a ele HTML, texto limpo ou uma captura de tela, sempre com o cardápio inteiro, e hambúrgueres e bebidas entram no contexto junto com a batata. A equipe da Deckard tentou resolver isso com um índice para agentes e publicou o agent-sitemap, um gerador de código aberto.

Em um teste preliminar, o Claude Code com esse mapa baixou 58% menos texto (24 627 caracteres em vez de 58 439), mas o total de tokens de entrada, ou seja, o volume que o modelo leu e pelo qual você paga, ficou 3,5% maior. Para o desenvolvedor, a conclusão é uma só: reduzir o tamanho das páginas baixadas não significa necessariamente gastar menos nas chamadas ao modelo.

Como o mapa funciona

O arquivo sitemap.xml informa quais páginas existem no site, mas não mostra em que ponto do cardápio está a batata. O llms.txt pode descrever links e servir versões das páginas em Markdown, mas um cardápio longo continua longo depois do clique, só que sem o HTML.

O gerador faz diferente: cria um arquivo Markdown separado para cada seção. O índice (index.md) leva à ficha da página; a ficha, com uma introdução e a lista de seções, leva à nota da seção; e esta leva a materiais vizinhos. O agente abre o índice, entra em “Cardápio”, escolhe “Batatas e petiscos” pela descrição e não lê os hambúrgueres nem as bebidas. A nota guarda o endereço da página original, para que o agente possa citá-lo como fonte e conferir o preço. Essas mesmas relações são gravadas em graph.json, para quem lê o mapa a partir do próprio código.

A entrada pode ser HTML e Markdown locais ou um site com seu próprio sitemap.xml. O texto é dividido pelos títulos de segundo nível (##).

Parte das relações já existe no documento: a página contém seções, uma seção vem depois da outra e o autor pode ter incluído um link para uma página vizinha. As relações que faltam são encontradas comparando as palavras de páginas diferentes (TF-IDF e similaridade de cosseno). Isso pode gerar falsos positivos: a palavra “entrega” aparece com a mesma frequência nas tarifas e nas regras de devolução.

Por isso é possível ativar uma etapa com LLM, que escreve explicações curtas para as notas e descarta parte das relações encontradas por palavras. Os links do autor continuam no mapa.

O que o teste mostrou

O README do projeto traz um teste preliminar: duas perguntas sobre o site da Deckard, cujas respostas ficam escondidas dentro de artigos longos. O Claude Code começava pela página inicial ou pelo índice do mapa, podia usar curl e sabia que o site servia Markdown. A correção foi verificada por um modelo, com base em respostas de referência definidas de antemão, e as quatro respostas foram aceitas.

Com o mapa, o agente fez 6 requisições HTTP em vez de 9 e baixou 24 627 caracteres em vez de 58 439. Na pergunta sobre developer, foram 33 029 tokens contra 31 828 sem o mapa; na pergunta sobre ship, 31 958 contra 30 983. No total, 64 987 contra 62 811, um aumento de cerca de 3,5%.

O próprio autor explica a divergência. O contador de caracteres considera apenas o conteúdo das respostas HTTP. O contador de tokens de entrada inclui também todo o restante do contexto que o modelo recebe a cada passo. Além disso, o teste soma tokens de entrada comuns, escrita em cache e leitura de cache, embora cada um tenha um preço diferente. Por isso, a tabela mostra quanto texto o site entregou, mas não quanto a resposta custou. Para entender o custo, é preciso examinar o percurso do agente e o relatório por categoria de token separadamente.

Há ainda outra ressalva: a indicação “aproximadamente N tokens” ao lado de um link é calculada por caracteres, com coeficientes diferentes para cirílico e para o restante do texto, sem usar o tokenizador de um modelo específico. A estimativa considera o texto principal, embora o arquivo tenha também títulos, metadados e links, que numa nota curta podem ser maiores que a própria seção.

O que fazer na prática

Convém tirar conclusões com cautela: foi uma única execução, com duas perguntas e um agente. Um assistente com busca web comum e navegador pode percorrer outro caminho. O teste não traz duas variantes de controle: llms.txt com páginas Markdown inteiras (para isolar o efeito de apenas limpar o HTML) e a página certa já de início. Se ela tiver só dois parágrafos, o caminho pelo índice e pela ficha quase certamente será mais longo que ler a página inteira.

Para a própria verificação, o autor recomenda pegar de 10 a 30 perguntas reais e repetir cada uma várias vezes em condições idênticas. Parte das respostas deve estar em uma única seção, parte deve exigir várias páginas e, para parte delas, o site não deve ter resposta alguma. É preciso medir a correção da resposta e a citação da fonte, o número de requisições, o volume de texto baixado, o tempo e o custo. O tempo que o modelo gasta para verificar as respostas é melhor registrar à parte.

O uso é simples: npx agent-sitemap https://example.com gera o diretório ai. Ele é publicado junto ao site, confirma-se que /ai/index.md abre e esse endereço é passado ao agente de forma explícita. Assim, o resultado da navegação pelo mapa não se mistura com a questão de o agente ter ou não encontrado o mapa.

Os riscos também são claros. A regra e a exceção podem cair em notas diferentes, e o agente responderá corretamente só pela metade. Um título como “Informações adicionais” não diz nada sobre o conteúdo. A cópia em Markdown pode ficar defasada em relação ao site, então, para preços, é melhor consultar a página ao vivo ou a API. E o texto das notas vem de fora, como qualquer página web, de modo que instruções dentro dele não devem ser tomadas como comandos do usuário. O código é aberto sob licença MIT, e o repositório se chama agent-sitemap.

História

Perguntas frequentes sobre a notícia

Como o mapa funciona?

O arquivo sitemap.xml informa quais páginas existem no site, mas não mostra em que ponto do cardápio está a batata. O llms.txt pode descrever links e servir versões das páginas em Markdown, mas um cardápio longo continua longo depois do clique, só que sem o HTML. O gerador faz diferente: cria um arquivo Markdown separado para cada seção. O índice (index.md) leva à ficha da página; a ficha, com uma introdução e a lista de seções, leva à nota da seção; e esta leva a materiais vizinhos.

O que o teste mostrou?

O README do projeto traz um teste preliminar: duas perguntas sobre o site da Deckard, cujas respostas ficam escondidas dentro de artigos longos. O Claude Code começava pela página inicial ou pelo índice do mapa, podia usar curl e sabia que o site servia Markdown. A correção foi verificada por um modelo, com base em respostas de referência definidas de antemão, e as quatro respostas foram aceitas. Com o mapa, o agente fez 6 requisições HTTP em vez de 9 e baixou 24 627 caracteres em vez de 58 439.

O que fazer na prática?

Convém tirar conclusões com cautela: foi uma única execução, com duas perguntas e um agente. Um assistente com busca web comum e navegador pode percorrer outro caminho. O teste não traz duas variantes de controle: llms.txt com páginas Markdown inteiras (para isolar o efeito de apenas limpar o HTML) e a página certa já de início. Se ela tiver só dois parágrafos, o caminho pelo índice e pela ficha quase certamente será mais longo que ler a página inteira.

ZK
Zhemal Khamidun — CPO da Alpina Digital, gerente de produto do AlpinaGPT. Cria produtos de IA desde 2019. O Hamidun News é um projeto pessoal que virou um agregador em produção com mais de 6.000 leitores.
✦ Hands-On AI Engineering · Hamidun Academy

Build & Ship Production AI Agents Without Boilerplate Code

Start your free 72-hour trial at Hamidun Academy (academy.hamidun.com) — interactive lessons on Claude Code & Cursor, live Tech Radar, and production agent templates.

Start 72h Free Trial →Vibe-Coding Intensive
O que você acha?
Carregando comentários…