Capturas como evidencia para agentes de IA: página completa, regiones y diffs

Conseguir que un agente instale Playwright y guarde un PNG cuesta un puñado de líneas. A estas alturas nadie se atasca con eso. El problema empieza cuando esas imágenes pasan a formar parte de un flujo de trabajo en producción y alguien tiene que fiarse de ellas.

En ese momento el agente tiene que demostrar que una página larga se capturó hasta el final. Tiene que cortar el resultado en trozos que un modelo de visión pueda leer de verdad, guardar evidencias que no cambien nunca después, comparar dos versiones sin que los desplazamientos del layout disparen falsas alarmas, lanzar comprobaciones programadas y no salirse del presupuesto cuando nadie está mirando.

Una API de capturas gestionada con un servidor MCP remoto es una forma de reunir todo eso, para páginas públicas o páginas que quien llama tiene permiso para ver. No pretende sustituir a Playwright a secas cuando basta una captura de usar y tirar. Su papel es servir de capa de evidencias para flujos que se repiten.

Capturar una página en un estado concreto

Una URL por sí sola no determina qué muestra una captura. El ancho en escritorio, tableta y móvil es distinto, igual que los temas claro y oscuro, y una página después de un clic ya es otra. Por eso un servicio de captura necesita ajustes para dispositivos con nombre y viewports personalizados, preferencia de tema, estrategia de espera, limpieza, selectores ocultos, cabeceras, cookies e interacciones guionizadas. Con ellos, el flujo dice qué versión de la página quiere conservar en lugar de conformarse con lo que se haya cargado tras la navegación.

La captura de página completa tiene su propia trampa. La altura puede seguir cambiando mientras llegan el contenido diferido, las fuentes web y las imágenes, así que el navegador puede devolver una imagen con la parte inferior todavía en blanco. La solución es de procedimiento: desplazarse paso a paso, esperar a que la altura del documento deje de moverse, volver arriba, hacer la captura y después comparar el ancho y el alto del PNG o JPEG final con el documento. Si la página nunca se estabiliza o sigue creciendo, la llamada devuelve un error tipado. Un fallo visible es mejor que una evidencia incompleta que se hace pasar por completa.

Cortar páginas largas en regiones legibles

Si metes una captura de 12.000 píxeles en la entrada pequeña de un modelo de visión, el texto se vuelve papilla. La respuesta del servicio es un flag regions en la petición.

curl --request POST https://api.scrinly.com/render/screenshot \
  --header "Authorization: Bearer $SCRINLY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://example.com",
    "device": "macbook-pro-14",
    "theme": "dark",
    "fullPage": true,
    "regions": true,
    "format": "jpg",
    "quality": 80
  }'

La respuesta trae la captura entera y recortes ordenados de la barra de navegación, el hero, el contenido principal, las llamadas a la acción, el pie y cualquier otra zona detectada. Un manifiesto recoge para cada región sus límites, orden, confianza, cobertura, dimensiones y hash. Cada recorte sale de la captura final entregada, nunca de una segunda captura que podría ser distinta.

Un flag design añade evidencia determinista sobre colores, tipografía, espaciado, layout y animaciones, saneada y con tamaño acotado. Ningún modelo de IA interviene en generarla.

Si el procesamiento de regiones falla después de que la captura en sí haya salido bien, quien llama recibe igualmente la captura y solo se reembolsa el recargo por las regiones.

Evidencias que no se pueden sobrescribir

Dos capturas de la misma URL no deben pisarse nunca. Por eso los archivos generados se guardan con nombres derivados de un hash de los bytes codificados finales.

{storagePrefix}/{screenshotSha256}.jpg

Bytes distintos producen claves distintas, y capturas idénticas pueden compartir una sin problema. Los resultados apuntan directamente al proveedor de almacenamiento y no a un proxy de imágenes. Por defecto todo se guarda en Backblaze B2, y los clientes de la API REST pueden enviar los archivos a sus propios buckets de B2, S3 o R2. La caché es opcional mediante un flag cache, y los lotes de capturas públicas admiten hasta 100 capturas almacenadas, con facturación y reembolsos calculados por elemento.

Comparar versiones sin falsos positivos

