Pular para o conteúdo
Browsa
  1. Guias
  2. Playwright e Puppeteer

Conecte Playwright ou Puppeteer a um navegador na nuvem via CDP.

Um navegador na nuvem via CDP é um navegador real que roda no servidor de outra pessoa e fala o Chrome DevTools Protocol, então seu código Playwright ou Puppeteer o controla do mesmo jeito que controla um navegador local. Na Browsa, uma chamada de API inicia o navegador e retorna o endereço CDP; você muda a linha que abre o navegador e mantém o resto do script.

Tempo
Cerca de 5 minutos
Custo
1 crédito a cada 12 minutos iniciados de navegador, 5 por uma hora inteira
Funciona com
Playwright (Python, Node), Puppeteer, qualquer cliente CDP

Como rodar Playwright na nuvem?

  1. Inicie um navegador. POST /v1/agents (ou create_agent() no SDK) inicia um navegador Phantom na nuvem da Browsa e retorna o id, o endereço cdp_http e uma live_url que você pode abrir para acompanhar.
  2. Conecte. Troque chromium.launch() por chromium.connect_over_cdp(cdp_http, headers={"X-API-Key": API_KEY}), ou puppeteer.launch() por puppeteer.connect({ browserURL, headers }). O navegador já tem um contexto e uma página aberta: use-os.
  3. Encerre. Chame destroy_agent() quando terminar, ou deixe o navegador desligar quando o TTL acabar. Você paga 1 crédito a cada 12 minutos iniciados de execução; o restante do que ele reservou volta para você.

Você precisa de uma chave de API da Browsa (ela começa com agt_live_). Crie sua conta e ganhe 100 créditos grátis assim que confirmar seu e-mail, sem cartão. Não é preciso instalar o Chrome na sua máquina nem na sua imagem Docker.

Conecte seu cliente

Playwright em Python

Terminal
pip install browsa playwright

Você não precisa de playwright install: o navegador roda na Browsa.

cloud_playwright.py
import os

from browsa import Client
from playwright.sync_api import sync_playwright

API_KEY = os.environ["BROWSA_API_KEY"]
client = Client(api_key=API_KEY)
agent = client.create_agent(ttl="10m")  # a cloud browser, up to 10 minutes

try:
    with sync_playwright() as p:
        browser = p.chromium.connect_over_cdp(
            agent["cdp_http"], headers={"X-API-Key": API_KEY}
        )
        context = browser.contexts[0]
        page = context.pages[0] if context.pages else context.new_page()
        page.goto("https://example.com")
        print(page.title())
        # the rest is plain Playwright
finally:
    client.destroy_agent(agent["id"])

Playwright em TypeScript ou Node

Terminal
npm i browsa playwright
cloud-playwright.ts
import { Client } from "browsa";
import { chromium } from "playwright";

const apiKey = process.env.BROWSA_API_KEY!;
const client = new Client({ apiKey });
const agent = await client.createAgent({ ttl: "10m" });

try {
  const browser = await chromium.connectOverCDP(agent.cdp_http, {
    headers: { "X-API-Key": apiKey },
  });
  const context = browser.contexts()[0];
  const page = context.pages()[0] ?? (await context.newPage());
  await page.goto("https://example.com");
  console.log(await page.title());
} finally {
  await client.destroyAgent(agent.id);
}

Puppeteer

Use puppeteer-core. Ele tem a mesma API do puppeteer, mas não baixa um navegador, que você não precisa mais.

Terminal
npm i browsa puppeteer-core
cloud-puppeteer.ts
import { Client } from "browsa";
import puppeteer from "puppeteer-core";

const apiKey = process.env.BROWSA_API_KEY!;
const client = new Client({ apiKey });
const agent = await client.createAgent({ ttl: "5m" });

try {
  const browser = await puppeteer.connect({
    browserURL: agent.cdp_http,
    headers: { "X-API-Key": apiKey },
  });
  const [page] = await browser.pages();
  await page.goto("https://example.com");
  console.log(await page.title());
  await browser.disconnect();
} finally {
  await client.destroyAgent(agent.id);
}

CDP puro e outros clientes

