Stagehand (Python)

Stagehand is an AI browser automation framework, and this package is its official Python library. It lets you control real web browsers by combining natural-language instructions (act, extract, observe) with the precision of conventional Playwright-style code, so you choose which parts of an automation are AI-driven and which are deterministic.

Built by Browserbase, it adds self-healing and action caching so scripts keep working when pages change and skip LLM inference on repeatable steps, making browser automation practical in production.

What You Get

• Natural-language act, extract, and observe primitives over a real browser
• A code escape hatch to Playwright-style precision when you need it
• Action caching that replays repeatable steps without LLM inference
• Self-healing automations that adapt when a page’s markup changes
• Sync and async clients with local and Browserbase cloud execution

Common Use Cases

• Automating web workflows across sites with unpredictable or changing UIs
• Extracting structured data from pages using natural-language schemas
• Building production browser agents that stay reliable over time
• Prototyping automations in natural language, then hardening them into code

Under The Hood

Architecture - The package (src/stagehand/) follows a generated-client structure with a _base_client.py, _resource.py, session.py, streaming (_streaming.py), and typed models (_types.py), exposing a Stagehand entry point that manages a browser session and dispatches act/extract/observe operations to the AI + browser layer, with results returned as typed responses.

Tech Stack - Python packaged with Hatch (pyproject.toml, hatch_build.py), using uv for locking (uv.lock). It integrates with Playwright for browser control and LLM providers for the AI actions, and can run browsers locally or on Browserbase’s cloud.

Code Quality - The source is cleanly modularized into private underscore-prefixed core modules and a small public surface, with roughly 25 test modules under tests/, a CHANGELOG, and release automation via release-please. Naming and typing are consistent, reflecting a Stainless-style generated SDK base.

API Design - The public API is intentionally small and intent-driven: create a Stagehand session, then call act, extract, and observe. Mixing natural language and code in the same script is the core ergonomic win, and examples plus hosted docs make getting started a few lines of code.