Stagehand Python SDK

In Stagehand API responses, both an explicit null in JSON and a missing key result in a value of None in Python. To distinguish between these two cases, use the .model_fields_set attribute on the response object to check if the key was actually present in the payload.

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.'.format(response.model_dump()))
    else:
        print('Got json like {"my_field": null}.')

Stagehand API responses are returned as Pydantic models. This allows for easy serialization and manipulation.

To work with responses:

• Serialize to JSON: Use model.to_json().
• Convert to dictionary: Use model.to_dict().
• Create a modified copy: Since response objects are immutable, use model.model_copy(update={...}) (for Pydantic v2) instead of mutating the object in place.

If you need to interact with undocumented endpoints or send extra parameters, you can use the generic HTTP verb methods on the client (e.g., client.get, client.post).

• Undocumented Endpoints: Use client.post("/path", ...).
• Extra Parameters: Use extra_query, extra_body, or extra_headers options.
• Undocumented Response Properties: Access them via response.unknown_prop or by inspecting response.model_extra (a dictionary of extra fields).

import httpx

# Requesting an undocumented endpoint
response = client.post(
    "/foo",
    cast_to=httpx.Response,
    body={"my_param": True},
)

print(response.headers.get("x-foo"))

To enable streaming responses, you must satisfy two requirements:

1. Set the header x_stream_response="true" in the request.
2. Set stream_response=True in the client call to instruct the client to parse the SSE stream.

Streaming events are of type "system" or "log".

import asyncio
from stagehand import AsyncStagehand

async def main() -> None:
    async with AsyncStagehand() as client:
        session = await client.sessions.start(model_name="anthropic/claude-sonnet-4-6")

        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())

While the library automatically closes connections when the client is garbage collected, it is best practice to manage the lifecycle manually using a context manager or by calling .close(). This ensures HTTP resources are released promptly.

from stagehand import Stagehand

with Stagehand() as client:
  # make requests here
  ...

# HTTP client is now closed

The Stagehand Python SDK is designed for asynchronous use. It is recommended to use AsyncStagehand and await every API call to ensure non-blocking execution.

import asyncio
from stagehand import AsyncStagehand

async def main() -> None:
    client = AsyncStagehand()
    session = await client.sessions.start(model_name="anthropic/claude-sonnet-4-6")
    response = await session.act(input="click the first link on the page")
    print(response.data)

asyncio.run(main())

Install the Stagehand framework using uv to manage dependencies from PyPI.

# install from PyPI
uv pip install stagehand

Stagehand requires specific environment variables for authentication. You can set these in a .env file.

Required variables:

• MODEL_API_KEY: Your API key for the LLM provider.
• BROWSERBASE_API_KEY: Your Browserbase API key.

To set up your environment from the examples directory:

cp examples/.env.example examples/.env
# Edit examples/.env with your credentials.

By default, the async client uses httpx. For improved concurrency performance, you can install and use aiohttp as the HTTP backend.

1. Install the extra dependency: uv pip install stagehand[aiohttp]

2. Instantiate the client with DefaultAioHttpClient().

import asyncio
from stagehand import AsyncStagehand, DefaultAioHttpClient

async def main() -> None:
    async with AsyncStagehand(http_client=DefaultAioHttpClient()) as client:
        session = await client.sessions.start(model_name="anthropic/claude-sonnet-4-6")
        response = await session.act(input="click the first link on the page")
        print(response.data)

asyncio.run(main())

The SDK uses the standard Python logging module. You can control verbosity by setting the STAGEHAND_LOG environment variable.

• export STAGEHAND_LOG=info (Standard info)
• export STAGEHAND_LOG=debug (Verbose debugging)