A resposta de criação traz dois endereços. cdp_http é o endpoint HTTP do navegador, o que o Playwright e o Puppeteer esperam. cdp_url é o WebSocket de uma única página, para clientes que falam CDP diretamente. Os dois exigem sua chave no header X-API-Key. Qualquer biblioteca que consiga se conectar a um navegador existente via CDP com um header personalizado pode usar o mesmo endereço; é assim que funcionam os guias de browser-use e Stagehand.

Sem o SDK, inicie o navegador com HTTP puro:

curl
curl https://browsa.io/v1/agents \
  -H "X-API-Key: $BROWSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttl": "10m", "initial_url": "https://example.com"}'

# -> { "id": "agt_…", "status": "running", "cdp_http": "https://browsa.io/api/v1/cdp/…",
#      "cdp_url": "wss://browsa.io/api/v1/cdp/…/ws/page/…", "live_url": "…", "cost_credits": 5 }

cost_credits é o que o navegador reserva enquanto roda: 1 crédito para um TTL de até 5 minutos, 5 para um maior. Quando ele termina, os blocos de 12 minutos não usados voltam para o seu saldo.

O que muda em relação a um navegador local?

Viewport e user agent

Tamanho da tela, user agent, fuso horário, idioma, geolocalização e número de CPUs são definidos juntos quando o navegador inicia. Comandos de emulação do CDP que mudam só um deles retornam sucesso e não mudam nada, então page.set_viewport_size(), page.setViewport() e page.setUserAgent() não têm efeito.

O que fazerPasse screen_resolution e os_type para POST /v1/agents. Para controlar a emulação você mesmo, adicione cdp_overrides=allow à query do endereço CDP; manter o fingerprint consistente passa a ser responsabilidade sua.

Contextos e páginas

O navegador inicia com um contexto e uma página aberta.

O que fazerUse browser.contexts[0] e a primeira página dele em vez de criar um novo contexto.

Downloads de arquivos

Os arquivos baixados ficam no navegador na nuvem, e o evento de download do Playwright informa canceled.

O que fazerBusque o arquivo de dentro da página (veja abaixo), o que usa os cookies e o endereço IP do navegador.

Tempo de vida

Um navegador roda até o TTL acabar, no máximo 1 hora, ou até você destruí-lo. Ele não encerra por inatividade.

O que fazerPeça o TTL de que precisa ("5m" a "1h"). Inicie um novo navegador para jobs mais longos, ou use uma identidade salva para manter os logins entre eles.

Rede

Sem proxy, o tráfego sai do data center da Browsa com um endereço IP de data center.

O que fazerPasse uma rede da Browsa em proxy ({"network": "residential"}), seu próprio proxy HTTP, HTTPS ou SOCKS5, ou um proxy salvo em proxy_id.

Sinais de automação

Playwright e Puppeteer ativam o domínio Runtime do CDP ao se conectar, e algumas verificações anti-bot conseguem detectar isso.

O que fazerSe um site sinalizar seu cliente, tente um cliente CDP puro sem Runtime.enable, ou o próprio agente de tarefas da Browsa (POST /v1/tasks). Veja os resultados com data na página de benchmarks.

Navegadores em paralelo

6 vagas de navegador por workspace. Uma requisição com todas as vagas ocupadas retorna 429 com Retry-After: 30 e não é cobrada.

O que fazerEnfileire o trabalho do seu lado, ou envie um e-mail para support@browsa.io pedindo mais vagas.

Como reconectar depois que a conexão cai?

Fechar a conexão do Playwright ou do Puppeteer não para o navegador. Ele continua rodando até o TTL acabar, então outro processo pode se conectar a ele. Pegue o endereço de novo com GET /v1/agents/{id}/cdp (ou get_agent(agent_id) em Python, getAgent(agentId) em TypeScript) e conecte com o mesmo header X-API-Key. O endpoint retorna 409 quando o navegador não está mais rodando.

Como baixar um arquivo?

Busque o arquivo de dentro da página e retorne os bytes:

Python
import base64

