Skip to main content
Version: Next

StagehandBrowserPlugin

A plugin for managing Stagehand AI-powered browser automation.

It acts as a factory for creating StagehandBrowserController instances and manages the lifecycle of the shared AsyncStagehand REST client and the Playwright context. Depending on the configured environment, the browser runs locally via a bundled Chromium binary (env='LOCAL') or in the Browserbase cloud (env='BROWSERBASE'). Playwright connects to the running browser via CDP, so only Chromium is supported.

Not all Playwright browser and context options are supported — only those accepted by Stagehand's BrowserLaunchOptions. Because Stagehand creates the browser and its context together in a single sessions.start() call, both browser_launch_options and browser_new_context_options are merged into one set of options applied at session start.

Hierarchy

Index

Methods

Properties

Methods

__aenter__

__aexit__

  • async __aexit__(exc_type, exc_value, exc_traceback): None

  • Exit the context manager and close the browser plugin.

    Parameters

    • exc_type: type[BaseException] | None
    • exc_value: BaseException | None
    • exc_traceback: TracebackType | None

    Returns None

__init__

  • __init__(*, user_data_dir, stagehand_options, browser_launch_options, browser_new_context_options, max_open_pages_per_browser): None

  • Initialize a new instance.

    Parameters

    • optionalkeyword-onlyuser_data_dir: (str | Path) | None = None

      Path to a user data directory, which stores browser session data like cookies and local storage.

    • optionalkeyword-onlystagehand_options: StagehandOptions | None = None

      Stagehand-specific configuration (model, API key, env, etc.).

    • optionalkeyword-onlybrowser_launch_options: dict[str, Any] | None = None

      Keyword arguments passed to Stagehand's BrowserLaunchOptions on session start. Supported keys are a subset of Playwright's browser_type.launch options. These take priority over browser_new_context_options for shared keys.

    • optionalkeyword-onlybrowser_new_context_options: dict[str, Any] | None = None

      Additional options merged with browser_launch_options at lower priority. Subject to the same BrowserLaunchOptions constraints.

    • optionalkeyword-onlymax_open_pages_per_browser: int = 20

      The maximum number of pages that can be open in a single browser instance. Once reached, a new browser instance will be launched.

    Returns None

new_browser

Properties

active

active: bool

Indicate whether the context is active.

AUTOMATION_LIBRARY

AUTOMATION_LIBRARY: str | None

The name of the automation library that the plugin is managing.

browser_launch_options

browser_launch_options: Mapping[str, Any]

Return the options passed to Stagehand's BrowserLaunchOptions on session start.

These are a subset of Playwright's browser_type.launch options — only keys recognised by Stagehand's BrowserLaunchOptions take effect.

browser_new_context_options

browser_new_context_options: Mapping[str, Any]

Return the browser context options passed to Stagehand's BrowserLaunchOptions.

Stagehand creates the browser and its context together in a single sessions.start() call, so context-level options such as viewport and locale are part of BrowserLaunchOptions and share the same dictionary as browser_launch_options. Pre-navigation hooks that modify these options before the first page will take effect, because session creation is deferred until the first new_page call.

browser_type

browser_type: BrowserType

Return the browser type name.

max_open_pages_per_browser

max_open_pages_per_browser: int

Return the maximum number of pages that can be opened in a single browser.

stagehand_options

stagehand_options: StagehandOptions

Return the Stagehand-specific configuration options.

Page Options