Skip to main content
Version: Next

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

__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

register_page_closed

  • register_page_closed(page): None
  • Stop tracking the page as open.

    Implementations must call it from the page's close event. The BrowserPool also calls it when closing the page never finishes, in which case that event never arrives, so it can be called more than once for the same page.


    Parameters

    • page: Page

      The page that is no longer open.

    Returns None

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.

is_opening_pages

is_opening_pages: bool

Return if the browser has any new_page calls currently in flight.

last_page_opened_at

last_page_opened_at: datetime

Return the time when the last page was opened.

pages

pages: Sequence[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.