# What changed in stagehand

> 13 changes in stagehand 4 from its official release notes, upgrade guides and advisories: 13 breaking. Each one cited. Sources checked 2026-10-23. HTML: https://unstale.sh/pypi/stagehand/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## stagehand 4

### Breaking changes

- agent() is gone with no one-for-one replacement; use code mode or build a tool-calling loop around the Stagehand API. (4.0.0) — [upgrade guide](https://docs.stagehand.dev/v4/migrations/v3)
- Browser context access moved from the Stagehand instance to the browser handle; page lookups are now async. (4.0.0) — [upgrade guide](https://docs.stagehand.dev/v4/migrations/v3)
- serverCache is now cache; enableCaching and cacheDir are gone. Browserbase server caching is on by default, and each call can opt out. (4.0.0) — [upgrade guide](https://docs.stagehand.dev/v4/migrations/v3)
- act(), extract(), and observe() now return { data, metadata }; read primitive results from data and call metadata for action ID, cache status, and token usage. (4.0.0) — [upgrade guide](https://docs.stagehand.dev/v4/migrations/v3)
- verbose and logger are replaced by a logging object with level, format, and callback settings. (4.0.0) — [upgrade guide](https://docs.stagehand.dev/v4/migrations/v3)
- deepLocator() is gone; page.locator() resolves the same selectors, including hop notation and deep XPath. (4.0.0) — [upgrade guide](https://docs.stagehand.dev/v4/migrations/v3)
- act(), extract(), and observe() moved from Page to the Stagehand instance; use options.page to target a non-active page. (4.0.0) — [upgrade guide](https://docs.stagehand.dev/v4/migrations/v3)
- The Browserbase session ID property is gone; create the session yourself and retain its ID when needed. (4.0.0) — [upgrade guide](https://docs.stagehand.dev/v4/migrations/v3)
- Construct Stagehand with Stagehand.create() after launching or connecting a browser; the constructor is private and init() is gone. (4.0.0) — [upgrade guide](https://docs.stagehand.dev/v4/migrations/v3)
- modelName and modelClientOptions are replaced by one model object; model names require a provider prefix, and Browserbase can select a model when model is omitted. (4.0.0) — [upgrade guide](https://docs.stagehand.dev/v4/migrations/v3)
- extract() now takes the instruction and optional schema as positional arguments; without a schema it returns { extraction: string }. (4.0.0) — [upgrade guide](https://docs.stagehand.dev/v4/migrations/v3)
- Metrics access changed from a property to a method. (4.0.0) — [upgrade guide](https://docs.stagehand.dev/v4/migrations/v3)
- Stagehand is rebuilt around its v4 browser protocol as a protocol-first monorepo, with TypeScript, Python, and Go SDKs over a shared core. (4.0.0) — [release notes](https://github.com/browserbase/stagehand/blob/HEAD/CHANGELOG.md)