AI Tools
WorkflowBeginner

Stagehand v3

Natural language-based browser automation — act, extract, observe, and agent: the four core primitives.

  • Four core primitives — act(), extract(), observe(), agent(): act() executes a single browser action based on natural language instructions ("click the login button"), extract() extracts structured data from a page based on a Zod schema, observe() proactively explores a list of possible actions on the current page, and agent() autonomously executes a multi-step workflow. These four are combined to integrate deterministic step control and autonomous agent execution into a single SDK.
  • v3 architecture rewrite — removal of internal Playwright dependencies: In v3, internal Playwright dependencies are completely removed, and the architecture is switched to directly communicate with the CDP (Chrome DevTools Protocol) engine. Playwright, Puppeteer, or Patchright can be selected and used as the backend. A 20-40% speed improvement is achieved across act(), extract(), and observe().
  • Three agent modes — CUA, DOM, Hybrid: CUA (Computer Use Agent) mode directly recognizes the screen through vision-based coordinate clicks, DOM mode executes semantic actions through accessibility tree analysis, and Hybrid mode (default from v3.4.0) combines vision and DOM to achieve both accuracy and speed. Incompatible models are automatically routed to DOM mode.
  • Multi-LLM provider support: Based on the Vercel AI SDK, major providers such as OpenAI, Anthropic (Claude), and Google Gemini can be freely switched. The Computer Use API supports Anthropic, OpenAI, Google, and Microsoft. When using Browserbase, all supported models can be accessed with a single API key through the Model Gateway.
  • Self-healing automation: Because natural language-based instructions are interpreted by AI at runtime, the script automatically adapts even if the website markup changes. This fundamentally eliminates maintenance costs compared to hardcoding CSS selectors. In v3, automatic traversal of Shadow DOM (both open and closed modes) and iFrames is added.
  • Action caching system: A dual structure consisting of a Browserbase server-side cache (cache key based on instruction + page content, response time of less than 100ms on HIT) and a local file cache (cacheDir setting). The automatic action caching in v3 can automatically convert CUA execution into a deterministic script without inference.
  • v3 new non-AI primitives: page, locator, frameLocator, deepLocator (cross-navigation of iFrame + Shadow Root) — used when direct DOM control is needed without AI inference. The precision of traditional automation tools and the flexibility of AI can be selectively used within a single SDK.
  • Custom tools and MCP integration: User-defined tools can be injected into agent() to perform actions outside the browser, such as sending emails or calling external APIs. The URL of the MCP (Model Context Protocol) server is passed as an array in the integrations, allowing immediate connection to the external tool ecosystem.
  • Framework integration: Directly integrated with major automation and web frameworks such as CrewAI, LangChain JS, Playwright, Puppeteer, Selenium, Next.js/Vercel, and Convex. Bun runtime is also officially supported from v3.

💻 System Requirements

🧠RAM

Not required (all LLM inference is delegated to an external API provider)

💾Storage

A few tens of MB based on npm packages. Additional space may be required depending on the accumulation of cached files when local caching is enabled (within a few hundred MB).

Installation

4-1. Quick Start

# TypeScript — Project scaffolding (recommended)
npx create-browser-app

# TypeScript — Add to an existing project
npm install @browserbasehq/stagehand

# Python
pip install stagehand
# Or, when using uv
uv pip install stagehand

4-2. Basic Usage Example (TypeScript)

import { Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod";

const stagehand = new Stagehand({ env: "LOCAL" });
await stagehand.init();
const page = stagehand.context.pages()[0];
await page.goto("https://github.com/browserbase");

// Execute a single action
await stagehand.act("click on the stagehand repo");

// Extract structured data (Zod schema)
const { author, title } = await stagehand.extract(
  "extract the author and title of the PR",
  z.object({
    author: z.string().describe("The username of the PR author"),
    title: z.string().describe("The title of the PR"),
  }),
);

// Multi-step autonomous agent
const agent = stagehand.agent({
  provider: "anthropic",
  model: "claude-sonnet-4-6",
});
await agent.execute("Get to the latest PR");

4-3. Environment Variable Configuration

# .env file
BROWSERBASE_API_KEY=your_api_key   # When using Browserbase Cloud
OPENAI_API_KEY=your_key            # When using OpenAI models
ANTHROPIC_API_KEY=your_key         # When using Anthropic models
GOOGLE_API_KEY=your_key            # When using Gemini models

🧬 Bio Use Cases

🔬

Production Web Scraping Pipeline

Build an automated pipeline for regularly collecting structured data from websites that do not offer an API. Use observe() to pre-explore the page structure, and pass a Zod schema to extract() to extract data such as prices, inventory, and reviews into a JSON structure. With self-healing capabilities, the script can continue to operate without modification even if the target site's UI changes. When a cache hit occurs, the response time is less than 100ms, reducing token costs by up to 90% when processing a large number of pages.

🧬

Advanced E2E Test Automation

Solve the problem of existing Playwright/Selenium tests breaking with every selector change. Describe key user flows, such as "Login -> Search for products -> Add to cart -> Checkout," in natural language, and the AI will identify and execute the elements at runtime. In Hybrid mode (default in v3.4.0), run fast, deterministic DOM-based tests, and automatically fall back to DOM mode when using incompatible models to ensure stability.

💊

Browser-Based RPA Agent

Build an RPA agent that integrates browser automation and business logic by injecting custom tools into the agent() primitive. For example, a workflow that logs in to a specific portal every day, downloads a report, extracts the data, and sends it via email can be autonomously executed with a single call to agent(). With MCP integration, subsequent actions such as Slack notifications and database storage can also be handled directly within the agent.

FAQ

What is Stagehand v3?

Four core primitives — act(), extract(), observe(), agent(): act() executes a single browser action based on natural language instructions ("click the login button"), extract() extracts structured data from a page based on a Zod schema, observe() proactively explores a list of possible actions on the current page, and agent() autonomously executes a multi-step workflow. These four are combined to integrate deterministic step control and autonomous agent execution into a single SDK. v3 architecture rewrite — removal of internal Playwright dependencies: In v3, internal Playwright dependencies are completely removed, and the architecture is switched to directly communicate with the CDP (Chrome DevTools Protocol) engine. Playwright, Puppeteer, or Patchright can be selected and used as the backend. A 20-40% speed improvement is achieved across act(), extract(), and observe(). Three agent modes — CUA, DOM, Hybrid: CUA (Computer Use Agent) mode directly recognizes the screen through vision-based coordinate clicks, DOM mode executes semantic actions through accessibility tree analysis, and Hybrid mode (default from v3.4.0) combines vision and DOM to achieve both accuracy and speed. Incompatible models are automatically routed to DOM mode. Multi-LLM provider support: Based on the Vercel AI SDK, major providers such as OpenAI, Anthropic (Claude), and Google Gemini can be freely switched. The Computer Use API supports Anthropic, OpenAI, Google, and Microsoft. When using Browserbase, all supported models can be accessed with a single API key through the Model Gateway. Self-healing automation: Because natural language-based instructions are interpreted by AI at runtime, the script automatically adapts even if the website markup changes. This fundamentally eliminates maintenance costs compared to hardcoding CSS selectors. In v3, automatic traversal of Shadow DOM (both open and closed modes) and iFrames is added. Action caching system: A dual structure consisting of a Browserbase server-side cache (cache key based on instruction + page content, response time of less than 100ms on HIT) and a local file cache (cacheDir setting). The automatic action caching in v3 can automatically convert CUA execution into a deterministic script without inference. v3 new non-AI primitives: page, locator, frameLocator, deepLocator (cross-navigation of iFrame + Shadow Root) — used when direct DOM control is needed without AI inference. The precision of traditional automation tools and the flexibility of AI can be selectively used within a single SDK. Custom tools and MCP integration: User-defined tools can be injected into agent() to perform actions outside the browser, such as sending emails or calling external APIs. The URL of the MCP (Model Context Protocol) server is passed as an array in the integrations, allowing immediate connection to the external tool ecosystem. Framework integration: Directly integrated with major automation and web frameworks such as CrewAI, LangChain JS, Playwright, Puppeteer, Selenium, Next.js/Vercel, and Convex. Bun runtime is also officially supported from v3.

When should I use Stagehand v3?

Natural language-based browser automation — act, extract, observe, and agent: the four core primitives.

What is a biomedical use case for Stagehand v3?

Production Web Scraping Pipeline: Build an automated pipeline for regularly collecting structured data from websites that do not offer an API. Use observe() to pre-explore the page structure, and pass a Zod schema to extract() to extract data such as prices, inventory, and reviews into a JSON structure. With self-healing capabilities, the script can continue to operate without modification even if the target site's UI changes. When a cache hit occurs, the response time is less than 100ms, reducing token costs by up to 90% when processing a large number of pages.

📄 Official Docs🐙 GitHub

📝 Update Notes

  1. v@browserbasehq/stagehand@3.7.38/28/2026

    이번 업데이트는 MCP SDK를 최신 버전으로 업데이트하여 시스템 안정성을 높이고, iframe 내 좌표 계산을 위한 XPath 로직 오류를 해결했습니다. 특히 분자 구조 뷰어나 복잡한 데이터 테이블이 iframe 형태로 포함된 생물학적 데이터베이스를 자동화할 때, 훨씬 더 정확한 요소 탐색과 제어가 가능해졌습니다. 웹 기반의 바이오 데이터 수집 자동화 프로세스를 운영 중이라면, 더욱 정교해진 자동화 성능을 위해 이번 패치를 적용해 보세요.

  2. vstagehand-server-v3/v3.7.58/20/2026

    What's Changed

  3. vbrowse@0.9.68/3/2026

    이번 업데이트에서는 브라우저 연결 오류 발생 시 해결에 필요한 명령어를 명확하게 안내해 주어, 자동화된 데이터 수집 중 발생하는 기술적 문제를 훨씬 빠르게 해결할 수 있습니다. 또한 환경 변수 자동 로딩에 대한 제어 기능이 강화되어, 실험 데이터나 API 키 등 민감한 정보를 다루는 연구 환경에서 보안성을 높일 수 있습니다. 웹 기반의 데이터 크롤링이나 연구 자동화 워크플로우를 운영 중이라면, 더욱 안정적이고 안전한 환경을 위해 이번 패치를 적용해 보세요.

  4. vstagehand-server-v3/v3.7.47/22/2026

    이번 업데이트에서는 OpenAI Chat Completions 형식을 지원하여, 연구자가 사용하는 다양한 LLM 엔드포인트를 더욱 유연하게 연결할 수 있게 되었어요. 덕분에 생명공학 데이터 분석에 특화된 맞춤형 모델을 Stagehand의 웹 자동화 워크플로우에 손쉽게 통합하여 활용할 수 있습니다. 또한 실험 경로(trajectories)를 그룹화하고 관리하는 기능이 개선되어, 복잡한 웹 기반 생물학적 데이터 수집 과정의 추적과 디버깅이 한층 정교해졌어요.

  5. vstagehand-server-v3/v3.7.37/16/2026

    Stagehand v3.7.3 업데이트에서는 데이터 추출(extract) 및 관찰(observe) 기능의 오류가 수정되어, 웹상의 논문이나 실험 데이터를 수집하는 자동화 작업이 더욱 안정적으로 수행될 수 있습니다. 최신 AI 모델들의 비용 정보가 업데이트됨에 따라, 연구 예산과 작업 복잡도에 맞춰 가장 효율적인 모델을 선택해 활용하기 좋아졌습니다. 또한 도메인 정책 설정 관련 문서가 보강되어, 특정 학술 사이트나 데이터베이스를 대상으로 하는 자동화 에이전트의 접근 제어를 더욱 정교하게 관리할 수 있습니다.

  6. v@browserbasehq/stagehand@3.7.07/13/2026

    Stagehand v3에서는 특정 도메인만 허용하거나 차단하는 정책 설정 기능이 추가되어, PubMed나 UniProt 같은 신뢰할 수 있는 학술 데이터베이스로만 탐색 범위를 안전하게 제한할 수 있습니다. 또한, 텍스트 데이터의 손상된 부분을 자동으로 복구하는 기능이 개선되어, 복잡한 단백질 서열이나 화학식 데이터를 수집할 때 발생할 수 있는 데이터 왜곡 오류를 방지합니다. 더불어 팝업 자동 차단 및 자동화 동작의 안정성이 향상되어, 웹 기반의 생물정보학 데이터 크롤링 작업을 더욱 정교하고 효율적으로 수행할 수 있습니다.

  7. vbrowse@0.9.06/25/2026

    browse screenshot 기능이 이제 base64 텍스트 대신 이미지 파일로 직접 저장되도록 변경되어, 웹 기반 실험 결과나 그래프의 시각적 기록을 관리하기 훨씬 편리해졌습니다. 윈도우 환경에서의 경로 인식 오류와 설치 중 무한 대기 문제가 해결되어, 자동화된 데이터 수집 및 모니터링 파이프라인의 안정성이 한층 강화되었습니다. 기존 스크립트와의 호환성을 위한 --base64 플래그도 유지되니, 연구 워크플로우에 맞춰 더욱 안정적인 데이터 아카이빙을 시작해 보세요.

  8. v@browserbasehq/stagehand@3.6.06/19/2026

    Stagehand v3에서는 Claude 모델의 지원이 강화되어, 복잡한 생물학적 데이터베이스로부터 구조화된 데이터를 더욱 정밀하게 추출할 수 있게 되었습니다. 또한 Azure OpenAI 인증 기능이 추가되어, 보안이 중요한 연구실 환경에서도 안전하게 AI 자동화 도구를 운용할 수 있습니다. 웹 요소 인식 및 캐싱 성능 개선을 통해, 다양한 과학 웹 사이트의 데이터를 수집하는 자동화 프로세스가 더욱 안정적이고 효율적으로 변할 것입니다.

  9. v@browserbasehq/stagehand@2.5.96/16/2026

    Stagehand v3는 팝업창 오류 해결과 데이터 추출 도구 업데이트를 통해 웹 자동화의 안정성과 정확도를 높였습니다. 특히 DOM 요청 시 재시도 로직이 강화되어, 대량의 학술 데이터나 실험 정보를 수집할 때 발생할 수 있는 연결 오류를 효과적으로 방지할 수 있습니다. 또한 Haiku 4.5 모델 지원이 추가되어 더욱 지능적인 웹 에이전트 활용이 가능해졌으니, 데이터 수집 자동화가 필요한 연구원님들께 유용한 업데이트입니다.

🧪 Related Code of Life

No related Code of Life posts yet.