stagehand

What it is and what it does

Stagehand is a Python SDK designed specifically for building browser agents—autonomous systems that interact with web pages on behalf of AI models. Unlike Playwright, which was built for testing, Stagehand combines familiar Playwright-style APIs with agent-specific features: self-healing actions that adapt when websites change, agent-optimized page context that reduces token usage, and native support for complex DOM structures including out-of-process iframes and closed Shadow DOMs. The SDK provides three core methods—act() for executing individual actions, observe() for reporting actionable elements on a page, and extract() for returning structured data validated by Pydantic models—plus deterministic Playwright-style locators for precise control.

The package integrates with local browsers via local_browser or hosted Browserbase sessions, supports async Python workflows, and includes OpenTelemetry instrumentation for observability. It is actively maintained with recent releases and carries no known security vulnerabilities. The runtime depends on browserbase, pydantic, opentelemetry-api, and websockets, all of which are standard ecosystem packages. Stagehand is intended for production use in agent systems where reliability, determinism, and token efficiency matter.

Use it for:

• Automate multi-step web tasks like form filling, navigation, and data extraction for AI agents without manual DOM selector maintenance.
• Build autonomous agents that interact with GitHub, e-commerce, or SaaS platforms while adapting to UI changes through self-healing actions.
• Extract structured data from web pages into Pydantic models, validated and typed for downstream processing.
• Monitor and interact with dynamic web content including iframes and Shadow DOMs that standard browser automation tools struggle with.
• Reduce LLM token consumption by providing agent-optimized page context and deterministic action feedback.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Stagehand is a Python SDK for building browser agents with self-healing actions, agent-optimized APIs, and support for complex DOM structures like iframes and Shadow DOMs.

Yes. Stagehand is actively maintained, carries no known vulnerabilities, and is purpose-built for agent-driven browser automation with features (self-healing, agent-optimized context, complex DOM support) that address real pain points in autonomous web interaction. The MIT license and low install friction make it a straightforward choice for projects building production browser agents. Install if you are building AI agents that need to interact reliably with web interfaces.

Install

stagehand on PyPI

pip install stagehand

uv add stagehand

poetry add stagehand

Installing stagehand

Before you install

Active maintenance with a recent release and high repository engagement (23940 stars). Low install friction via a pure-Python wheel. Requires Python 3.11 or later and four runtime dependencies including browserbase, pydantic, opentelemetry-api, and websockets.

License in practice

MIT license permits commercial and private use with minimal restrictions, making it suitable for production agent applications.

Quickstart

import asyncio
from stagehand import Stagehand, local_browser

async def main():
    browser = await local_browser.launch(headless=True)
    stagehand = await Stagehand.create(browser=browser, model="openai/gpt-4-mini", model_api_key="...")
    await stagehand.act("click on element")
    result = await stagehand.observe("find something")
    await stagehand.close()
    await browser.close()

asyncio.run(main())

Requires Python 3.11 or later; LLM API credentials (e.g., OpenAI key) needed for agent operations.

Verify before relying

• Whether self-healing actions reduce token consumption compared to standard Playwright in typical agent workflows.
• Performance characteristics and latency profile for complex multi-step agent tasks.
• Compatibility and interoperability with non-OpenAI LLM providers beyond the documented examples.

Package facts

Evidence: stagehand-4.0.1-py3-none-any.whl

Keywords: ai, browser, automation, web-scraping, testing

Tags

More Artificial Intelligence packages

Further reading