Agent Browser

Um Headless Browser baseado na nuvem com segurança adaptativa integrada, gerenciamento de CAPTCHA e Residential Proxies. Teste-o com exemplos de código e personalize-o com recursos avançados.

Agent Browser permite executar e controlar instâncias remotas para automação baseada em navegador, testes e web scraping sem gerenciá-las localmente. Ele oferece segurança adaptativa integrada, tratamento automático de CAPTCHA, geotargeting, proxies residenciais integrados, gravação de sessão, sessões fixas e perfis persistentes.

Bibliotecas compatíveis

Agent Browser funciona com qualquer biblioteca que suporte o Chrome DevTools Protocol (CDP), incluindo:

• Playwright (Python e Node.js)
• Puppeteer (Node.js)
• Outros frameworks de automação compatíveis com CDP

Detalhes da conexão

Atenção: Agent Browser está migrando para uma nova infraestrutura. Atualize sua string de conexão de ubc.oxylabs.io para hb.oxylabs.io antes de 1º de outubro. A partir de 1º de outubro, o tráfego enviado ao domínio antigo será automaticamente roteado para o novo.

O Dashboard e as ferramentas de inspeção de sessão também foram movidos de headlesify.io para hb.oxylabs.io. Veja a Inspeção e gravação de sessão para detalhes.

Campo	Descrição
Protocolo	wss:// (WebSocket Secure)
Host (Chromium)	hb.oxylabs.io
Autenticação	Na URL, informações do usuário – wss://USERNAME:PASSWORD@host. Deve incluir o token de sufixo do nome de usuário (ex.: user_ab12). Autenticação baseada em cabeçalho não suportada.
Transporte	CDP – chromium.connectOverCDP (Playwright) / puppeteer.connect (Puppeteer).
Domínio	oxylabs.io – usado para endpoints de conexão (ex.: hb.oxylabs.io), o Dashboard (hb.oxylabs.io/dashboard), e a inspeção de sessão (hb.oxylabs.io/novnc).
Limites de taxa	100 sessões simultâneas, 10 sessão por segundo. Veja mais.

Recursos

O Oxylabs Agent Browser inclui recursos integrados e nativos da nuvem, projetados para serem usados por meio de parâmetros de consulta na URL da sua conexão WebSocket.

Tratamento de CAPTCHA	Tratamento e monitoramento automático de CAPTCHA em tempo real (padrão – desativado).
Direcionamento de proxy e geolocalização	Roteie sessões por países, estados ou cidades específicos.
Emulação de dispositivo	Emule fingerprints e viewports específicos do dispositivo.
Inspeção de sessão (VNC)	Monitore sessões ao vivo de navegador headless.
Gravação de sessão	Grave sessões do navegador em formato de vídeo.
Sessões Persistentes	Crie e gerencie instâncias persistentes de navegador.
Perfis Persistentes	Salve e restaure cookies/localStorage entre sessões.

Passando parâmetros

Todos os recursos são ativados e configurados acrescentando parâmetros de consulta diretamente ao seu endpoint WebSocket Secure, encadeando vários recursos usando e comerciais (&).

# Exemplo: Conectando ao Chrome com geolocalização nos EUA e tratamento de CAPTCHA ativados
wss://USER:[e-mail]?p_cc=US&solve_captcha=true

Exemplos de código

Abaixo estão exemplos básicos para inicializar uma sessão de navegador hospedado na nuvem:

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();
})();

Observação: Os exemplos usam USERNAME e PASSWORD apenas para facilitar a leitura. Em projetos reais, carregue-os de variáveis de ambiente (por exemplo, process.env.OXYLABS_USERNAME / process.env.OXYLABS_PASSWORD) por meio de um .env arquivo.

JavaScript: Use NODE_TLS_REJECT_UNAUTHORIZED="0" a flag before requiring Playwright in Node.js if you encounter TLS/certificate errors. For local testing only. In production, scope trust to the specific connection or add the provider’s CA certificate to your trust store instead.

Referência de parâmetros

