Stagehand
자연어 지시와 코드를 섞어 쓰는 브라우저 SDK
npm install @browserbasehq/stagehand브라우저 에이전트를 만드는 SDK 입니다. 흔들리는 부분만 자연어로 지시하고 나머지는 Playwright 코드로 고정해, 자동화가 통째로 불안정해지는 것을 막습니다. 페이지에서 구조화된 데이터를 뽑는 기능도 있습니다.
판단
이럴 때 씁니다
- 자동화 대부분은 안정적인데 일부 단계만 화면 변화에 취약할 때
- 그 취약한 단계만 자연어로 맡기고 나머지는 코드로 고정하고 싶을 때
- 페이지에서 구조화된 데이터를 스키마에 맞춰 뽑아야 할 때
- Playwright 경험을 그대로 살리고 싶을 때
이럴 땐 쓰지 마세요
- 작업 전체를 지시 한 줄로 맡기고 싶을 때
- Playwright 를 쓰지 않는 스택일 때
- 브라우저 자동화 자체가 과한 단순 HTTP 요청 작업일 때
차별점
- 자연어 지시와 Playwright 코드를 한 스크립트에서 섞어 씁니다.
- 취약한 단계만 모델에 맡겨 비용과 안정성을 조절합니다.
- 스키마 기반 데이터 추출을 제공합니다.
- Playwright 위에 얹히므로 기존 지식을 그대로 씁니다.
워크플로
- 01npm 으로 패키지를 설치하고 Playwright 설정을 잇습니다.
- 02안정적인 단계는 기존 Playwright 코드로 그대로 씁니다.
- 03화면 변화에 취약한 단계만 자연어 지시로 바꿉니다.
- 04데이터 추출은 스키마를 정의해 결과 형식을 고정합니다.
주요 명령
| 명령 | 설명 |
|---|---|
npm install @browserbasehq/stagehand | 패키지를 설치합니다. |
함정
설치 전에 확인하세요
- v3 로 오며 패키지 구성이 바뀌었습니다. 예전 예제와 API 가 다를 수 있습니다.
- 자연어 단계는 호출마다 모델 비용이 듭니다. 남용하면 비용과 지연이 함께 늘어납니다.
- Browserbase 호스팅과 함께 쓰는 흐름이 문서 중심이라, 자체 실행 구성은 별도로 확인해야 합니다.
비교
Browser Use 는 작업 전체를 맡기는 방식이고 Stagehand 는 부분만 맡기는 방식입니다. 반복 실행하는 파이프라인이라면 어디가 흔들리는지 알고 그 지점만 유연하게 두는 편이 낫습니다. 탐색적 작업이라면 전부 맡기는 쪽이 빠릅니다.
최근 변경
v3.7.6 은 유지보수 릴리스입니다. iframe 안 좌표로 요소를 지목할 때 XPath 생성 로직이 어긋나던 문제를 고쳤고 전이 의존성을 정리했습니다. 문서 패키지는 저장소에서 분리됐습니다.