Vercel agent-browser 실전 가이드: AI 에이전트의 눈과 손 — 토큰 90% 절감하는 브라우저 자동화
- Rust 기반 CLI: Vercel Labs가 만든 헤드리스 브라우저 자동화 도구. 설치 후 한 줄로 브라우저를 제어한다.
- 22,500+ GitHub 스타: 출시 직후 커뮤니티에서 폭발적인 반응. AI 에이전트 생태계의 새로운 표준으로 자리잡는 중.
- 스냅샷 기반 참조: DOM 셀렉터 대신
@e1,@e2같은 단순 ref를 사용. 에이전트가 처리해야 할 컨텍스트를 드라마틱하게 줄인다. - 토큰 90% 절감: Playwright MCP 대비 55,000+ 토큰에서 수천 토큰 수준으로. 긴 세션에서 비용 차이가 눈에 띄게 난다.
- Claude Code / Cursor 즉시 연동: AGENTS.md 내장 지원, skills 시스템 호환. 별도 설정 없이 AI 에이전트가 바로 쓸 수 있다.
AI 에이전트가 브라우저를 쓸 때 생기는 문제
AI 에이전트에게 "이 웹사이트에서 가격을 찾아줘"라고 말하면 어떤 일이 벌어질까.
에이전트는 브라우저를 열고, 페이지를 렌더링하고, 그 결과를 컨텍스트에 집어넣는다. 문제는 그 "결과"가 얼마나 큰지다.
Playwright MCP를 써본 사람이라면 알 것이다. 페이지 하나를 snapshot하면 HTML 전체, 모든 DOM 노드, aria 속성, 중첩된 div들이 전부 컨텍스트로 들어온다. 평범한 커머스 페이지 하나에서 55,000토큰이 넘어가는 경우가 흔하다. Claude Opus 기준으로 입력 토큰 1,000개당 $0.015니까, 세션 몇 번만 돌려도 비용이 쌓인다.
더 심각한 문제는 품질이다. 컨텍스트가 길어질수록 에이전트의 집중력이 떨어진다. 필요한 버튼을 찾아야 하는데, 그 버튼 주변에 광고 배너, 추천 상품, 쿠키 동의 팝업, 헤더 네비게이션이 전부 컨텍스트를 차지하고 있다. 에이전트가 엉뚱한 곳을 클릭하는 이유 중 하나가 여기 있다.
Vercel Labs는 이 문제를 다르게 접근했다.
agent-browser란 무엇인가
agent-browser는 Vercel Labs가 개발한 헤드리스 브라우저 자동화 CLI다. 핵심 아이디어는 단순하다. 에이전트에게 페이지 전체를 보여주는 대신, 접근성 트리(accessibility tree)의 압축된 스냅샷만 보여준다.
Rust로 작성됐다. 빠르고, 의존성이 적고, 바이너리 하나로 동작한다.
GitHub에 올라온 지 얼마 되지 않아 22,500개 이상의 스타를 받았다. 이 속도는 단순한 관심이 아니라 실제 pain point를 건드렸다는 신호다. AI 에이전트를 실제로 운영하는 개발자들이 겪고 있는 문제를 해결하기 때문이다.
라이선스는 Apache 2.0. 상업적 사용에도 아무 제약이 없다.
핵심 차이: DOM 셀렉터 vs 스냅샷 참조
기존 브라우저 자동화 도구들은 DOM 셀렉터를 쓴다.
# Playwright 방식
page.click('button[data-testid="submit-button"]')
page.fill('#email-input', 'user@example.com')
에이전트가 이 셀렉터를 알아내려면 페이지 전체 HTML을 봐야 한다. data-testid가 뭔지, #email-input이 어디 있는지 찾으려면 컨텍스트가 필요하다.
agent-browser는 다르다. snapshot 명령을 실행하면 이런 출력이 나온다:
@e1 [button] "로그인"
@e2 [input] "이메일 주소" (type=email)
@e3 [input] "비밀번호" (type=password)
@e4 [link] "비밀번호 찾기"
@e5 [button] "회원가입"
페이지에서 상호작용 가능한 요소만 추출해서 단순한 참조(@e1, @e2)로 보여준다. 에이전트는 이걸 보고 click @e1 또는 fill @e2 "user@example.com"을 실행한다.
DOM 전체를 보는 것과 이 스냅샷을 보는 것의 토큰 차이가 90%다. 에이전트 입장에서는 같은 작업을 10분의 1의 토큰으로 할 수 있다는 뜻이다.
스냅샷 기반 참조는 페이지가 리렌더링돼도 안정적이다. 동적 클래스명(btn-xk3j9)이나 자동 생성 ID가 바뀌어도 접근성 레이블이 같으면 동일한 @ref로 접근된다. 이는 기존 CSS 셀렉터 기반 자동화가 깨지는 주요 원인을 제거한다.
설치와 기본 사용법
설치는 두 단계다.
# CLI 설치
npm install -g agent-browser
# Chrome 브라우저 설치 (내장 Chromium)
agent-browser install
agent-browser install은 자체 Chromium 인스턴스를 내려받는다. 로컬에 Chrome이 있어도 별도 설치하는 것이 권장된다. 시스템 Chrome 버전에 의존하지 않아서 재현 가능한 환경이 된다.
기본 명령어
# 브라우저에서 URL 열기
agent-browser open https://example.com
# 현재 페이지 스냅샷 (상호작용 가능한 요소 목록)
agent-browser snapshot
# 요소 클릭
agent-browser click @e2
# 텍스트 입력
agent-browser fill @e3 "입력할 텍스트"
# 키 입력 (엔터, 탭 등)
agent-browser press Enter
# 현재 URL 확인
agent-browser url
# 페이지 뒤로 가기
agent-browser back
명령어가 직관적이다. open → snapshot → click/fill 순서로 흐른다. 에이전트가 이 패턴을 학습하면 새로운 사이트에도 즉시 적용할 수 있다.
실제 스냅샷 출력 예시
네이버 메인 페이지를 열고 스냅샷을 찍으면 이런 식으로 나온다:
@e1 [button] "검색"
@e2 [input] "검색어를 입력해 주세요" (role=searchbox)
@e3 [link] "메일"
@e4 [link] "카페"
@e5 [link] "블로그"
@e6 [link] "지식IN"
@e7 [button] "로그인"
...
전체 DOM이 아니라 사용자가 실제로 상호작용할 수 있는 요소만 보인다. 광고 배너, 장식용 이미지, 숨겨진 div들은 필터링된다.
AI 에이전트 연동: Claude Code에서 쓰기
agent-browser의 진가는 AI 에이전트와 연동할 때 나온다.
AGENTS.md 내장 지원
agent-browser는 AGENTS.md 파일을 자동으로 생성하는 기능을 제공한다. AGENTS.md는 AI 코딩 에이전트(Claude Code, Cursor, Windsurf 등)가 프로젝트의 작업 방식을 이해하도록 돕는 문서다.
# 프로젝트 루트에 AGENTS.md 자동 생성
agent-browser init
생성된 AGENTS.md에는 agent-browser 명령어 사용법, 스냅샷 해석 방법, 폼 작성 패턴 등이 포함된다. Claude Code가 이 파일을 읽으면 브라우저 자동화 작업을 별도 설명 없이 처리할 수 있다.
Claude Code skills 시스템 연동
Claude Code의 .claude/ 디렉토리에 skill을 등록하면 /agent-browser 명령으로 즉시 사용할 수 있다.
# Claude Code 프로젝트에서
agent-browser setup-claude
이 명령은 .claude/skills/agent-browser/SKILL.md를 생성한다. 이후 Claude Code 세션에서 "이 폼을 자동으로 작성해줘"라고 하면 에이전트가 agent-browser CLI를 사용해 직접 실행한다.
직접 프롬프트에서 사용
Claude Code에서 직접 지시할 수도 있다:
나: agent-browser로 https://example.com 에 접속해서
"Contact Us" 폼에 이메일 주소를 입력하고 제출해줘
Claude: agent-browser open https://example.com 실행 중...
snapshot 결과:
@e1 [link] "Contact Us"
@e3 [input] "Your Email"
@e5 [button] "Submit"
agent-browser click @e1
agent-browser fill @e3 "hello@example.com"
agent-browser click @e5
Playwright MCP와 다르게 중간 과정의 컨텍스트가 최소화된다. 에이전트가 각 단계에서 봐야 하는 정보가 명확하게 분리된다.
agent-browser는 현재 헤드리스 모드로 동작한다. 로그인이 필요한 사이트의 경우 세션 쿠키를 export/import하는 방법을 활용해야 한다. agent-browser export-cookies와 agent-browser import-cookies로 인증 상태를 유지할 수 있다.
실전 사용 예시
1. 경쟁사 가격 모니터링
1인 개발자가 자주 하는 작업 중 하나가 경쟁사 가격 추적이다.
#!/bin/bash
# monitor-prices.sh
agent-browser open https://competitor.com/pricing
agent-browser snapshot | grep -E "@e[0-9]+ .*(price|plan|원|달러)"
Claude Code나 다른 AI 에이전트와 연동하면 이 스냅샷 결과를 분석해서 가격 변동을 감지하고 Slack 알림까지 자동화할 수 있다.
2. 폼 자동 제출
B2B 영업에서 여러 플랫폼에 동일한 정보를 등록해야 할 때:
agent-browser open https://directory.example.com/register
agent-browser snapshot
# 출력된 @ref 보고 각 필드에 fill 실행
agent-browser fill @e2 "회사명"
agent-browser fill @e3 "이메일@example.com"
agent-browser fill @e4 "제품 설명..."
agent-browser click @e10 # Submit 버튼
에이전트에게 "이 목록의 10개 디렉토리에 모두 등록해줘"라고 하면 반복 작업을 자동화한다.
3. E2E 테스트 자동화
기존 Playwright 테스트를 대체하거나 보완하는 용도로도 쓸 수 있다. 특히 AI 에이전트가 테스트 케이스를 자동 생성하는 시나리오에서 유용하다.
# 결제 플로우 검증
agent-browser open https://myapp.com/pricing
agent-browser snapshot
agent-browser click @e3 # "시작하기" 버튼
agent-browser snapshot
agent-browser fill @e1 "test@example.com"
agent-browser fill @e2 "password123"
agent-browser click @e5 # 다음 단계
Claude Code에서 "결제 플로우를 테스트해줘"라고 하면 에이전트가 이 과정을 자동으로 실행하고 각 단계의 성공/실패를 보고한다.
4. 웹 리서치 자동화
경쟁사 분석, 트렌드 리서치, 링크드인 프로필 수집 등 반복적인 리서치 작업:
agent-browser open https://producthunt.com
agent-browser snapshot
# 오늘의 top products @ref 목록 확인
agent-browser click @e5 # 첫 번째 제품 링크
agent-browser snapshot
# 제품 설명, 투표 수, 댓글 @ref 확인
AI 에이전트에게 "오늘 Product Hunt top 10 제품의 이름, 설명, 투표 수를 정리해줘"라고 하면 자동으로 탐색하고 데이터를 수집한다.
Playwright MCP vs agent-browser 비교
| 항목 | Playwright MCP | agent-browser |
|---|---|---|
| 토큰 사용량 | 페이지당 55,000+ | 페이지당 수천 토큰 (90% 절감) |
| 설치 방식 | MCP 서버 + Claude 연동 설정 | npm 글로벌 설치, 2분 이내 |
| 셀렉터 방식 | CSS/XPath/ARIA | 스냅샷 기반 @ref |
| 언어 | TypeScript/JavaScript | Rust (CLI) |
| 에이전트 친화성 | MCP 프로토콜 | 직접 CLI 실행 |
| 동적 페이지 안정성 | 클래스명 변경에 취약 | 접근성 레이블 기반으로 안정적 |
| 학습 곡선 | Playwright API 이해 필요 | open/snapshot/click/fill 4개 |
| 오픈소스 | 오픈소스 (Apache 2.0) | 오픈소스 (Apache 2.0) |
| GitHub 스타 | Playwright: 68K+ | 22.5K+ (출시 직후) |
| 커뮤니티 | 성숙한 생태계 | 빠르게 성장 중 |
Playwright MCP가 무조건 나쁜 것은 아니다. 복잡한 인터랙션, 네트워크 요청 인터셉트, 스크린샷 캡처 등 Playwright의 full power가 필요한 경우가 있다. 하지만 AI 에이전트가 단순히 "페이지에서 정보 찾기"와 "폼 작성"을 하는 대부분의 케이스에서는 agent-browser가 훨씬 효율적이다.
두 도구를 함께 쓰는 전략도 유효하다. 토큰 비용이 중요한 반복 작업은 agent-browser로, 세밀한 제어가 필요한 복잡한 테스트는 Playwright로 분리하면 된다. 에이전트에게 작업 성격에 따라 도구를 선택하도록 지시할 수 있다.
1인 개발자에게 특히 유용한 이유
agent-browser가 1인 개발자 도구로 주목받는 이유가 있다.
비용: AI 에이전트를 일상적으로 쓰는 개발자라면 토큰 비용이 월 수만 원씩 나온다. 브라우저 자동화 작업에서 90% 절감이 된다면 그 차이는 실질적이다.
속도: Rust 기반이라 빠르다. 브라우저 자동화의 병목은 보통 네트워크와 렌더링이지만, CLI 오버헤드가 없는 것도 세션이 많아질수록 체감된다.
단순함: 배워야 할 API가 4개다. open, snapshot, click, fill. 복잡한 설정 없이 30분 안에 첫 자동화 스크립트를 만들 수 있다.
에이전트 시대 적합성: Playwright는 인간이 직접 셀렉터를 작성하는 시대를 위해 설계됐다. agent-browser는 AI 에이전트가 도구를 쓰는 시대를 위해 설계됐다. 접근 방식 자체가 다르다.
현재 한계와 주의사항
솔직히 말하면 아직 초기 단계다.
- 문서가 부족하다: GitHub README 수준의 문서가 전부다. 엣지 케이스 처리 방법은 직접 실험해야 한다.
- 세션 관리: 로그인 상태 유지, 다중 탭, 팝업 처리 등 복잡한 시나리오에서 아직 미완성인 부분이 있다.
- JavaScript-heavy 사이트: SPA에서 동적 렌더링이 완료되기 전에 스냅샷을 찍으면 요소가 누락될 수 있다.
wait명령을 활용해야 한다. - 커뮤니티: Playwright 대비 레퍼런스와 예제가 적다. 문제가 생겨도 Stack Overflow에서 답을 찾기 어렵다.
빠르게 발전하고 있는 도구다. Vercel Labs가 만든 만큼 장기 유지보수에 대한 신뢰는 있다. 다만 프로덕션 크리티컬한 자동화에 쓰기 전에 충분히 테스트해볼 것을 권장한다.
결론: 에이전트 시대의 브라우저 자동화
AI 에이전트가 실제로 작동하려면 세 가지가 필요하다. 생각하는 능력(LLM), 행동하는 능력(도구), 그리고 그 중간의 효율(컨텍스트 관리).
Playwright MCP는 에이전트에게 브라우저를 주는 첫 번째 방법이었다. agent-browser는 그것을 훨씬 효율적으로 만드는 두 번째 방법이다.
22,500개의 스타는 이 방향이 맞다는 시장의 투표다.
1인 개발자로서 AI 에이전트를 매일 쓴다면, agent-browser를 도구 벨트에 추가할 가치가 있다. 설치에 2분, 첫 스크립트 실행에 10분이면 충분하다. 비용 절감과 속도 향상이 실제로 느껴지는 도구다.
npm install -g agent-browser
agent-browser install
agent-browser open https://example.com
agent-browser snapshot
# 여기서부터 에이전트가 나머지를 처리한다