browserbase-sdk

Browserbase SDK

Browserbase は、本番環境向けのヘッドレス Chromium を分離された VM で実行し、セッションごとに CDP WebSocket を公開します。コードから Playwright、Puppeteer、Selenium、または Stagehand（Playwright 上に構築された AI プリミティブ）を使用してブラウザーを操作できます。@browserbasehq/sdk パッケージは、セッション、コンテキスト、拡張機能、プロジェクト向けの薄い REST クライアントであり、ブラウザー自体を操作するものではありません。

ベース URL と認証

POST https://api.browserbase.com/v1/sessions
x-bb-api-key: $BROWSERBASE_API_KEY
Content-Type: application/json

すべての公式パッケージで使用する環境変数：

• BROWSERBASE_API_KEY — https://browserbase.com/settings から取得します
• BROWSERBASE_PROJECT_ID — Stagehand では必須です。@browserbasehq/sdk ではキーから推定されます

各ブラウザーは専用 VM で実行され、セッション終了後に破棄されます。すべてのプランで SOC 2 Type II に対応し、Scale では HIPAA に対応します。

3 つの統合方法

方法	パッケージ	最適な用途
生の SDK	@browserbasehq/sdk	セッション／コンテキスト／拡張機能の管理。ブラウザー操作は行いません
SDK + Playwright/Puppeteer	@browserbasehq/sdk + playwright-core または puppeteer-core	決定論的なスクリプトによる自動化
Stagehand	@browserbasehq/stagehand	Playwright 上での AI 駆動型 act／extract／observe／agent

SDK は REST のみです。ブラウザーの制御には connectUrl（Playwright/Puppeteer/CDP）または seleniumRemoteUrl（Selenium）を使用します。Stagehand は SDK と Playwright を内部でラップします。

クイックスタート — Playwright（TypeScript）

import { chromium } from 'playwright-core';
import Browserbase from '@browserbasehq/sdk';

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

const session = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID!,
});

const browser = await chromium.connectOverCDP(session.connectUrl);
const defaultContext = browser.contexts()[0];
const page = defaultContext.pages()[0];

await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
await page.screenshot({ path: 'shot.png', fullPage: true });

await page.close();
await browser.close();
console.log(`Replay: https://browserbase.com/sessions/${session.id}`);

クイックスタート — Puppeteer（TypeScript）

import puppeteer from 'puppeteer-core';
import Browserbase from '@browserbasehq/sdk';

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });
const session = await bb.sessions.create({ projectId: process.env.BROWSERBASE_PROJECT_ID! });

const browser = await puppeteer.connect({ browserWSEndpoint: session.connectUrl });
const [page] = await browser.pages();
await page.goto('https://example.com');
await browser.disconnect();

クイックスタート — Stagehand（TypeScript）

import { Stagehand } from '@browserbasehq/stagehand';
import { z } from 'zod';

const stagehand = new Stagehand({
  env: 'BROWSERBASE',
  apiKey: process.env.BROWSERBASE_API_KEY,
  projectId: process.env.BROWSERBASE_PROJECT_ID,
  model: 'google/gemini-3-flash-preview', // routed through Browserbase Model Gateway
});

await stagehand.init();
const page = stagehand.page;
await page.goto('https://news.ycombinator.com');

await page.act('click the first story link');
const data = await page.extract({
  instruction: 'extract the title and points',
  schema: z.object({ title: z.string(), points: z.number() }),
});

await stagehand.close();

クイックスタート — 生の HTTP

curl -X POST https://api.browserbase.com/v1/sessions \
  -H "x-bb-api-key: $BROWSERBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"'"$BROWSERBASE_PROJECT_ID"'"}'

セッション — リクエスト形式

type CreateSessionParams = {
  projectId: string;                  // optional with SDK; required via REST
  extensionId?: string;
  timeout?: number;                   // 60–21600 sec; defaults to project setting
  keepAlive?: boolean;                // Hobby+; survives disconnect
  region?: 'us-west-2' | 'us-east-1' | 'eu-central-1' | 'ap-southeast-1';
  proxies?: boolean | ProxyConfig[];
  userMetadata?: Record<string, string>; // ≤512 chars JSON, string values, no arrays
  browserSettings?: {
    context?: { id: string; persist?: boolean };
    viewport?: { width: number; height: number };
    blockAds?: boolean;               // default false
    solveCaptchas?: boolean;          // default true
    recordSession?: boolean;          // default true
    logSession?: boolean;             // default true
    advancedStealth?: boolean;        // Scale plan
    verified?: boolean;               // Scale plan, premium fingerprint
    captchaImageSelector?: string;
    captchaInputSelector?: string;
    os?: 'windows' | 'mac' | 'linux' | 'mobile' | 'tablet';
    ignoreCertificateErrors?: boolean; // default true
  };
};

セッション — レスポンス形式

type Session = {
  id: string;
  createdAt: string; updatedAt: string;
  startedAt?: string; endedAt?: string; expiresAt?: string;
  projectId: string;
  status: 'PENDING' | 'RUNNING' | 'ERROR' | 'TIMED_OUT' | 'COMPLETED';
  region: string;
  contextId?: string;
  keepAlive: boolean;
  proxyBytes: number;
  userMetadata?: Record<string, string>;
  connectUrl: string;            // wss://… CDP endpoint
  seleniumRemoteUrl: string;     // https://… Selenium grid
  signingKey: string;
};

