Registry / llm-agents / stagehand

stagehand

JSON →
library4.0.2pypypi✓ verified 21d ago

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.

pip install stagehand
INSTALL
IMPORT
SIG · STAGEHAND
S
stagehand
llm-agentspythonv4.0.2
Install
4.5s avg
Import
1128ms
Disk
56MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v3.23.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 1.164s · 32.9MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 4.5s · import 1.092s · 139MB
56MB installed
● package 56MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Stagehand
from stagehand import Stagehand
from stagehand.sync import Stagehand
AsyncStagehand
from stagehand import AsyncStagehand
Client
from stagehand import Client

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.")
Debug
Known issues
breakingSome 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'.
affects: v3.19.3, v3.19.4
gotchaFor 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.
affects: All versions
gotchaWhen 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`.
affects: All versions
gotchaThe 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.
affects: All versions
Upgrade
Version history
4.0.2latest on PyPI · released Aug 20, 2026
Audit
Dependencies
python>=3.9requiredRequired Python version.
playwrightrequiredUnderlying browser automation library for local execution.
httpxrequiredAsynchronous HTTP client for the SDK.
requestsrequiredSynchronous HTTP client for the SDK.
pydanticrequiredUsed for response modeling and data validation.
python-dotenvoptionalOptional for loading environment variables from .env files.
Agent activity
24 hits · last 30 days
node
18
OpenAI (training)
1
Resources
stagehand — pip install stagehand · libregistry