Browserbase Changelog

We’re excited to welcome a new leading search provider to our Browserbase Search API.

Parallel comes with 2 search modes: Parallel Fast returns sub-second results when speed matters. Parallel Advanced goes deeper for multi-step research when quality matters most.

By default, any Browserbase Search request defaults to Parallel Advanced. You can switch your provider and mode at any time

import { Browserbase } from "@browserbasehq/sdk";

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

const response = await bb.search.web({
  query: "browserbase",
  provider: "parallel",
  mode: "fast", // enable Parallel's fast search mode
  numResults: 10,
});

console.log(`Request ID: ${response.requestId}`);
for (const result of response.results) {
  console.log(`${result.title} - ${result.url}`);
}

→ Read the docs

We're excited to announce Stagehand 4.2!

In this release, we've focused on helping browser agents update WebMCP tools as pages change, export documents programmatically, and give developers more control over how long browser operations run.

Here are the highlights:

• WebMCP tools that change with the page — subscribe to page.onToolsAdded() and page.onToolsRemoved() to react as websites expose new actions or update their forms. Useful for checkout flows where available inputs and actions change throughout the session.
• Native PDF exports — export browser pages as PDFs, with configurable print settings. Save invoices, reports, and other documents directly from your browser workflow.
• Timeouts for locator operations and snapshots — configure { timeout } on locator.click(), fill(), other locator operations, and page.snapshot(). Defaults to 20 seconds; use timeout: 0 to disable it.
• More reliable iframe and shadow DOM interactions — iframe-crossing page.locator() calls wait for the frame to be ready, page.snapshot({ includeIframes: true }) produces correct element references across frames, and XPath text() selectors correctly match direct text on pages with shadow DOM.

Give it a try and tell us what you build!

Browserbase Functions now support Secrets, so you can securely use credentials and API keys when connecting to external services.

Store a secret in Browserbase, then reference it at runtime from your Function’s ctx object without hardcoding sensitive values in your source code. This makes it safer to build Functions that authenticate with third-party APIs, databases, and other providers.

Secrets can be created and managed through the API and SDK, with CLI support for local workflows.

What you can do

• Securely store credentials in Browserbase
• Reference secrets at runtime in Functions
• Build authenticated workflows with external providers
• Keep sensitive values out of your code and logs

Learn more: ${ docs url }

defineFn("login-example", async (context) => {
  const { LOGIN_EMAIL, LOGIN_PASSWORD } = context.secrets;

  const browser = await chromium.connectOverCDP(
    context.session.connectUrl,
  );
  const browserContext = browser.contexts()[0]!;
  const page = browserContext.pages()[0] ?? await browserContext.newPage();

  await page.goto("https://your-app.example/login");
  await page.getByLabel("Email", { exact: true }).fill(LOGIN_EMAIL);
  await page.getByLabel("Password", { exact: true }).fill(LOGIN_PASSWORD);
  await page.getByRole("button", { name: "Sign in", exact: true }).click();

  return { loggedIn: true, heading, sessionId: context.session.id };
});

Agents can now pause mid-run for human-in-the-loop steps, then resume in the same session. Set a natural-language pauseWhen condition on the run; the agent gets a pause tool and enters PAUSED when that condition is met. Resume with a follow-up task.

const run = await bb.agents.runs.create({
  task: "Open the app and wait for the MFA challenge",
  pauseWhen: "an MFA or verification code is required",
});

// Later, after the user provides the code:
await bb.agents.runs.resume(run.id, {
  task: "Continue with the verification code 123456",
});

We're excited to announce Stagehand 4.1!

In this release, we've focused on providing first-class support for the Browserbase platform, namely our Fetch and Search APIs, as well as improving support for WebMCP across all websites, which helps agents interact with the web more reliably and deterministically.

Here are the highlights:

• WebMCP works better with iframes — discover and call tools inside embedded frames running in separate browser processes.
• First-party Search + Fetch tools — use browserbase.search() and browserbase.fetch() directly from Stagehand without needing to import the Browserbase SDK separately. Available in every language!
• Clearer close behavior — stagehand.close() now preserves the browser for reuse. browser.close() and browser.context.close() terminate it, regardless of keepAlive status.

Full release notes

We can't wait to see what you build!

Webhooks are now available for Browserbase Functions. Create a Webhook in the Browserbase dashboard and subscribe to events like Function pending, running, completed, and failed.

const webhook = await bb.webhooks.create({
  endpoint: "https://your.tunnel/browserbase/events",
  eventTypes: [
    "functions.invocations.completed",
    "functions.invocations.failed",
  ],
});

Search gives your agents read access to the internet, extending their context with the most up‑to‑date information.

Now, Search is natively in our dashboard, allowing you to sample queries before taking them to production.

Stagehand v4 caches act(), observe(), and extract() results on Browserbase's servers. Now you control it.

Pass cache to set a hit-count threshold - how many identical results Browserbase must see before it starts serving that result from the cache. A hit skips inference entirely: no model call, no tokens.

const stagehand = await Stagehand.create({
  browser,
  cache: { threshold: 2 }, // Serve hits after two identical results
});

// Prime this one step aggressively: the second call is a hit
await stagehand.act("click the Sign in button", {
  cache: { threshold: 1 },
});

Read the docs →

Plus:

• Every call can override the instance setting; pass cache: false to skip the cache for a single step.
• Results carry metadata.cache with a HIT / MISS / DISABLED status, a miss reason, and the tokens a hit saved.
• Model configuration stays out of the cache key, so switching models does not invalidate your cache.

You can now assign human-readable names your Contexts for easier recall, and view all previously created Contexts in the dashboard.

Create new Contexts, delete old ones, and see all previous browser sessions created using a specific Context.

Enterprise customers can now deliver Chrome DevTools Protocol (CDP) session logs straight to their own AWS S3 bucket.

BYOS is available on Enterprise plans and enabled per project. See the BYOS setup guide to get started, or contact your account manager.

Playwright was built for testing, we built Stagehand for your agent: improved context management, self-healing actions, and iframe support.

Stagehand now lives in the browser as an extension, bringing the local experience to remote browsers. Being in the browser means lower round trip time, which makes actions execute faster and minimizes potential CDP race conditions.

We benchmarked v4 extensively and found that it’s performs 2x faster than Playwright, while being ~80% more token efficient.

Fetch lets your agents read any page on the internet as Markdown or HTML. You can now view past Fetch calls, inspect their responses, and rerun them directly in the playground.