vercel-labs/agent-browser

AI 에이전트를 위한 브라우저 자동화 CLI (Command Line Interface). 빠른 네이티브 Rust CLI입니다.

네이티브 Rust 바이너리를 설치합니다:

npm install -g agent-browser
agent-browser install # (최초 1회) Chrome for Testing에서 Chrome 다운로드

package.json에 버전을 고정하려는 프로젝트의 경우:

npm install agent-browser
agent-browser install

그 후 package.json 스크립트를 통해 사용하거나 agent-browser를 직접 호출하여 사용합니다.

brew install agent-browser
agent-browser install # (최초 1회) Chrome for Testing에서 Chrome 다운로드

cargo install agent-browser
agent-browser install # (최초 1회) Chrome for Testing에서 Chrome 다운로드

Node.js 24+, pnpm 11+, 그리고 Rust가 필요합니다.

git clone https://github.com/vercel-labs/agent-browser
cd agent-browser
pnpm install
...

Linux의 경우, 시스템 의존성(system dependencies)을 설치하세요:

agent-browser install --with-deps

패키지 관리자가 필요한 모든 브라우저 라이브러리를 설치할 수 없는 경우, 이 명령은 0이 아닌 종료 코드(nonzero exit)를 반환합니다.

최신 버전으로 업그레이드:

agent-browser upgrade

설치 방법(npm, Homebrew 또는 Cargo)을 감지하여 적절한 업데이트 명령을 자동으로 실행합니다.

Chrome- agent-browser install을 실행하여 Chrome for Testing(Google의 공식 자동화 채널)에서 Chrome을 다운로드합니다. 기존에 설치된 Chrome, Brave, Playwright 및 Puppeteer는 자동으로 감지됩니다. 데몬(daemon) 실행에는 Playwright나 Node.js가 필요하지 않습니다.

Node.js 24+ 및 pnpm 11+- 소스에서 빌드할 때만 필요합니다.

Rust- 소스에서 빌드할 때만 필요합니다 (위의 'From Source' 섹션 참조).

agent-browser open example.com
agent-browser snapshot # 참조(refs)가 포함된 접근성 트리(accessibility tree) 가져오기
agent-browser click @e2 # 스냅샷의 참조를 통해 클릭
...

동의 배너나 모달과 같이 다른 요소가 대상의 클릭 지점을 가리고 있는 경우 클릭이 조기에 실패합니다. 보고된 가림 요소를 닫거나 상호작용한 다음, 원래의 참조를 다시 시도하기 전에 새로운 스냅샷을 찍으세요.

Headless Chromium 스크린샷은 일관된 이미지 출력을 위해 기본 스크롤바를 숨깁니다. 기본 스크롤바를 보이게 유지하려면 실행 시 --hide-scrollbars false를 전달하세요.

agent-browser click "#submit"
agent-browser fill "#email" "test@example.com"
agent-browser find role button click --name "Submit"

agent-browser open # 브라우저 실행 (탐색 없음); about:blank 상태 유지
agent-browser open <url> # 실행 + URL로 탐색 (별칭: goto, navigate)
agent-browser click <sel> # 요소 클릭 (--new-tab을 사용하여 새 탭에서 열기)
...

agent-browser get text <sel> # 텍스트 콘텐츠 가져오기
agent-browser get html <sel> # innerHTML 가져오기
agent-browser get value <sel> # 입력값 (input value) 가져오기
...

agent-browser is visible <sel> # 가시성 여부 확인
agent-browser is enabled <sel> # 활성화 여부 확인
agent-browser is checked <sel> # 체크 여부 확인

agent-browser find role <role> <action> [value] # ARIA 역할 (role)로 찾기
agent-browser find text <text> <action> # 텍스트 콘텐츠로 찾기
agent-browser find label <label> <action> [value] # 레이블 (label)로 찾기
...

Actions (동작): click, fill, type, hover, focus, check, uncheck, text

Options (옵션): --name <name> (접근 가능한 이름으로 역할 필터링), --exact (정확한 텍스트 일치 요구)

Examples (예시):

agent-browser find role button click --name "Submit"
agent-browser find text "Sign In" click
agent-browser find label "Email" fill "test@test.com"
...

agent-browser wait <selector> # 요소가 보일 때까지 대기
agent-browser wait <ms> # 지정된 시간(밀리초) 동안 대기
agent-browser wait --text "Welcome" # 텍스트가 나타날 때까지 대기 (부분 일치)
...

