Python SDK

This documentation is automatically synced from the Python SDK GitHub repository.

Migrating from the old v2 Python SDK? See our migration guide here.

What is Stagehand?

Stagehand is a browser automation framework used to control web browsers with natural language and code. By combining the power of AI with the precision of code, Stagehand makes web automation flexible, maintainable, and actually reliable.

Why Stagehand?

Most existing browser automation tools either require you to write low-level code in a framework like Selenium, Playwright, or Puppeteer, or use high-level agents that can be unpredictable in production. By letting developers choose what to write in code vs. natural language (and bridging the gap between the two) Stagehand is the natural choice for browser automations in production.

Choose when to write code vs. natural language: use AI when you want to navigate unfamiliar pages, and use code when you know exactly what you want to do.
Go from AI-driven to repeatable workflows: Stagehand lets you preview AI actions before running them, and also helps you easily cache repeatable actions to save time and tokens.
Write once, run forever: Stagehand’s auto-caching combined with self-healing remembers previous actions, runs without LLM inference, and knows when to involve AI whenever the website changes and your automation breaks.

Installation

uv pip install stagehand

For local development or when working from this repository, sync the dependency lockfile with uv (see the Local development section below) before running project scripts.

Requirements

Python 3.9 or higher.

Running the Example

A complete working example is available at examples/full_example.py. To run it, first export the required environment variables, then use Python:

export BROWSERBASE_API_KEY="your-bb-api-key"
export MODEL_API_KEY="sk-proj-your-llm-api-key"

uv run python examples/full_example.py

Local mode example

If you want to run Stagehand locally, use the local example (examples/local_example.py). It shows how to configure the client for server="local". Local mode runs Stagehand’s embedded server and launches a local Chrome/Chromium browser (it is not bundled with the Python wheel), so you must have Chrome installed on the machine running the example. If Chrome is installed but Stagehand can’t find it, set CHROME_PATH to your browser executable (or pass browser.launchOptions.executablePath when starting the session). Common Windows paths:

C:\Program Files\Google\Chrome\Application\chrome.exe
C:\Program Files (x86)\Google\Chrome\Application\chrome.exe

PowerShell:

# optional if you don't already have Chrome installed
winget install -e --id Google.Chrome

# optional if Stagehand can't auto-detect Chrome
$env:CHROME_PATH="C:\Program Files\Google\Chrome\Application\chrome.exe"

uv run python examples/local_example.py

uv pip install stagehand
uv run python examples/local_example.py

Streaming logging example

See examples/logging_example.py for a remote-only flow that streams StreamEvents with verbose=2, stream_response=True, and x_stream_response="true" so you can watch the SDK’s logs as they arrive.

uv run python examples/logging_example.py

Usage

This example demonstrates the full Stagehand workflow: starting a session, navigating to a page, observing possible actions, acting on elements, extracting data, and running an autonomous agent.

import asyncio

from stagehand import AsyncStagehand

async def main() -> None:
    # Create client using environment variables:
    # BROWSERBASE_API_KEY, MODEL_API_KEY
    client = AsyncStagehand()

    # Start a new browser session (returns a session helper bound to a session_id)
    session = await client.sessions.create(model_name="openai/gpt-5-nano")

    print(f"Session started: {session.id}")

    try:
        # Navigate to a webpage
        await session.navigate(
            url="https://news.ycombinator.com",
        )
        print("Navigated to Hacker News")

        # Observe to find possible actions on the page
        observe_response = await session.observe(
            instruction="find the link to view comments for the top post",
        )

        results = observe_response.data.result
        print(f"Found {len(results)} possible actions")
        if not results:
            return

        # Take the first action returned by Observe and pass it to Act
        action = results[0].to_dict(exclude_none=True)
        print("Acting on:", action.get("description"))

        act_response = await session.act(input=action)
        print("Act completed:", act_response.data.result.message)

        # Extract structured data from the page using a JSON schema
        extract_response = await session.extract(
            instruction="extract the text of the top comment on this page",
            schema={
                "type": "object",
                "properties": {
                    "commentText": {"type": "string"},
                    "author": {"type": "string"},
                },
                "required": ["commentText"],
            },
        )

        extracted = extract_response.data.result
        author = extracted.get("author", "unknown") if isinstance(extracted, dict) else "unknown"
        print("Extracted author:", author)

        # Run an autonomous agent to accomplish a complex task
        execute_response = await session.execute(
            execute_options={
                "instruction": f"Find any personal website, GitHub, or LinkedIn profile for the Hacker News user '{author}'.",
                "max_steps": 10,
            },
            agent_config={"model": "openai/gpt-5-nano"},
            timeout=300.0,
        )

        print("Agent completed:", execute_response.data.result.message)
        print("Agent success:", execute_response.data.result.success)
    finally:
        # End the browser session to clean up resources
        await session.end()
        print("Session ended")

