Frameworks e o Playground
Notas para conectar frameworks específicos a um navegador hospedado e o Playground do painel, para testar uma tarefa ou um script enquanto você acompanha a visualização ao vivo.
Frameworks
Qualquer coisa que se conecte ao Chrome via CDP funciona com a connectUrl. Ela é de uso único, então um framework que se reconecta sozinho precisa de uma nova sessão para cada conexão. O navegador inicia quando você se conecta, geralmente em poucos segundos (veja a observação sobre o timeout acima); não há nenhum status para consultar antes.
// Patchright (optional; a Playwright fork): npm i patchright
import { chromium } from "patchright";
const browser = await chromium.connectOverCDP(connectUrl, { timeout: 120_000 });
const page = browser.contexts()[0].pages()[0];# Browser Use
from browser_use import Agent, Browser
agent = Agent(task="Find the cheapest flight to Lisbon next Friday", llm=llm, browser=Browser(cdp_url=connect_url))
await agent.run()
# Crawl4AI
from crawl4ai import AsyncWebCrawler, BrowserConfig
config = BrowserConfig(browser_mode="custom", cdp_url=connect_url, use_managed_browser=True)
async with AsyncWebCrawler(config=config) as crawler:
result = await crawler.arun("https://example.com")// Stagehand v4
import { localBrowser, Stagehand } from "@browserbasehq/stagehand";
const stagehand = await Stagehand.create({ browser: await localBrowser.connect({ cdpUrl: connectUrl }) });setContent e exposeFunction
O motor nunca envia eventos de console ao cliente, porque repassá-los é exatamente o que medem as páginas que procuram um cliente de automação. Os navegadores hospedados mantêm isso: a opção stock_runtime do SDK, que volta a ativá-los numa execução de depuração na sua própria máquina ou no Docker, não é aplicada a uma inicialização na nuvem. Duas chamadas do driver dependem deles:
- O
page.setContent()do Playwright espera por um evento de console que nunca chega, então dá timeout (o do Puppeteer funciona). Em vez disso, abra o HTML como uma URLdata:ou escreva-o você mesmo na página, como abaixo. - O
exposeFunction()e oexposeBinding(), no Playwright e no Puppeteer, funcionam na página que está aberta quando você os chama e somem assim que essa página navega. Chame-os depois da última navegação ou, em vez disso, devolva os resultados peloevaluate.
// Instead of await page.setContent(html):
// Short HTML: a data: URL (the page gets no origin of its own, so no cookies or storage)
await page.goto("data:text/html," + encodeURIComponent(html));
// Any HTML: write it into a page you have navigated to; it keeps that page's origin
await page.evaluate((html) => {
document.open();
document.write(html);
document.close();
}, html);# Instead of page.set_content(html):
from urllib.parse import quote
page.goto("data:text/html," + quote(html))
# or
page.evaluate("html => { document.open(); document.write(html); document.close(); }", html)Um helper para começar
Criar com as novas tentativas descritas acima, conectar e sempre encerrar, tudo numa só função:
// clearcote-hosted.ts
import { chromium, type Browser } from "playwright"; // or "patchright"
const API = "https://www.clearcotelabs.com/api/v1/browsers";
const AUTH = { authorization: "Bearer " + process.env.CLEARCOTE_API_KEY };
const RETRY_CODES = new Set(["NO_CAPACITY", "NO_WORKER"]);
export async function createSession(options: Record<string, unknown> = {}, attempts = 5) {
for (let i = 0; ; i++) {
const res = await fetch(API, {
method: "POST",
headers: { ...AUTH, "content-type": "application/json" },
body: JSON.stringify(options),
});
const body = await res.json().catch(() => ({}));
if (res.ok) return body as { id: string; connectUrl: string; worker: string };
const retry = RETRY_CODES.has(body.code) || (res.status === 429 && !body.code) || [500, 502, 504].includes(res.status);
if (!retry || i + 1 >= attempts) throw new Error([res.status, body.code, body.error].filter(Boolean).join(" "));
await new Promise((r) => setTimeout(r, Math.min(15_000, 1000 * 2 ** i) * (0.5 + Math.random())));
}
}
export async function withBrowser<T>(options: Record<string, unknown>, work: (browser: Browser) => Promise<T>) {
const session = await createSession(options);
try {
const browser = await chromium.connectOverCDP(session.connectUrl, { timeout: 120_000 });
try {
return await work(browser);
} finally {
await browser.close().catch(() => {});
}
} finally {
// Ends the session if closing the browser did not (a no-op otherwise).
await fetch(API + "/" + session.id, { method: "DELETE", headers: AUTH }).catch(() => {});
}
}
// await withBrowser({ profile: { name: "shop", persist: true }, country: "de" }, async (browser) => {
// const page = browser.contexts()[0].pages()[0];
// await page.goto("https://example.com");
// });Enviando arquivos
Uma página que pede um arquivo — um <input type="file">, um botão de “procurar”, uma área de arrastar e soltar — recebe esse arquivo da mesma forma num navegador hospedado e num local. O arquivo é lido na sua máquina e seus bytes trafegam pela conexão, então o navegador nunca vê um caminho no seu disco e você pode enviar um arquivo que só existe onde o seu script roda. O limite é de 50 MB por arquivo.
Playwright é o mais simples. O setInputFiles coloca um arquivo direto no input, sem nenhum clique, e funciona mesmo quando o input está oculto — muitos sites escondem o input de verdade atrás de um botão estilizado, então mire no próprio input em vez de clicar.
// Node.js + Playwright
await page.setInputFiles("input[type=file]", "C:/Users/me/invoice.pdf");
// or build the file in your script, with nothing on disk:
await page.setInputFiles("input[type=file]", {
name: "invoice.pdf",
mimeType: "application/pdf",
buffer: Buffer.from("%PDF-1.4 …"),
});# Python + Playwright
page.set_input_files("input[type=file]", "/home/me/invoice.pdf")Quando um botão abre a janela de arquivos do sistema e não há nenhum input que você possa mirar, capture o seletor de arquivos em vez disso:
const [chooser] = await Promise.all([
page.waitForEvent("filechooser"),
page.click("text=Browse"), // the page's own button
]);
await chooser.setFiles("C:/Users/me/invoice.pdf");Puppeteer. O elementHandle.uploadFile() e o fileChooser.accept() não estão disponíveis em navegadores hospedados: eles indicam um caminho para o servidor ler, que poderia apontar para qualquer lugar do worker, então o gateway os recusa. Construa o arquivo dentro da página a partir dos bytes que você envia e entregue-o ao input:
// Puppeteer: construct the file in the page
const b64 = fs.readFileSync("invoice.pdf").toString("base64");
await page.evaluate(({ b64, name, type }) => {
const data = Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
const dt = new DataTransfer();
dt.items.add(new File([data], name, { type }));
const input = document.querySelector("input[type=file]");
input.files = dt.files;
input.dispatchEvent(new Event("change", { bubbles: true }));
}, { b64, name: "invoice.pdf", type: "application/pdf" });O mesmo DataTransfer comanda uma área de arrastar e soltar: dispare dragenter, dragover e drop nela carregando esse objeto. Um arraste de CDP de verdade com um caminho local (Input.dispatchDragEvent com arquivos) é recusado pela mesma razão que o uploadFile().
Baixando arquivos
Um arquivo que a página baixa é salvo no nosso servidor, na pasta própria da sessão. Você o busca pela conexão que o seu script já tem, com quatro comandos do domínio Hosted, que o próprio gateway hospedado responde, enviados em qualquer sessão CDP. A pasta é apagada quando a sessão termina, então busque o que precisar antes de fechar o navegador.
O Playwright salva cada download com um id. Hosted.listFiles mostra esse id como o name do arquivo e acrescenta o nome que o site deu ao arquivo; então compare com suggestedFilename():
// Node.js + Playwright
const cdp = await browser.newBrowserCDPSession();
const [download] = await Promise.all([
page.waitForEvent("download"),
page.click("text=Export"), // whatever starts the download
]);
// Wait until the browser has finished writing it.
const isIt = (f) => f.download?.suggestedFilename === download.suggestedFilename() && f.download.state === "completed";
let file;
while (!(file = (await cdp.send("Hosted.listFiles")).files.find(isIt))) {
await new Promise((r) => setTimeout(r, 250));
}
// Read it in chunks (4 MB each unless you pass length, 8 MB at most).
const parts = [];
for (let offset = 0, eof = false; !eof; ) {
const chunk = await cdp.send("Hosted.readFile", { name: file.name, offset });
parts.push(Buffer.from(chunk.data, "base64"));
offset += chunk.bytes;
eof = chunk.eof;
}
fs.writeFileSync(download.suggestedFilename(), Buffer.concat(parts));
await cdp.send("Hosted.deleteFile", { name: file.name }); // frees room in the session's folder# Python + Playwright
import base64, time
cdp = browser.new_browser_cdp_session()
with page.expect_download() as info:
page.click("text=Export")
name = info.value.suggested_filename
def find():
for f in cdp.send("Hosted.listFiles")["files"]:
d = f.get("download") or {}
if d.get("suggestedFilename") == name and d.get("state") == "completed":
return f
file = find()
while not file:
time.sleep(0.25)
file = find()
data, offset = b"", 0
while True:
chunk = cdp.send("Hosted.readFile", {"name": file["name"], "offset": offset})
data += base64.b64decode(chunk["data"])
offset += chunk["bytes"]
if chunk["eof"]:
break
cdp.send("Hosted.deleteFile", {"name": file["name"]})O Puppeteer e outros clientes que não mexem nas configurações de download recebem o arquivo com o nome que o site deu a ele. Ele aparece quando o download termina; até lá o navegador grava um arquivo .crdownload, listado com partial: true.
// Puppeteer
const cdp = await page.createCDPSession();
await page.click("#export");
let file;
while (!(file = (await cdp.send("Hosted.listFiles")).files.find((f) => f.name === "report.csv"))) {
await new Promise((r) => setTimeout(r, 250));
}
const { data, eof } = await cdp.send("Hosted.readFile", { name: file.name }); // loop on offset for files over 4 MB| Comando | Recebe | Retorna |
|---|---|---|
Hosted.listFiles | nada | files: name, size, modified (ms), partial e download (suggestedFilename, url, state) para um download que o Playwright nomeou; além de totalBytes e limits. |
Hosted.readFile | name, offset (0), length (4 MB, no máximo 8 MB) | data (base64), offset, bytes, size, eof |
Hosted.deleteFile | name | nada |
Hosted.writeFile | name, data (base64, no máximo 8 MB por chamada), append | name, size |
Um name é sempre um único nome de arquivo, exatamente como listFiles o retorna, nunca um caminho. A pasta comporta no máximo 1 GB, somando downloads e arquivos que você coloca. Um navegador que baixa além disso encerra a sessão (motivo max_files_size); então, numa sessão longa, apague o que você já buscou.
Hosted.writeFile coloca um arquivo na pasta da sessão, para ler de volta mais tarde na mesma sessão: até 50 MB por arquivo, enviados em chamadas de no máximo 8 MB, com append: true para o restante. Tipos de arquivo executáveis (.exe, .bat, .ps1 e semelhantes) são recusados. Uma página não consegue abrir arquivos dessa pasta; para dar um arquivo a uma página, use setInputFiles como em Enviando arquivos.
O Playground
O Playground do painel roda um desses navegadores enquanto você acompanha tudo na visualização ao vivo. Ele abre em Task: escreva o que o navegador deve fazer e um agente faz isso passo a passo. É uma execução de agente, a mesma de POST /api/v1/runs, e cada passo aparece em What it did conforme acontece. Você pode assumir o controle na visualização ao vivo quando quiser. Com Ask me when it gets stuck ativado (vem ativado por padrão), o agente pausa quando precisa de uma pessoa, por exemplo para um código de login, e continua quando você marca como concluído.
Os chips abaixo da tarefa definem onde ela começa (Start at), o país do IP residencial (Exit), se é um dispositivo novo ou um que volta (Device) e se a resposta é texto ou JSON no formato que você definir (Output). Em More ficam todas as outras opções de sessão, o máximo de passos, a gravação em vídeo e os segredos: escreva {{password}} na tarefa e informe o valor ali. O modelo só vê o placeholder, e o valor fica na sua aba: nunca é salvo e nunca vai num link.
Script roda o seu próprio código em vez disso. Ele roda num frame isolado (sandbox) na sua aba e fala CDP com o navegador pelo WebSocket dele. log() imprime em What it did, e em More você pode manter o navegador aberto para que o próximo script continue nele. O page dele é um pequeno helper, e não o Playwright, então um script do Playground é um rascunho para adaptar, não um arquivo para colar:
| Helper | O que faz |
|---|---|
page.goto(url, { timeout? }) | Navega e espera o evento load. |
page.click(sel) · page.type(sel, text) · page.press(key) | Input real de mouse e teclado, rolando o elemento para a área visível antes. |
page.evaluate(fn, ...args) | Executa uma função na página e devolve o resultado em JSON. |
page.waitForSelector(sel, { timeout? }) · page.waitForNavigation() | Espera um elemento ou o próximo carregamento de página. |
page.scroll(px) · page.screenshot({ fullPage? }) | Rolagem com a roda do mouse; um JPEG que aparece no resultado da execução. |
page.title() · page.url() · page.content() | O título, o endereço e o HTML do documento. |
log(...values) · sleep(ms) | Imprime uma linha em What it did (objetos saem formatados); pausa. |
cdp(method, params) | Um comando CDP bruto para o navegador (Target.*, Browser.*, Storage.*). |
page.cdp(method, params) | Um comando CDP bruto para a página (Page.*, Runtime.*, DOM.*, Network.*). |
Os erros informam a linha do script de onde vieram. Save as… guarda um script neste navegador.
Quando uma execução termina, o resultado aparece logo abaixo: a resposta de uma tarefa e a página em que ela terminou, com a gravação se você pediu uma e a linha do tempo completa da execução, ou as capturas de um script. O resultado oferece a mesma execução de mais três formas. Use in code mostra tudo como código para o seu próprio projeto: uma tarefa como uma chamada à API de runs em Node, Python ou curl, um script como o mesmo navegador e as mesmas opções para Playwright ou Puppeteer. Copy for AI copia um prompt para um agente de código com a API, esta execução e as opções dela. Share copia um link que leva a tarefa ou o script e as opções na própria URL, então nada fica armazenado do nosso lado; quem abrir o link roda tudo com o próprio saldo. Nenhum dos três leva o valor de um segredo.