> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/pt-br/agent-browser.md). # 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. O 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, direcionamento geográfico, proxies residenciais integrados, gravação de sessões, sessões persistentes e perfis persistentes. ## Bibliotecas compatíveis O Agent Browser funciona com qualquer biblioteca compatível com o **Chrome DevTools Protocol (CDP)**, incluindo: * [Playwright](https://playwright.dev/) (Python e Node.js) * [Puppeteer](https://pptr.dev/) (Node.js) * Frameworks de agentes de IA, como [Stagehand](https://github.com/browserbase/stagehand) e [browser-use](https://github.com/browser-use/browser-use). Consulte [Integração com CDP](/products/pt-br/agent-browser/integracao-com-cdp.md). * Outros frameworks de automação compatíveis com CDP ## Detalhes da conexão
CampoDescrição
Protocolowss:// (WebSocket Secure)
Host (Chromium)hb.oxylabs.io
AutenticaçãoNa URL, informações do usuário – wss://USERNAME:PASSWORD@host. Deve incluir o token de sufixo do nome de usuário (por exemplo, user_ab12). Criar cabeçalhos Authorization personalizados não é recomendado.
TransporteCDP – chromium.connectOverCDP (Playwright) / puppeteer.connect (Puppeteer).
Domíniooxylabs.io – usado para endpoints de conexão (por exemplo, hb.oxylabs.io), o Dashboard (hb.oxylabs.io/dashboard), e inspeção de sessão (hb.oxylabs.io/novnc).
Limites de taxa100 sessões simultâneas, 10 sessão por segundo. Ver 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 de conexão WebSocket.
Manipulador de páginasIdentifique todas as páginas, trate desafios compatíveis e rastreie o estado da página (padrão – desativado).
Tratamento de CAPTCHAIdentifique páginas e trate desafios de acesso automaticamente (padrão – desativado).
Mecanismo e fingerprintsSelecione o mecanismo do navegador e os perfis de impressão digital.
Proxy e direcionamento geográficoEncaminhe sessões por países, estados ou cidades específicos.
Emulação de dispositivoEmule impressões digitais e viewports específicos de dispositivos.
Inspeção de sessão (VNC)Monitore sessões ativas de navegador headless.
Gravação de sessãoGrave sessões do navegador em formato de vídeo.
Sessões persistentesCrie e gerencie instâncias persistentes de navegador.
Perfis persistentesSalve e restaure cookies/localStorage entre sessões.
{% hint style="success" %} **Usando um assistente de programação com IA?** Configure [Agent Skills](/ai-workflows/agent-skills.md) ou o [servidor MCP](/ai-workflows/mcp.md). {% endhint %} ### Passagem de parâmetros Todos os recursos são ativados e configurados adicionando parâmetros de consulta diretamente ao seu endpoint WebSocket Secure, encadeando vários recursos com e comercial (`&`). ```bash # Exemplo: conexão ao Chrome com geolocalização dos EUA e tratamento de CAPTCHA ativados wss://USER:PASS@hb.oxylabs.io?p_cc=US&solve_captcha=true ``` ## Integrações
Integração com CDPConecte o Stagehand e o browser-use para abrir a inspeção de sessão ao vivo.
Agent SkillsConfigure o Agent Browser no Claude Code, Cursor e outros assistentes de programação com IA.
Servidor MCPForneça um Agent Browser remoto a assistentes de IA compatíveis com MCP.
## Exemplos de código Abaixo estão exemplos básicos para inicializar uma sessão de navegador hospedada na nuvem: {% tabs %} {% tab title="Python (Playwrigth)" %} ```python 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() ``` {% endtab %} {% tab title="JavaScript (Playwright)" %} ```javascript 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(); })(); ``` {% endtab %} {% tab title="JavaScript (Puppeteer)" %} ```javascript 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(); })(); ``` {% endtab %} {% endtabs %} {% hint style="info" %} **Observação:** Os exemplos usam `USERNAME` e `PASSWORD` apenas para legibilidade. Em projetos reais, carregue-os de variáveis de ambiente (por exemplo, `process.env.OXYLABS_USERNAME` / `process.env.OXYLABS_PASSWORD`) por meio de um arquivo `.env` . {% endhint %} {% hint style="warning" %} **JavaScript:** Use a `NODE_TLS_REJECT_UNAUTHORIZED="0"` flag antes de importar o Playwright no Node.js se encontrar erros de TLS/certificado. Somente para testes locais. Em produção, limite a confiança à conexão específica ou adicione o certificado de CA do provedor ao seu armazenamento de confiança. {% endhint %} ## Referência de parâmetros
ParâmetroDescriçãoTipo
p_ccGeolocalização do país em ISO 3166-1 alpha-2 código de 2 letras (por exemplo, US, DE).string
p_stateGeolocalização do estado em minúsculas (por exemplo, texas). Substitui p_cc se ambos forem usados. Lista de estados compatíveis.string
p_cityGeolocalização da cidade, em minúsculas, _ para espaços (por exemplo, new_york). p_cc / p_state obrigatório.string
p_deviceDefina impressões digitais de dispositivos, viewports e user-agents. Compatível com desktop (padrão) e mobile.string
p_srcMecanismo do navegador. Compatível com oxybrowser mecanismo proprietário. Se omitido, o mecanismo padrão será usado. Consulte Mecanismo e fingerprints.string
p_fp_tagPerfil de impressão digital: oxyfp_win (padrão), oxyfp_mac, oxyfp_mac_optimized (somente com p_src=oxybrowser), oxyfp_win_v1 (legado). Consulte Mecanismo e fingerprints.string
page_handlerIdentifique páginas e trate desafios de acesso automaticamente. Padrão: false. Consulte Manipulador de páginas.booleano
solve_captchaResolução automática de CAPTCHA em tempo real nos carregamentos de página. Padrão: false.booleano
recordGrave o vídeo da sessão headless. Padrão: false.booleano
record_nameNomeie a gravação para facilitar a busca (^[a-zA-Z0-9_-]{1,64}$).string
session_nameSessões persistentes. Reconecta ao mesmo navegador remoto ativo (^[A-Za-z0-9-]{3,36}$, aceita hífens, não aceita sublinhados). TTL máximo – 24 h.string
keep_aliveMantém a instância remota do navegador ativa quando o cliente se desconecta se definido como true. Requer session_name. Padrão: false.booleano
o_profilePerfis persistentes – salve/restaure cookies e localStorage com um perfil nomeado (^[a-zA-Z0-9][a-zA-Z0-9_-]{2,35}$).string
o_profile_savePerfis persistentes – force o salvamento do perfil durante ou ao final da sessão. Requer o_profile. Padrão: false.booleano
proxy_resi_ses_idID de sessão personalizado para fixar o IP de saída residencial entre sessões (^[A-Za-z0-9]{3,36}$).string
proxy_resi_ses_timeDuração, em minutos, para manter o IP de saída do proxy residencial fixado. Mín. 1, máx. 1440 (24 h).inteiro
## Configuração recomendada ### Otimização do tráfego A extração de páginas dinâmicas frequentemente faz o navegador baixar recursos desnecessários, como mídia pesada, scripts de rastreamento, imagens e fontes. Isso consome largura de banda e torna os tempos de execução mais lentos. Você pode interceptar e abortar programaticamente essas solicitações antes que consumam recursos: {% tabs %} {% tab title="Python (Playwright)" %} ```python # 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) ``` {% endtab %} {% tab title="JavaScript (Playwright)" %} ```javascript // 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(); }); ``` {% endtab %} {% endtabs %} {% hint style="warning" %} Se você usar o Manipulador de páginas, não bloqueie folhas de estilo, imagens, mídia ou fontes para o destino. Bloqueá-las pode impedir que um widget de desafio seja carregado. {% endhint %} ### Tratamento de erros e novas tentativas Instabilidades de rede e o limite de taxa de 10 sessões por segundo significam que uma única chamada `connectOverCDP` pode falhar temporariamente. Envolva a conexão em uma `nova tentativa` com `backoff exponencial`, e limite cada tentativa com um tempo limite. O exemplo abaixo usa a API padrão do Playwright. ```javascript 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; } ``` {% hint style="info" %} Para a lista completa de erros de handshake, fechamento de WebSocket e erros na página, consulte [Códigos de resposta](/products/pt-br/agent-browser/codigos-de-resposta.md). {% endhint %} ### Limpeza de recursos Sempre feche o navegador quando terminar, mesmo que sua automação gere uma exceção no meio da execução. Use um `try { ... } finally { ... }` bloco para que a limpeza seja executada em todos os caminhos: ```javascript 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(); } ``` Se ocorrer uma exceção entre a conexão e o fechamento e você não fizer a limpeza, a sessão remota permanecerá aberta e consumirá 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 de um recurso ativado? 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](https://oxylabs.io/) ou [e-mail](mailto:support@oxylabs.io)) 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. * **Destinos restritos** – desbloqueie mais categorias de destino por meio do processo de KYC. * **Limites de taxa mais altos** – aumente além de 100 sessões simultâneas / 10 por segundo. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://developers.oxylabs.io/products/pt-br/agent-browser.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.