Load states (로드 상태): load, domcontentloaded, networkidle

단일 호출 내에서 여러 명령을 실행하세요. 명령은 따옴표로 묶인 인자로 전달하거나 stdin을 통해 JSON으로 파이프(pipe)할 수 있습니다. 이를 통해 다단계 워크플로를 실행할 때 명령마다 발생하는 프로세스 시작 오버헤드를 방지할 수 있습니다.

# 인자 모드 (Argument mode): 각 따옴표로 묶인 인자가 전체 명령어가 됩니다.
agent-browser batch "open https://example.com" "snapshot -i" "screenshot"
# 첫 번째 에러 발생 시 중단하려면 --bail 사용
...

agent-browser clipboard read # 클립보드에서 텍스트 읽기
agent-browser clipboard write "Hello, World!" # 클립보드에 텍스트 쓰기
agent-browser clipboard copy # 현재 선택 영역 복사 (Ctrl+C)
...

agent-browser mouse move <x> <y> # 마우스 이동
agent-browser mouse down [button] # 버튼 누르기 (left/right/middle)
agent-browser mouse up [button] # 버튼 떼기
...

agent-browser set viewport <w> <h> [scale] # 뷰포트 (viewport) 크기 설정 (Retina용 scale, 예: 2)
agent-browser set device <name> # 디바이스 (device) 에뮬레이션 ("iPhone 14")
agent-browser set geo <lat> <lng> # 지리적 위치 (geolocation) 설정
...

agent-browser cookies # 모든 쿠키 (cookies) 가져오기
agent-browser cookies set <name> <val> # 쿠키 설정
agent-browser cookies set --curl <file> # Copy-as-cURL 덤프에서 쿠키 가져오기
...

agent-browser network route <url> # 요청 가로채기 (Intercept)
agent-browser network route <url> --abort # 요청 차단 (Block)
agent-browser network route <url> --body <json> # 응답 모킹 (Mock response)
...

agent-browser tab # 탭 (tab) 목록 표시 (`tabId` 및 선택적 라벨 표시)
agent-browser tab new [url] # 새 탭 열기 (선택적으로 URL 포함)
agent-browser tab new --label docs [url] # 사용자 지정 라벨이 지정된 새 탭 열기
...

탭 ID는 t1, t2, t3 형태의 고정된 문자열입니다.
이 ID들은 세션 내에서 재사용되지 않으므로, 스크립트와 에이전트(agent)는 다른 탭이 열리거나 닫힌 후에도 동일한 탭을 계속 참조할 수 있습니다. tab 2와 같은 위치 기반 정수는 허용되지 않습니다. t 접두사는 핸들(handle)과 인덱스(index)를 구분하며, 요소 참조(element refs)에 사용되는 @e1 컨벤션을 따릅니다.

또한 기억하기 쉬운 라벨(docs, app, admin)을 할당하여 ID와 교체하여 사용할 수 있습니다. 라벨은 자동으로 생성되지 않으며 페이지 이동 시에도 다시 작성되지 않습니다. 사용자가 직접 이름을 짓고 유지할 수 있습니다.

agent-browser tab new --label docs https://docs.example.com
agent-browser tab docs # docs 탭으로 전환
agent-browser snapshot # docs를 위한 refs 채우기
...

agent-browser frame <sel> # iframe으로 전환
agent-browser frame main # 메인 프레임으로 복귀

agent-browser dialog accept [text] # 수락 (선택 사항인 프롬프트 텍스트와 함께)
agent-browser dialog dismiss # 거절
agent-browser dialog status # 다이얼로그가 현재 열려 있는지 확인

기본적으로 alert 및 beforeunload 다이얼로그는 자동으로 수락되어 에이전트를 차단하지 않습니다. confirm 및 prompt 다이얼로그는 여전히 명시적인 처리가 필요합니다. 자동 처리를 비활성화하려면 --no-auto-dialog (또는 AGENT_BROWSER_NO_AUTO_DIALOG=1)를 사용하세요.

JavaScript 다이얼로그가 대기 중일 때, 모든 명령 응답에는 다이얼로그 유형과 메시지가 포함된 warning 필드가 포함됩니다.

