browserbase/stagehand-python

What it solves

Stagehand is a browser automation framework that lets you control web browsers using a mix of natural language and code. Most browser automation tools are either too low-level (like Selenium or Playwright) or too unpredictable (like high-level AI agents). Stagehand tries to bridge that gap: you can use AI for unfamiliar pages and fall back to precise code when you know exactly what to do. This Python SDK communicates with the Stagehand API to perform browser actions like clicking, observing, extracting data, and executing multi-step instructions.

Note: This specific repository (stagehand-python) is no longer maintained. The official Stagehand Python source has moved to the main Stagehand monorepo (browserbase/stagehand), and this version will not receive updates, bug fixes, or security patches.

How it works

The SDK is a client for the Stagehand API. You start a session, connect a browser (via Browserbase or a local Playwright browser), and then call methods like observe, act, extract, and execute to perform tasks. These methods accept natural-language instructions and return results as Pydantic models. The SDK supports both synchronous (Stagehand) and asynchronous (AsyncStagehand) clients, configurable with API keys and environment variables. It includes streaming responses via Server-Sent Events (SSE), raw response access, error handling with automatic retries, and timeouts. The README shows examples of using the SDK with Playwright to connect to a remote browser, observe elements, click links, and extract structured data based on a schema.

Who it’s for

Developers who want to build reliable, production-grade browser automations using AI. It’s for teams that need to automate interactions with websites that change often and want a mix of human-written code and AI flexibility. Because this SDK requires a Stagehand API and API keys (for model and browserbase), it’s aimed at users who are comfortable with cloud-based browser orchestration.

Highlights

• Natural language + code hybrid: Choose between AI-driven instructions and explicit code for actions, giving you control and reliability.
• Session-based API: Start a session, connect a browser, and run operations like observe, act, extract, and execute.
• Streaming and raw responses: Support for Server-Sent Events (SSE) streaming and access to raw HTTP responses for debugging.
• Multiple client modes: Synchronous and asynchronous clients, with aiohttp support for better concurrency.
• Configurable error handling: Retries, timeouts, and strict response validation options.
• Deprecated status: The repository is no longer maintained; users are directed to the new location (browserbase/stagehand) for the official SDK.