Navegador del agente

Un navegador headless basado en la nube con seguridad adaptativa integrada, gestión de CAPTCHA y residential proxies. Pruébalo con ejemplos de código y personalízalo con funciones avanzadas.

Agent Browser te permite ejecutar y controlar instancias remotas para automatización basada en navegador, pruebas y web scraping sin administrarlas localmente. Incluye seguridad adaptable integrada, manejo automático de CAPTCHA, geolocalización, Residential Proxies integradas, grabación de sesiones, sesiones persistentes y perfiles persistentes.

Bibliotecas compatibles

Agent Browser funciona con cualquier biblioteca que admita Chrome DevTools Protocol (CDP)y, entre ellas:

• Playwright (Python y Node.js)
• Puppeteer (Node.js)
• Otros marcos de automatización compatibles con CDP

Detalles de conexión

Atención: Agent Browser se está moviendo a una nueva infraestructura. Actualiza tu cadena de conexión de ubc.oxylabs.io a hb.oxylabs.io antes del 1 de octubre. A partir del 1 de octubre, el tráfico enviado al dominio antiguo se redirigirá automáticamente al nuevo.

El Dashboard y las herramientas de inspección de sesiones también se han movido de headlesify.io a hb.oxylabs.io. Consulta la Inspección y grabación de sesiones para más detalles.

Campo	Descripción
Protocolo	wss:// (WebSocket seguro)
Host (Chromium)	hb.oxylabs.io
Autenticación	En la URL, la información de usuario – wss://USERNAME:PASSWORD@host. Debe incluir el token de sufijo del nombre de usuario (p. ej. user_ab12). No se admite autenticación basada en encabezados.
Transporte	CDP – chromium.connectOverCDP (Playwright) / puppeteer.connect (Puppeteer).
Dominio	oxylabs.io – se usa para los endpoints de conexión (p. ej. hb.oxylabs.io), el Dashboard (hb.oxylabs.io/dashboard), y la inspección de sesiones (hb.oxylabs.io/novnc).
Límites de tasa	100 sesiones concurrentes, 10 sesiones por segundo. Ver más.

Funciones

Oxylabs Agent Browser incluye funciones integradas, nativas de la nube, diseñadas para usarse mediante parámetros de consulta en la URL de conexión WebSocket.

Gestión de CAPTCHA	Gestión y monitoreo automáticos de CAPTCHA en tiempo real (predeterminado – desactivado).
Segmentación de proxy y geolocalización	Dirige las sesiones a través de países, estados o ciudades específicos.
Emulación de dispositivos	Emula huellas digitales y viewports específicos del dispositivo.
Inspección de sesiones (VNC)	Supervisa sesiones en vivo de Headless Browser.
Grabación de sesiones	Graba las sesiones del navegador en formato de video.
Sesiones persistentes	Crea y administra instancias de navegador persistentes.
Perfiles persistentes	Guarda y restaura cookies/localStorage entre sesiones.

Paso de parámetros

Todas las funciones se habilitan y configuran agregando parámetros de consulta directamente a tu extremo WebSocket Secure encadenando varias funciones usando ampersands (&).

# Example: Connecting to Chrome with US Geolocation and CAPTCHA handling enabled
wss://USER:[e-mail]?p_cc=US&solve_captcha=true

Ejemplos de código

A continuación se muestran ejemplos básicos para inicializar una sesión de navegador alojada en la nube:

Python (Playwrigth)

from playwright.sync_api import sync_playwright

username = "USERNAME" # include any account suffix
password = "PASSWORD"
endpoint = "hb.oxylabs.io"
browser_url = f"wss://{username}:{password}@{endpoint}?p_cc=US"

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(browser_url)
    page = browser.new_page()
    page.goto("https://ip.oxylabs.io/location")
    print(page.title())
    browser.close()

JavaScript (Playwright)

process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0"; //For testing only
import { chromium } from "playwright";

const username = "USERNAME";
const password = "PASSWORD";
const endpoint = "hb.oxylabs.io";
const browserUrl = `wss://${username}:${password}@${endpoint}?p_cc=US`;

(async () => {
    const browser = await chromium.connectOverCDP(browserUrl);
    const ctx = browser.contexts()[0] || (await browser.newContext());
    const page = ctx.pages()[0] || (await ctx.newPage());
    await page.goto("https://ip.oxylabs.io/location");
    console.log(await page.title());
    await browser.close();
})();

JavaScript (Puppeteer)

process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0"; //For testing only
import puppeteer from "puppeteer";

const username = "USERNAME";
const password = "PASSWORD";
const endpoint = "hb.oxylabs.io";
const browserUrl = `wss://${username}:${password}@${endpoint}?p_cc=US`;

(async () => {
    const browser = await puppeteer.connect({ browserWSEndpoint: browserUrl });
    const page = await browser.newPage();
    await page.goto("https://ip.oxylabs.io/location");
    console.log(await page.title());
    await browser.close();
})();

Nota: Los ejemplos usan USERNAME y PASSWORD solo para facilitar la lectura. En proyectos reales, cárgalas desde variables de entorno (p. ej. process.env.OXYLABS_USERNAME / process.env.OXYLABS_PASSWORD) mediante un .env archivo.

JavaScript: Usa NODE_TLS_REJECT_UNAUTHORIZED="0" la bandera antes de requerir Playwright en Node.js si encuentras errores de TLS/certificado. Solo para pruebas locales. En producción, limita la confianza a la conexión específica o añade el certificado CA del proveedor a tu almacén de confianza en su lugar.

Referencia de parámetros