Parâmetro	Descrição	Tipo
p_cc	Geolocalização do país em ISO 3166-1 alpha-2 código de 2 letras (ex.: US, DE).	cadeia de caracteres
p_state	Geolocalização do estado em minúsculas (ex.: texas). Substitui p_cc se ambos forem usados. Lista de estados compatíveis.	cadeia de caracteres
p_city	Geolocalização da cidade, em minúsculas, _ para espaços (ex.: new_york). p_cc / p_state ), obrigatório.	cadeia de caracteres
p_device	Defina fingerprints de dispositivo, viewports e user-agents. Suporta desktop (padrão) e mobile.	cadeia de caracteres
solve_captcha	Resolução automática de CAPTCHA em tempo real ao carregar páginas. Padrão: false.	booleano
record	Grave o vídeo da sessão headless. Padrão: false.	booleano
record_name	Nomeie a gravação para fácil busca (^[a-zA-Z0-9_-]{1,64}$).	cadeia de caracteres
session_name	Sessões fixas – reconecta ao mesmo navegador remoto ativo (^[A-Za-z0-9-]{3,36}$, suporta hífens, sem sublinhados). TTL máx. – 24h.	cadeia de caracteres
keep_alive	Mantém a instância remota do navegador ativa quando a desconexão do cliente é definida para true. Padrão: false.	booleano
o_profile	Perfis persistentes – salve/restaure cookies e localStorage com um perfil nomeado (^[A-Za-z0-9_-]{1,36}$).	cadeia de caracteres
o_profile_save	Perfis persistentes – force o salvamento do perfil durante ou ao final da sessão. Padrão: false.	booleano
proxy_resi_ses_id	ID de sessão personalizado para fixar o IP de saída residencial entre sessões (^[A-Za-z0-9]{3,36}$).	cadeia de caracteres
proxy_resi_ses_time	Duração para manter o IP de saída do proxy residencial fixado, em minutos. Mín 1, máx 1440 (24h).	inteiro

Configuração recomendada

Otimizando o tráfego

O scraping de páginas dinâmicas frequentemente faz o navegador baixar ativos desnecessários, como mídia pesada, scripts de rastreamento, imagens e fontes. Isso consome largura de banda e reduz o tempo de execução.

Você pode interceptar e abortar essas solicitações programaticamente antes que consumam recursos:

Python (Playwright)

# 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();
});

Tratamento de erros e novas tentativas

Falhas momentâneas de rede e o limite de 10 sessões por segundo significam que uma única chamada connectOverCDP pode falhar de forma transitória. Envolva a conexão em uma nova tentativa com backoff exponencial, e limite cada tentativa com um timeout. O exemplo abaixo usa a API padrão do 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;
}

Limpeza de recursos

Sempre feche o navegador quando terminar, mesmo que sua automação lance uma exceção no meio do processo. Use um try { ... } finally { ... } bloco para que a limpeza seja executada em todos os caminhos:

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");
    // ... sua automação ...
} finally {
    // Executa mesmo se o bloco acima lançar. Sem isso, uma sessão deixada aberta
    // após uma exceção permanece ativa e conta contra seu limite de 100 sessões simultâneas.
    await browser.close();
}

Se ocorrer uma exceção entre connect e close e você não fizer a limpeza, a sessão remota permanece aberta e consome uma das suas 100 sessões simultâneas até ser recuperada. Vazamentos de sessões sob carga podem esgotar o limite e bloquear novas conexões.

Precisa habilitar um recurso?

Alguns recursos do Agent Browser são limitados por padrão. Para ajustar seus limites, entre em contato com o suporte da Oxylabs (chat ao vivo ou e-mail) ou seu Gerente de Conta Dedicado:

• Mais perfis persistentes – aumente o limite padrão da sua conta de 5 perfis salvos.
• Mais sessões persistentes – aumente o limite padrão da sua conta de 5 sessões persistentes simultâneas.
• Alvos restritos – desbloqueie mais categorias de alvos via processo KYC.
• Limites de taxa mais altos – aumente para além de 100 sessões simultâneas / 10 por segundo.