if __name__ == "__main__":
    asyncio.run(main())

Client configuration

Configure the client using environment variables:

from stagehand import AsyncStagehand

client = AsyncStagehand()

Or manually:

from stagehand import AsyncStagehand

client = AsyncStagehand(
    browserbase_api_key="My Browserbase API Key",
    model_api_key="My Model API Key",
)

Or using a combination of the two approaches:

from stagehand import AsyncStagehand

client = AsyncStagehand(
    # Configures using environment variables
    browserbase_api_key="My Browserbase API Key",  # override just this one
)

See this table for the available options:

Keyword argument	Environment variable	Required	Default value
`browserbase_api_key`	`BROWSERBASE_API_KEY`	true	-
`model_api_key`	`MODEL_API_KEY`	true	-
`base_url`	`STAGEHAND_API_URL`	false	`"https://api.stagehand.browserbase.com"`

Keyword arguments take precedence over environment variables.

[!TIP] Don’t create more than one client in the same application. Each client has a connection pool, which is more efficient to share between requests.

Modifying configuration

To temporarily use a modified client configuration while reusing the same connection pool, call with_options() on any client:

client_with_options = client.with_options(model_api_key="sk-your-llm-api-key-here", max_retries=42)

The with_options() method does not affect the original client.

Requests and responses

To send a request to the Stagehand API, call the corresponding client method using keyword arguments. Nested request parameters are dictionaries typed using TypedDict. Responses are Pydantic models which also provide helper methods like:

Serializing back into JSON: model.to_json()
Converting to a dictionary: model.to_dict()

Immutability

Response objects are Pydantic models. If you want to build a modified copy, prefer model.model_copy(update={...}) (Pydantic v2) rather than mutating in place.

Asynchronous execution

This SDK recommends using AsyncStagehand and awaiting each API call:

import asyncio
from stagehand import AsyncStagehand

async def main() -> None:
    client = AsyncStagehand()
    session = await client.sessions.create(model_name="openai/gpt-5-nano")
    response = await session.act(input="click the first link on the page")
    print(response.data)

asyncio.run(main())

With aiohttp

By default, the async client uses httpx for HTTP requests. For improved concurrency performance you may also use aiohttp as the HTTP backend. Install aiohttp:

uv run pip install stagehand[aiohttp]

Then instantiate the client with http_client=DefaultAioHttpClient():

import asyncio
from stagehand import AsyncStagehand, DefaultAioHttpClient

async def main() -> None:
    async with AsyncStagehand(http_client=DefaultAioHttpClient()) as client:
        session = await client.sessions.create(model_name="openai/gpt-5-nano")
        response = await session.act(input="click the first link on the page")
        print(response.data)

asyncio.run(main())

Streaming responses

We provide support for streaming responses using Server-Sent Events (SSE). To enable SSE streaming, you must:

Ask the server to stream by setting x_stream_response="true" (header), and
Tell the client to parse an SSE stream by setting stream_response=True.

import asyncio

from stagehand import AsyncStagehand

async def main() -> None:
    async with AsyncStagehand() as client:
        session = await client.sessions.create(model_name="openai/gpt-5-nano")

        stream = await client.sessions.act(
            id=session.id,
            input="click the first link on the page",
            stream_response=True,
            x_stream_response="true",
        )
        async for event in stream:
            # event is a StreamEvent (type: "system" | "log")
            print(event.type, event.data)

