- Renderizado de JavaScript e interacciones reales de usuario (clic, desplazamiento, rellenado de formularios)
- Sesiones persistentes (cookies/almacenamiento) mediante perfiles
- Enrutamiento por proxy y configuración de navegador repetible
Nota: Esta página describe un patrón técnico de integración. No modifica las reglas de los sitios web de destino ni garantiza el acceso.
Patrón de integración general
Los agentes de IA normalmente no “se conectan a un navegador” directamente. En su lugar:- planifican qué hacer a continuación
- llaman a las herramientas/funciones que tú expones (tool calling)
- leen los resultados estructurados y continúan
- se conectan a una sesión en la nube (token + perfil opcional)
- ejecutan acciones en el navegador (navegar, hacer clic, extraer, capturar pantalla)
- devuelven resultados estructurados al agente
Arquitectura recomendada
Agente de IA (Claude / Codex / otro) -> llama a tu servidor de herramientas (tu servicio en Node/Python) -> el servidor de herramientas usa Playwright/Puppeteer -> se conecta a Gologin Cloud Browser (endpoint remoto) -> devuelve los resultados (texto/JSON/referencia de captura de pantalla) al agente Por qué este patrón:- tu token de Gologin permanece en el servidor
- puedes aplicar límites de velocidad, reintentos, registros y comprobaciones de seguridad
- puedes reutilizar perfiles y proxies de forma coherente
Requisitos previos
1) Token de API (en el servidor)
Crea tu token en la aplicación de Gologin: API & MCP → API → New Token.Trata el token como un secreto. No lo expongas en código del lado del cliente.
2) (Recomendado) Perfiles y proxies mediante la API REST
Cloud Browser es la capa de ejecución. Para gestionar perfiles (crear/actualizar) y configurar proxies, usa la API REST:- API de perfiles: https://gologin.com/docs/api-reference/profile
- API de proxies: https://gologin.com/docs/api-reference/proxy
Importante: Si un perfil tiene un proxy mal configurado o inaccesible, la sesión del navegador en la nube no se iniciará y mostrará un error de tiempo de espera del proxy. Verifica que tu proxy sea accesible antes de conectarte, o establece el modo de proxy en none para hacer pruebas.
Dos URL: conoce la diferencia
Gologin expone dos URL distintas para Cloud Browser. Cada una tiene un propósito diferente:
Solo el endpoint
/connect funciona con Puppeteer/Playwright. La URL de Live View devuelve una interfaz HTML de streaming y no se puede usar como browserWSEndpoint.
Conexión a una sesión en la nube
Usa el endpoint canónico de Cloud Browser:token: tu token de API de Gologinprofile: ID del perfil (opcional)- Usa
profileIdcuando quieras sesiones persistentes y una configuración controlada - Si se omite
profile, es posible que se cree un perfil nuevo para la sesión
- Usa
/connect inicia la sesión del navegador automáticamente; no es necesaria ninguna llamada a la API independiente antes de conectarte.
Ejemplos de implementación (Puppeteer/Playwright):
https://gologin.com/docs/api-reference/cloud-browser/getting-started
Herramientas CLI predefinidas frente a herramientas personalizadas
Tienes dos opciones para dar acceso al navegador a los agentes:Opción A: Usar las herramientas CLI de Gologin (recomendada en la mayoría de los casos)
- Agent Browser CLI: CLI listo para usar con
open,snapshot,click,type,fill,screenshot,closey más de 30 comandos adicionales. Incluye un daemon persistente, interacción basada en referencias y una salida compacta pensada para los bucles de los agentes. - Web Access CLI: CLI unificado que combina el scraping (Web Unlocker) y la interacción con el navegador en una sola herramienta.
- AI Skills: skills plug-and-play para Claude Code que se encargan de todo automáticamente.
Opción B: Crear herramientas personalizadas con Puppeteer/Playwright
Si necesitas control total, implementa un pequeño conjunto de wrappers en torno a Playwright/Puppeteer y expónlos como herramientas. Normalmente basta con un conjunto mínimo:open_url(url)click(selector)type(selector, text)wait_for(selector | timeout)extract_text(selector | page)screenshot()close_session()
Importante: gestión de sesiones entre llamadas a herramientas
Este es el aspecto de arquitectura más importante en los flujos de trabajo con agentes. Un agente de IA llama a las herramientas de forma secuencial a lo largo de varios pasos. Cada llamada a una herramienta debe reutilizar la misma conexión del navegador: si creas un nuevopuppeteer.connect() en cada llamada, pierdes las cookies, el almacenamiento local y el estado de la página entre un paso y otro.
Patrón recomendado: mantén una instancia única (singleton) de la sesión en tu servidor de herramientas.
getSession() para obtener la instancia compartida:
¿Qué deben devolver las herramientas al agente?
Devuelve resultados pequeños y estructurados para que el agente pueda continuar de forma fiable, por ejemplo:- la URL actual
- texto extraído / JSON
- si se encontró un elemento
- referencia de la captura de pantalla (si la almacenas)
- tipo de error (tiempo de espera agotado, error de navegación, etc.)
Notas operativas
- Seguridad: mantén el token en el servidor; nunca lo incluyas en aplicaciones cliente.
- Gestión de sesiones: cierra las sesiones al terminar para no alcanzar los límites de concurrencia. Llama a
closeSession()cuando el flujo de trabajo del agente finalice. - Fiabilidad: añade reintentos con retroceso (backoff) para fallos transitorios (tiempos de espera agotados, errores de navegación).
- Observabilidad: para depurar, puedes abrir Live View cuando esté disponible. Formato de URL de ejemplo:
https://cloudbrowser.gologin.com/browsers/{profileId}/{sessionId-or-view-token}/
Limitaciones
- Los resultados dependen del sitio web de destino y de tu configuración.
- Los sitios web pueden bloquear la automatización; Cloud Browser es un entorno de ejecución, no una garantía.
- Conectarte al mismo perfil desde varias sesiones simultáneas puede causar conflictos: usa una sola conexión por perfil a la vez.
- Se aplican cuotas y límites de velocidad: https://gologin.com/docs/api-reference/limitations/rate-limits