Browserbase Changelog

We're excited to announce Stagehand 4.4!

This release is about long-lived browsers. You can now let go of a browser without closing it, come back to it later, and trust Stagehand to clean up when your process dies. Here are the highlights:

Disconnect from a browser and reattach later

browser.disconnect() closes Stagehand's connection without closing the browser or releasing its Browserbase session. Tabs, cookies, and signed-in profiles stay where they are. Connect again with localBrowser.connect({ cdpUrl }) or browserbase.connect({ sessionId }), create a new Stagehand instance, and pick up where you left off. Available in TypeScript and Python.

const browser = await browserbase.launch({
  apiKey: process.env.BROWSERBASE_API_KEY,
  keepAlive: true,
});
const stagehand = await Stagehand.create({ browser });
const sessionId = browser.sessionId!;

// Let go: Stagehand closes, the session keeps running
await browser.disconnect();

// Later, from any process
const again = await browserbase.connect({
  apiKey: process.env.BROWSERBASE_API_KEY,
  sessionId,
});
const stagehand2 = await Stagehand.create({ browser: again });

The same works for a local Chrome you started yourself:

let browser = await localBrowser.connect({ cdpUrl: "http://127.0.0.1:9222" });
let stagehand = await Stagehand.create({ browser });

await browser.disconnect(); // Chrome and its tabs keep running

browser = await localBrowser.connect({ cdpUrl: "http://127.0.0.1:9222" });
stagehand = await Stagehand.create({ browser });

On Browserbase, keepAlive decides whether the session survives the disconnect, so launch with keepAlive: true. Calling close() on a handle after you disconnect it throws, so you never close a browser you meant to keep. Read the docs.

Crash-safe sessions

If your SDK process crashes or gets killed, the Stagehand extension now notices from inside the browser, without heartbeats or timers, and cleans up. A local Chrome that Stagehand launched without keepAlive shuts down instead of being orphaned. A keepAlive browser or Browserbase session is released so a new client can attach right away. The watchdog needs Chrome 137 or later.

That also means keepAlive actually works on local browsers now: launch with localBrowser.launch({ keepAlive: true }) and Chrome outlives your script, ready for you to reconnect.

Built on Stagehand: browser use in LangChain Deep Agents

LangChain is giving Deep Agents a browser, and the tools are built on Stagehand. Managed Deep Agents now runs a browser for your agent, with browser_snapshot, browser_run, browser_screenshot, and browser_handoff tools. In LangChain's tests on 100 WebVoyager tasks, the Stagehand-based tools passed 90% for $1.98 in total, the highest pass rate of the seven toolsets they tested. The runner-up passed 89% at 9x the cost.

For open source agents, LangChain now ships langchain-stagehand on PyPI. StagehandMiddleware gives any LangChain or Deep Agents agent Stagehand's run, snapshot, and screenshot tools over one persistent browser, local Chrome or Browserbase, with no MCP server needed.

from deepagents import create_deep_agent
from langchain_stagehand import StagehandMiddleware
from stagehand import Stagehand, browserbase

browser = await browserbase.launch(api_key=os.environ["BROWSERBASE_API_KEY"])
stagehand = await Stagehand.create(browser=browser)

agent = create_deep_agent(
    "anthropic:claude-sonnet-4-6",
    middleware=[StagehandMiddleware(stagehand=stagehand)],
)

Read Sydney Runkle's post, Browser Use in Managed Deep Agents, or get started with the browser use guide.

Here's what else is new:

