> 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 navegador headless baseado em nuvem com segurança adaptativa integrada, gerenciamento de CAPTCHA e Residential Proxies. Teste-o com exemplos de código e personalize com recursos avançados.

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

## Bibliotecas compatíveis

Agent Browser funciona com qualquer biblioteca que ofereça suporte ao **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). Veja [Integração com CDP](https://developers.oxylabs.io/products/pt-br/agent-browser/integracao-cdp.md).
* Outros frameworks de automação compatíveis com CDP

## Detalhes de conexão

<table><thead><tr><th width="161">Campo</th><th>Descrição</th></tr></thead><tbody><tr><td><strong>Protocolo</strong></td><td><code>wss://</code> (WebSocket seguro)</td></tr><tr><td><strong>Host (Chromium)</strong></td><td><code>hb.oxylabs.io</code></td></tr><tr><td><strong>Autenticação</strong></td><td>Na URL, as informações do usuário – <code>wss://USERNAME:PASSWORD@host</code>. Deve incluir o token sufixo do nome de usuário (ex.: <code>user_ab12</code>). Criar <code>Autorização</code> cabeçalhos personalizados não é recomendado.</td></tr><tr><td><strong>Transporte</strong></td><td>CDP – <code>chromium.connectOverCDP</code> (Playwright) / <code>puppeteer.connect</code> (Puppeteer).</td></tr><tr><td><strong>Domínio</strong></td><td><code>oxylabs.io</code> – usado para endpoints de conexão (ex.: <a href="http://hb.oxylabs.io">hb.oxylabs.io</a>), o Dashboard (<a href="http://hb.oxylabs.io/dashboard">hb.oxylabs.io/dashboard</a>), e inspeção de sessão (<a href="http://hb.oxylabs.io/novnc">hb.oxylabs.io/novnc</a>).</td></tr><tr><td><strong>Limites de taxa</strong></td><td><code>100</code> sessões simultâneas, <code>10</code> sessão por segundo. <a href="#need-a-feature-enabled-1">Veja mais</a>.</td></tr></tbody></table>

## Recursos

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

<table data-header-hidden><thead><tr><th width="250"></th><th></th></tr></thead><tbody><tr><td><a href="https://developers.oxylabs.io/products/pt-br/agent-browser/tratamento-de-paginas.md"><strong>Gerenciador de páginas</strong></a></td><td>Identifique cada página, trate os desafios suportados e acompanhe o estado da página (padrão – desativado).</td></tr><tr><td><a href="https://developers.oxylabs.io/products/pt-br/agent-browser/captcha-handling.md"><strong>Tratamento de CAPTCHA</strong></a></td><td>Identifique páginas e trate desafios de acesso automaticamente (padrão – desativado).</td></tr><tr><td><a href="https://developers.oxylabs.io/products/pt-br/agent-browser/engine-e-fingerprints.md"><strong>Engine e fingerprints</strong></a></td><td>Selecione o motor do navegador e os perfis de fingerprint.</td></tr><tr><td><a href="https://developers.oxylabs.io/products/pt-br/agent-browser/geolocation-and-proxy-selection.md"><strong>Proxy e segmentação geográfica</strong></a></td><td>Roteie as sessões por países, estados ou cidades específicos.</td></tr><tr><td><a href="https://developers.oxylabs.io/products/pt-br/agent-browser/device-type.md"><strong>Emulação de dispositivo</strong></a></td><td>Emule fingerprints e viewports específicos do dispositivo.</td></tr><tr><td><a href="https://developers.oxylabs.io/products/pt-br/agent-browser/session-inspection-and-recording.md#session-inspection-vnc"><strong>Inspeção de sessão (VNC)</strong></a></td><td>Monitore sessões ativas de navegador headless.</td></tr><tr><td><a href="https://developers.oxylabs.io/products/pt-br/agent-browser/session-inspection-and-recording.md#session-recording"><strong>Gravação de sessão</strong></a></td><td>Grave sessões do navegador em formato de vídeo.</td></tr><tr><td><a href="https://developers.oxylabs.io/products/pt-br/agent-browser/persistent-sessions-and-profiles.md#persistent-sessions"><strong>Sessões Persistentes</strong></a></td><td>Crie e gerencie instâncias sticky do navegador.</td></tr><tr><td><a href="https://developers.oxylabs.io/products/pt-br/agent-browser/persistent-sessions-and-profiles.md#persistent-profiles"><strong>Perfis Persistentes</strong></a></td><td>Salve e restaure cookies/localStorage entre sessões.</td></tr></tbody></table>

{% hint style="success" %}
**Usando um assistente de codificação com IA?** Configurar [Habilidades do agente](https://developers.oxylabs.io/ai-workflows/pt-br/habilidades-de-agente.md) ou o [servidor MCP](https://developers.oxylabs.io/ai-workflows/pt-br/mcp.md).
{% endhint %}

### Passando parâmetros

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

```bash
# Exemplo: Conectando ao Chrome com geolocalização nos EUA e tratamento de CAPTCHA ativado
wss://USER:PASS@hb.oxylabs.io?p_cc=US&solve_captcha=true
```

## Integrações

<table data-header-hidden><thead><tr><th width="154.5"></th><th></th></tr></thead><tbody><tr><td><a href="https://developers.oxylabs.io/products/pt-br/agent-browser/integracao-cdp.md"><strong>Integração com CDP</strong></a></td><td>Conecte Stagehand e browser-use para habilitar a inspeção de sessão ao vivo.</td></tr><tr><td><a href="https://developers.oxylabs.io/ai-workflows/pt-br/habilidades-de-agente.md"><strong>Habilidades do agente</strong></a></td><td>Configure o Agent Browser no Claude Code, Cursor e em outros assistentes de codificação com IA.</td></tr><tr><td><a href="https://developers.oxylabs.io/ai-workflows/pt-br/mcp.md"><strong>Servidor MCP</strong></a></td><td>Forneça aos assistentes de IA compatíveis com MCP um Agent Browser remoto.</td></tr></tbody></table>

## Exemplos de código

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

{% tabs %}
{% tab title="Python (Playwright)" %}

```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 (ex.: `process.env.OXYLABS_USERNAME` / `process.env.OXYLABS_PASSWORD`) via um `.env` arquivo.
{% endhint %}

{% hint style="warning" %}
**JavaScript:** Use `NODE_TLS_REJECT_UNAUTHORIZED="0"` Defina a flag antes de importar o Playwright no Node.js se você encontrar erros de TLS/certificado. Apenas para testes locais. Em produção, restrinja a confiança à conexão específica ou adicione o certificado CA do provedor ao seu repositório de confiança em vez disso.
{% endhint %}

## Referência de parâmetros <a href="#need-a-feature-enabled" id="need-a-feature-enabled"></a>

<table><thead><tr><th width="184">Parâmetro</th><th width="467">Descrição</th><th>Tipo</th></tr></thead><tbody><tr><td><code>p_cc</code></td><td>Geolocalização por país em <code>ISO 3166-1 alpha-2</code> código de 2 letras (ex.: <code>US</code>, <code>DE</code>).</td><td>cadeia de caracteres</td></tr><tr><td><code>p_state</code></td><td>Geolocalização por estado em minúsculas (ex.: <code>texas</code>). Substitui <code>p_cc</code> se ambos forem usados. <a href="https://content.gitbook.com/content/BQ7Zf9paoN3FTeGcyfY1/blobs/cVjpiu1GKicluiVIT9og/us_states.txt">Lista de estados suportados</a>.</td><td>cadeia de caracteres</td></tr><tr><td><code>p_city</code></td><td>Geolocalização por cidade, em minúsculas, <code>_</code> use <code>new_york</code>). <code>p_cc</code> / <code>p_state</code> é obrigatório.</td><td>cadeia de caracteres</td></tr><tr><td><code>p_device</code></td><td>Defina fingerprints de dispositivo, viewports e user-agents. Suporta <code>desktop</code> (padrão) e <code>pesquisa móvel</code>.</td><td>cadeia de caracteres</td></tr><tr><td><code>p_src</code></td><td>Motor do navegador. Suporta <code>oxybrowser</code> motor proprietário. Se omitido, o motor padrão é usado. Veja <a href="https://developers.oxylabs.io/products/pt-br/agent-browser/engine-e-fingerprints.md">Engine e fingerprints</a>.</td><td>cadeia de caracteres</td></tr><tr><td><code>p_fp_tag</code></td><td>Perfil de fingerprint: <code>oxyfp_win</code> (padrão), <code>oxyfp_mac</code>, <code>oxyfp_mac_optimized</code> (somente com <code>p_src=oxybrowser</code>), <code>oxyfp_win_v1</code> (legado). Veja <a href="https://developers.oxylabs.io/products/pt-br/agent-browser/engine-e-fingerprints.md">Engine e fingerprints</a>.</td><td>cadeia de caracteres</td></tr><tr><td><code>page_handler</code></td><td>Identifique páginas e trate desafios de acesso automaticamente. Padrão: <code>false</code>. Veja <a href="https://developers.oxylabs.io/products/pt-br/agent-browser/tratamento-de-paginas.md">Gerenciador de páginas</a>.</td><td>booleano</td></tr><tr><td><code>solve_captcha</code></td><td>Resolução automática de CAPTCHA em tempo real no carregamento de páginas. Padrão: <code>false</code>.</td><td>booleano</td></tr><tr><td><code>record</code></td><td>Grave vídeo da sessão headless. Padrão: <code>false</code>.</td><td>booleano</td></tr><tr><td><code>record_name</code></td><td>Nomeie a gravação para facilitar a busca (<code>^[a-zA-Z0-9_-]{1,64}$</code>).</td><td>cadeia de caracteres</td></tr><tr><td><code>session_name</code></td><td>Sticky sessions. Reconecta ao mesmo navegador remoto ao vivo (<code>^[A-Za-z0-9-]{3,36}$</code>, suporta hífens, sem sublinhados). TTL máximo – 24h.</td><td>cadeia de caracteres</td></tr><tr><td><code>keep_alive</code></td><td>Mantém a instância remota do navegador ativa ao ocorrer desconexão do cliente quando definido como <code>true</code>. Requer <code>session_name</code>. Padrão: <code>false</code>.</td><td>booleano</td></tr><tr><td><code>o_profile</code></td><td>Perfis persistentes – salve/restaure cookies e <code>localStorage</code> com um perfil nomeado (<code>^[a-zA-Z0-9][a-zA-Z0-9_-]{2,35}$</code>).</td><td>cadeia de caracteres</td></tr><tr><td><code>o_profile_save</code></td><td>Perfis persistentes – força o salvamento do perfil durante ou ao final da sessão. Requer <code>o_profile</code>. Padrão: <code>false</code>.</td><td>booleano</td></tr><tr><td><code>proxy_resi_ses_id</code></td><td>ID de sessão personalizado para fixar o IP de saída residencial entre sessões (<code>^[A-Za-z0-9]{3,36}$</code>).</td><td>cadeia de caracteres</td></tr><tr><td><code>proxy_resi_ses_time</code></td><td>Duração, em minutos, para manter fixo o IP de saída do proxy residencial. Mín <code>1</code>, máx. <code>1440</code> (24h).</td><td>inteiro</td></tr></tbody></table>

## Configuração recomendada

### Otimizando o tráfego

Fazer scraping de páginas dinâmicas muitas vezes faz o navegador baixar recursos desnecessários, como mídia pesada, scripts de rastreamento, imagens e fontes. Isso consome largura de banda e desacelera os tempos de execução.

Você pode interceptar e cancelar essas solicitações programaticamente 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 Page Handler, não bloqueie folhas de estilo, imagens, mídia ou fontes para o alvo. Bloqueá-las pode impedir que um widget de desafio seja carregado.
{% endhint %}

### Tratamento de erros e novas tentativas <a href="#error-handling-and-retries" id="error-handling-and-retries"></a>

Falhas momentâneas de rede e o limite de 10 sessões por segundo significam que uma única `connectOverCDP` chamada pode falhar de forma transitória. Envolva a conexão em uma `nova tentativa` com backoff exponencial `backoff`, e limite cada tentativa com um timeout. 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, veja [Códigos de Resposta](https://developers.oxylabs.io/products/pt-br/agent-browser/codigos-de-resposta.md).
{% endhint %}

### Limpeza de recursos <a href="#resource-cleanup" id="resource-cleanup"></a>

Sempre feche o navegador quando terminar, mesmo que sua automação lance uma exceção no meio do caminho. 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 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 liberada. Vazamento de sessões sob carga pode esgotar o limite e bloquear novas conexões.

## Precisa ativar um recurso? <a href="#need-a-feature-enabled" id="need-a-feature-enabled"></a>

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/) or [e-mail](mailto:support@oxylabs.io)) ou com seu Gerente de Conta Dedicado:

* **Mais perfis persistentes** – aumente o limite padrão da sua conta para 5 perfis salvos.
* **Mais sessões persistentes** – aumente o limite padrão da sua conta para 5 sessões persistentes simultâneas.
* **Alvos restritos** – desbloqueie mais categorias de destino por meio do processo de KYC.
* **Limites de taxa mais altos** – aumente para 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=<question>&goal=<user_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.
