Stagehand v4가 줄인 것은 모델이 아니라 브라우저 왕복이다

브라우저 자동화에 LLM을 붙이면 모델 응답만큼이나 브라우저와 제어 코드 사이의 왕복이 느려진다. 특히 제어 코드는 한 리전에 있고 원격 브라우저는 다른 곳에 있으면 클릭, 조회, 입력을 할 때마다 네트워크 지연이 쌓인다. Stagehand v4에서 내가 주목한 부분은 모델을 더 크게 만든 것이 아니라 이 실행 경로를 브라우저 가까이 옮겼다는 점이다.

Stagehand v4.0.0은 npm 메타데이터 기준 2026년 8월 10일 공개됐고, 현재 최신 안정 버전은 9월 9일 공개된 4.1.0이다. 이 소식이 GeekNews 피드에 등록된 시각은 9월 20일 오전 7시 52분이다. 출시일과 피드 등록일은 한 달 넘게 차이 난다. 따라서 이 글은 당일 출시 소식보다 v4의 구조와 적용 조건을 살펴보는 글에 가깝다.

브라우저 옆으로 옮긴 실행 경로

v4는 브라우저 프로토콜을 중심으로 TypeScript, Python, Go SDK가 같은 코어를 사용하는 구조로 다시 만들어졌다. 공식 변경 기록은 이를 protocol-first 모노레포라고 설명한다. 브라우저를 시작할 때 확장 런타임을 함께 로드하고, SDK 명령을 브라우저 가까이에서 처리한다.

이 변화가 중요한 이유는 브라우저 작업이 대개 잘게 쪼개져 있기 때문이다. 요소를 찾고, 상태를 읽고, 클릭한 뒤 다시 결과를 확인한다. 각 호출의 처리 시간이 짧아도 왕복 횟수가 많으면 전체 지연은 커진다. v4의 실험적 experimentalBatch()는 여러 결정적 작업을 브라우저 옆에서 묶어 실행해 이 비용을 줄인다. 다만 콜백이 애플리케이션 프로세스의 변수를 캡처할 수 없고 패치 버전에서도 바뀔 수 있는 실험 기능이라는 제한이 있다. 공식 마이그레이션 문서도 이 전제를 명시한다.

공식 저장소는 Browserbase 환경에서 동등한 클라우드 Playwright 브라우저보다 2배 빠르다고 주장한다. 접근성 트리에서 모델에 불필요한 내용을 덜어 토큰 사용도 줄였다고 설명한다. 하지만 이는 Browserbase가 정한 스크립트와 환경에서 나온 결과다. 로컬 브라우저, 대상 사이트의 응답 시간, 선택한 모델, 캐시 적중률이 달라지면 같은 배수를 기대할 근거는 없다. 평가 결과는 도입 전 자체 시나리오로 다시 측정할 출발점이지 보편적인 성능 보장은 아니다.

안정된 선택자와 모델 호출을 섞어 쓴다

Stagehand의 핵심 API는 자연어로 동작을 실행하는 act(), 후보 요소와 선택자를 찾는 observe(), 스키마에 맞춰 데이터를 읽는 extract()다. 페이지가 바뀌면 동작을 다시 추론하는 self-healing도 제공한다. 반면 고정된 CSS 선택자를 아는 작업에는 locator()를 그대로 쓸 수 있다. 공식 README는 이 두 방식을 함께 제공하는 점을 강조한다.

여기서 자연어 호출을 모든 클릭에 쓰는 것은 좋은 기본값이 아니다. 모델 호출은 지연과 비용을 추가하고 결과의 변동성도 만든다. 결제 버튼처럼 의미는 안정적이지만 DOM 구조가 자주 바뀌는 지점에는 observe()나 act()가 유용하다. 반대로 data-testid가 관리되는 내부 서비스라면 결정적 선택자를 유지하는 편이 빠르고 디버깅하기 쉽다.

로그인 자동화에서는 경계를 더 분명히 해야 한다. 공식 예제는 observe()로 이메일·비밀번호 필드의 선택자만 찾고, 실제 자격 증명은 모델 프롬프트가 아니라 locator().fill()에 전달한다. 세션 파일, 모델 제공자 로그, 원격 브라우저 녹화에 어떤 데이터가 남는지도 별도로 확인해야 한다. self-healing은 선택자 변경을 견디게 할 뿐 권한과 비밀 관리 문제를 해결하지 않는다.

Playwright 테스트를 그대로 대체하지는 않는다

이름이 비슷한 API가 많아도 Stagehand v4는 Playwright 호환 계층이 아니다. 공식 변환 표를 보면 Chromium만 지원하고 Firefox와 WebKit은 지원하지 않는다. 브라우저당 컨텍스트도 하나이며 Playwright의 자동 대기, 네트워크 요청 가로채기, 요청·응답 이벤트, PDF 생성에는 같은 수준의 내장 대응 API가 없다. 테스트 러너와 assertion도 Vitest나 Jest 같은 별도 도구를 가져와야 한다.

이 차이는 용도를 나누는 기준이 된다.

요구	우선 검토할 선택
세 브라우저 회귀 테스트, 네트워크 모킹, 엄격한 assertion	Playwright 유지
외부 사이트의 잦은 DOM 변경을 견디는 에이전트 작업	Stagehand의 act()·observe() 검토
반복되는 구조화 데이터 수집	extract()와 스키마 검증 검토
안정된 내부 화면의 단순 조작	결정적 선택자 우선, 필요한 구간만 모델 호출

기존 Playwright 스위트 전체를 옮기기보다 변동이 잦은 흐름 한두 개를 골라 병행 평가하는 편이 안전하다. 네트워크 계층을 직접 관찰하거나 브라우저별 차이를 검증하는 테스트라면 전환 비용이 이득보다 클 가능성이 높다.

도입 판단은 성공률과 비용을 함께 본다

Stagehand는 MIT 라이선스이며 로컬 실행과 Browserbase 실행을 모두 제공한다. 4.1.0의 npm 메타데이터에는 Node.js 22.18 이상이 요구되고, 로컬 실행에는 설치된 Chrome이 필요하다. 저장소의 설치 안내와 npm 레지스트리 메타데이터를 함께 확인할 수 있다.

작은 검증에서는 다음 네 가지를 기록하는 것이 좋다.

1. 같은 입력을 반복했을 때 작업 성공률과 실패 유형
2. 단계별 브라우저 왕복 횟수와 전체 지연 시간
3. 모델 토큰, 원격 브라우저, 캐시를 합친 실행 비용
4. 사이트 변경 뒤 self-healing이 복구한 경우와 잘못된 동작을 한 경우

내가 내릴 결론은 Playwright를 Stagehand로 바꾸자는 것이 아니다. 결정적 자동화만으로 유지하기 어려운 외부 UI가 있고, 그 흐름에서 모델 호출 비용보다 변경 대응 비용이 더 크다면 v4의 구조가 의미가 있다. 반대로 브라우저 호환성, 네트워크 모킹, 재현 가능한 assertion이 핵심이라면 Playwright가 맡을 범위를 남겨야 한다. 다음에 확인할 것은 홍보된 평균 속도가 아니라 우리 작업에서 가장 자주 실패하는 단계가 실제로 브라우저 왕복과 선택자 변경 때문인지다.

참고 자료

• Stagehand 공식 저장소
• Stagehand 변경 기록
• Playwright에서 Stagehand v4로 옮기기
• Stagehand 브라우저 에이전트 평가
• Stagehand npm 레지스트리 메타데이터