• Cross-origin iframes are more reliable: iframes that were already loaded when Stagehand attached (for example after a reconnect), or that are nested inside another cross-origin iframe, are now picked up, so snapshots and actions can reach them (#3339). act() also no longer stops cross-origin iframes from loading (#3388).
• Know when a connection is gone: browser handles expose connected, which reports whether the handle still has a live connection, and cdpUrl (cdp_url in Python) for local browsers, so you always know where to reconnect.
• Claude Opus 5.5 fixes: act(), observe(), and extract() now work correctly with Claude Opus 5.5 (#3340).
• Tighter domain policies: closed ways around domain allow and block lists through URLs with credentials, background requests, and speculative page loads (#3387).

Give it a try and tell us what you build!

Control where your browser agents can go with Navigation Policies. Define which categories of sites to allow or block, add rules for specific domains, and reuse the same policy across sessions.

For example, a research agent can browse classified sites while blocking gambling, adult content, malware, and phishing sites. You can also choose how to handle unclassified domains. Domain overrides take priority over category rules and apply to subdomains, so you can make exceptions for sites your workflow needs.

Create a policy through the API, then pass its ID as browserSettings.riskPolicyId when starting a session. Browserbase checks page loads, iframe navigations, popups, and each redirect hop against that policy. Policy changes apply to new sessions; running sessions keep the policy they started with.

Contact support@browserbase.com to enable Navigation Policies for your project, then follow the setup guide to create your first policy.

Fetch can now reuse saved login cookies from a Browserbase Context to retrieve pages behind a login. Pass contextId to the existing Fetch endpoint and return the page as raw content, markdown, or structured JSON.

Log in through a browser session with persist: true, then end the session to save its cookies. Use that Context ID in subsequent Fetch requests to read authenticated pages without starting an interactive browser session for each request.

curl -X POST https://api.browserbase.com/v1/fetch \
  -H "Content-Type: application/json" \
  -H "X-BB-API-Key: $BROWSERBASE_API_KEY" \
  -d '{
    "url": "https://example.com/account/orders",
    "contextId": "<context-id>",
    "format": "markdown"
  }'

Authenticated Fetch uses the cookies from the last saved session and does not write updated cookies back to the Context. For pages that need JavaScript rendering or JavaScript-generated authentication tokens, use a browser session.

Learn more in our docs.

We’ve partnered with 1Password to let your agents sign in to websites securely, without ever seeing your passwords.

With our new 1Password integration, your agents can:

• Request access to a specific login when they hit a sign-in form
• Wait while you approve or deny the request from 1Password on your own device
• Have 1Password autofill and submit the credentials directly into the browser

Credentials never pass through your application, models, or logs. 1Password handles the OAuth connection, token management, and autofill inside the browser extension, and removes filled values after submission.

Browserbase sessions can be configured with zero data retention and no session recording or logging, so your agents can do real work—like logging into dashboards, SaaS tools, or test environments—while your secrets stay protected in your vault.

This release includes:

• Support for 1Password Agentic Autofill via the Browserbase extension system
• Guidance for securely storing client credentials, tokens, and integration keys on your backend

Get started today by reading our reference documentation.

We’re excited to announce Stagehand 4.3!

We’ve been working on more ways to build browser agents with your preferred models and tools, plus better control over how your workflows run. Here are the highlights:

Use Stagehand with the official OpenAI and Anthropic SDKs

Give GPT and Claude a browser through Stagehand’s toolset integrations. Build with the official model SDKs while Stagehand handles navigation, screenshots, and browser interactions. Available in TypeScript and Python, with local Chrome or Browserbase.

Get started with the OpenAI quickstart or Claude quickstart.

Here’s what else is new:

• New models without waiting for a Stagehand release — use new model IDs from supported providers including OpenAI, Anthropic, Google, Groq, and Cerebras. When your provider makes a model available, you can pass its ID directly to Stagehand without waiting for us to add it to a list. Details.
• Wait for the page to be ready — use page.waitForFunction() to wait for application state, updated text, or another browser-side condition before continuing. It supports async conditions and resumes polling after navigation while keeping the original timeout.
• More flexible remote browser connections — connect through authenticated CDP gateways using custom headers. When your application and the Stagehand extension need different routes to the same browser, configure a separate extensionCdpUrl.
• Bring the Stagehand extension to your own browser setup — getExtensionArchive() returns the bundled extension as ZIP bytes, ready to save or upload wherever you run Chrome.
• WebMCP support for newer Chromium versions — updated launch flags keep WebMCP enabled as Chromium’s feature flags change. Details.

Give it a try and tell us what you build!

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.