本文へスキップ

フレームワークと Playground

特定のフレームワークをホスト型ブラウザにつなぐ際の注意点と、ライブビューを見ながらタスクやスクリプトを試せるダッシュボードの Playground を紹介します。

フレームワーク

CDP 経由で Chrome に接続するものであれば、何でも connectUrl で動作します。URL は 1 回限りなので、自動で再接続するフレームワークでは接続ごとに新しいセッションが必要です。ブラウザは接続時に起動し、通常は数秒以内に立ち上がります(上記のタイムアウトについての注記を参照)。事前にステータスをポーリングする必要はありません。

javascript
// 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];
python
# 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")
javascript
// Stagehand v4
import { localBrowser, Stagehand } from "@browserbasehq/stagehand";
const stagehand = await Stagehand.create({ browser: await localBrowser.connect({ cdpUrl: connectUrl }) });

setContent と exposeFunction

エンジンはコンソールイベントをクライアントに一切送信しません。自動化クライアントの有無を調べるページが計測しているのは、まさにその転送だからです。ホスト型ブラウザでもこれは変わりません。自分のマシンや Docker でのデバッグ用の実行でこれらのイベントを再び有効にする SDK の stock_runtime オプションは、クラウドでの起動には適用されません。次の 2 つのドライバー呼び出しは、これらのイベントに依存しています。

  • Playwright の page.setContent() は届くことのないコンソールイベントを待ち続けるため、タイムアウトします(Puppeteer では動作します)。代わりに HTML を data: URL として開くか、下の例のように自分でページに書き込んでください。
  • Playwright と Puppeteer の exposeFunction() と exposeBinding() は、呼び出した時点で開いているページでは動作しますが、そのページが遷移すると消えてしまいます。最後の遷移の後に呼び出すか、代わりに evaluate の戻り値として結果を受け取ってください。
javascript
// 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);
python
# 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)

たたき台にできるヘルパー

上記のリトライ付きの作成、接続、確実な停止を 1 つの関数にまとめたものです。

typescript
// 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");
// });

ファイルのアップロード

ファイルを求めるページ(<input type="file"> や “browse” ボタン、ドラッグ&ドロップ領域など)には、ローカルのブラウザと同じ方法で、ホスト型ブラウザでもファイルを渡せます。ファイルはお使いのマシン上で読み込まれ、そのバイト列が接続を通じて送られます。そのため、ブラウザがディスク上のパスを見ることはなく、スクリプトが動作している場所にしか存在しないファイルもアップロードできます。上限は 1 ファイルあたり 50 MB です。

Playwright が最もシンプルです。setInputFiles はクリックせずにファイルを直接 input に渡せて、input が隠れている場合でも機能します。多くのサイトは本物の input をスタイルを付けたボタンの背後に隠しているため、クリックするのではなく input そのものを対象にしてください。

javascript
// 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
# Python + Playwright
page.set_input_files("input[type=file]", "/home/me/invoice.pdf")

ボタンがシステムのファイルダイアログを開き、対象にできる input がない場合は、代わりに file chooser を受け取ります。

javascript
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() と fileChooser.accept() は、ホスト型ブラウザでは使えません。これらはサーバー側が読み取るパスを指定するもので、ワーカー上のどこでも指し示せてしまうため、ゲートウェイが拒否します。送り込んだバイト列からページ内でファイルを組み立て、それを input に渡してください。

javascript
// 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" });

同じ DataTransfer を使えば、ドラッグ&ドロップ領域も操作できます。そのオブジェクトを載せて dragenter、dragover、drop を領域にディスパッチします。ローカルパスを使った本物の CDP ドラッグ(ファイルを指定した Input.dispatchDragEvent)は、uploadFile() と同じ理由で拒否されます。

ファイルのダウンロード

ページがダウンロードしたファイルは、当社のサーバー上のセッション専用フォルダーに保存されます。スクリプトがすでに持っている接続を通じて、ホスト型ゲートウェイ自身が応答する Hosted ドメインの 4 つのコマンドで取得します。コマンドはどの CDP セッションから送ってもかまいません。フォルダーはセッションの終了時に削除されるため、必要なものはブラウザを閉じる前に取得してください。

Playwright は各ダウンロードを ID で保存します。Hosted.listFiles はその ID をファイルの name として示し、サイトが付けたファイル名も加えるので、suggestedFilename() と照合してください。

javascript
// 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
# 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 など、ダウンロード設定を変更しないクライアントでは、ファイルはサイトが付けた名前で保存されます。ダウンロードが完了すると表示され、それまではブラウザが .crdownload ファイルを書き込み、partial: true 付きで一覧に表示されます。

