![[TIP]Vercel Agent Browser 완벽 설치 가이드](/_next/image?url=https%3A%2F%2Ftzmluihlahuykicindyt.supabase.co%2Fstorage%2Fv1%2Fobject%2Fpublic%2Fblog%2Fthumbnails%2F1768895150595_7nqag.png&w=3840&q=75)
[TIP]Vercel Agent Browser 완벽 설치 가이드
Vercel Agent Browser 완벽 설치 가이드
Vercel Labs에서 공개한 Agent Browser는 AI 에이전트(Claude Code, Cursor 등)가 브라우저를 직접 제어할 수 있게 해주는 혁신적인 도구입니다. 이 가이드에서는 CLI 엔진 설치부터 AI 에이전트용 Skill 설정까지 완벽하게 다룹니다.
🔄 설치 워크플로우
[CLI 설치] ──▶ [브라우저 엔진 설정] ──▶ [Skill 설치] ──▶ [테스트 및 검증]
| 단계 | 설명 | 결과 |
|---|---|---|
| 1 | Agent Browser CLI 설치 | 전역 브라우저 제어 도구 |
| 2 | 브라우저 엔진 다운로드 | Chromium 기반 엔진 구성 |
| 3 | AI 에이전트 Skill 설치 | Claude/Cursor와 연동 |
| 4 | 테스트 및 검증 | 브라우저 자동화 작동 확인 |
📖 상세 설치 가이드
1단계: Agent Browser CLI 설치
가장 먼저 로컬 환경에서 브라우저를 제어할 수 있는 CLI 엔진을 설치해야 합니다.
방법 A: npm 전역 설치 (권장)
# 1. 전역(Global) 패키지 설치
npm install -g agent-browser
# 2. 전용 브라우저(Chromium) 엔진 다운로드 및 설정
agent-browser install
방법 B: 소스 코드 빌드 (Rust 환경 필요)
Rust의 빠른 성능을 활용하려는 개발자라면 소스에서 직접 빌드할 수 있습니다.
# 1. 저장소 클론
git clone https://github.com/vercel-labs/agent-browser
cd agent-browser
# 2. 의존성 설치 및 빌드
pnpm install
pnpm build
# 3. 브라우저 엔진 설치
agent-browser install
2단계: AI 에이전트용 Skill 설치
Vercel은 add-skill이라는 전용 패키지 매니저를 통해 AI 에이전트에 스킬을 쉽게 추가할 수 있는 기능을 출시했습니다.
자동 설치 (추천)
# Vercel Labs의 공식 에이전트 스킬셋 전체 설치
npx add-skill vercel-labs/agent-skills
# Agent Browser 스킬만 선택 설치 (전역)
npx add-skill vercel-labs/agent-skills --skill agent-browser -g
# 특정 에이전트 전용 설치 (예: Claude Code)
npx add-skill vercel-labs/agent-skills --skill agent-browser -a claude-code
옵션 설명:
-g: 전역(Global)으로 설치하여 모든 프로젝트에서 사용 가능-a: 특정 에이전트 전용으로 지정 (claude-code, cursor 등)
수동 설치
자동 설치가 작동하지 않거나 직접 관리하고 싶을 경우:
- GitHub vercel-labs/agent-browser 저장소에서
agent-browser.ts파일 다운로드 - 사용 중인 에이전트의 스킬 폴더에 복사:
- Claude Code:
~/.claude/skills/agent-browser/ - Cursor:
~/.cursor/skills/agent-browser/
- Claude Code:
- 에이전트 재시작 또는
What skills do you have?질문으로 로드 확인
3단계: 설치 확인 및 테스트
설치가 완료되었다면 AI 에이전트에게 다음과 같이 요청하여 정상 작동 여부를 확인할 수 있습니다.
테스트 요청:
"agent-browser를 사용해서 https://www.google.com을 열고 화면 스냅샷을 찍어줘."
에이전트 내부 동작 과정:
agent-browser open https://google.com- 브라우저 세션 시작 및 URL 이동agent-browser snapshot -i- 인터랙티브 요소(버튼, 입력창)에 인덱스 번호(@e1, @e2...) 부착- 인덱스를 기반으로 후속 작업(
click,type등) 수행
📊 핵심 명령어 레퍼런스
AI 에이전트가 Skill을 통해 호출하는 주요 명령어들입니다.
| 명령어 | 설명 | 사용 예시 |
|---|---|---|
open <url> | 브라우저 세션 시작 및 URL 이동 | agent-browser open https://google.com |
snapshot -i | 인터랙티브 요소에 인덱스 번호 부착 | agent-browser snapshot -i |
click @e# | 특정 인덱스 요소 클릭 | agent-browser click @e5 |
type @e# "text" | 특정 인덱스 요소에 텍스트 입력 | agent-browser type @e3 "hello" |
🛠️ 트러블슈팅
| 문제 | 원인 | 해결 방법 |
|---|---|---|
| command not found | 전역 설치 실패 또는 PATH 미설정 | npm install -g agent-browser 재실행 후 터미널 재시작 |
| 브라우저 엔진 오류 | agent-browser install 미실행 | agent-browser install로 Chromium 엔진 다운로드 |
| Skill 미인식 | 에이전트 스킬 폴더 경로 오류 | ~/.claude/skills/ 또는 ~/.cursor/skills/ 경로 확인 |
| 권한 거부 | 파일 시스템 권한 문제 | sudo 또는 관리자 권한으로 재시도 (macOS/Windows) |
| 포트 충돌 | 기본 포트 사용 중 | 다른 포트 지정 또는 사용 중인 프로세스 종료 |
✨ 활용 팁
- 전역 설치 우선: 프로젝트마다 설치하지 말고 전역 설치(
-g)로 모든 프로젝트에서 활용 - 에이전트 자동 감지:
add-skillCLI는 설치된 에이전트 경로를 자동으로 감지하므로 수동 경로 지정 불필요 - 스냅샷 활용:
-i옵션을 사용하면 요소에 인덱스가 부착되어 AI 에이전트가 정확한 요소를 선택 가능 - Chromium 엔진: 별도의 브라우저 설치 없이 내장된 Chromium 엔진을 사용하므로 가볍고 빠름
- Rust 빌드: 성능이 중요한 경우 소스에서 빌드하여 네이티브 속도 활용
📚 추가 자료
- GitHub Repository: vercel-labs/agent-browser - CLI 설치 및 명령어 가이드
- Vercel Agent-Skills: vercel-labs/agent-skills - add-skill CLI 사용법 및 에이전트 연동
- Claude Code Docs: Agent Skills Guide - Skill 디렉토리 구조 및 로드 원리
- Technical Blog: "Complete Guide to agent-browser" (2026.01.13 업데이트)
★ Insight ─────────────────────────────────────
Agent Browser는 기존의 Playwright나 Puppeteer 같은 브라우저 자동화 도구와 달리,
AI 에이전트와의 통합에 최적화되어 있습니다.
특히 -i 옵션을 통한 요소 인덱싱은 LLM이 정확한 요소를 선택하기 어렵다는 문제를 해결합니다.
또한 Rust로 작성된 CLI 엔진은 Node.js 기반 도구보다 현저히 빠른 성능을 제공합니다.
─────────────────────────────────────────────────
⚠️ 면책 조항
본 가이드를 따르면서 발생하는 모든 결과에 대한 책임은 전적으로 사용자 본인에게 있습니다. 이 문서는 참고용으로 제공되며, 작성자는 어떠한 손해나 문제에 대해 책임지지 않습니다.
금지 사항:
- 본 내용을 악의적인 목적으로 사용하는 것을 엄격히 금지합니다.
- 타인의 권리를 침해하거나 불법적인 활동에 사용하는 것을 금지합니다.
- 상업적 목적의 무단 복제나 재배포를 금지합니다.
본 가이드의 내용은 학습 및 교육 목적으로만 사용해야 합니다.