pypi / stagehand
stagehand
What changed in stagehand 4, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-23.
13 breaking
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initstagehand 413 changes
Breaking changes 13
agent() is gone with no one-for-one replacement; use code mode or build a tool-calling loop around the Stagehand API.
Browser context access moved from the Stagehand instance to the browser handle; page lookups are now async.
serverCache is now cache; enableCaching and cacheDir are gone. Browserbase server caching is on by default, and each call can opt out.
act(), extract(), and observe() now return { data, metadata }; read primitive results from data and call metadata for action ID, cache status, and token usage.
verbose and logger are replaced by a logging object with level, format, and callback settings.
deepLocator() is gone; page.locator() resolves the same selectors, including hop notation and deep XPath.
act(), extract(), and observe() moved from Page to the Stagehand instance; use options.page to target a non-active page.
The Browserbase session ID property is gone; create the session yourself and retain its ID when needed.
Construct Stagehand with Stagehand.create() after launching or connecting a browser; the constructor is private and init() is gone.
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.
extract() now takes the instruction and optional schema as positional arguments; without a schema it returns { extraction: string }.
Metrics access changed from a property to a method.
Stagehand is rebuilt around its v4 browser protocol as a protocol-first monorepo, with TypeScript, Python, and Go SDKs over a shared core.