{"id":28913169,"url":"https://github.com/browserbase/stagehand-python","last_synced_at":"2026-04-02T20:22:35.618Z","repository":{"id":299673998,"uuid":"917301647","full_name":"browserbase/stagehand-python","owner":"browserbase","description":"The AI Browser Automation Framework","archived":false,"fork":false,"pushed_at":"2025-06-17T17:42:58.000Z","size":952,"stargazers_count":18,"open_issues_count":3,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-06-17T18:42:18.911Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://stagehand.dev","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/browserbase.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.txt","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-01-15T18:20:25.000Z","updated_at":"2025-06-17T18:39:06.000Z","dependencies_parsed_at":"2025-06-17T18:54:17.857Z","dependency_job_id":null,"html_url":"https://github.com/browserbase/stagehand-python","commit_stats":null,"previous_names":["browserbase/stagehand-python"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/browserbase/stagehand-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/browserbase%2Fstagehand-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/browserbase%2Fstagehand-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/browserbase%2Fstagehand-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/browserbase%2Fstagehand-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/browserbase","download_url":"https://codeload.github.com/browserbase/stagehand-python/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/browserbase%2Fstagehand-python/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261191254,"owners_count":23122716,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-21T20:31:39.605Z","updated_at":"2026-04-02T20:22:35.611Z","avatar_url":"https://github.com/browserbase.png","language":"Python","readme":"\u003c!-- x-stagehand-custom-start --\u003e\n\u003cdiv id=\"toc\" align=\"center\" style=\"margin-bottom: 0;\"\u003e\n  \u003cul style=\"list-style: none; margin: 0; padding: 0;\"\u003e\n    \u003ca href=\"https://stagehand.dev\"\u003e\n      \u003cpicture\u003e\n        \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/browserbase/stagehand/main/media/dark_logo.png\" /\u003e\n        \u003cimg alt=\"Stagehand\" src=\"https://raw.githubusercontent.com/browserbase/stagehand/main/media/light_logo.png\" width=\"200\" style=\"margin-right: 30px;\" /\u003e\n      \u003c/picture\u003e\n    \u003c/a\u003e\n  \u003c/ul\u003e\n\u003c/div\u003e\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eThe AI Browser Automation Framework\u003c/strong\u003e\u003cbr\u003e\n  \u003ca href=\"https://docs.stagehand.dev/v3/sdk/python\"\u003eRead the Docs\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/browserbase/stagehand/tree/main?tab=MIT-1-ov-file#MIT-1-ov-file\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/browserbase/stagehand/main/media/dark_license.svg\" /\u003e\n      \u003cimg alt=\"MIT License\" src=\"https://raw.githubusercontent.com/browserbase/stagehand/main/media/light_license.svg\" /\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://stagehand.dev/discord\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/browserbase/stagehand/main/media/dark_discord.svg\" /\u003e\n      \u003cimg alt=\"Discord Community\" src=\"https://raw.githubusercontent.com/browserbase/stagehand/main/media/light_discord.svg\" /\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\u003c!-- prettier-ignore --\u003e\n[![PyPI version](https://img.shields.io/pypi/v/stagehand.svg?label=pypi%20(stable))](https://pypi.org/project/stagehand/)\n\n\u003cp align=\"center\"\u003e\n\t\u003ca href=\"https://trendshift.io/repositories/12122\" target=\"_blank\"\u003e\u003cimg src=\"https://trendshift.io/api/badge/repositories/12122\" alt=\"browserbase%2Fstagehand | Trendshift\" style=\"width: 250px; height: 55px;\" width=\"250\" height=\"55\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\nIf you're looking for other languages, you can find them\n\u003ca href=\"https://docs.stagehand.dev/v3/first-steps/introduction\"\u003e here\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cdiv align=\"center\" style=\"display: flex; align-items: center; justify-content: center; gap: 4px; margin-bottom: 0;\"\u003e\n  \u003cb\u003eVibe code\u003c/b\u003e\n  \u003cspan style=\"font-size: 1.05em;\"\u003e Stagehand with \u003c/span\u003e\n  \u003ca href=\"https://director.ai\" style=\"display: flex; align-items: center;\"\u003e\n    \u003cspan\u003eDirector\u003c/span\u003e\n  \u003c/a\u003e\n  \u003cspan\u003e \u003c/span\u003e\n  \u003cpicture\u003e\n    \u003cimg alt=\"Director\" src=\"https://raw.githubusercontent.com/browserbase/stagehand/main/media/director_icon.svg\" width=\"25\" /\u003e\n  \u003c/picture\u003e\n\u003c/div\u003e\n\u003c!-- x-stagehand-custom-end --\u003e\n\n\u003e [!TIP]\n\u003e Migrating from the old v2 Python SDK? See our [migration guide here](https://docs.stagehand.dev/v3/migrations/python).\n\n## What is Stagehand?\n\nStagehand 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.\n\n## Why Stagehand?\n\nMost 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.\n\n1. **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.\n\n2. **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.\n\n3. **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.\n\n## Installation\n\n```sh\n# install from PyPI\nuv pip install stagehand\n```\n\nFor local development or when working from this repository, sync the dependency lockfile with `uv` (see the Local development section below) before running project scripts.\n\n## Requirements\n\nPython 3.9 or higher.\n\n## Running the Example\n\nSet your environment variables (from `examples/.env.example`):\n\n- `STAGEHAND_API_URL`\n- `MODEL_API_KEY`\n- `BROWSERBASE_API_KEY`\n- `BROWSERBASE_PROJECT_ID`\n\n```bash\ncp examples/.env.example examples/.env\n# Edit examples/.env with your credentials.\n```\n\nThe examples load `examples/.env` automatically.\n\nExamples and dependencies:\n\n- `examples/full_example.py`: stagehand only\n- `examples/act_example.py`: stagehand only\n- `examples/agent_execute.py`: stagehand only\n- `examples/local_example.py`: stagehand only\n- `examples/logging_example.py`: stagehand only\n- `examples/remote_browser_playwright_example.py`: Playwright + Playwright browsers\n- `examples/local_browser_playwright_example.py`: Playwright + Playwright browsers\n- `examples/playwright_page_example.py`: Playwright + Playwright browsers\n- `examples/byob_example.py`: Playwright + Playwright browsers\n- `examples/pydoll_tab_example.py`: `pydoll-python` (Python 3.10+)\n\nMultiregion support: see `examples/local_server_multiregion_browser_example.py`.\n\nRun any example:\n\n```bash\nuv run python examples/remote_browser_playwright_example.py\n```\n\n## Usage\n\nThis mirrors `examples/remote_browser_playwright_example.py`.\n\n```python\nimport os\n\nfrom playwright.sync_api import sync_playwright\n\nfrom env import load_example_env\nfrom stagehand import Stagehand\n\n\ndef main() -\u003e None:\n    load_example_env()\n\n    with Stagehand(\n        server=\"remote\",\n        browserbase_api_key=os.environ.get(\"BROWSERBASE_API_KEY\"),\n        browserbase_project_id=os.environ.get(\"BROWSERBASE_PROJECT_ID\"),\n        model_api_key=os.environ.get(\"MODEL_API_KEY\"),\n    ) as client:\n        session = client.sessions.start(\n            model_name=\"anthropic/claude-sonnet-4-6\",\n            browser={\"type\": \"browserbase\"},\n        )\n\n        cdp_url = session.data.cdp_url\n        if not cdp_url:\n            raise RuntimeError(\"No cdp_url returned from the API for this session.\")\n\n        with sync_playwright() as p:\n            browser = p.chromium.connect_over_cdp(cdp_url)\n            context = browser.contexts[0] if browser.contexts else browser.new_context()\n            page = context.pages[0] if context.pages else context.new_page()\n\n            client.sessions.navigate(session.id, url=\"https://news.ycombinator.com\")\n            page.wait_for_load_state(\"domcontentloaded\")\n\n            observe_stream = client.sessions.observe(\n                session.id,\n                instruction=\"find the link to view comments for the top post\",\n                stream_response=True,\n                x_stream_response=\"true\",\n            )\n            for _ in observe_stream:\n                pass\n\n            act_stream = client.sessions.act(\n                session.id,\n                input=\"Click the comments link for the top post\",\n                stream_response=True,\n                x_stream_response=\"true\",\n            )\n            for _ in act_stream:\n                pass\n\n            extract_stream = client.sessions.extract(\n                session.id,\n                instruction=\"extract the text of the top comment on this page\",\n                schema={\n                    \"type\": \"object\",\n                    \"properties\": {\n                        \"commentText\": {\"type\": \"string\"},\n                        \"author\": {\"type\": \"string\"},\n                    },\n                    \"required\": [\"commentText\"],\n                },\n                stream_response=True,\n                x_stream_response=\"true\",\n            )\n            for _ in extract_stream:\n                pass\n\n            execute_stream = client.sessions.execute(\n                session.id,\n                execute_options={\n                    \"instruction\": \"Click the 'Learn more' link if available\",\n                    \"max_steps\": 3,\n                },\n                agent_config={\n                    \"model\": {\"model_name\": \"anthropic/claude-opus-4-6\"},\n                    \"cua\": False,\n                },\n                stream_response=True,\n                x_stream_response=\"true\",\n            )\n            for _ in execute_stream:\n                pass\n\n        client.sessions.end(session.id)\n\n\nif __name__ == \"__main__\":\n    main()\n```\n\n## Client configuration\n\nConfigure the client using environment variables:\n\n```python\nfrom stagehand import AsyncStagehand\n\nclient = AsyncStagehand()\n```\n\nOr manually:\n\n```python\nfrom stagehand import AsyncStagehand\n\nclient = AsyncStagehand(\n    browserbase_api_key=\"My Browserbase API Key\",\n    browserbase_project_id=\"My Browserbase Project ID\",\n    model_api_key=\"My Model API Key\",\n)\n```\n\nOr using a combination of the two approaches:\n\n```python\nfrom stagehand import AsyncStagehand\n\nclient = AsyncStagehand(\n    # Configures using environment variables\n    browserbase_api_key=\"My Browserbase API Key\",  # override just this one\n)\n```\n\nSee this table for the available options:\n\n| Keyword argument         | Environment variable     | Required | Default value                             |\n| ------------------------ | ------------------------ | -------- | ----------------------------------------- |\n| `browserbase_api_key`    | `BROWSERBASE_API_KEY`    | true     | -                                         |\n| `browserbase_project_id` | `BROWSERBASE_PROJECT_ID` | true     | -                                         |\n| `model_api_key`          | `MODEL_API_KEY`          | true     | -                                         |\n| `base_url`               | `STAGEHAND_BASE_URL`     | false    | `\"https://api.stagehand.browserbase.com\"` |\n\nKeyword arguments take precedence over environment variables.\n\n\u003e [!TIP]\n\u003e 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.\n\n### Modifying configuration\n\nTo temporarily use a modified client configuration while reusing the same connection pool, call `with_options()` on any client:\n\n```python\nclient_with_options = client.with_options(model_api_key=\"sk-your-llm-api-key-here\", max_retries=42)\n```\n\nThe `with_options()` method does not affect the original client.\n\n## Requests and responses\n\nTo send a request to the Stagehand API, call the corresponding client method using keyword arguments.\n\nNested request parameters are dictionaries typed using [`TypedDict`](https://docs.python.org/3/library/typing.html#typing.TypedDict). Responses are [Pydantic models](https://docs.pydantic.dev) which also provide helper methods like:\n\n- Serializing back into JSON: `model.to_json()`\n- Converting to a dictionary: `model.to_dict()`\n\n## Immutability\n\nResponse objects are Pydantic models. If you want to build a modified copy, prefer `model.model_copy(update={...})` (Pydantic v2) rather than mutating in place.\n\n## Asynchronous execution\n\nThis SDK recommends using `AsyncStagehand` and `await`ing each API call:\n\n```python\nimport asyncio\nfrom stagehand import AsyncStagehand\n\n\nasync def main() -\u003e None:\n    client = AsyncStagehand()\n    session = await client.sessions.start(model_name=\"anthropic/claude-sonnet-4-6\")\n    response = await session.act(input=\"click the first link on the page\")\n    print(response.data)\n\n\nasyncio.run(main())\n```\n\n### With aiohttp\n\nBy default, the async client uses `httpx` for HTTP requests. For improved concurrency performance you may also use `aiohttp` as the HTTP backend.\n\nInstall `aiohttp`:\n\n```sh\n# install from PyPI\nuv pip install stagehand[aiohttp]\n```\n\nThen instantiate the client with `http_client=DefaultAioHttpClient()`:\n\n```python\nimport asyncio\nfrom stagehand import AsyncStagehand, DefaultAioHttpClient\n\n\nasync def main() -\u003e None:\n    async with AsyncStagehand(http_client=DefaultAioHttpClient()) as client:\n        session = await client.sessions.start(model_name=\"anthropic/claude-sonnet-4-6\")\n        response = await session.act(input=\"click the first link on the page\")\n        print(response.data)\n\n\nasyncio.run(main())\n```\n\n## Streaming responses\n\nWe provide support for streaming responses using Server-Sent Events (SSE).\n\nTo enable SSE streaming, you must:\n\n1. Ask the server to stream by setting `x_stream_response=\"true\"` (header), and\n2. Tell the client to parse an SSE stream by setting `stream_response=True`.\n\n```python\nimport asyncio\n\nfrom stagehand import AsyncStagehand\n\n\nasync def main() -\u003e None:\n    async with AsyncStagehand() as client:\n        session = await client.sessions.start(model_name=\"anthropic/claude-sonnet-4-6\")\n\n        stream = await client.sessions.act(\n            id=session.id,\n            input=\"click the first link on the page\",\n            stream_response=True,\n            x_stream_response=\"true\",\n        )\n        async for event in stream:\n            # event is a StreamEvent (type: \"system\" | \"log\")\n            print(event.type, event.data)\n\n\nasyncio.run(main())\n```\n\n## Raw responses\n\nThe 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.\n\nTo access this data, prefix any HTTP method call on a client or service with `with_raw_response`:\n\n```python\nimport asyncio\n\nfrom stagehand import AsyncStagehand\n\n\nasync def main() -\u003e None:\n    async with AsyncStagehand() as client:\n        response = await client.sessions.with_raw_response.start(model_name=\"anthropic/claude-sonnet-4-6\")\n        print(response.headers.get(\"X-My-Header\"))\n\n        session = response.parse()  # get the object that `sessions.start()` would have returned\n        print(session.data)\n\n\nasyncio.run(main())\n```\n\n### `.with_streaming_response`\n\nThe `with_raw_response` interface eagerly reads the full response body when you make the request.\n\nTo 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()`.\n\n```python\nimport asyncio\n\nfrom stagehand import AsyncStagehand\n\n\nasync def main() -\u003e None:\n    async with AsyncStagehand() as client:\n        async with client.sessions.with_streaming_response.start(model_name=\"anthropic/claude-sonnet-4-6\") as response:\n            print(response.headers.get(\"X-My-Header\"))\n            async for line in response.iter_lines():\n                print(line)\n\n\nasyncio.run(main())\n```\n\n## Error handling\n\nWhen 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.\n\nWhen 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.\n\nAll errors inherit from `stagehand.APIError`.\n\n```python\nimport asyncio\n\nimport stagehand\nfrom stagehand import AsyncStagehand\n\n\nasync def main() -\u003e None:\n    async with AsyncStagehand() as client:\n        try:\n            await client.sessions.start(model_name=\"anthropic/claude-sonnet-4-6\")\n        except stagehand.APIConnectionError as e:\n            print(\"The server could not be reached\")\n            print(e.__cause__)  # an underlying Exception, likely raised within httpx.\n        except stagehand.RateLimitError:\n            print(\"A 429 status code was received; we should back off a bit.\")\n        except stagehand.APIStatusError as e:\n            print(\"A non-200-range status code was received\")\n            print(e.status_code)\n            print(e.response)\n\n\nasyncio.run(main())\n```\n\nError codes are as follows:\n\n| Status Code | Error Type                 |\n| ----------- | -------------------------- |\n| 400         | `BadRequestError`          |\n| 401         | `AuthenticationError`      |\n| 403         | `PermissionDeniedError`    |\n| 404         | `NotFoundError`            |\n| 422         | `UnprocessableEntityError` |\n| 429         | `RateLimitError`           |\n| \u003e=500       | `InternalServerError`      |\n| N/A         | `APIConnectionError`       |\n\n### Retries\n\nCertain 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 \u003e=500 Internal errors are all retried by default.\n\nYou can use the `max_retries` option to configure or disable retry settings:\n\n```python\nimport asyncio\n\nfrom stagehand import AsyncStagehand\n\n\nasync def main() -\u003e None:\n    async with AsyncStagehand(max_retries=0) as client:\n        # Or, configure per-request:\n        await client.with_options(max_retries=5).sessions.start(model_name=\"anthropic/claude-sonnet-4-6\")\n\n\nasyncio.run(main())\n```\n\n### Timeouts\n\nBy default requests time out after 1 minute. You can configure this with a `timeout` option, which accepts a float or an [`httpx.Timeout`](https://www.python-httpx.org/advanced/timeouts/#fine-tuning-the-configuration) object.\n\nOn timeout, an `APITimeoutError` is thrown. Note that requests that time out are [retried twice by default](#retries).\n\n## Logging\n\nThe SDK uses the standard library [`logging`](https://docs.python.org/3/library/logging.html) module.\n\nEnable logging by setting the `STAGEHAND_LOG` environment variable to `info`:\n\n```sh\nexport STAGEHAND_LOG=info\n```\n\nOr to `debug` for more verbose logging:\n\n```sh\nexport STAGEHAND_LOG=debug\n```\n\n## Undocumented API functionality\n\nThis library is typed for convenient access to the documented API, but you can still access undocumented endpoints, request params, or response properties when needed.\n\n### Undocumented endpoints\n\nTo make requests to undocumented endpoints, use `client.get`, `client.post`, and other HTTP verbs. Client options (such as retries) are respected.\n\n```python\nimport httpx\nfrom stagehand import AsyncStagehand\n\nimport asyncio\n\n\nasync def main() -\u003e None:\n    async with AsyncStagehand() as client:\n        response = await client.post(\"/foo\", cast_to=httpx.Response, body={\"my_param\": True})\n        print(response.headers.get(\"x-foo\"))\n\n\nasyncio.run(main())\n```\n\n### Undocumented request params\n\nTo send extra params that aren't available as keyword args, use `extra_query`, `extra_body`, and `extra_headers`.\n\n### Undocumented response properties\n\nTo 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`](https://docs.pydantic.dev/latest/api/base_model/#pydantic.BaseModel.model_extra).\n\n## Response validation\n\nIn rare cases, the API may return a response that doesn't match the expected type.\n\nBy default, the SDK is permissive and will only raise an error if you later try to use the invalid data.\n\nIf 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.\n\n```python\nimport asyncio\n\nfrom stagehand import APIResponseValidationError, AsyncStagehand\n\ntry:\n    async def main() -\u003e None:\n        async with AsyncStagehand(_strict_response_validation=True) as client:\n            await client.sessions.start(model_name=\"anthropic/claude-sonnet-4-6\")\n\n    asyncio.run(main())\nexcept APIResponseValidationError as e:\n    print(\"Response failed schema validation:\", e)\n```\n\n## FAQ\n\n### Why are some values typed as `Literal[...]` instead of Python `Enum`s?\n\nUsing `Literal[...]` types is forwards compatible: the API can introduce new enum values without breaking older SDKs at runtime.\n\n### How can I tell whether `None` means `null` or “missing” in a response?\n\nIn 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`:\n\n```python\nif response.my_field is None:\n    if \"my_field\" not in response.model_fields_set:\n        print('Got json like {}, without a \"my_field\" key present at all.')\n    else:\n        print('Got json like {\"my_field\": null}.')\n```\n\n### Accessing raw response data (e.g. headers)\n\nThe \"raw\" Response object can be accessed by prefixing `.with_raw_response.` to any HTTP method call, e.g.,\n\n```py\nfrom stagehand import Stagehand\n\nclient = Stagehand()\nresponse = client.sessions.with_raw_response.start(\n    model_name=\"anthropic/claude-sonnet-4-6\",\n)\nprint(response.headers.get('X-My-Header'))\n\nsession = response.parse()  # get the object that `sessions.start()` would have returned\nprint(session.data)\n```\n\nThese methods return an [`APIResponse`](https://github.com/browserbase/stagehand-python/tree/main/src/stagehand/_response.py) object.\n\nThe async client returns an [`AsyncAPIResponse`](https://github.com/browserbase/stagehand-python/tree/main/src/stagehand/_response.py) with the same structure, the only difference being `await`able methods for reading the response content.\n\n#### `.with_streaming_response`\n\nThe above interface eagerly reads the full response body when you make the request, which may not always be what you want.\n\nTo stream the response body, use `.with_streaming_response` instead, which requires a context manager and only reads the response body once you call `.read()`, `.text()`, `.json()`, `.iter_bytes()`, `.iter_text()`, `.iter_lines()` or `.parse()`. In the async client, these are async methods.\n\n```python\nwith client.sessions.with_streaming_response.start(\n    model_name=\"anthropic/claude-sonnet-4-6\",\n) as response:\n    print(response.headers.get(\"X-My-Header\"))\n\n    for line in response.iter_lines():\n        print(line)\n```\n\nThe context manager is required so that the response will reliably be closed.\n\n### Making custom/undocumented requests\n\nThis library is typed for convenient access to the documented API.\n\nIf you need to access undocumented endpoints, params, or response properties, the library can still be used.\n\n#### Undocumented endpoints\n\nTo make requests to undocumented endpoints, you can make requests using `client.get`, `client.post`, and other\nhttp verbs. Options on the client will be respected (such as retries) when making this request.\n\n```py\nimport httpx\n\nresponse = client.post(\n    \"/foo\",\n    cast_to=httpx.Response,\n    body={\"my_param\": True},\n)\n\nprint(response.headers.get(\"x-foo\"))\n```\n\n#### Undocumented request params\n\nIf you want to explicitly send an extra param, you can do so with the `extra_query`, `extra_body`, and `extra_headers` request\noptions.\n\n#### Undocumented response properties\n\nTo access undocumented response properties, you can access the extra fields like `response.unknown_prop`. You\ncan also get all the extra fields on the Pydantic model as a dict with\n[`response.model_extra`](https://docs.pydantic.dev/latest/api/base_model/#pydantic.BaseModel.model_extra).\n\n### Configuring the HTTP client\n\nYou can directly override the [httpx client](https://www.python-httpx.org/api/#client) to customize it for your use case, including:\n\n- Support for [proxies](https://www.python-httpx.org/advanced/proxies/)\n- Custom [transports](https://www.python-httpx.org/advanced/transports/)\n- Additional [advanced](https://www.python-httpx.org/advanced/clients/) functionality\n\n```python\nimport httpx\nfrom stagehand import Stagehand, DefaultHttpxClient\n\nclient = Stagehand(\n    # Or use the `STAGEHAND_BASE_URL` env var\n    base_url=\"http://my.test.server.example.com:8083\",\n    http_client=DefaultHttpxClient(\n        proxy=\"http://my.test.proxy.example.com\",\n        transport=httpx.HTTPTransport(local_address=\"0.0.0.0\"),\n    ),\n)\n```\n\nYou can also customize the client on a per-request basis by using `with_options()`:\n\n```python\nclient.with_options(http_client=DefaultHttpxClient(...))\n```\n\n### Managing HTTP resources\n\nBy default the library closes underlying HTTP connections whenever the client is [garbage collected](https://docs.python.org/3/reference/datamodel.html#object.__del__). You can manually close the client using the `.close()` method if desired, or with a context manager that closes when exiting.\n\n```py\nfrom stagehand import Stagehand\n\nwith Stagehand() as client:\n  # make requests here\n  ...\n\n# HTTP client is now closed\n```\n\n## Versioning\n\nThis package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:\n\n1. Changes that only affect static types, without breaking runtime behavior.\n2. 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.)_\n3. Changes that we do not expect to impact the vast majority of users in practice.\n\nWe take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.\n\nWe are keen for your feedback; please open an [issue](https://www.github.com/browserbase/stagehand-python/issues) with questions, bugs, or suggestions.\n\n### Determining the installed version\n\nIf 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.\n\nYou can determine the version that is being used at runtime with:\n\n```python\nimport stagehand\n\nprint(stagehand.__version__)\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrowserbase%2Fstagehand-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrowserbase%2Fstagehand-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrowserbase%2Fstagehand-python/lists"}