Hay dos modos de comparación: coincidencia exacta de píxeles y un modo perceptual que tolera el ruido. La salida puede ser una superposición anotada, un mapa de calor contextual, una máscara binaria o solo metadatos.

Lo que complica las comparaciones son los desplazamientos. Si insertas una sección nueva bajo el hero, un diff normal de la imagen completa marca como cambiado todo lo que hay debajo. En cambio, cuando ambas capturas tienen manifiestos de regiones compatibles, cada sección lógica se compara por separado. El bloque insertado aparece como añadido, y un pie que solo se ha desplazado hacia abajo se da por no modificado.

La monitorización reutiliza el mismo pipeline. Un monitor toma una captura nueva y la compara con una línea base móvil o fija. Cuando se supera un umbral, o una región aparece o desaparece, abre un incidente visual, envía webhooks firmados o alertas a correos verificados y avisa de la recuperación cuando la página vuelve a la normalidad.

Los trabajos lentos de capturas y diffs pueden ejecutarse de forma asíncrona. La API devuelve un id de trabajo ligado a la cuenta, consultar el estado no cuesta nada y un webhook firmado puede entregar el resultado terminado.

La IA, solo después de los pasos deterministas

Las capturas, regiones, evidencias de diseño, hashes y diffs son todos deterministas. Una guía de estilo visual opcional añade la interpretación de un modelo, pero solo cuando esa evidencia ya está disponible.

El modelo, que elige el servidor, recibe una imagen general de tamaño acotado, las imágenes ordenadas de las regiones y una proyección saneada. La URL de destino, el nombre de host, el HTML, las cookies, las cabeceras, los selectores, las credenciales y cualquier texto de página aportado no se le pasan como texto. Eso sí, los textos y la marca visibles en pantalla pueden aparecer igualmente en los píxeles.

El resultado cubre la base visual, el color, la tipografía, el espaciado, los componentes, las animaciones, el comportamiento responsive y las lagunas en la evidencia, y cada afirmación se contrasta con esa evidencia. Las guías de estilo se cachean automáticamente y un flag regenerate pide una nueva. Quien llama también puede enviar una clave temporal de OpenAI en una cabecera dedicada, que no se almacena. Si la generación falla, la captura y las regiones siguen disponibles y solo se reembolsa el incremento por IA.

Ofrecerlo a los agentes mediante MCP

El servidor MCP remoto ofrece cuatro herramientas:

• capture_screenshot
• compare_screenshots
• get_job_status
• get_usage

La conexión se hace por OAuth, con una clave de API como alternativa. En Codex queda así:

codex mcp add scrinly --url https://mcp.scrinly.com/mcp

Una skill de código abierto para agentes complementa el servidor. MCP hace que las herramientas se puedan llamar, mientras que la skill enseña a los agentes compatibles cuándo merece la pena una captura, cómo elegir el límite de créditos más bajo que funcione, qué hacer mientras un trabajo aceptado sigue en marcha para no enviar dos veces la petición de pago y cómo guardar juntas las capturas, regiones y hashes que se corresponden.

npx skills add davmixcool/skills --skill scrinly -g

Las operaciones de pago de MCP exigen un valor maxCredits. Si el cargo en el peor caso superara el límite que declaró el usuario, la petición se rechaza antes de renderizar o cobrar nada. Así se traza una línea práctica entre lo que un agente puede hacer por su cuenta y lo que paga el usuario.

Lecciones de diseño que sirven en otros casos

1. Que una llamada al navegador salga bien no demuestra que la captura esté completa.
2. Los recortes derivados deben salir de la imagen exacta que se entregó.
3. Una evidencia estable requiere almacenamiento direccionado por contenido.
4. El procesamiento determinista debe ir antes de la interpretación por IA.
5. Ante un éxito parcial hay que devolver el trabajo útil y reembolsar solo la parte que falló.
6. Las herramientas autónomas necesitan límites de gasto explícitos además de autenticación.
7. Playwright controla el navegador, pero un flujo de evidencias visuales en producción necesita bastante infraestructura a su alrededor.

En cuanto a precios, el plan gratuito incluye 100 créditos al mes. Una captura sin más cuesta un crédito, tres si se añaden regiones, uno por cada diff visual y hasta seis por una guía de estilo recién generada y financiada por la plataforma.