asyncio.run(main())

Raw responses

The SDK defines methods that deserialize responses into Pydantic models. However, these methods don’t provide access to response headers, status code, or the raw response body. To access this data, prefix any HTTP method call on a client or service with with_raw_response:

import asyncio

from stagehand import AsyncStagehand

async def main() -> None:
    async with AsyncStagehand() as client:
        response = await client.sessions.with_raw_response.start(model_name="openai/gpt-5-nano")
        print(response.headers.get("X-My-Header"))

        session = response.parse()  # get the object that `sessions.start()` would have returned
        print(session.data)

asyncio.run(main())

`.with_streaming_response`

The with_raw_response interface eagerly reads the full response body when you make the request. To stream the response body (not SSE), use with_streaming_response instead. It requires a context manager and only reads the response body once you call .read(), .text(), .json(), .iter_bytes(), .iter_text(), .iter_lines() or .parse().

import asyncio

from stagehand import AsyncStagehand

async def main() -> None:
    async with AsyncStagehand() as client:
        async with client.sessions.with_streaming_response.start(model_name="openai/gpt-5-nano") as response:
            print(response.headers.get("X-My-Header"))
            async for line in response.iter_lines():
                print(line)

asyncio.run(main())

Error handling

When the library is unable to connect to the API (for example, due to network connection problems or a timeout), a subclass of stagehand.APIConnectionError is raised. When the API returns a non-success status code (that is, 4xx or 5xx response), a subclass of stagehand.APIStatusError is raised, containing status_code and response properties. All errors inherit from stagehand.APIError.

import asyncio

import stagehand
from stagehand import AsyncStagehand

async def main() -> None:
    async with AsyncStagehand() as client:
        try:
            await client.sessions.start(model_name="openai/gpt-5-nano")
        except stagehand.APIConnectionError as e:
            print("The server could not be reached")
            print(e.__cause__)  # an underlying Exception, likely raised within httpx.
        except stagehand.RateLimitError:
            print("A 429 status code was received; we should back off a bit.")
        except stagehand.APIStatusError as e:
            print("A non-200-range status code was received")
            print(e.status_code)
            print(e.response)

asyncio.run(main())

Error codes are as follows:

Status Code	Error Type
400	`BadRequestError`
401	`AuthenticationError`
403	`PermissionDeniedError`
404	`NotFoundError`
422	`UnprocessableEntityError`
429	`RateLimitError`
>=500	`InternalServerError`
N/A	`APIConnectionError`

Retries

Certain errors are automatically retried 2 times by default, with a short exponential backoff. Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, and >=500 Internal errors are all retried by default. You can use the max_retries option to configure or disable retry settings:

import asyncio

from stagehand import AsyncStagehand

async def main() -> None:
    async with AsyncStagehand(max_retries=0) as client:
        # Or, configure per-request:
        await client.with_options(max_retries=5).sessions.start(model_name="openai/gpt-5-nano")

asyncio.run(main())

Timeouts

By default requests time out after 1 minute. You can configure this with a timeout option, which accepts a float or an httpx.Timeout object. On timeout, an APITimeoutError is thrown. Note that requests that time out are retried twice by default.

Logging

The SDK uses the standard library logging module. Enable logging by setting the STAGEHAND_LOG environment variable to info:

export STAGEHAND_LOG=info

Or to debug for more verbose logging:

export STAGEHAND_LOG=debug

Undocumented API functionality

This library is typed for convenient access to the documented API, but you can still access undocumented endpoints, request params, or response properties when needed.

Undocumented endpoints

To make requests to undocumented endpoints, use client.get, client.post, and other HTTP verbs. Client options (such as retries) are respected.

import httpx
from stagehand import AsyncStagehand

import asyncio

async def main() -> None:
    async with AsyncStagehand() as client:
        response = await client.post("/foo", cast_to=httpx.Response, body={"my_param": True})
        print(response.headers.get("x-foo"))

asyncio.run(main())

Undocumented request params

