Framework và Playground
Ghi chú để kết nối từng framework với trình duyệt hosted, và Playground trong dashboard để thử một tác vụ hoặc một script trong khi theo dõi live view.
Framework
Bất cứ thứ gì gắn vào Chrome qua CDP đều hoạt động với connectUrl. URL này chỉ dùng một lần, nên framework nào tự kết nối lại sẽ cần một phiên mới cho mỗi kết nối. Trình duyệt khởi động khi bạn kết nối, thường trong vòng vài giây (xem ghi chú về timeout ở trên); không có trạng thái nào cần poll trước.
// 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 và exposeFunction
Engine không bao giờ gửi sự kiện console tới client, vì chính việc chuyển tiếp chúng là thứ mà các trang dò tìm client tự động hóa đo lường. Trình duyệt hosted vẫn giữ nguyên như vậy: tùy chọn stock_runtime của SDK, vốn bật lại các sự kiện này cho một lần chạy debug trên máy của bạn hoặc trong Docker, không được áp dụng cho một lần khởi chạy trên cloud. Có hai lệnh gọi của driver phụ thuộc vào các sự kiện này:
page.setContent()của Playwright chờ một sự kiện console không bao giờ tới, nên sẽ bị timeout (bản của Puppeteer thì vẫn chạy). Thay vào đó, hãy mở HTML dưới dạng URLdata:, hoặc tự ghi nó vào trang, như bên dưới.exposeFunction()vàexposeBinding(), trong cả Playwright lẫn Puppeteer, hoạt động trong trang đang mở lúc bạn gọi chúng, và sẽ mất khi trang đó điều hướng sang trang khác. Hãy gọi chúng sau lần điều hướng cuối cùng, hoặc thay vào đó trả kết quả về từevaluate.
// 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)Một helper để bắt đầu
Tạo phiên với cơ chế thử lại ở trên, kết nối, và luôn dừng phiên, tất cả trong một hàm:
// 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");
// });Upload file
Một trang yêu cầu một file — một <input type="file">, một nút “browse”, một vùng kéo-thả — nhận file theo cùng một cách trong một trình duyệt hosted như trong một trình duyệt local. File được đọc trên máy của bạn và các byte của nó truyền qua kết nối, nên trình duyệt không bao giờ thấy đường dẫn trên ổ đĩa của bạn, và bạn có thể upload một file chỉ tồn tại ở nơi script của bạn chạy. Giới hạn là 50 MB mỗi file.
Playwright là cách đơn giản nhất. setInputFiles đưa thẳng một file vào input, không cần click, và vẫn chạy ngay cả khi input bị ẩn — nhiều site giấu input thật đằng sau một nút được tạo kiểu riêng, nên hãy nhắm vào chính input đó thay vì đi click.
// 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")Khi một nút mở hộp thoại chọn file của hệ thống và không có input nào để bạn nhắm tới, hãy bắt lấy chooser thay vì vậy:
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() và fileChooser.accept() không dùng được trên trình duyệt hosted: chúng chỉ định một đường dẫn để máy chủ đọc, mà đường dẫn đó có thể trỏ tới bất cứ đâu trên worker, nên gateway từ chối chúng. Hãy dựng file ngay bên trong trang từ các byte bạn gửi vào, rồi giao nó cho 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" });Chính DataTransfer đó điều khiển một vùng kéo-thả: hãy dispatch dragenter, dragover và drop lên nó kèm theo object đó. Một thao tác kéo CDP thật với đường dẫn local (Input.dispatchDragEvent kèm file) bị từ chối vì cùng lý do như uploadFile().
Download file
File mà trang download sẽ được lưu trên máy chủ của chúng tôi, trong thư mục riêng của phiên. Bạn lấy file qua kết nối mà script của bạn đã có, bằng bốn lệnh thuộc domain Hosted do chính gateway hosted trả lời, gửi trên bất kỳ phiên CDP nào. Thư mục bị xóa khi phiên kết thúc, nên hãy lấy những gì bạn cần trước khi đóng trình duyệt.
Playwright lưu mỗi lần download dưới một id. Hosted.listFiles hiển thị id đó làm name của file và thêm tên mà trang web đặt cho file, vì vậy hãy so khớp theo 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 và các client khác không đổi thiết lập download sẽ nhận file với tên mà trang web đặt cho nó. File xuất hiện khi download xong; trước đó trình duyệt ghi một file .crdownload, được liệt kê với 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| Lệnh | Nhận | Trả về |
|---|---|---|
Hosted.listFiles | không có | files: name, size, modified (ms), partial, và download (suggestedFilename, url, state) cho một download do Playwright đặt tên; cùng với totalBytes và limits. |
Hosted.readFile | name, offset (0), length (4 MB, tối đa 8 MB) | data (base64), offset, bytes, size, eof |
Hosted.deleteFile | name | không có |
Hosted.writeFile | name, data (base64, tối đa 8 MB mỗi lần gọi), append | name, size |
Một name luôn là đúng một tên file như listFiles trả về, không bao giờ là đường dẫn. Thư mục chứa tối đa 1 GB, gồm cả file download và file bạn đưa vào. Trình duyệt download vượt quá mức đó sẽ làm phiên kết thúc (lý do max_files_size), nên trong một phiên dài hãy xóa những gì bạn đã lấy về.
Hosted.writeFile đưa một file vào thư mục của phiên, để đọc lại sau trong cùng phiên đó: tối đa 50 MB mỗi file, gửi theo các lần gọi tối đa 8 MB, phần còn lại dùng append: true. Các loại file thực thi (.exe, .bat, .ps1 và tương tự) bị từ chối. Trang không thể mở file từ thư mục đó; để đưa một file cho trang, hãy dùng setInputFiles như trong Upload file.
Playground
Playground trong dashboard chạy một trong các trình duyệt này trong khi bạn theo dõi nó qua live view. Nó mở ở chế độ Task: bạn viết điều trình duyệt cần làm, và một agent thực hiện từng bước. Đó là một lượt chạy agent, giống như khi gọi POST /api/v1/runs, và mỗi bước hiện ra trong What it did ngay khi nó diễn ra. Bạn có thể tiếp quản điều khiển trong live view bất cứ lúc nào. Khi bật Ask me when it gets stuck (mặc định là bật), agent sẽ tạm dừng khi cần một người, chẳng hạn để nhập mã đăng nhập, và tiếp tục sau khi bạn đánh dấu là đã xong.
Các chip bên dưới tác vụ đặt nơi nó bắt đầu (Start at), quốc gia của IP dân cư (Exit), đó là một thiết bị mới hay một thiết bị quay lại (Device), và câu trả lời là văn bản hay JSON theo cấu trúc bạn đưa ra (Output). More chứa mọi tùy chọn phiên khác, số bước tối đa, bản ghi video và các secret: hãy viết {{password}} trong tác vụ và thêm giá trị của nó ở đó. Mô hình chỉ thấy phần giữ chỗ, còn giá trị nằm lại trong tab của bạn: nó không bao giờ được lưu và không bao giờ nằm trong một liên kết.
Script thì chạy code của chính bạn. Code chạy trong một frame sandbox ngay trong tab của bạn và giao tiếp CDP với trình duyệt qua WebSocket của nó. log() in ra trong What it did, và trong More bạn có thể giữ trình duyệt mở để script tiếp theo chạy tiếp trong đó. page của nó là một helper nhỏ, không phải Playwright, nên script Playground là bản phác thảo cần chuyển đổi, không phải file để dán nguyên vào:
| Helper | Chức năng |
|---|---|
page.goto(url, { timeout? }) | Điều hướng và chờ sự kiện load. |
page.click(sel) · page.type(sel, text) · page.press(key) | Thao tác chuột và bàn phím thật, cuộn phần tử vào tầm nhìn trước. |
page.evaluate(fn, ...args) | Chạy một hàm trong trang và nhận lại kết quả JSON. |
page.waitForSelector(sel, { timeout? }) · page.waitForNavigation() | Chờ một phần tử, hoặc chờ lần tải trang tiếp theo. |
page.scroll(px) · page.screenshot({ fullPage? }) | Cuộn bằng con lăn chuột; một ảnh JPEG hiện trong kết quả của lượt chạy. |
page.title() · page.url() · page.content() | Tiêu đề, địa chỉ và HTML của tài liệu. |
log(...values) · sleep(ms) | In một dòng trong What it did (object được định dạng cho dễ đọc); tạm dừng. |
cdp(method, params) | Một lệnh CDP thô gửi tới trình duyệt (Target.*, Browser.*, Storage.*). |
page.cdp(method, params) | Một lệnh CDP thô gửi tới trang (Page.*, Runtime.*, DOM.*, Network.*). |
Lỗi cho biết dòng script gây ra nó. Save as… lưu một script trong trình duyệt này.
Khi một lượt chạy kết thúc, kết quả hiện ngay bên dưới: với tác vụ là câu trả lời và trang nơi nó kết thúc, kèm bản ghi nếu bạn yêu cầu và toàn bộ dòng thời gian của lượt chạy; với script là các ảnh chụp của nó. Kết quả cung cấp cùng lượt chạy đó theo ba cách nữa. Use in code hiển thị nó dưới dạng code cho dự án của bạn: tác vụ là một lời gọi API runs bằng Node, Python hoặc curl, script là cùng trình duyệt và tùy chọn đó cho Playwright hoặc Puppeteer. Copy for AI sao chép một prompt cho coding agent, gồm API, lượt chạy này và các tùy chọn của nó. Share sao chép một liên kết chứa tác vụ hoặc script cùng các tùy chọn ngay trong URL, nên không có gì được lưu ở phía chúng tôi; ai mở liên kết sẽ chạy nó bằng số dư của chính họ. Không cách nào trong ba cách này chứa giá trị của secret.