Stagehand v3
4대 핵심 프리미티브 — `act()`, `extract()`, `observe()`, `agent()`**: `act()`는 자연어 지시("로그인 버튼을 클릭해")로 단일 브라우저 액션을 실행하고, `extract()`는 Zod 스키마 기반으로 페이지에서 구조화된 데이터를 추출하며, `observe()`는 현재 페이지에서 실행 가능한 액션 목록을 사전 탐색하고, `agent()`는 다단계 워크플로우를 자율 실행. 이 네 가지를 조합해 결정적(deterministic) 단계 제어와 자율 에이전트 실행을 하나의 SDK로 통합
- 4대 핵심 프리미티브 — `act()`, `extract()`, `observe()`, `agent()`: `act()`는 자연어 지시("로그인 버튼을 클릭해")로 단일 브라우저 액션을 실행하고, `extract()`는 Zod 스키마 기반으로 페이지에서 구조화된 데이터를 추출하며, `observe()`는 현재 페이지에서 실행 가능한 액션 목록을 사전 탐색하고, `agent()`는 다단계 워크플로우를 자율 실행. 이 네 가지를 조합해 결정적(deterministic) 단계 제어와 자율 에이전트 실행을 하나의 SDK로 통합 - v3 아키텍처 리라이트 — Playwright 내부 의존성 제거: v3에서 내부 Playwright 의존성을 완전히 제거하고 CDP(Chrome DevTools Protocol) 엔진을 직접 통신하는 구조로 전환. Playwright, Puppeteer, Patchright 중 선택하여 백엔드로 사용 가능. `act()`, `extract()`, `observe()` 전반에 걸쳐 20-40% 속도 향상 달성 - 3가지 에이전트 모드 — CUA, DOM, Hybrid: CUA(Computer Use Agent) 모드는 비전 기반 좌표 클릭으로 화면을 직접 인식, DOM 모드는 접근성 트리(Accessibility Tree) 분석으로 시맨틱 액션 실행, Hybrid 모드(v3.4.0부터 기본값)는 비전과 DOM을 결합하여 정확도와 속도를 동시에 확보. 비호환 모델은 자동으로 DOM 모드로 라우팅 - 멀티 LLM 프로바이더 지원: Vercel AI SDK 기반으로 OpenAI, Anthropic(Claude), Google Gemini 등 주요 프로바이더를 자유 전환. Computer Use API는 Anthropic, OpenAI, Google, Microsoft 모두 지원. Browserbase 사용 시 Model Gateway로 단일 API 키로 모든 지원 모델 접근 - 셀프힐링(Self-Healing) 자동화: 자연어 기반 지시는 런타임에 AI가 해석하므로 웹사이트 마크업이 변경되어도 스크립트가 자동 적응. CSS 셀렉터 하드코딩 방식 대비 유지보수 비용을 근본적으로 제거. v3에서 Shadow DOM(open/closed 모드 모두)과 iFrame 자동 트래버설 추가 - 액션 캐싱 시스템: Browserbase 서버사이드 캐시(지시 + 페이지 콘텐츠 기반 캐시 키, HIT 시 100ms 미만 응답)와 로컬 파일 캐시(`cacheDir` 설정) 이중 구조. v3의 자동 액션 캐싱은 CUA 실행을 추론 없는 결정적 스크립트로 자동 전환 가능 - v3 신규 non-AI 프리미티브: `page`, `locator`, `frameLocator`, `deepLocator`(iFrame + Shadow Root 교차 탐색) — AI 추론 없이 직접 DOM 제어가 필요한 경우 사용. 전통적 자동화 도구의 정밀성과 AI 유연성을 한 SDK 내에서 선택적으로 활용 - 커스텀 도구 및 MCP 통합: `agent()`에 사용자 정의 도구를 주입하여 이메일 발송, 외부 API 호출 등 브라우저 외 액션 수행 가능. MCP(Model Context Protocol) 서버 URL을 integrations 배열로 전달하여 외부 도구 생태계 즉시 연결 - 프레임워크 통합: CrewAI, LangChain JS, Playwright, Puppeteer, Selenium, Next.js/Vercel, Convex 등 주요 자동화·웹 프레임워크와 직접 연동. Bun 런타임도 v3부터 공식 지원
💻 필요한 컴퓨터 사양
불필요 (모든 LLM 추론은 외부 API 프로바이더에 위임)
npm 패키지 기준 수십 MB 수준. 로컬 캐시 활성화 시 캐시 파일 누적에 따라 추가 공간 필요 (수백 MB 이내)
⚡ 설치법
### 4-1. Quick Start
```bash
# TypeScript — 프로젝트 스캐폴딩 (권장)
npx create-browser-app
# TypeScript — 기존 프로젝트에 추가
npm install @browserbasehq/stagehand
# Python
pip install stagehand
# 또는 uv 사용 시
uv pip install stagehand
```
### 4-2. 기본 사용 예시 (TypeScript)
```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");
// 단일 액션 실행
await stagehand.act("click on the stagehand repo");
// 구조화 데이터 추출 (Zod 스키마)
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"),
}),
);
// 다단계 자율 에이전트
const agent = stagehand.agent({
provider: "anthropic",
model: "claude-sonnet-4-6",
});
await agent.execute("Get to the latest PR");
```
### 4-3. 환경 변수 설정
```bash
# .env 파일
BROWSERBASE_API_KEY=your_api_key # Browserbase 클라우드 사용 시
OPENAI_API_KEY=your_key # OpenAI 모델 사용 시
ANTHROPIC_API_KEY=your_key # Anthropic 모델 사용 시
GOOGLE_API_KEY=your_key # Gemini 모델 사용 시
```🧬 바이오 활용
프로덕션 웹 스크래핑 파이프라인**
API를 제공하지 않는 웹사이트에서 구조화된 데이터를 정기 수집하는 자동화 파이프라인 구축. `observe()`로 페이지 구조를 사전 탐색하고, `extract()`에 Zod 스키마를 전달하여 가격·재고·리뷰 등을 JSON 구조로 추출. 셀프힐링 기능으로 대상 사이트의 UI 변경에도 스크립트 수정 없이 지속 운영 가능. 캐시 HIT 시 100ms 미만 응답으로 대량 페이지 처리 시 토큰 비용을 최대 90% 절감
E2E 테스트 자동화 고도화**
기존 Playwright/Selenium 테스트가 셀렉터 변경마다 깨지는 문제를 해결. "로그인 → 상품 검색 → 장바구니 추가 → 결제"와 같은 핵심 사용자 흐름을 자연어로 기술하면 AI가 런타임에 요소를 식별하여 실행. Hybrid 모드(v3.4.0 기본값)로 DOM 기반 빠른 결정적 테스트를 실행하고, 비호환 모델 사용 시 자동으로 DOM 모드로 폴백하여 안정성 확보
브라우저 기반 RPA 에이전트**
`agent()` 프리미티브에 커스텀 도구를 주입하여 브라우저 자동화와 비즈니스 로직을 통합한 RPA 에이전트 구축. 예: 매일 특정 포털에 로그인하여 보고서를 다운로드하고, 데이터를 추출한 뒤 이메일로 발송하는 워크플로우를 `agent()` 한 번의 호출로 자율 실행. MCP 통합으로 Slack 알림, 데이터베이스 저장 등 후속 액션도 에이전트 내에서 직접 처리
📝 업데이트 노트
아직 업데이트 노트가 없습니다.
🧪 관련 생명의 코드
관련된 생명의 코드 글이 아직 없습니다.