This release is a pre-release and may not be stable for production use.
Stagehand is the SDK for browser agents.
Read the Docs
Stagehand Python SDK
What is Stagehand?
Stagehand is the SDK for browser agents. Playwright was built for testing, Stagehand is built for agents. Use familiar APIs, self-healing actions, and network-level security across TypeScript, Python, and Go.
Why Stagehand?
Stagehand gives browser agents an interface built for how they actually work. It combines familiar Playwright-style APIs with self-healing actions, agent-optimized page context, and native support for complex DOM structures like out-of-process iframes and closed Shadow DOMs.
Agents use fewer tokens, recover when websites change, and complete tasks more reliably. With a complete browser driver across TypeScript, Python, and Go, Stagehand delivers the flexibility of AI without sacrificing the speed, control, determinism, reliability, and observability required in production.
For the full overview, examples, and contributing guide, see the main README.
Example
The async Python SDK for Stagehand browser automation:
import asyncio
import os
from pydantic import BaseModel
from stagehand import Stagehand, browserbase, local_browser
class PullRequest(BaseModel):
author: str
title: str
async def main() -> None:
browser = await local_browser.launch(headless=True)
try:
stagehand = await Stagehand.create(
browser=browser,
model="openai/gpt-5.4-mini",
model_api_key=os.environ["OPENAI_API_KEY"],
)
try:
page = (await browser.context.pages())[0]
await page.goto("https://github.com/browserbase")
# act() executes individual actions
await stagehand.act("click on the stagehand repo")
# observe() reports what is actionable on the page
observed = await stagehand.observe("find the latest PR")
# Locators give deterministic, Playwright-style actions
await page.locator(observed.data[0].selector).click()
# extract() returns structured data validated by a pydantic model
result = await stagehand.extract(
"extract the author and title of the PR",
PullRequest,
)
print(result.data.author, result.data.title)
finally:
await stagehand.close()
finally:
await browser.close()
asyncio.run(main())
See examples for action, extraction, observation, and custom LLM usage.
For hosted browsers, import browserbase from stagehand and use
browserbase.launch(api_key=...) or browserbase.connect(api_key=..., session_id=...) instead of
local_browser. A launched session is released when you close() the browser handle, except with
keep_alive=True: that handle's close() only disconnects, and the session keeps running until it
is released out of band (Browserbase dashboard or API) or reaches its configured timeout. The
Stagehand extension that launch() uploaded for that session is retained on the account for the
same reason, so a keep_alive=True workflow that launches repeatedly accumulates extensions until
they are deleted out of band. Sessions reached through browserbase.connect() are never released by
close() — whoever created the session owns it.
The same browserbase facade exposes Browserbase Search and Fetch without launching a browser:
import asyncio
import os
from stagehand import browserbase
async def search_and_fetch() -> None:
results = await browserbase.search(
api_key=os.environ["BROWSERBASE_API_KEY"],
query="browser agent frameworks",
num_results=5,
)
fetched = await browserbase.fetch(
api_key=os.environ["BROWSERBASE_API_KEY"],
url=results.results[0].url,
format="markdown",
)
print(fetched.content)
asyncio.run(search_and_fetch())
Stagehand.act(), Stagehand.observe(), and Stagehand.extract() use the active page by
default. Pass page=page to target a specific SDK Page.
Page.goto(), reload(), go_back(), and go_forward() return the main-document Response,
or None when navigation does not produce one. Response bodies and complete headers are retrieved
lazily while the Stagehand session remains open.
When contributing examples or tests, keep browser ownership explicit: launch or connect a
browser handle, pass it to Stagehand.create(), close Stagehand first, and close the browser in
the outermost finally block.
Contributing
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install just
brew install just
just install
just generate
just check
just test
just build
2 maintainers
Metadata
2 maintainers
Release files for stagehand 4.2.0a0.dev1575
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| stagehand-4.2.0a0.dev1575.tar.gz | 501.2 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| stagehand-4.2.0a0.dev1575-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.0 MB
Release files / stagehand-4.2.0a0.dev1575.tar.gz
| Download URL | stagehand-4.2.0a0.dev1575.tar.gz |
|---|---|
| Size | 501.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
46a673a5d02aa7598b4fa191e1e70f736fe4c17ab47a40e743b7a07a772caca6
|
|
BLAKE2b-256 checksum How to use checksums |
f69c8fce78bafeb165a3e6ead90c2e895c22470810b17980ce301736e60f6ff2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / stagehand-4.2.0a0.dev1575-py3-none-any.whl
| Download URL | stagehand-4.2.0a0.dev1575-py3-none-any.whl |
|---|---|
| Size | 513.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8d7fc35c3e5a9bc59dcfc6f9cbf19c5dd9fbef1135b20e89a2a6dae4c3977003
|
|
BLAKE2b-256 checksum How to use checksums |
23fe6e5acce81bb3c0dba129df4beff5382ea64466718c7bb3e3f29dc99dfd76
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
