ステージハンド + スクラップレス：クラウドブラウザでのAIブラウザ自動化

TL;DR:

• Stagehandは、平易な英語の指示と実際のPlaywrightコードを結びつけるAIブラウザー自動化フレームワークです。 Chrome DevTools Protocolセッションの上にact、extract、observeという3つのプライミティブを公開しています。
• StagehandをScrapeless Scraping Browserに向けるには、1つのフィールドlocalBrowserLaunchOptions.cdpUrlを設定します。 Scrapeless WebSocketエンドポイントを指定します。他にStagehandコードは変更しません。
• ブラウザーはクラウド内で実行されます。 そのため、あなたの自動化には管理されたセッション、フィンガープリンティング、住宅用エグレスが提供され、ローカルのChromiumを立ち上げ、スケールし、ブロック解除する必要はありません。
• 自分のモデルキーを持ち込むことができます。 Stagehandはact/extract/observeのために言語モデルを呼び出します; ブラウザーとモデルは別々の関心事です。
• 無料で始められます。 新しいScrapelessアカウントには無料のScraping Browserクレジットが含まれています — app.scrapeless.comにサインアップしてください。

Stagehandは、Browserbaseのオープンソースフレームワークであり、2つの極端な選択肢の間に位置します：マークアップの変更ごとに壊れる脆弱なセレクタースクリプトと、予測不可能な自由に動くエージェントです。Stagehandは、自然言語の指示に基づき、あなたの制御に戻る3つの構成可能なプライミティブを提供します — actで何かを行い、extractで構造化データを取得し、observeで要素を見つけます。Stagehandには、制御するためのブラウザーがまだ必要です。そのブラウザーをローカルで実行するということは、Chromiumを立ち上げ、スケールし、ブロックされないように維持することを意味します。このガイドは、StagehandをScrapelessのScraping Browserに接続し、フレームワークはそのまま、ブラウザーがクラウドに移るようにします。以下のすべてのコマンドと出力は、ライブ実行からキャプチャされました。

この統合が提供するもの

Stagehandは、Chrome DevTools Protocolを介してブラウザーに接続します。Scrapeless Scraping Browserはまさにそれを公開しています：WebSocket URLを介してアクセスできる実際のChrome環境です。これらを接続するということは、

• 操作するためのローカルブラウザーが不要です。 Chromiumを立ち上げたり、パッチを当てたり、スケールしたりする必要はありません；セッションはサーバー側で実行され、あなたはそれに接続します。
• 管理されたセッションとエグレス。 クラウドブラウザーが現実的なデバイスプロファイルと住宅用ルーティングを処理するため、Stagehandが読み取るページは実際の訪問者のように見えます。
• 同じStagehand API。 act、extract、observeは、ブラウザーがローカルであってもリモートであっても同じ動作をします — 変更されるのは接続URLだけです。
• 関心事の明確な分離。 Scrapelessがブラウザーを運営し、あなたが選択したモデルが推論を実行します。どちらも相手に触れずに入れ替えることができます。

前提条件

• Node.js 20.19+または22.12+およびパッケージマネージャー（このガイドではpnpmを使用しています）。
• Scraping Browser用のScrapeless APIキー — app.scrapeless.comで無料プランを取得してください。
• モデルプロバイダーのAPIキー。Stagehandはそのプライミティブのために言語モデルを呼び出します；サポートされているプロバイダーがどれでも機能します。

インストール

StagehandとZodを追加します。Zodはextractの構造化出力の型を定義します：

pnpm add @browserbasehq/stagehand zod

StagehandをScraping Browserに接続する

統合は1つのフィールドです。StagehandのlocalBrowserLaunchOptions.cdpUrlはCDP WebSocketエンドポイントを受け入れます。Scrapeless Scraping BrowserのURLと、あなたのAPIキーをtokenクエリパラメータとして渡します。モデルはllmClientとして別に提供されます。

import { Stagehand, AISdkClient, getAISDKLanguageModel } from "@browserbasehq/stagehand";
import { z } from "zod";

// あなた自身のモデルプロバイダー（ここではOpenAI；サポートされているプロバイダーキーを利用できます）。
const model = getAISDKLanguageModel("openai", "gpt-4o-mini", {
  apiKey: process.env.OPENAI_API_KEY,
});

const stagehand = new Stagehand({
  env: "LOCAL",
  llmClient: new AISdkClient({ model }),
  localBrowserLaunchOptions: {
    cdpUrl:
      `wss://browser.scrapeless.com/api/v2/browser` +
      `?token=${process.env.SCRAPELESS_API_KEY}` +
      `&session_ttl=180&proxy_country=US`,
  },
});

await stagehand.init();

init()の後、StagehandはScrapelessがホストするChromeセッションを操作しています。Playwrightコンテキストはstagehand.contextとして利用でき、3つのAIプライミティブはstagehandインスタンス上に存在します。

ページを操作する

ナビゲーションは標準のPlaywrightコンテキストを使用します。アクティブなページを取得し、ターゲットに移動します：

const context = stagehand.context;
const page = context.pages()[0] ?? (await context.newPage());
await page.goto("https://news.ycombinator.com", { waitUntil: "domcontentloaded" });

観察 — 平易な英語で要素を見つける

observeは解決されたセレクタを持つ候補要素を返すので、アクションを実行する前にターゲットを確認できます：

const candidates = await stagehand.observe("上部ナビゲーションバーのログインリンク");
console.log(candidates[0]);

ライブ実行では、単一の解決された候補が返されました：

