agent-browser: AI 에이전트를 위한 브라우저 자동화 CLI

AI 에이전트에게 브라우저를 맡기는 시대가 점점 현실이 되고 있습니다. 이전에 Playwright MCP를 소개하면서 AI 에이전트가 MCP 서버를 통해 브라우저를 조작하는 방법을 다뤘는데요. 이번에는 좀 다른 접근 방식을 가져온 도구를 살펴보려고 합니다.

Vercel Labs에서 만든 agent-browser는 AI 에이전트가 쉘 명령어만으로 브라우저를 제어할 수 있게 해주는 CLI 도구입니다. MCP 프로토콜이나 프로그래밍 언어에 종속되지 않고 터미널에서 바로 agent-browser open example.com처럼 실행할 수 있어서 어떤 AI 에이전트든 쉘 접근만 가능하면 바로 브라우저를 다룰 수 있죠.

이 글에서는 agent-browser의 설치부터 핵심 기능, 그리고 실제로 AI 에이전트와 함께 활용하는 방법까지 살펴보겠습니다.

왜 CLI 기반 브라우저 자동화인가?

기존 브라우저 자동화 도구는 대부분 라이브러리 형태입니다. Playwright나 Puppeteer를 쓰려면 JavaScript나 Python 코드를 작성해야 하고, Playwright MCP는 MCP 프로토콜을 지원하는 클라이언트가 필요합니다.

agent-browser는 이런 의존성을 걷어냈습니다. 모든 기능이 쉘 명령어로 제공되니까 AI 에이전트가 Bash 도구 하나만 있으면 브라우저를 열고 클릭하고 텍스트를 입력하고 스크린샷까지 찍을 수 있습니다. 코드를 생성할 필요 없이 명령어를 실행하기만 하면 되는 거예요.

Rust로 만들어진 네이티브 CLI라서 명령어 파싱 오버헤드가 거의 없다는 점도 특징입니다. Node.js 런타임이 없는 환경에서도 동작할 수 있도록 Rust 바이너리가 우선 사용되고, 없으면 Node.js로 폴백하는 구조를 가지고 있어요.

설치하기

npm으로 전역 설치하는 것이 가장 간단합니다.

npm install -g agent-browser
agent-browser install

agent-browser install 명령어가 Chromium 브라우저를 다운로드합니다. 이 과정은 처음 한 번만 필요해요.

설치 없이 바로 시험해보고 싶다면 npx를 사용할 수 있습니다.

npx agent-browser install
npx agent-browser open example.com

macOS에서는 Homebrew로도 설치할 수 있어요.

brew install agent-browser
agent-browser install

Linux에서는 시스템 의존성이 추가로 필요할 수 있는데 --with-deps 옵션을 붙이면 알아서 설치해줍니다.

agent-browser install --with-deps

페이지 탐색과 상호작용

가장 기본적인 사용법부터 보겠습니다. 웹 페이지를 열고 요소를 클릭하고 텍스트를 입력하는 명령어예요.

agent-browser open https://example.com

페이지가 열리면 요소와 상호작용할 수 있습니다.

agent-browser click "#login-button"
agent-browser type "#email" "user@example.com"
agent-browser fill "#password" "secret123"
agent-browser press Enter

type은 기존 내용에 이어서 타이핑하고, fill은 기존 내용을 지운 뒤 새로 입력합니다. 로그인 폼 같은 곳에서는 fill이 더 적합하겠죠.

드롭다운 선택, 체크박스 토글, 스크롤, 파일 업로드 같은 기능도 명령어 하나로 됩니다.

agent-browser select "#country" "KR"
agent-browser check "#agree-terms"
agent-browser scroll down 500
agent-browser upload "#file-input" "./document.pdf"

스냅샷: AI 에이전트의 눈

agent-browser에서 가장 중요한 명령어를 하나만 꼽으라면 snapshot입니다. 이 명령어는 현재 페이지의 접근성 트리를 텍스트로 출력하는데요. AI 에이전트가 페이지 구조를 이해하는 데 최적화된 형태로 정보를 제공합니다.