agent-browser diff snapshot # 현재 스냅샷과 마지막 스냅샷 비교
agent-browser diff snapshot --baseline before.txt # 현재 상태와 저장된 스냅샷 파일 비교
agent-browser diff snapshot --selector "#main" --compact # 범위가 지정된 스냅샷 차이(diff)
...

agent-browser trace start # 트레이스(trace) 기록 시작
agent-browser trace stop [path] # 트레이스 중지 및 저장
agent-browser profiler start # Chrome DevTools 프로파일링(profiling) 시작
...

agent-browser back # 뒤로 가기
agent-browser forward # 앞으로 가기
agent-browser reload # 페이지 새로고침
...

일부 흐름(SSR 디버깅, 보호된 오리진(origin)을 위한 인증 쿠키, 초기화 스크립트)은 첫 번째 탐색(navigation) 전에 상태를 설정해야 합니다. URL 없이 open을 사용하여 브라우저를 실행한 다음, 쿠키 / 라우트(route) / 초기화 스크립트를 준비하고 탐색을 진행하세요. batch는 이 모든 것을 하나의 CLI 호출로 전송합니다:

agent-browser batch \
'["open"]' \
'["network","route","*","--abort","--resource-type","script"]' \
...

batch를 사용하지 않으면 동일한 시퀀스가 세 개의 명령으로 나뉘며, 이들은 모두 동일한 데몬(daemon)을 재사용합니다 (빠르지만 한 번의 턴(turn)에 수행되지는 않습니다).

Agent-browser는 일급 객체 수준의 React introspection (자기 성찰) 기능과 범용 Web Vitals 메트릭을 제공합니다. React 명령어를 사용하려면 실행 시 React DevTools hook이 설치되어 있어야 합니다. Web Vitals와 pushstate는 프레임워크에 구애받지 않습니다 (framework-agnostic).

agent-browser open --enable react-devtools <url> # React hook을 설치하여 실행
agent-browser react tree # 전체 컴포넌트 트리
agent-browser react inspect <fiberId> # props, hooks, state, 소스
...

각 react ... 하위 명령어(subcommand)는 실행 시 --enable react-devtools 옵션이 전달되어 있어야 합니다 (React DevTools의 installHook.js가 바이너리에 내장되어 있습니다). 이 옵션이 없으면 React DevTools hook not installed - relaunch with --enable react-devtools 에러가 발생합니다.

Next.js, Remix, Vite+React, CRA, TanStack Start, React Native Web 등 모든 React 앱에서 작동합니다. vitals와 pushstate는 프레임워크에 구애받지 않습니다 (framework-agnostic). vitals는 기본적으로 요약본을 출력하며, 전체 구조화된 페이로드(payload)를 받으려면 --json을 전달하세요.

agent-browser open --init-script <path> # 첫 번째 탐색(navigation) 전에 페이지 초기화 스크립트 등록
# (반복 가능; AGENT_BROWSER_INIT_SCRIPTS 환경 변수도 사용 가능)
agent-browser addinitscript <js> # 런타임에 등록 (식별자 반환)
...

agent-browser install # Chrome for Testing(Google의 공식 자동화 채널)에서 Chrome 다운로드
agent-browser install --with-deps # 시스템 의존성(deps)도 함께 설치 (Linux)
agent-browser upgrade # agent-browser를 최신 버전으로 업그레이드
...

doctor는 환경, Chrome 설치 상태, 데몬(daemon) 상태, 설정 파일, 암호화 키, 프로바이더(providers), 네트워크 도달 가능성을 점검하고, 실제 라이브 헤드리스 브라우저(headless browser) 실행 테스트를 수행합니다. 오래된 소켓(socket)/pid 사이드카(sidecar) 파일은 자동으로 정리됩니다. 출력 결과는 에이전트(agents)를 위해 --json 형식으로도 제공됩니다.

agent-browser skills # 사용 가능한 스킬(skills) 목록 표시
agent-browser skills list # 위와 동일
agent-browser skills get <name> # 스킬의 전체 내용 출력
...

설치된 CLI 버전과 항상 일치하는 번들링된 스킬 콘텐츠를 제공합니다. AI 에이전트는 캐시된 복사본에 의존하는 대신 이를 사용하여 최신 지침을 가져옵니다. 스킬 디렉토리 경로를 재정의하려면 AGENT_BROWSER_SKILLS_DIR을 설정하세요.

agent-browser mcp
agent-browser mcp --tools all
agent-browser mcp --tools core,network,react

