Stagehand - AI 기반 브라우저 자동화 프레임워크

프로젝트 개요

Stagehand는 Browserbase 회사에서 개발한 프로덕션 준비 완료 AI 브라우저 자동화 프레임워크입니다. 이 프레임워크는 기존 브라우저 자동화 도구의 문제점을 해결합니다. 기존 도구들은 저수준 코드 작성(예: Selenium, Playwright, Puppeteer)이 필요하거나, 고수준 에이전트를 사용하지만 프로덕션 환경에서 예측 불가능하다는 단점이 있었습니다.

핵심 기능

1. 유연한 제어 방식

• 코드와 자연어 결합: 개발자는 코드와 자연어를 언제 사용할지 선택할 수 있습니다.
• AI 내비게이션: 익숙하지 않은 페이지에서 AI를 사용하여 내비게이션합니다.
• 정밀 제어: 무엇을 해야 할지 명확히 아는 경우 코드(Playwright)를 사용합니다.

2. 미리보기 및 캐싱 기능

• 작업 미리보기: AI 작업을 실행하기 전에 미리 볼 수 있습니다.
• 캐싱 메커니즘: 반복 가능한 작업을 쉽게 캐싱하여 시간과 토큰 소모를 절약합니다.

3. 원클릭 컴퓨터 비전 모델 통합

• SOTA 모델 지원: OpenAI 및 Anthropic의 최신 컴퓨터 비전 모델을 한 줄의 코드로 통합할 수 있습니다.
• 원활한 통합: stagehand.agent 도입: 한 줄의 코드로 SOTA 컴퓨터 비전 모델 또는 Browserbase의 Open Operator를 Stagehand에 통합하는 강력한 새로운 방법입니다.

빠른 시작

설치

npx create-browser-app

로컬 개발

git clone https://github.com/browserbase/stagehand.git
cd stagehand
npm install
npx playwright install
npm run build
npm run example # ./examples/example.ts의 예시 스크립트 실행

환경 설정

cp .env.example .env
nano .env # .env 파일 편집하여 API 키 추가

사용 예시

기본 사용법

// Playwright 함수를 사용하여 페이지 객체 조작
const page = stagehand.page;
await page.goto("https://github.com/browserbase");

// act()를 사용하여 단일 작업 실행
await page.act("click on the stagehand repo");

// 컴퓨터 비전 에이전트를 사용하여 더 큰 작업 실행
const agent = stagehand.agent({
  provider: "openai",
  model: "computer-use-preview",
});
await agent.execute("Get to the latest PR");

// extract()를 사용하여 페이지에서 데이터 읽기
const { author, title } = await page.extract({
  instruction: "extract the author and title of the PR",
  schema: z.object({
    author: z.string().describe("The username of the PR author"),
    title: z.string().describe("The title of the PR"),
  }),
});

핵심 메서드

1. act() 메서드

• 단일 브라우저 작업 실행
• 자연어 지시 지원
• 클릭, 입력, 내비게이션 등 작업에 적합

2. extract() 메서드

• 페이지에서 구조화된 데이터 추출
• Zod 스키마 유효성 검사 통합
• 복잡한 데이터 추출 작업 지원

3. observe() 메서드

• 페이지 상태 및 변경 사항 관찰
• 조건 판단 및 상태 모니터링에 사용

4. agent() 메서드 (V2 새로운 기능)

• 고급 컴퓨터 비전 모델 통합
• 다단계 워크플로우 지원
• 복잡한 상호작용 시나리오에 적합

버전 2.0 새로운 기능

Stagehand V2는 여러 가지 주요 개선 사항을 도입했습니다.

성능 향상

• 번개처럼 빠른 act 및 extract: 자동화 실행 속도를 크게 향상시키는 주요 성능 개선
• a11y-tree 기반 최적화: 더 빠른 접근성 트리 기반의 act/extract 메서드

향상된 로깅

• 자동화 프로세스 가시성 향상
• 개선된 로깅 및 디버깅 기능

포괄적인 문서

• 완전히 재설계된 문서 사이트
• 더 나은 예시, 가이드 및 모범 사례

오류 처리 개선

• 더 안정적인 오류 처리 메커니즘
• 더 나은 오류 메시지 및 디버깅 지원

기술 아키텍처

의존성

• Playwright: 웹 자동화의 핵심 기반
• Zod: 데이터 구조 유효성 검사에 사용
• TypeScript: 주요 개발 언어

다국어 지원

TypeScript/JavaScript 버전 외에도 프로젝트는 다음을 제공합니다.

• Python 버전

Browserbase와의 통합

Browserbase는 클라우드 브라우저 제공업체이며, Stagehand를 사용하여 세션 재생, 프롬프트 관찰 가능성, 캡차 해결 등 고급 기능을 포함한 더 강력한 기능을 구축할 수 있습니다.

요약

Stagehand는 기존 코드 제어의 정밀성과 AI 자연어 처리의 유연성을 완벽하게 결합한 혁신적인 브라우저 자동화 프레임워크입니다. 간단한 웹 페이지 작업이든 복잡한 데이터 추출 작업이든 Stagehand는 프로덕션 수준의 솔루션을 제공할 수 있습니다. 2.0 버전의 성능 향상과 새로운 기능은 Stagehand를 현대 브라우저 자동화의 최고의 도구로 만듭니다.