agent-browser snapshot

결과

[ref=e1] heading "Example Domain"
[ref=e2] paragraph "This domain is for use in..."
[ref=e3] link "More information..."
[ref=e4] button "Sign Up"
[ref=e5] textbox "Email address"

출력 결과에서 각 요소 앞에 ref=e1, ref=e2 같은 참조 ID가 붙는 것이 보이시나요? 이 참조를 사용하면 CSS 셀렉터 대신 @e4처럼 간단하게 요소를 지정할 수 있습니다.

agent-browser click @e4
agent-browser fill @e5 "user@example.com"

CSS 셀렉터는 페이지 구조가 바뀌면 깨지기 쉬운데, 스냅샷 참조는 현재 페이지 상태를 기반으로 하니까 더 안정적입니다. AI 에이전트 입장에서도 “4번째 요소를 클릭해”가 “ID가 submit-btn인 요소를 클릭해”보다 훨씬 쉽고요.

이것이 agent-browser를 사용한 전형적인 워크플로우입니다. 스냅샷을 찍고, AI가 결과를 분석하고, 참조 ID로 요소와 상호작용하고, 다시 스냅샷을 찍어서 결과를 확인하는 과정을 반복하는 거예요.

시맨틱 요소 찾기

CSS 셀렉터나 참조 ID 말고도 요소를 찾는 방법이 있습니다. find 명령어를 쓰면 역할(role), 텍스트, 레이블 같은 의미 기반으로 요소를 찾아서 바로 동작을 수행할 수 있어요.

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 find placeholder "Enter name" type "John"

find role button click --name "Submit"은 “Submit이라는 이름을 가진 버튼 역할의 요소를 찾아서 클릭해라”라는 뜻입니다. CSS 셀렉터보다 사람이 읽기 쉽고 페이지 구조 변경에도 강한 편이에요.

위치 기반으로 찾을 수도 있습니다.

agent-browser find first ".item" click
agent-browser find last "a" text
agent-browser find nth 2 "a" click

정보 추출하기

페이지에서 데이터를 가져오는 것도 간단합니다.

agent-browser get text "h1"
agent-browser get html "#content"
agent-browser get value "#search-input"
agent-browser get attr "a.logo" "href"
agent-browser get title
agent-browser get url
agent-browser get count ".product-card"

get text는 요소의 텍스트 내용을, get html은 innerHTML을, get value는 입력 필드의 값을 가져옵니다. get count는 셀렉터에 매칭되는 요소 개수를 알려주니까 “상품 목록에 몇 개가 표시되는지” 확인할 때 유용합니다.

요소의 상태를 확인하는 명령어도 있어요.

agent-browser is visible "#modal"
agent-browser is enabled "#submit-btn"
agent-browser is checked "#newsletter-opt-in"

스크린샷과 시각적 확인

스냅샷이 텍스트 기반이라면 스크린샷은 시각적 확인용입니다.

agent-browser screenshot page.png
agent-browser screenshot --full full-page.png

--full 옵션을 붙이면 스크롤 영역을 포함한 전체 페이지를 캡처합니다.

특히 재밌는 기능이 --annotate 옵션인데요.

agent-browser screenshot --annotate annotated.png

이 옵션을 사용하면 페이지 요소 위에 번호 라벨이 오버레이됩니다. 비전 모델을 가진 AI 에이전트가 스크린샷을 보고 “3번 요소를 클릭해”처럼 지시할 수 있게 해주는 거예요. 접근성 트리 기반의 스냅샷과 비전 기반의 접근 방식을 모두 지원하는 셈이죠.

PDF로 저장하는 것도 가능합니다.

agent-browser pdf report.pdf

대기 조건 설정

웹 페이지는 비동기로 동작하기 때문에 특정 조건이 충족될 때까지 기다려야 하는 경우가 많습니다. agent-browser는 여러 가지 대기 조건을 지원해요.

