ArtificialGuyBR

Home / Blog / Fixing things

Agent Scrape Kit: descobrir um site uma vez, extrair dele para sempre

Duas skills com LLM para agente: uma engenheira o site ao contrário num blueprint com endpoint, autenticação e paginação; a outra executa esse blueprint de f…

2 sources cited Fixing things

On this page

  1. TL;DR
  2. O que é e para quem
  3. Duas skills, dois trabalhos
  4. O blueprint
  5. Como usar
  6. Quando usar, quando não usar
  7. Sources
  8. FAQ

Agent Scrape Kit: descobrir um site uma vez, extrair dele para sempre

TL;DR

  • O kit são duas skills em vez de um scraper: scraper-discover gasta tempo de LLM uma vez para engenheirar o site ao contrário num blueprint.json, e scraper-run executa esse blueprint de forma determinística.
  • O resultado é o argumento em uma linha: você paga pela exploração uma vez e tem extração confiável para sempre — sem navegador no caminho quente, sem token de LLM na execução repetida.
  • A descoberta classifica a arquitetura do site, sonda endpoint de API direto, faz fingerprint de proteção anti-bot e mapeia o padrão de paginação, e depois valida o blueprint extraindo pelo menos cinco registros.
  • A execução trata refresh de autenticação, limite de taxa com throttling e backoff, e checkpoint a cada 500 registros, então extração longa é retomada em vez de recomeçada.

O que é e para quem

O Agent Scrape Kit é um par de skills com LLM para agente que faz scraping sistemático, e o diagnóstico do README é o familiar: a maior parte do scraping é ad hoc — abre navegador, acha o elemento, extrai, repete no próximo site — o que funciona e não escala, porque toda execução paga o mesmo custo de descoberta outra vez.

É para quem raspa os mesmos cinco sites toda semana e tem cinco scripts que quebram todo trimestre, e para o agente que precisa de dado de um site cuja API ninguém documentou.

Duas skills, dois trabalhos

scraper-discover é reconhecimento. Classifica a arquitetura do site por arquétipo — o README nomeia SSR, SPA REST, SPA GraphQL, comércio estático e blindado por anti-bot — sonda endpoint de API direto, captura tráfego de rede com Playwright só quando é necessário, detecta mecanismo de autenticação com token CSRF e cookie de sessão, faz fingerprint de proteção anti-bot em Cloudflare, Datadome, PerimeterX e Akamai, e identifica o padrão de paginação: cursor, offset, número de página ou scroll infinito.

Depois valida o blueprint extraindo pelo menos cinco registros e salva o JSON reutilizável. O passo de validação é a parte honesta: blueprint que nunca extraiu um registro é hipótese, não especificação.

scraper-run é execução. Carrega e valida o blueprint, executa a paginação automaticamente, trata refresh de autenticação para cookie de sessão, JWT e CSRF, respeita limite de taxa com throttling e backoff incluídos, salva checkpoint a cada 500 registros, e se autorrecupera quando detecta endpoint obsoleto, mudança de formato de resposta ou escalada de anti-bot. A saída é JSON limpo mais CSV.

A autorrecuperação é a decisão de projeto que vale nomear: scraper que falha alto numa mudança de formato de resposta é honesto, e scraper que escreve metade dos campos em silêncio não é.

O blueprint

Os blueprints ficam em ~/.hermes/scraper/blueprints/<domain>.json e descrevem o site, não o script:

Como usar

A descoberta é conversacional: você dá uma URL e o que quer extrair — por exemplo, todos os produtos com nome, preço e SKU — e ela produz o blueprint. Depois a execução pega o nome do blueprint e extrai tudo. Um cron transforma isso em job recorrente com aviso de mudança.

# 1. descobrir o site e produzir o blueprint
# 2. rodar o blueprint para extrair tudo
# 3. opcional: agendar scraper-run a cada 24h e avisar em mudança

Os scripts da descoberta são scripts/recon_capture.py para captura de rede com Playwright e scripts/detect_antibot.py para fingerprint de anti-bot.

Quando usar, quando não usar

Use quando você raspa o mesmo site várias vezes, quando quer pagar a descoberta uma vez em vez de a cada execução, ou quando o site tem endpoint JSON atrás de uma página e você quer pular o navegador.

Não use num site que você raspa uma vez só: a descoberta é a metade cara, e extração única não amortiza. E não use num site cujo dado exige interação só de navegador, como formulário de vários passos — a execução é HTTP e extração, e o README coloca o navegador na descoberta.

Sources

  1. Agent Scrape Kit — repositório — as duas skills, comportamento de descoberta e execução, formato do blueprint e uso citados acima.
  2. README.md — skills, scripts, comandos de uso, exemplo de blueprint.

Página do projeto: Agent Scrape Kit

Para o lado de SEO do que o site raspado deveria fazer depois, veja a skill de SEO, GEO e ASO.

FAQ

A skill de execução usa navegador? Não. O scraper-run executa o blueprint com chamada HTTP e extração; o navegador aparece na descoberta, quando é preciso capturar rede.

Gasta token de LLM em toda execução? Não, e esse é o ponto: a descoberta gasta tempo de LLM uma vez, e a execução é determinística depois.

Como o blueprint é validado? Extraindo pelo menos cinco registros antes de salvar o JSON reutilizável.

O que a execução faz em escala? Trata paginação, refresh de autenticação, limite de taxa com throttling e backoff, e salva checkpoint a cada 500 registros.