Stagehand

3.19.5 · active · verified Sun Apr 12

Stagehand is an AI-powered browser automation framework that allows controlling web browsers using natural language instructions and code. It is built on top of Playwright but integrates an intelligent agent to interpret high-level commands, making web automations more resilient and maintainable by reducing reliance on brittle CSS selectors. The Python library (stagehand-py) provides an official SDK for interacting with the Stagehand API, supporting both local browser environments and cloud execution via Browserbase. It is currently at version 3.19.5 and has a rapid release cadence.

Warnings

breaking Some minor versions have been marked as 'DO NOT USE' shortly after release (e.g., v3.19.4, v3.19.3). Always check the GitHub releases or changelog for the latest recommended version before upgrading to avoid known issues.
Fix: Refer to the official GitHub releases for the latest stable version and avoid versions explicitly marked as 'DO NOT USE'.
gotcha For cloud execution via Browserbase, `BROWSERBASE_API_KEY` and `BROWSERBASE_PROJECT_ID` environment variables are required for authentication. Without these, the client will default to local mode or fail to connect to the cloud service.
Fix: Set `BROWSERBASE_API_KEY` and `BROWSERBASE_PROJECT_ID` as environment variables, or pass them directly to `StagehandConfig` when initializing the client.
gotcha When running Stagehand in 'LOCAL' environment mode, a Chromium-based browser (like Chrome or Chromium) must be installed on the machine where the script is executed. If Stagehand cannot automatically locate it, you might need to specify its path using the `CHROME_PATH` environment variable or `browser.launchOptions.executablePath` in the configuration.
Fix: Ensure a compatible browser is installed. If needed, configure the `CHROME_PATH` environment variable or pass `localBrowserLaunchOptions` in `StagehandConfig`.
gotcha The library is actively developed and has a high release cadence, indicating rapid evolution. Features and APIs may change or be refined frequently as it is still considered an 'early release'.
Fix: Regularly review the official documentation and changelog before major upgrades. Consider pinning minor versions in production environments to control updates.

Install

pip install stagehand Install with pip

Imports

Stagehand
```
from stagehand.sync import Stagehand
```
StagehandConfig
```
from stagehand import StagehandConfig
```

Quickstart

This quickstart demonstrates how to initialize the Stagehand client, navigate to a URL, and perform AI-powered actions like clicking and extracting information using natural language instructions. It's configured for the Browserbase cloud environment, requiring `BROWSERBASE_API_KEY` and `BROWSERBASE_PROJECT_ID`. For local execution, `env="LOCAL"` can be set in `StagehandConfig`, but a Chromium-based browser must be installed and accessible.

import os
from stagehand.sync import Stagehand
from stagehand import StagehandConfig

# Ensure BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID are set in your environment
# For local mode, set env="LOCAL" and ensure a Chromium browser is installed.
api_key = os.environ.get('BROWSERBASE_API_KEY', 'your_browserbase_api_key_here')
project_id = os.environ.get('BROWSERBASE_PROJECT_ID', 'your_browserbase_project_id_here')

if not api_key or not project_id:
    print("Warning: BROWSERBASE_API_KEY or BROWSERBASE_PROJECT_ID not found. \n"\
          "Using placeholder values. For full functionality, set these environment variables.")

try:
    # Initialize Stagehand client for Browserbase cloud environment
    config = StagehandConfig(
        env="BROWSERBASE",
        api_key=api_key,
        project_id=project_id
    )
    stagehand = Stagehand(config=config)
    print("Stagehand client initialized.")

    # Navigate to a page
    print("Navigating to example.com...")
    page = stagehand.context.pages()[0] # Get the default page
    page.goto("https://www.example.com")
    print("Navigation complete.")

    # Use natural language to interact (act) and extract data
    print("Performing an action: clicking a link...")
    # This 'act' command will try to find a link and click it
    # For a deterministic action on example.com, a more specific instruction might be needed.
    # For demonstration, we'll try a generic act.
    # In a real scenario, you'd specify something like "click the 'More information...' link"
    # if it existed and was prominent.
    try:
        page.act("click the first link on the page")
        print("Clicked the first link.")
    except Exception as e:
        print(f"Could not perform 'act' on a link: {e}")
        print("Continuing with extraction.")

    print("Extracting page heading...")
    # Extract the main heading using natural language
    heading = page.extract("the main heading on the page")
    print(f"Extracted heading: {heading}")

    # End the session
    stagehand.close()
    print("Stagehand session closed.")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Ensure you have a valid Browserbase API key and project ID, or configure for local mode.")

view raw JSON →