Skip to main content
Version: 1.7

StagehandBrowserController

Controller for managing a Stagehand-controlled browser instance.

It creates and connects to the browser lazily on the first new_page call: Stagehand starts a session, and Playwright then connects to it via CDP. All pages share a single browser context, as Stagehand creates the browser and its context together during session initialisation.

Hierarchy

Index

Methods

Properties

Methods

__init__

  • __init__(*, playwright, stagehand_client, stagehand_options, max_open_pages_per_browser, header_generator): None

  • Initialize a new instance.

    Parameters

    • keyword-onlyplaywright: Playwright

      Active Playwright instance used to connect to the browser via CDP.

    • keyword-onlystagehand_client: AsyncStagehand

      Active Stagehand REST client used to start and end sessions.

    • keyword-onlystagehand_options: StagehandOptions

      Stagehand-specific configuration (model, env, self-heal, etc.).

    • optionalkeyword-onlymax_open_pages_per_browser: int = 20

      Maximum number of pages that can be open at the same time.

    • optionalkeyword-onlyheader_generator: HeaderGenerator | None = _DEFAULT_HEADER_GENERATOR

      An optional HeaderGenerator instance used to generate and manage HTTP headers for requests made by the browser. By default, a predefined header generator is used. Set to None to disable automatic header modifications.

    Returns None

close

  • async close(*, force): None

  • Close the browser.

    Parameters

    • optionalkeyword-onlyforce: bool = False

      Whether to force close all open pages before closing the browser.

    Returns None

new_page

  • async new_page(browser_new_context_options, proxy_info): StagehandPage

  • Create a new page in the Stagehand-managed browser.

    On the first call, starts the Stagehand session with the provided options. On subsequent calls, browser_new_context_options and proxy_info are ignored because the session context cannot be reconfigured once it is running.

    Parameters

    • optionalbrowser_new_context_options: Mapping[str, Any] | None = None

      Options merged on top of the plugin's launch options when creating the first session. Ignored if the session already exists.

    • optionalproxy_info: ProxyInfo | None = None

      Proxy injected into the session on first creation.

    Returns StagehandPage

Properties

AUTOMATION_LIBRARY

AUTOMATION_LIBRARY: str | None

The name of the automation library that the controller is using.

browser_type

browser_type: BrowserType

Return the type of the browser.

has_free_capacity

has_free_capacity: bool

Return if the browser has free capacity to open a new page.

idle_time

idle_time: timedelta

Return the idle time of the browser controller.

is_browser_connected

is_browser_connected: bool

Return if the browser is closed.

last_page_opened_at

last_page_opened_at: datetime

Return the time when the last page was opened.

pages

pages: list[Page]

Return the list of opened pages.

pages_count

pages_count: int

Return the number of currently open pages.

total_opened_pages

total_opened_pages: int

Return the total number of pages opened since the browser was launched.

Page Options