browserbase-sdk

Browserbase SDK

Browserbase 在隔离的 VM 中运行生产级无头 Chromium，并为每个会话提供一个 CDP WebSocket。代码通过 Playwright、Puppeteer、Selenium 或 Stagehand（基于 Playwright 构建的 AI 原语）驱动浏览器。@browserbasehq/sdk 包是用于会话、上下文、扩展和项目的轻量 REST 客户端——它本身不驱动浏览器。

Base 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。

三种集成方式

方式	包	适用场景
原始 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 只能使用一次。断开连接后，若要重新连接同一个 connectUrl，需要设置 keepAlive: true。

默认上下文注意事项

Browserbase 会预先创建浏览器上下文。在 Playwright 中调用 browser.newContext() 会新建第二个上下文，并忽略 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、自带 LLM	import { Stagehand }	references/stagehand.md
通过上下文持久化身份验证状态、persist: true、每个站点一个上下文的规则	bb.contexts.*, browserSettings.context	references/contexts.md
Browserbase 管理的/外部/无代理、地理位置、domainPattern 规则	proxies: true, proxies: [{type:...}]	references/proxies.md
高级隐身、已验证浏览器、验证码求解（自定义选择器）、屏蔽广告	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

始终保持最新的文档

在任意文档页面的 URL 后添加 .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.contexts()[0]，而不是 browser.newContext() —— 只有预先创建的上下文会应用 browserSettings.context、代理和指纹。
• Browser.setDownloadBehavior 的 downloadPath 是字面字符串 "downloads" —— /tmp/downloads 这类绝对路径会导致同步失败。
• solveCaptchas 默认为 true —— 合规性或审计运行时请将其禁用。
• recordSession 和 logSession 默认为 true —— 对隐私敏感的流程中请将其禁用；会话中途无法重新启用。
• 每次 CDP 连接中的 connectUrl 只能使用一次 —— 断开连接后若要重新连接，需要设置 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 使用 seleniumRemoteUrl，而不是 connectUrl —— 两者使用完全不同的协议。