javascript
// 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
コマンド受け取るもの返すもの
Hosted.listFilesなしfiles:name、size、modified(ms)、partial、Playwright が名前を付けたダウンロードには download(suggestedFilename、url、state)。ほかに totalBytes と limits。
Hosted.readFilename、offset(0)、length(4 MB、最大 8 MB)data(base64)、offset、bytes、size、eof
Hosted.deleteFilenameなし
Hosted.writeFilename、data(base64、1 回の呼び出しで最大 8 MB)、appendname、size

name は常に listFiles が返すとおりの 1 つのファイル名で、パスではありません。フォルダーに置けるのは、ダウンロードとご自身で置いたファイルを合わせて最大 1 GB です。それを超えてダウンロードすると、セッションは終了します(理由 max_files_size)。長いセッションでは、取得し終えたファイルを削除してください。

Hosted.writeFile は、同じセッション内で後から読み戻すためにファイルをセッションのフォルダーに置きます。1 ファイルあたり最大 50 MB で、1 回の呼び出しは最大 8 MB、残りは append: true で送ります。実行可能なファイル形式(.exe、.bat、.ps1 など)は拒否されます。ページはこのフォルダーのファイルを開けません。ページにファイルを渡すには、ファイルのアップロードのとおり setInputFiles を使ってください。

Playground

ダッシュボードの Playground では、これらのブラウザの 1 つをライブビューで見ながら動かせます。最初に開くのは「Task」です。ブラウザにさせたいことを書くと、エージェントが一歩ずつ実行します。これは POST /api/v1/runs と同じエージェント実行で、各ステップは進むたびに「What it did」に表示されます。ライブビューではいつでも操作を引き継げます。「Ask me when it gets stuck」がオン(既定)なら、サインインコードなど人の手が必要になったところでエージェントが一時停止し、完了を知らせると続きを実行します。

タスク欄の下のチップでは、開始する場所(「Start at」)、住宅用 IP の国(「Exit」)、毎回新しいデバイスか同じデバイスで戻ってくるか(「Device」)、回答をテキストにするか指定した形の JSON にするか(「Output」)を設定します。「More」には、ほかのすべてのセッションオプション、最大ステップ数、動画の録画、シークレットがあります。タスクに {{password}} と書き、その値をここで追加してください。モデルが見るのはプレースホルダーだけで、値はあなたのタブの中にとどまり、保存されることもリンクに含まれることもありません。

「Script」は、代わりに自分のコードを実行します。コードはタブ内のサンドボックス化されたフレームで動き、ブラウザの WebSocket 経由で CDP を直接やり取りします。log() の出力は「What it did」に表示され、「More」でブラウザを開いたままにすると、次のスクリプトはそのブラウザで続きを実行します。page は Playwright ではなく小さなヘルパーなので、Playground のスクリプトはそのまま貼り付けて使うファイルではなく、書き換えて使うためのたたき台です。

ヘルパー動作
page.goto(url, { timeout? })ページに移動し、load イベントを待ちます。
page.click(sel) · page.type(sel, text) · page.press(key)要素を表示領域までスクロールしてから、実際のマウスとキーボードで入力します。
page.evaluate(fn, ...args)ページ内で関数を実行し、その結果を JSON で受け取ります。
page.waitForSelector(sel, { timeout? }) · page.waitForNavigation()要素の出現、または次のページ読み込みを待ちます。
page.scroll(px) · page.screenshot({ fullPage? })マウスホイールでのスクロール。スクリーンショットは JPEG で実行結果に表示されます。
page.title() · page.url() · page.content()ドキュメントのタイトル、アドレス、HTML。
log(...values) · sleep(ms)「What it did」への 1 行の出力(オブジェクトは整形して表示)と一時停止。
cdp(method, params)ブラウザへの生の CDP コマンド(Target.*、Browser.*、Storage.*)。
page.cdp(method, params)ページへの生の CDP コマンド(Page.*、Runtime.*、DOM.*、Network.*)。

エラーには、発生元のスクリプトの行番号が示されます。「Save as…」を使うと、スクリプトをこのブラウザに保存できます。

実行が終わると、その下に結果が表示されます。タスクなら回答と最後に開いていたページ、録画を指定した場合はその録画、実行の完全なタイムライン、スクリプトならキャプチャした画像です。結果からは、同じ実行をさらに 3 つの形で受け取れます。「Use in code」は、自分のプロジェクト用のコードとして表示します。タスクなら Node、Python、curl での runs API の呼び出し、スクリプトなら Playwright や Puppeteer 向けの同じブラウザとオプションです。「Copy for AI」は、API、この実行、そのオプションを含むコーディングエージェント向けのプロンプトをコピーします。「Share」は、タスクまたはスクリプトとそのオプションを URL に含めたリンクをコピーするため、当社側には何も保存されません。リンクを開いた人は、自分の残高で実行します。3 つのどれにも、シークレットの値は含まれません。