stdio를 통해 Model Context Protocol (MCP) 서버를 시작합니다. MCP 클라이언트는 이 명령을 서브프로세스 (subprocess)로 실행하며, stdin 및 stdout을 통해 줄 바꿈으로 구분된 JSON-RPC를 교환합니다. 서버는 기본적으로 MCP 프로토콜 2025-11-25 버전을 사용하며, 초기화 과정에서 지원되는 이전 클라이언트 프로토콜 버전을 수용합니다.

기본 도구 프로필은 core이며, 이는 일상적인 브라우저 자동화를 위해 MCP 컨텍스트 (context)를 작게 유지합니다. 전체 타입 지정 CLI 패리티 (typed CLI parity) 표면을 사용하려면 --tools all을 사용하거나, --tools core,network,react와 같이 쉼표로 프로필을 조합하여 사용하세요.

프로필:

core — 기본값. 탐색 (Navigation), 스냅샷 (snapshots), 상호작용 (interaction), 대기 (waits), 읽기 (reads), 스크린샷 (screenshots), JavaScript 실행 (eval), 종료 (close), 탭 기본 기능 (tab basics), 프로필 검색 (profile discovery)

network — 네트워크 경로 (Network routes), 요청 검사 (request inspection), HAR, 헤더 (headers), 자격 증명 (credentials), 오프라인 (offline)

state — 쿠키 (Cookies), 스토리지 (storage), 인증 (auth), 저장된 상태 (saved state), 세션 (sessions), 프로필 (profiles), 스킬 (skills)

debug — 콘솔/에러 (Console/errors), 트레이싱 (tracing), 프로파일링 (profiling), 녹화 (recording), 클립보드 (clipboard), 플러그인 (plugins), doctor, 대시보드 (dashboard), 설치 (install), 업그레이드 (upgrade), 채팅 (chat), 차이점 (diff), 배치 (batch), 승인/거부 (confirm/deny)

tabs — 뒤로 가기/앞으로 가기/새로고침 (Back/forward/reload), 탭 (tabs), 창 (windows), 프레임 (frames), 대화 상자 (dialogs)

react — React 트리/검사/렌더링/suspense (React tree/inspect/renders/suspense), vitals, pushstate

mobile — 뷰포트/기기/지리적 위치/미디어 (Viewport/device/geolocation/media), 터치 (touch), 스와이프 (swipe), 마우스 (mouse), 키보드 (keyboard)

all — 전체 타입 지정 CLI 패리티 (full typed CLI parity) 표면을 포함한 모든 MCP 도구

공통 도구에는 다음이 포함됩니다:

agent_browser_tools_profiles
agent_browser_open
agent_browser_snapshot
agent_browser_click
agent_browser_fill
agent_browser_type
agent_browser_press
agent_browser_wait_for_selector
agent_browser_screenshot
agent_browser_get_url
agent_browser_eval
agent_browser_close

각 도구는 url, selector, text, key, session과 같은 타입 지정 필드 (typed fields)를 가집니다.

, 따라서 MCP 클라이언트가 가공되지 않은 명령 배열 (raw command arrays) 대신 의미 있는 승인 프롬프트 (approval prompts)를 표시할 수 있습니다. 각 도구는 또한 고급 CLI 플래그 (CLI flags) 및 정확한 CLI 일치성 (CLI parity)을 위해 extraArgs를 허용합니다.

도구 검색 (Tool discovery)은 페이지가 나뉘어 있으며 (paginated), 현대적인 MCP 클라이언트가 방대한 타입 표면 (typed surface)을 점진적으로 로드할 수 있도록 읽기 전용/오픈 월드 주석 (read-only/open-world annotations)을 포함합니다.

예시 MCP 클라이언트 설정 (Example MCP client config):

{
"mcpServers": {
"agent-browser": {
...

전체 일치 MCP 클라이언트 설정 (Full parity MCP client config):

{
"mcpServers": {
"agent-browser": {
...

도구 호출 (Tool invocations)은 CLI와 동일한 설정 파일 및 환경 변수를 사용합니다. 브라우저 상태 (browser state)를 격리하려면 도구 인자 (tool arguments)에서 session을 사용하거나, AGENT_BROWSER_SESSION을 설정하십시오.

agent-browser는 매 실행마다 다시 인증할 필요가 없도록 로그인 세션 (login sessions)을 유지하는 여러 가지 방법을 제공합니다.