b64 = page.evaluate("""async (url) => {
  const buf = new Uint8Array(await (await fetch(url)).arrayBuffer());
  let s = ""; for (const b of buf) s += String.fromCharCode(b);
  return btoa(s);
}""", "https://example.com/report.pdf")
open("report.pdf", "wb").write(base64.b64decode(b64))

Como usar meu próprio proxy?

Adicione um objeto proxy ao iniciar o navegador. O navegador passa a usar o endereço IP do proxy e, com country definido, o fuso horário e o idioma acompanham esse país. O tráfego via proxy não tem custo extra na Browsa.

curl
curl https://browsa.io/v1/agents \
  -H "X-API-Key: $BROWSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ttl": "10m",
    "proxy": {"type": "http", "host": "proxy.example.com", "port": 8080,
              "username": "your-proxy-user", "password": "your-proxy-password"},
    "country": "de"
  }'

Um navegador puro inicia mesmo se o proxy estiver inacessível, então teste o proxy antes. Um proxy salvo tem um endpoint de verificação e pode ser passado como proxy_id.

Como manter os logins entre execuções?

Use uma identidade persistente em vez de um navegador descartável. Ela mantém cookies, local storage e fingerprint entre sessões. Crie uma vez com "mode": "persistent" e abra uma sessão sempre que um script precisar: POST /v1/agents/{id}/sessions retorna o mesmo formato de um navegador novo, incluindo cdp_http, e você se conecta exatamente como acima. Uma identidade custa 50 créditos a cada 30 dias e cada sessão custa 1 crédito. Veja Abrir uma sessão.

Quanto custa?

O que você rodaCréditos
Navegador que roda até 12 minutos1
Navegador que roda uma hora inteira5
Identidade persistente, a cada 30 dias50
Sessão em uma identidade persistente (até 1 hora)1
Navegador que não consegue iniciarReembolsado

Um crédito custa $0.10 no pacote Starter de $20, e menos nos pacotes maiores. Os créditos não expiram. Preços completos.

Solução de problemas

401 Unauthorized ao conectar

O header X-API-Key não chegou à Browsa, ou a chave está errada. Envie o header na chamada de conexão exatamente como nos exemplos e confira se a chave começa com agt_.

402 ao iniciar um navegador

INSUFFICIENT_CREDIT significa que o saldo não cobre o TTL pedido; BUDGET_REACHED significa que seu limite mensal de gastos foi atingido. Consulte GET /v1/credits e GET /v1/budget.

A conexão cai depois de alguns minutos

O navegador chegou ao fim do TTL. Peça um TTL maior, de até "1h".

Perguntas

Por que set_viewport_size() não muda o navegador?

Tamanho da tela, user agent, fuso horário, idioma e geolocalização de um navegador da Browsa são definidos juntos quando ele é criado, para que a página encontre uma máquina consistente. Comandos de emulação do CDP que mudariam só um deles retornam sucesso e não mudam nada. Defina screen_resolution e os_type ao criar o navegador, ou adicione cdp_overrides=allow ao endereço CDP se quiser controlar a emulação você mesmo.

Como baixar um arquivo de um navegador na nuvem?

Os arquivos que uma página baixa ficam no navegador na nuvem, e o Playwright informa o download como cancelado. Busque o arquivo de dentro da página com page.evaluate(), que usa os cookies e o endereço IP do navegador, e retorne os bytes em base64.

Quantos navegadores podem rodar ao mesmo tempo?

Um workspace tem 6 vagas de navegador. Cada navegador em execução ocupa uma, assim como cada identidade salva. Um novo navegador com todas as vagas ocupadas retorna 429 TOO_MANY_REQUESTS com Retry-After: 30, e nada é cobrado. Envie um e-mail para support@browsa.io se precisar de mais.

A Browsa fornece proxies?

Sim. Data center a 5 créditos por GB, residencial a 50 créditos por GB. Ou passe seu próprio proxy HTTP, HTTPS ou SOCKS5 por navegador, grátis. Sem proxy, o navegador usa o endereço IP do data center da Browsa.

Próximos passos

Rode seu script em um navegador na nuvem.

100 créditos grátis. Sem cartão, sem assinatura.