// Scrapeless Scraping Browserに対するライブスクレイパー実行から取得。
{
  "description": "上部ナビゲーションバーのログインページへのリンク",
  "method": "click",
  "arguments": [],
  "selector": "xpath=/html[1]/body[1]/center[1]/table[1]/tbody[1]/tr[1]/td[1]/table[1]/tbody[1]/tr[1]/td[3]/span[1]/a[1]"
}

抽出 — ページを型付きデータに変換する

extractは命令とZodスキーマを受け取り、スキーマに合致するデータを返します。スキーマは契約であり、Stagehandはページからそれを埋めます：

const result = await stagehand.extract(
  "フロントページから上位3つのストーリータイトルとそのポイント数を抽出する",
  z.object({
    stories: z.array(z.object({ title: z.string(), points: z.number() })).max(3),
  }),
);
console.log(result);

ライブ実行では、フロントページから型付きの行が返されました：

// フロントページからの実際のタイトルとポイント数を持つライブ実行から取得。
{
  "stories": [
    { "title": "13年の古いGPUなしで、5トークン/秒でGemma 4 26Bを稼働させる (neomindlabs.com)", "points": 82 },
    { "title": "Telegramデータセンターの謎 (dev.moe)", "points": 163 },
    { "title": "コーディングエージェントのためのオープンソースメモリ、SSH経由で同期 (github.com/vshulcz)", "points": 43 }
  ]
}

アクション — 命令からアクションを実行する

actはページに対して平易な英語のアクションを実行します。ここでは、セッションを新しいURLに移動させるナビゲーションリンクをクリックします：

console.log(page.url()); // https://news.ycombinator.com/
await stagehand.act("上部ナビゲーションの'新着'リンクをクリックする");
await page.waitForLoadState("domcontentloaded");
console.log(page.url()); // https://news.ycombinator.com/newest

ライブ実行では、https://news.ycombinator.com/からhttps://news.ycombinator.com/newestに移動し、命令が実際のクリックに解決されたことを確認しました。

セッションを閉じる

実行が終了したら、クラウドブラウザを解放します：

await stagehand.close();

Scrapelessでブラウザを実行する理由

Stagehandはブラウザの置き場所に対して意見を持たないように設計されています — これがcdpUrlの交換を非常にクリーンにしている理由です。自分でChromiumを実行するのはノートパソコンのデモには問題ありませんが、実際の作業負荷は同時実行性、セッションの衛生、および多数のページをブロックされずに維持することを意味します。Scrapeless Scraping Browserは、現実的なデバイスとフィンガープリントプロファイル、および住宅の出口を持つ実際のChrome環境であり、Stagehandが既に話す同じCDP WebSocket経由で接続されます。Stagehandのプログラミングモデルを保持し、ブラウザの操作は管理されたサービスに渡します。接続オプション — セッションの寿命、地域、およびフィンガープリント — はScraping Browserのドキュメントに記載されており、異なるCDP駆動エージェント統合についてはHermesブラウザスキルのウォークスルーを参照してください。

無料プランでキーを取得するにはapp.scrapeless.comにアクセスし、Scraping Browserクレジットが最初の実行をカバーします。

結論

Stagehandは、単一のURLを指定してブラウザに対してact、extract、observeを提供します。localBrowserLaunchOptions.cdpUrlをScrapeless Scraping Browserのエンドポイントに設定し、モデルキーを提供すると、フレームワークは管理されたクラウドブラウザで変更なしに実行されます — extractはスキーマ型データを返し、actは平易な英語からページを操作します。接続は一つのフィールドであり、その上に構築するものはすべて変わらずに維持されます。
クラウドブラウザでStagehandスクリプトを実行する準備はできていますか？Scrapelessダッシュボードから無料で始めるか、スクレイピングブラウザ製品ページを確認するか、Scrapelessの価格ページでプランを比較してください。

よくある質問

Q: Stagehandとは何ですか？
A: StagehandはBrowserbaseからのオープンソースのブラウザ自動化フレームワークで、Chrome DevTools Protocolセッションの上に3つの自然言語のプライミティブ（act、extract、observe）を追加し、平易な英語の指示と確定的なPlaywrightコードを混在させることができます。

Q: StagehandはどのようにScrapeless Scraping Browserに接続しますか？
A: Stagehandコンストラクタ内でlocalBrowserLaunchOptions.cdpUrlをScrapeless WebSocketエンドポイントwss://browser.scrapeless.com/api/v2/browserに設定し、APIキーをtokenクエリパラメータとして指定します。Stagehandはその後、CDP経由でクラウドセッションを操作します。

Q: 言語モデルのキーはまだ必要ですか？
A: はい。Scrapelessがブラウザを提供し、Stagehandがact、extract、observeにモデルを呼び出します。ブラウザとモデルは別々に保持されるため、Stagehandのモデル構成を通じて独自のプロバイダーキーを供給します。

Q: クラウドブラウザに移動してもStagehandコードは変更されますか？
A: いいえ。接続URLだけが変更されます。act、extract、observe、およびPlaywrightコンテキストは、ブラウザがローカルであろうとリモートのScrapelessセッションであろうと同じように動作します。

Q: ページから構造化データを取得するにはどうすればよいですか？
A: 指示とZodスキーマを使ってextractを呼び出します。Stagehandはスキーマに一致するオブジェクトを返します。たとえば{ title, points }の配列のような形で、生のHTMLではなく型付きデータを取得できます。

Q: ブラウザの地域を設定するにはどうすればよいですか？
A: Scrapeless CDP URLにproxy_countryクエリパラメータを追加し、セッションの出口が見たい市場と一致するようにします。

Q: 行動を起こす前に要素を検査できますか？
A: はい。説明を付けてobserveを呼び出すと、解決されたセレクタと提案されたメソッドを持つ候補要素が返され、actを実行する前に確認できます。