{"id":4779,"library":"stagehand","title":"Stagehand","description":"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.","status":"active","version":"3.19.5","language":"en","source_language":"en","source_url":"https://github.com/browserbase/stagehand-python","tags":["browser automation","AI","web scraping","natural language processing","playwright"],"install":[{"cmd":"pip install stagehand","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Required Python version.","package":"python>=3.9","optional":false},{"reason":"Underlying browser automation library for local execution.","package":"playwright","optional":false},{"reason":"Asynchronous HTTP client for the SDK.","package":"httpx","optional":false},{"reason":"Synchronous HTTP client for the SDK.","package":"requests","optional":false},{"reason":"Used for response modeling and data validation.","package":"pydantic","optional":false},{"reason":"Optional for loading environment variables from .env files.","package":"python-dotenv","optional":true}],"imports":[{"symbol":"Stagehand","correct":"from stagehand.sync import Stagehand"},{"symbol":"StagehandConfig","correct":"from stagehand import StagehandConfig"}],"quickstart":{"code":"import os\nfrom stagehand.sync import Stagehand\nfrom stagehand import StagehandConfig\n\n# Ensure BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID are set in your environment\n# For local mode, set env=\"LOCAL\" and ensure a Chromium browser is installed.\napi_key = os.environ.get('BROWSERBASE_API_KEY', 'your_browserbase_api_key_here')\nproject_id = os.environ.get('BROWSERBASE_PROJECT_ID', 'your_browserbase_project_id_here')\n\nif not api_key or not project_id:\n    print(\"Warning: BROWSERBASE_API_KEY or BROWSERBASE_PROJECT_ID not found. \\n\"\\\n          \"Using placeholder values. For full functionality, set these environment variables.\")\n\ntry:\n    # Initialize Stagehand client for Browserbase cloud environment\n    config = StagehandConfig(\n        env=\"BROWSERBASE\",\n        api_key=api_key,\n        project_id=project_id\n    )\n    stagehand = Stagehand(config=config)\n    print(\"Stagehand client initialized.\")\n\n    # Navigate to a page\n    print(\"Navigating to example.com...\")\n    page = stagehand.context.pages()[0] # Get the default page\n    page.goto(\"https://www.example.com\")\n    print(\"Navigation complete.\")\n\n    # Use natural language to interact (act) and extract data\n    print(\"Performing an action: clicking a link...\")\n    # This 'act' command will try to find a link and click it\n    # For a deterministic action on example.com, a more specific instruction might be needed.\n    # For demonstration, we'll try a generic act.\n    # In a real scenario, you'd specify something like \"click the 'More information...' link\"\n    # if it existed and was prominent.\n    try:\n        page.act(\"click the first link on the page\")\n        print(\"Clicked the first link.\")\n    except Exception as e:\n        print(f\"Could not perform 'act' on a link: {e}\")\n        print(\"Continuing with extraction.\")\n\n    print(\"Extracting page heading...\")\n    # Extract the main heading using natural language\n    heading = page.extract(\"the main heading on the page\")\n    print(f\"Extracted heading: {heading}\")\n\n    # End the session\n    stagehand.close()\n    print(\"Stagehand session closed.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Ensure you have a valid Browserbase API key and project ID, or configure for local mode.\")","lang":"python","description":"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."},"warnings":[{"fix":"Refer to the official GitHub releases for the latest stable version and avoid versions explicitly marked as 'DO NOT USE'.","message":"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.","severity":"breaking","affected_versions":"v3.19.3, v3.19.4"},{"fix":"Set `BROWSERBASE_API_KEY` and `BROWSERBASE_PROJECT_ID` as environment variables, or pass them directly to `StagehandConfig` when initializing the client.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure a compatible browser is installed. If needed, configure the `CHROME_PATH` environment variable or pass `localBrowserLaunchOptions` in `StagehandConfig`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Regularly review the official documentation and changelog before major upgrades. Consider pinning minor versions in production environments to control updates.","message":"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'.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}