Agent Scrape Kit: descubrir un sitio una vez, extraer de él para siempre

TL;DR

• El kit son dos skills en vez de un scraper: scraper-discover gasta tiempo de LLM una vez para reconstruir el sitio a la inversa en un blueprint.json, y scraper-run ejecuta ese blueprint de forma determinista.
• El resultado es el argumento en una línea: pagas la exploración una vez y tienes extracción confiable para siempre — sin navegador en el camino caliente, sin tokens de LLM en la ejecución repetida.
• El descubrimiento clasifica la arquitectura del sitio, sondea endpoints de API directo, identifica la huella de la protección anti-bot y mapea el patrón de paginación, y después valida el blueprint extrayendo al menos cinco registros.
• La ejecución maneja refresh de autenticación, límites de tasa con throttling y backoff, y checkpoint cada 500 registros, así que una extracción larga se reanuda en vez de recomenzar.

Qué es y para quién

Agent Scrape Kit es un par de skills con LLM para agentes que hacen scraping sistemático, y el diagnóstico del README es el conocido: casi todo el scraping es ad hoc — abre el navegador, busca el elemento, extrae, repite en el sitio siguiente — lo que funciona y no escala, porque cada ejecución paga otra vez el mismo coste de descubrimiento.

Es para quien raspa los mismos cinco sitios cada semana y tiene cinco scripts que se rompen cada trimestre, y para el agente que necesita datos de un sitio cuya API nadie documentó.

Dos skills, dos trabajos

scraper-discover es reconocimiento. Clasifica la arquitectura del sitio por arquetipo — el README nombra SSR, SPA REST, SPA GraphQL, comercio estático y blindado con anti-bot — sondea endpoints de API directo, captura tráfico de red con Playwright solo cuando hace falta, detecta mecanismos de autenticación con tokens CSRF y cookies de sesión, identifica la huella de protección anti-bot en Cloudflare, Datadome, PerimeterX y Akamai, y detecta el patrón de paginación: cursor, offset, número de página o scroll infinito.

Después valida el blueprint extrayendo al menos cinco registros y guarda el JSON reutilizable. El paso de validación es la parte honesta: un blueprint que nunca extrajo un registro es una hipótesis, no una especificación.

scraper-run es ejecución. Carga y valida el blueprint, ejecuta la paginación automáticamente, maneja refresh de autenticación para cookies de sesión, JWT y CSRF, respeta límites de tasa con throttling y backoff, guarda checkpoint cada 500 registros y se autorrepara cuando detecta endpoint obsoleto, cambio en la forma de la respuesta o escalada de anti-bot. La salida es JSON limpio más CSV.

La autorreparación es la decisión de diseño que merece nombrarse: un scraper que falla en voz alta ante un cambio de forma es honesto, y uno que escribe la mitad de los campos en silencio no lo es.

El blueprint

Los blueprints se guardan en ~/.hermes/scraper/blueprints/<dominio>.json y describen el sitio, no el script:

Cómo usarlo

El descubrimiento es conversacional: das una URL y qué quieres extraer — por ejemplo todos los productos con nombre, precio y SKU — y produce el blueprint. Después la ejecución toma el nombre del blueprint y extrae todo. Un cron lo convierte en trabajo recurrente con aviso de cambios.

# 1. descubrir el sitio y producir el blueprint
# 2. ejecutar el blueprint para extraer todo
# 3. opcional: programar scraper-run cada 24h y avisar de cambios

Los scripts del descubrimiento son scripts/recon_capture.py para captura de red con Playwright y scripts/detect_antibot.py para la huella de anti-bot.

Cuándo usarlo, cuándo no

Úsalo cuando raspas el mismo sitio repetidamente, cuando quieres pagar el descubrimiento una vez en vez de en cada ejecución, o cuando el sitio tiene un endpoint JSON detrás de una página y quieres saltarte el navegador.

No lo uses en un sitio que raspas una sola vez: el descubrimiento es la mitad cara y una extracción única no lo amortiza. Y no lo uses en un sitio cuyo dato exige interacción solo de navegador, como un formulario de varios pasos — la ejecución es HTTP y extracción, y el README pone el navegador en el descubrimiento.

Sources

1. Agent Scrape Kit — repositorio — las dos skills, el comportamiento de descubrimiento y de ejecución, el formato del blueprint y el uso citados arriba.
2. README.md — skills, scripts, comandos de uso, ejemplo de blueprint.

Página del proyecto: Agent Scrape Kit

Para el lado de SEO de lo que el sitio raspado debería hacer después, mira la skill de SEO, GEO y ASO.

FAQ

¿La skill de ejecución usa navegador? No. scraper-run ejecuta el blueprint con llamadas HTTP y extracción; el navegador aparece en el descubrimiento, cuando hace falta capturar red.

¿Gasta tokens de LLM en cada ejecución? No, y ese es el punto: el descubrimiento gasta tiempo de LLM una vez y la ejecución es determinista después.

¿Cómo se valida el blueprint? Extrayendo al menos cinco registros antes de guardar el JSON reutilizable.

¿Qué hace la ejecución a escala? Maneja paginación, refresh de autenticación, límites de tasa con throttling y backoff, y guarda checkpoint cada 500 registros.