agent-browser wait "#loading-spinner"
agent-browser wait 2000
agent-browser wait --text "Welcome back"
agent-browser wait --url "**/dashboard"
agent-browser wait --load networkidle
agent-browser wait --fn "window.dataLoaded === true"

셀렉터가 나타날 때까지, 특정 텍스트가 보일 때까지, URL 패턴이 매칭될 때까지, 네트워크 요청이 끝날 때까지 등 원하는 조건을 지정할 수 있습니다. 밀리초 단위의 단순 대기나 JavaScript 조건식도 됩니다. SPA에서 페이지 전환을 기다리거나 API 응답을 기다릴 때 유용하겠죠.

네트워크 가로채기

테스트나 개발 과정에서 네트워크 요청을 가로채서 응답을 바꾸거나 차단해야 할 때가 있습니다.

agent-browser network route "**/api/users" --body '{"users": [{"name": "Test"}]}'
agent-browser network route "**/ads/**" --abort

첫 번째 명령어는 /api/users 요청에 대해 가짜 응답을 돌려줍니다. API 서버 없이 프론트엔드를 테스트하거나 특정 응답 시나리오를 재현할 때 쓸 수 있어요. 두 번째 명령어는 광고 관련 요청을 아예 차단합니다.

어떤 네트워크 요청이 발생했는지도 확인할 수 있습니다.

agent-browser network requests
agent-browser network requests --filter api

브라우저 환경 설정

뷰포트 크기 변경이나 디바이스 에뮬레이션, 위치 정보 설정 같은 브라우저 환경도 명령어로 조절합니다.

agent-browser set viewport 375 812
agent-browser set device "iPhone 14"
agent-browser set geo 37.5665 126.9780
agent-browser set media dark
agent-browser set offline on

모바일 환경에서 페이지가 어떻게 보이는지 확인하거나 위치 기반 서비스를 테스트할 때 쓸 수 있고, 다크모드 스타일 검증이나 오프라인 동작 확인에도 활용할 수 있어요.

탭과 프레임 관리

여러 탭을 열고 전환하거나 iframe 안의 콘텐츠를 조작하는 것도 됩니다.

agent-browser tab new https://docs.example.com
agent-browser tab                  # 탭 목록 확인
agent-browser tab 0                # 첫 번째 탭으로 전환
agent-browser tab close 1          # 두 번째 탭 닫기

iframe이 있는 페이지에서는 frame 명령어로 컨텍스트를 전환합니다.

agent-browser frame "#embedded-widget"
agent-browser click "#inner-button"
agent-browser frame main           # 메인 프레임으로 복귀

인증 상태 저장과 복원

로그인이 필요한 사이트를 반복적으로 테스트할 때마다 매번 로그인하는 건 번거롭습니다. agent-browser는 쿠키와 로컬 스토리지를 포함한 브라우저 상태를 파일로 저장하고 복원할 수 있어요.

agent-browser open https://app.example.com/login
agent-browser fill "#email" "user@example.com"
agent-browser fill "#password" "password123"
agent-browser click "#login-btn"
agent-browser wait --url "**/dashboard"

agent-browser state save auth-state

다음번에는 저장된 상태를 불러오기만 하면 로그인 과정을 건너뛸 수 있습니다.

agent-browser state load auth-state
agent-browser open https://app.example.com/dashboard

저장된 상태 파일을 관리하는 명령어도 있습니다.

agent-browser state list
agent-browser state show auth-state
agent-browser state clean --older-than 30

시각적 비교(Diff)

페이지 변경 사항을 비교하는 기능도 내장되어 있습니다.

agent-browser diff snapshot
agent-browser diff snapshot --baseline before.txt
agent-browser diff screenshot --baseline before.png

두 URL을 직접 비교할 수도 있어서 배포 전후 페이지를 비교하거나 스테이징과 프로덕션 환경을 비교할 때 쓸 수 있습니다.

