Frameworks y el Playground
Notas para conectar frameworks concretos a un navegador alojado, y el Playground del panel para probar una tarea o un script mientras miras la vista en vivo.
Frameworks
Todo lo que se conecte a Chrome por CDP funciona con la connectUrl. Es de un solo uso, así que un framework que se reconecta por su cuenta necesita una sesión nueva para cada conexión. El navegador arranca cuando te conectas, normalmente en pocos segundos (mira la nota sobre el timeout más arriba); no hay ningún estado que 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 y exposeFunction
El motor nunca envía eventos de consola al cliente, porque reenviarlos es justo lo que miden las páginas que buscan un cliente de automatización. Los navegadores alojados lo mantienen así: la opción stock_runtime del SDK, que los vuelve a activar para una ejecución de depuración en tu propia máquina o en Docker, no se aplica a un lanzamiento en la nube. Dos llamadas del driver dependen de ellos:
page.setContent()de Playwright espera un evento de consola que nunca llega, así que se agota el tiempo de espera (el de Puppeteer funciona). En su lugar, abre el HTML como una URLdata:o escríbelo tú mismo en la página, como se muestra abajo.exposeFunction()yexposeBinding(), en Playwright y Puppeteer, funcionan en la página que está abierta cuando las llamas y desaparecen en cuanto esa página navega. Llámalas después de la última navegación o, en su lugar, devuelve los resultados desdeevaluate.
// 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)Un helper para empezar
Crear la sesión con los reintentos de arriba, conectarse y detenerla siempre, en una sola función:
// 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");
// });Subir archivos
Una página que pide un archivo —un <input type="file">, un botón “examinar”, una zona de arrastrar y soltar— lo recibe igual en un navegador alojado que en uno local. El archivo se lee en tu máquina y sus bytes viajan por la conexión, así que el navegador nunca ve una ruta en tu disco y puedes subir un archivo que solo existe donde se ejecuta tu script. El límite es de 50 MB por archivo.
Playwright es lo más sencillo. setInputFiles coloca un archivo directamente en el input, sin ningún clic, y funciona incluso cuando el input está oculto: muchos sitios ocultan el input real detrás de un botón con estilos, así que apunta al input en sí en lugar de hacer clic.
// 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")Cuando un botón abre el diálogo de archivos del sistema y no hay ningún input al que puedas apuntar, captura el selector de archivos:
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. elementHandle.uploadFile() y fileChooser.accept() no están disponibles en los navegadores alojados: indican una ruta para que la lea el servidor, que podría apuntar a cualquier parte del worker, así que el gateway los rechaza. Construye el archivo dentro de la página a partir de los bytes que envías y pásalo al 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" });El mismo DataTransfer hace funcionar una zona de arrastrar y soltar: despacha dragenter, dragover y drop sobre ella con ese objeto. Un arrastre real por CDP con una ruta local (Input.dispatchDragEvent con archivos) se rechaza por la misma razón que uploadFile().
Descargar archivos
Un archivo que descarga la página se guarda en nuestro servidor, en la carpeta propia de la sesión. Lo obtienes por la conexión que tu script ya tiene, con cuatro comandos del dominio Hosted que responde el propio gateway alojado y que envías por cualquier sesión CDP. La carpeta se borra cuando termina la sesión, así que obtén lo que necesites antes de cerrar el navegador.
Playwright guarda cada descarga con un id. Hosted.listFiles muestra ese id como el name del archivo y añade el nombre que le dio el sitio, así que compara con 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"]})Puppeteer y otros clientes que no cambian la configuración de descargas reciben el archivo con el nombre que le dio el sitio. Aparece cuando la descarga termina; hasta entonces el navegador escribe un archivo .crdownload, que aparece con 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 | Recibe | Devuelve |
|---|---|---|
Hosted.listFiles | nada | files: name, size, modified (ms), partial y download (suggestedFilename, url, state) para una descarga que nombró Playwright; además totalBytes y limits. |
Hosted.readFile | name, offset (0), length (4 MB, como máximo 8 MB) | data (base64), offset, bytes, size, eof |
Hosted.deleteFile | name | nada |
Hosted.writeFile | name, data (base64, como máximo 8 MB por llamada), append | name, size |
Un name es siempre un solo nombre de archivo, tal como lo devuelve listFiles, nunca una ruta. La carpeta admite como máximo 1 GB, sumando descargas y archivos que pongas tú. Si el navegador descarga más, la sesión termina (motivo max_files_size), así que en una sesión larga borra lo que ya obtuviste.
Hosted.writeFile pone un archivo en la carpeta de la sesión para volver a leerlo más tarde en la misma sesión: hasta 50 MB por archivo, enviado en llamadas de como máximo 8 MB, con append: true para el resto. Se rechazan los tipos de archivo ejecutables (.exe, .bat, .ps1 y similares). Una página no puede abrir archivos de esa carpeta; para darle un archivo a una página, usa setInputFiles como en Subir archivos.
El Playground
El Playground del panel ejecuta uno de estos navegadores mientras lo miras en la vista en vivo. Se abre en Task: escribe lo que debe hacer el navegador y un agente lo hace paso a paso. Es una ejecución de agente, la misma que con POST /api/v1/runs, y cada paso aparece en What it did a medida que ocurre. Puedes tomar el control en la vista en vivo cuando quieras. Con Ask me when it gets stuck activado (lo está por defecto), el agente se detiene cuando necesita a una persona, por ejemplo para un código de inicio de sesión, y continúa cuando lo marcas como hecho.
Los chips bajo la tarea definen dónde empieza (Start at), el país de su IP residencial (Exit), si es un dispositivo nuevo o uno que vuelve (Device) y si la respuesta es texto o JSON con la forma que indiques (Output). En More están todas las demás opciones de sesión, el máximo de pasos, la grabación en video y los secretos: escribe {{password}} en la tarea y agrega ahí su valor. El modelo solo ve el marcador, y el valor se queda en tu pestaña: nunca se guarda ni forma parte de un enlace.
Script ejecuta tu propio código en su lugar. Corre en un frame aislado (sandbox) dentro de tu pestaña y habla CDP con el navegador por su WebSocket. log() imprime en What it did, y en More puedes dejar el navegador abierto para que el siguiente script continúe en él. Su page es un pequeño helper, no Playwright, así que un script del Playground es un boceto que hay que traducir, no un archivo para pegar:
| Helper | Qué hace |
|---|---|
page.goto(url, { timeout? }) | Navegar y esperar el evento load. |
page.click(sel) · page.type(sel, text) · page.press(key) | Entrada real de mouse y teclado, con desplazamiento previo hasta el elemento. |
page.evaluate(fn, ...args) | Ejecutar una función en la página y recibir su resultado en JSON. |
page.waitForSelector(sel, { timeout? }) · page.waitForNavigation() | Esperar un elemento o la siguiente carga de página. |
page.scroll(px) · page.screenshot({ fullPage? }) | Desplazamiento con la rueda del mouse; un JPEG que aparece en el resultado de la ejecución. |
page.title() · page.url() · page.content() | El título, la dirección y el HTML del documento. |
log(...values) · sleep(ms) | Imprimir una línea en What it did (los objetos se muestran formateados); pausar. |
cdp(method, params) | Un comando CDP directo al navegador (Target.*, Browser.*, Storage.*). |
page.cdp(method, params) | Un comando CDP directo a la página (Page.*, Runtime.*, DOM.*, Network.*). |
Los errores indican la línea del script de la que provienen. Save as… guarda un script en este navegador.
Cuando termina una ejecución, su resultado aparece debajo: la respuesta de una tarea y la página donde terminó, con la grabación si la pediste y la línea de tiempo completa de la ejecución, o las capturas de un script. El resultado ofrece la misma ejecución de tres formas más. Use in code la muestra como código para tu propio proyecto: una tarea como una llamada a la API de runs en Node, Python o curl, un script como el mismo navegador y las mismas opciones para Playwright o Puppeteer. Copy for AI copia un prompt para un agente de programación con la API, esta ejecución y sus opciones. Share copia un enlace que lleva la tarea o el script y sus opciones en la URL, así que no se guarda nada de nuestro lado; quien lo abra lo ejecuta con su propio saldo. Ninguno de los tres lleva el valor de un secreto.