Parámetro	Descripción	Tipo
p_cc	Geolocalización de país en ISO 3166-1 alpha-2 código de 2 letras (p. ej., EE. UU., DE).	cadena
p_state	Geolocalización de estado en minúsculas (p. ej., texas). Sobrescribe p_cc si se usan ambos. Lista de estados admitidos.	cadena
p_city	Geolocalización de ciudad, en minúsculas, _ usa guiones bajos para los espacios (p. ej., new_york). p_cc / p_state requerido.	cadena
p_device	Establece huellas digitales del dispositivo, viewports y user-agents. Compatible con desktop (predeterminado) y mobile.	cadena
solve_captcha	Resolución automática de CAPTCHA en tiempo real al cargar páginas. Por defecto: false.	booleano
record	Graba el video de la sesión de Headless Browser. Por defecto: false.	booleano
record_name	Nombra la grabación para facilitar su búsqueda (^[a-zA-Z0-9_-]{1,64}$).	cadena
session_name	Sesiones persistentes – se reconecta al mismo navegador remoto en vivo (^[A-Za-z0-9-]{3,36}$, admite guiones, no guiones bajos). TTL máx. – 24h.	cadena
keep_alive	Mantiene la instancia remota del navegador activa cuando el cliente se desconecta al establecerse en true. Por defecto: false.	booleano
o_profile	Perfiles persistentes – guarda/restaura cookies y localStorage con un perfil con nombre (^[A-Za-z0-9_-]{1,36}$).	cadena
o_profile_save	Perfiles persistentes – fuerza el guardado del perfil durante o al final de la sesión. Por defecto: false.	booleano
proxy_resi_ses_id	ID de sesión personalizado para fijar la IP de salida residencial entre sesiones (^[A-Za-z0-9]{3,36}$).	cadena
proxy_resi_ses_time	Duración para mantener fijada la IP de salida del proxy residencial en minutos. Mín 1, máx. 1440 (24 h).	entero

Configuración recomendada

Optimización del tráfico

Al hacer scraping de páginas dinámicas, el navegador a menudo descarga recursos innecesarios como medios pesados, scripts de seguimiento, imágenes y fuentes. Esto consume ancho de banda y ralentiza los tiempos de ejecución.

Puedes interceptar y abortar estas solicitudes programáticamente antes de que consuman recursos:

Python (Playwrigth)

# Abort heavy assets to save bandwidth and improve speeds
def block_resources(route):
    if route.request.resource_type in ["image", "stylesheet", "media", "font"]:
        route.abort()
    else:
        route.continue_()

page.route("**/*", block_resources)

JavaScript (Playwright)

// Abort heavy assets to save bandwidth and improve speeds
await page.route("**/*", (route) => {
    const type = route.request().resourceType();
    if (["image", "stylesheet", "media", "font"].includes(type)) {
        return route.abort();
    }
    return route.continue();
});

Gestión de errores y reintentos

Las interrupciones de red y el límite de 10 sesiones por segundo hacen que una sola llamada connectOverCDP pueda fallar de forma transitoria. Envuelve la conexión en un reintento con backoff exponencial, y limita cada intento con un tiempo de espera. El ejemplo siguiente usa la API estándar de Playwright:

const { chromium } = require("playwright");

const MAX_RETRIES = 5;
const BASE_DELAY_MS = 1000;

async function connectWithRetry(endpoint, { maxRetries = MAX_RETRIES } = {}) {
    let lastError;
    for (let attempt = 0; attempt < maxRetries; attempt++) {
        try {
            // Cap how long a single connection attempt may take.
            return await chromium.connectOverCDP(endpoint, { timeout: 60_000 });
        } catch (err) {
            lastError = err;
            // Exponential backoff with jitter — backs off when you hit the
            // 10-new-sessions/second rate limit instead of hammering the endpoint.
            const delay = BASE_DELAY_MS * 2 ** attempt + Math.random() * 250;
            console.warn(
                `connect attempt ${attempt + 1} failed: ${err.message}; ` +
                `retrying in ${Math.round(delay)}ms`
            );
            await new Promise((resolve) => setTimeout(resolve, delay));
        }
    }
    throw lastError;
}

Limpieza de recursos

Cierra siempre el navegador cuando termines, incluso si tu automatización falla a mitad de camino. Usa un try { ... } finally { ... } bloque para que la limpieza se ejecute en todas las rutas:

const browser = await connectWithRetry(endpoint);
try {
    const ctx = browser.contexts()[0] || (await browser.newContext());
    const page = ctx.pages()[0] || (await ctx.newPage());
    await page.goto("https://ip.oxylabs.io/location");
    // ... your automation ...
} finally {
    // Runs even if the block above throws. Without this, a session left open
    // after an exception lingers and counts against your 100 concurrent-session limit.
    await browser.close();
}

Si ocurre una excepción entre connect y close y no haces la limpieza, la sesión remota permanece abierta y consume una de tus 100 sesiones concurrentes hasta que se recupere. Las sesiones filtradas bajo carga pueden agotar el límite y bloquear nuevas conexiones.

¿Necesitas activar una función?

Algunas funciones de Agent Browser están limitadas de forma predeterminada. Para ajustar tus límites, contacta con el soporte de Oxylabs (chat en vivo o correo electrónico) o tu gestor de cuenta dedicado:

• Más perfiles persistentes – aumenta el límite predeterminado de tu cuenta de 5 perfiles guardados.
• Más sesiones persistentes – aumenta el límite predeterminado de tu cuenta de 5 sesiones persistentes concurrentes.
• Objetivos restringidos – desbloquea más categorías de objetivos mediante el proceso KYC.
• Límites de tasa más altos – aumenta por encima de 100 sesiones concurrentes / 10 por segundo.