agent-browser diff url https://staging.example.com https://example.com --screenshot
agent-browser diff url https://staging.example.com https://example.com --selector "#main"

Playwright MCP와 비교하기

같은 브라우저 자동화 영역에 있는 Playwright MCP와 어떤 차이가 있는지 궁금하실 수 있습니다.

Playwright MCP는 MCP 프로토콜을 통해 동작합니다. MCP 클라이언트(Claude Code, VS Code 등)가 서버에 도구 호출을 보내고, 서버가 브라우저를 조작하는 구조예요. AI 에이전트가 자연어로 요청하면 내부적으로 적절한 MCP 도구를 선택해서 실행합니다.

agent-browser는 순수 CLI입니다. MCP 같은 프로토콜이 필요 없고 쉘에서 명령어를 실행하는 것만으로 동작해요. AI 에이전트가 Bash 도구를 가지고 있다면 바로 사용할 수 있습니다. 특정 클라이언트에 종속되지 않는다는 게 장점이죠.

agent-browser만의 고유한 기능도 있습니다. 번호가 붙은 스크린샷(--annotate)이나 시각적 비교(diff), 네트워크 모킹, 디바이스 에뮬레이션 같은 건 Playwright MCP에는 없거나 제한적이에요. 반면 Playwright MCP는 MCP 생태계와의 통합이나 접근성 트리 기반의 안정적인 요소 식별 등에서 강점이 있고요.

결국 어떤 도구가 더 나은지보다는 AI 에이전트가 동작하는 환경에 따라 선택하면 됩니다. MCP 클라이언트를 쓰고 있다면 Playwright MCP가 자연스럽고, 쉘 접근만 가능한 환경이라면 agent-browser가 더 적합합니다.

실전 활용 시나리오

agent-browser는 AI 에이전트가 쉘 명령어를 실행할 수 있는 환경이라면 어디서든 활용할 수 있습니다. 몇 가지 시나리오를 생각해볼게요.

CI/CD 파이프라인에서 배포 후 스모크 테스트를 자동으로 돌릴 수 있습니다. 페이지를 열고 핵심 요소가 렌더링되는지 확인하고 스크린샷을 남기는 걸 스크립트 몇 줄로 처리할 수 있어요.

agent-browser open https://my-app.com
agent-browser wait --load networkidle
agent-browser get text "h1"
agent-browser screenshot smoke-test.png
agent-browser close

웹 스크래핑도 간단합니다. 로그인이 필요한 사이트에서 데이터를 가져오거나 JavaScript로 렌더링되는 SPA에서 정보를 추출하는 작업을 명령어 조합으로 할 수 있어요.

프론트엔드 개발 중에 API 응답을 모킹해서 여러 시나리오를 테스트하는 것도 가능합니다. 에러 응답이나 빈 데이터, 대량 데이터 같은 상황을 네트워크 가로채기로 재현할 수 있죠.

마치며

agent-browser는 AI 에이전트의 브라우저 자동화에 가장 단순한 해법을 제시합니다. MCP 프로토콜도 SDK도 필요 없고 코드를 짤 필요도 없이 쉘 명령어만으로 브라우저를 제어할 수 있어요.

snapshot으로 페이지 구조를 파악하고 참조 ID로 요소를 지정하고 get text로 데이터를 추출하고 screenshot으로 시각적 확인까지 하는 워크플로우가 AI 에이전트와 잘 맞아요. 사람이 브라우저를 쓸 때처럼 “보고 → 판단하고 → 행동하는” 흐름을 명령어 단위로 쪼갠 것이니까요.

AI 에이전트가 브라우저까지 다루게 되면 가능해지는 일이 크게 늘어납니다. 브라우저 자동화가 필요한 상황이 있다면 프로젝트 환경에 맞게 agent-browser와 Playwright MCP를 비교해보고 적합한 도구를 선택해보세요. LLM이 자연어로 직접 브라우저를 조종하는 접근이 궁금하다면 browser-use도 살펴볼 만합니다.

This work is licensed under CC BY 4.0