connectUrl はブラウザー接続ごとに 1 回のみ使用できます。切断後に同じ connectUrl で再接続するには、keepAlive: true が必要です。

デフォルトコンテキストに関する注意点

Browserbase はブラウザーコンテキストを事前に作成します。Playwright で browser.newContext() を呼び出すと 2 つ目のコンテキストが生成され、browserSettings.context／プロキシが無視されます。既存のコンテキストを使用してください。

const defaultContext = browser.contexts()[0];
const page = defaultContext.pages()[0]; // pre-created blank page

ライフサイクル

// Release a session early
await bb.sessions.update(session.id, {
  projectId: process.env.BROWSERBASE_PROJECT_ID!,
  status: 'REQUEST_RELEASE',
});

// Live debugger URLs
const live = await bb.sessions.debug(session.id);
// { debuggerUrl, debuggerFullscreenUrl, wsUrl, pages: [{ id, url, debuggerUrl, ... }] }

// Filter sessions by metadata
const matches = await bb.sessions.list({ q: "user_metadata['env']:'staging'" });

機能一覧

機能	トリガー	リファレンス
セッション API 全般：作成／一覧表示／取得／更新／デバッグ、ライフサイクル、リージョン、キープアライブ、メタデータ	bb.sessions.*	references/sessions.md
Playwright + Puppeteer の接続パターン、デフォルトコンテキストの注意点、スクリーンショット、ナビゲーション	connectOverCDP, puppeteer.connect	references/playwright-puppeteer.md
Stagehand の AI プリミティブ：act／extract／observe／agent、ConstructorParams、Model Gateway、BYO LLM	import { Stagehand }	references/stagehand.md
Contexts、persist: true、サイトごとに 1 つというルールによる認証状態の永続化	bb.contexts.*, browserSettings.context	references/contexts.md
Browserbase 管理／外部／なしのプロキシ、位置情報、domainPattern ルール	proxies: true, proxies: [{type:...}]	references/proxies.md
高度なステルス機能、検証済みブラウザー、CAPTCHA の解決（カスタムセレクター）、広告ブロック	advancedStealth, verified, solveCaptchas	references/stealth-and-captcha.md
ダウンロード（Browser.setDownloadBehavior で "downloads" を指定）、アップロード（setInputFiles、大容量ファイル API）、ファイル選択ダイアログ	bb.sessions.downloads.*, bb.sessions.uploads.*	references/downloads-uploads.md
ライブビュー、録画（rrweb）、ログ、デバッガー URL、埋め込み	bb.sessions.debug, sessions.recording, sessions.logs	references/observability.md
アップロードした zip を使用したカスタム拡張機能	bb.extensions.create, extensionId	references/extensions.md

常に最新のドキュメント

任意のドキュメントページの末尾に .md を追加すると、整った Markdown を取得できます。

• はじめに：https://docs.browserbase.com/reference/introduction.md
• Node SDK リファレンス：https://docs.browserbase.com/reference/sdk/nodejs.md
• セッション作成 API：https://docs.browserbase.com/reference/api/create-a-session.md
• 全内容の統合版：https://docs.browserbase.com/llms-full.txt
• インデックス：https://docs.browserbase.com/llms.txt
• SDK のソース：https://github.com/browserbase/sdk-node
• Stagehand のソース：https://github.com/browserbase/stagehand

よくある落とし穴

• browser.newContext() ではなく browser.contexts()[0] を使用してください — 事前に作成されたコンテキストのみが、browserSettings.context、プロキシ、フィンガープリントを適用します。
• Browser.setDownloadBehavior の downloadPath は、リテラル文字列 "downloads" です — /tmp/downloads などの絶対パスを指定すると、同期処理に失敗します。
• solveCaptchas のデフォルト値は true です — コンプライアンスや監査を目的とする実行では無効にしてください。
• recordSession と logSession のデフォルト値は true です — プライバシーに配慮が必要なワークフローでは無効にしてください。セッション中に再度有効にすることはできません。
• connectUrl は CDP 接続ごとに一度だけ使用できます — 切断後に再接続するには、keepAlive: true が必要です。
• userMetadata の JSON 上限は 512 文字で、値は文字列のみ、配列は使用できません — q: "user_metadata['env']:'staging'" でクエリしてください。
• Stagehand には BROWSERBASE_PROJECT_ID が必要です。一方、SDK 単体では API キーから推定できます。
• 無料プランの同時実行数は 3 セッションで、作成エンドポイントではレート制限が適用されます。最大同時実行数を下回っている場合も同様です。
• verified: true と advancedStealth は Scale プラン専用です — 下位プランでは 4xx エラーになります。
• browserbase プロキシのセッションごとの最低使用量は 1 MB で、その後は最も近い MB 単位に切り上げられます。制限対象カテゴリのサイト（Apple、金融、ストリーミング、チケット販売、一部の Google サイト）へのアクセスはブロックされます。
• セッションは明示的に解放しない限り、スクリプトの終了後も維持されます — sessions.update で REQUEST_RELEASE を送信するか、timeout の期限切れを待ってください。keepAlive を指定すると、さらに長く維持されます。
• os と verified を併用するには、Scale プランが必要です — os: 'windows' | 'mac' | 'linux' | 'mobile' | 'tablet'。
• Selenium では connectUrl ではなく seleniumRemoteUrl を使用します — プロトコルがまったく異なります。