To send extra params that aren’t available as keyword args, use extra_query, extra_body, and extra_headers.

Undocumented response properties

To access undocumented response properties, you can access extra fields like response.unknown_prop. You can also get all extra fields as a dict with response.model_extra.

Response validation

In rare cases, the API may return a response that doesn’t match the expected type. By default, the SDK is permissive and will only raise an error if you later try to use the invalid data. If you would prefer to validate responses upfront, instantiate the client with _strict_response_validation=True. An APIResponseValidationError will be raised if the API responds with invalid data for the expected schema.

import asyncio

from stagehand import APIResponseValidationError, AsyncStagehand

try:
    async def main() -> None:
        async with AsyncStagehand(_strict_response_validation=True) as client:
            await client.sessions.start(model_name="openai/gpt-5-nano")

    asyncio.run(main())
except APIResponseValidationError as e:
    print("Response failed schema validation:", e)

FAQ

Why are some values typed as `Literal[...]` instead of Python `Enum`s?

Using Literal[...] types is forwards compatible: the API can introduce new enum values without breaking older SDKs at runtime.

How can I tell whether `None` means `null` or “missing” in a response?

In an API response, a field may be explicitly null, or missing entirely; in either case its value is None in this library. You can differentiate the two cases with .model_fields_set:

if response.my_field is None:
    if "my_field" not in response.model_fields_set:
        print('Got json like {}, without a "my_field" key present at all.')
    else:
        print('Got json like {"my_field": null}.')

Semantic versioning

This package generally follows SemVer conventions, though certain backwards-incompatible changes may be released as minor versions:

Changes that only affect static types, without breaking runtime behavior.
Changes to library internals which are technically public but not intended or documented for external use. (Please open a GitHub issue to let us know if you are relying on such internals.)
Changes that we do not expect to impact the vast majority of users in practice.

We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience. We are keen for your feedback; please open an issue with questions, bugs, or suggestions.

Determining the installed version

If you’ve upgraded to the latest version but aren’t seeing any new features you were expecting then your python environment is likely still using an older version. You can determine the version that is being used at runtime with:

import stagehand

print(stagehand.__version__)

SDK Reference

API Reference

What is Stagehand?

Why Stagehand?

Installation

Requirements

Running the Example

Local mode example

Streaming logging example

Usage

Client configuration

Modifying configuration

Requests and responses

Immutability

Asynchronous execution

With aiohttp

Streaming responses

Raw responses

`.with_streaming_response`

Error handling

Retries

Timeouts

Logging

Undocumented API functionality

Undocumented endpoints

Undocumented request params

Undocumented response properties

Response validation

FAQ

Why are some values typed as `Literal[...]` instead of Python `Enum`s?

How can I tell whether `None` means `null` or “missing” in a response?

Semantic versioning

Determining the installed version

​What is Stagehand?

​Why Stagehand?

​Installation

​Requirements

​Running the Example

​Local mode example

​Streaming logging example

​Usage

​Client configuration

​Modifying configuration

​Requests and responses

​Immutability

​Asynchronous execution

​With aiohttp

​Streaming responses

​Raw responses

​.with_streaming_response

​Error handling

​Retries

​Timeouts

​Logging

​Undocumented API functionality

​Undocumented endpoints

​Undocumented request params

​Undocumented response properties

​Response validation

​FAQ

​Why are some values typed as Literal[...] instead of Python Enums?

​How can I tell whether None means null or “missing” in a response?

​Semantic versioning

​Determining the installed version

What is Stagehand?

Why Stagehand?

Installation

Requirements

Running the Example

Local mode example

Streaming logging example

Usage

Client configuration

Modifying configuration

Requests and responses

Immutability

Asynchronous execution

With aiohttp

Streaming responses

Raw responses

`.with_streaming_response`

Error handling

Retries

Timeouts

Logging

Undocumented API functionality

Undocumented endpoints

Undocumented request params

Undocumented response properties

Response validation

FAQ

Why are some values typed as `Literal[...]` instead of Python `Enum`s?

How can I tell whether `None` means `null` or “missing” in a response?

Semantic versioning

Determining the installed version