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

주식회사 Palette Link의 @t-yonefu입니다. 바로 이건 개인적인 의견입니다만, 개발에서 가장 재미없는 공정은 테스트 공정이라고 생각하지 않으시나요? 코딩은 기량이 뒷받침되면 빨리 끝낼 수 있지만, 테스트에 관해서는 그렇지 않고, 그렇다고 건너뛸 수도 없어서 매우 번거롭다고 생각합니다. 최근에는 AI를 사용하여 테스트 자동화를 하게 되었는데, 다시 한번 정리하면서 평소 도움을 받고 있는 도구를 소개하겠습니다.

에이전트에 의한 브라우저 자동화란, Cursor나 Claude Code와 같은 코딩 에이전트가 브라우저를 열고, 페이지를 읽고, 클릭이나 입력을 반복하는 것을 말합니다. 긴 E2E(End-to-End) 테스트를 먼저 작성하지 않고 "이 URL을 열어서 확인해줘"라고 부탁함으로써 테스트나 수정을 간략화할 수 있습니다.

본고에서는 에이전트에 의한 브라우저 자동화의 한 예로서 agent-browser의 개요와 용도 구분을 다룹니다.

agent-browser (Vercel Labs)는 Rust로 제작된 브라우저 자동화 CLI입니다. Chrome을 CDP (Chrome DevTools Protocol)로 직접 제어하며, 페이지를 액세서빌리티 트리(Accessibility Tree, 웹 페이지의 구조/DOM을 도구가 해석하기 쉽게 만든 것)로 요약하여 에이전트에게 전달합니다.

항목	내용
리포지토리	vercel-labs/agent-browser
...

설치는 다음 두 줄로 가능합니다.

npm install -g agent-browser
agent-browser install # Chrome for Testing을 취득 (최초 1회)

agent-browser doctor로 환경 진단을, agent-browser upgrade로 업데이트를 할 수 있습니다.

agent-browser는 아래 그림과 같은 클라이언트·데몬(Client-Daemon) 구조로 구성되어 있습니다.

• Rust CLI — 명령을 파싱하고 데몬에 의뢰함
• Rust Daemon — 브라우저 세션을 유지. Node.js 런타임은 불필요
• Chrome — CDP로 조작. 최초 실행 시 agent-browser install로 Chrome for Testing을 취득

최초 명령 시 데몬이 기동하며, 이후의 명령은 동일한 브라우저 세션을 재사용하기 때문에 연속 조작이 빠르다는 것이 특징입니다.

agent-browser가 에이전트에게 반환하는 것은 HTML 전문이 아니라 스냅샷(에이전트가 조작하기 쉬운 형태로 만든 텍스트)입니다. 화면상의 버튼, 입력란, 링크 등 사람이 조작할 수 있는 부분을 중심으로 액세서빌리티 트리로서 짧게 요약한 것입니다. 버튼이나 입력란에는 @e1, @e2와 같이 ref(참조 번호)가 붙으며, 에이전트는 "지금 화면에 있는 3번 버튼을 눌러"와 같은 방식으로 조작을 지시할 수 있습니다.

포인트는 다음 두 가지입니다.

• 매번 "현재 화면"을 확인 — 에이전트는 조작할 때마다 스냅샷을 다시 찍으며, 거기에 적힌 ref만을 사용합니다. 미리 DOM 구조를 기억해 둘 필요가 없습니다.
• ref는 일회성 — 링크를 클릭하여 화면이 바뀌거나, 폼 전송 후 표시가 전환되면 이전의 @e3는 더 이상 존재하지 않을 수 있습니다. 따라서 "한 번 보고 → 조작 → 다시 보기"라는 짧은 사이클이 기본이 됩니다.

사람이 브라우저를 다룰 때와 마찬가지로, 눈으로 확인한 뒤 손을 움직이는 이미지에 가까운 설계입니다. HTML을 통째로 해석하게 하는 것보다 토큰을 절약하면서 조작 대상을 명확하게 할 수 있습니다.

어느 쪽이든 브라우저를 프로그램으로 움직인다는 점은 같습니다. 정리의 축은 누가 절차를 결정하는가(사람이 작성한 테스트인가, 에이전트인가)와 에이전트를 위한 공식적인 입구가 있는가입니다.

도구	형태	사용자	페이지 가시성	적합한 용도
Playwright (테스트 API)	@playwright/test 등의 Node 라이브러리	개발자	코드 내의 셀렉터(Selector)·로케이터(Locator)	.spec.ts를 작성하고 npx playwright test로 회귀 테스트(Regression Test) 수행. 테스트 케이스를 자산으로 남김
playwright-cli	터미널 CLI (@playwright/cli)	에이전트	스냅샷(Snapshot) + eN ref	셸(Shell)에서 짧은 명령어로 조작. 조작한 흐름을 Playwright 테스트 코드로 옮기기 쉬움
Playwright MCP	MCP 서버	에이전트	도구를 통해 (스냅샷, HTML 전체 등)	MCP로 조작. (토큰은 CLI보다 무거워지기 쉬움)
Puppeteer	Node 라이브러리	개발자	직접 작성한 셀렉터	작은 규모의 자동화·스크레이핑 (공식 에이전트용 CLI는 없음)
agent-browser	Rust CLI + 데몬(Daemon)	에이전트	스냅샷 + @eN ref	현장에서의 확인 작업을 빠르게 수행. Vault나 도메인 제한 등 에이전트 운영을 위한 기능이 풍부함

Playwright에는 세 가지 입구가 있습니다. 모두 동일한 엔진 위에서 동작하지만, 목적과 조작 방법이 다릅니다.

Puppeteer는 Node에서 Chrome을 제어하는 라이브러리로, 에이전트 조작용이 아니라 직접 스크립트에 작성하는 것을 전제로 하는 도구입니다.

둘 다 "스냅샷을 보고 ref로 조작한다"는 기본 원리는 같습니다. 차이점을 정리하면 아래 표와 같습니다.

관점	playwright-cli	agent-browser
토대	Playwright 공식 (Node)	Vercel 제작 Rust CLI (Playwright 불필요)
...

또한 로그인 처리와 같은 보안 측면에서도 차이가 있지만, 그 내용은 다음 장에서 다룹니다.

한 번 로그인한 후, Cookie나 localStorage 등을 JSON으로 내보내어 다음부터 재사용하는 방식은 Playwright에서도 자주 사용됩니다.

Playwright (테스트 API)	playwright-cli	agent-browser
메커니즘 이름	storageState	state-save / state-load
파일 예시	playwright/.auth/user.json 등	임의의 JSON
내용	로그인된 세션 (Cookie 등)	좌동

둘 다 "비밀번호를 JSON에 쓰는" 것이 아니라, 브라우저가 보유하고 있는 세션 정보를 재사용하는 개념입니다. Playwright 테스트에서는 global setup에서 한 번 로그인하여 JSON을 만들고, 이후 테스트에서 storageState를 지정하는 패턴이 정석입니다.

세션 JSON만으로는 로그인이 완결되지 않습니다. Cookie의 만료나 로그아웃 등으로 세션이 끊기면 저장된 JSON을 사용할 수 없게 되며, 다시 로그인해야 합니다. Playwright에서는 global setup을 재실행하거나, 환경 변수·CI의 secrets로부터 자격 증명(Credentials)을 전달하여 다시 로그인하는 것이 일반적입니다. agent-browser에서도 후술할 기능을 사용하지 않는다면 마찬가지로, 첫 로그인이나 세션 만료 시마다 에이전트가 화면을 보면서 로그인 절차를 밟거나(또는 사람이 한 번 로그인한 뒤 state save를 하는) 형태가 됩니다.

agent-browser만의 추가 계층으로 Auth Vault (auth save / auth login)가 있습니다. 사용자 이름과 비밀번호를 ~/.agent-browser/auth/에 암호화하여 보관하며, 세션 만료 시 auth login

CLI가 폼 입력까지 맡아줄 수 있기 때문에, 매번 에이전트에게 로그인 절차를 다시 설명해야 하는 부담을 줄이려는 용도에 적합합니다. 세션 JSON과 병용하여 로그인/세션 관리를 간소화할 수 있습니다.

요약하자면, Playwright는 "형식으로서 테스트를 남기는 것"에, agent-browser는 "그 자리에서의 확인을 빠르게 반복하는 것"에 적합합니다.

Playwright (테스트 API / playwright-cli)는 로그인이나 구매 플로우 등을 정해진 절차로 고정하여, 테스트 케이스나 .spec.ts 등의 자산으로 남길 때 유효합니다. CI에서 동일한 조건을 반복하여 검증하거나, 회귀 테스트 (Regression)를 추적하는 형식적인 테스트에 적합합니다.

agent-browser는 미리 긴 테스트 코드를 모두 작성하기보다, 에이전트가 스냅샷을 보면서 짧은 루프(Loop)로 진행하는 운영 방식에 맞습니다. Rust로 제작된 CLI + 상주 데몬 (Daemon) 구조로 기동 및 연속 조작이 가볍고, Auth Vault가 있다면 세션 만료 시의 재로그인도 CLI 측으로 넘길 수 있습니다. 따라서 사양 변경이 있을 때마다 테스트 코드를 수정하기보다, 애자일 (Agile)하게 "지금 작동하는가"를 확인하는 상황에서 효과적입니다.

하고 싶은 것	적합한 선택
테스트 케이스를 남기고, CI에서 동일한 절차를 반복해서 검증하고 싶다	Playwright (테스트 API. 필요 시 playwright-cli로 코드 생성)
...

agent-browser에는 많은 명령어가 있지만, 본고에서는 명령어의 상세 내용까지는 다루지 않습니다. 에이전트가 Rules나 Skills로서 절차를 받아들여 대화형으로 진행하는 것을 상정하고 있기 때문입니다.

아래에 Rules의 예시를 보여드립니다. 프로젝트의 Rules 등으로 도입하여 필요에 따라 추가하거나 조정해 주세요.

---
alwaysApply: true
---
...

agent-browser skills get core를 실행하면, 설치된 agent-browser의 버전과 일치하는 사양을 가져올 수 있습니다. 릴리스마다 내용이 변경될 가능성이 있으므로, 실행 시점에 가져오는 방법을 권장합니다.

본고에서 다룬 핵심 포인트는 다음과 같습니다.

agent-browser는 Rust로 제작된 CLI가 Chrome을 CDP (Chrome DevTools Protocol)로 구동하여, 페이지를 스냅샷(텍스트 개요)과 @eN ref로 에이전트에게 전달하는 도구입니다. HTML 전체가 아니라 "지금 만질 수 있는 것"으로 범위를 좁힘으로써, 에이전트가 "본다 → 조작한다 → 다시 본다"라는 짧은 루프로 진행할 수 있습니다.

Playwright와의 관계에서는 둘 다 브라우저 자동화 도구이지만 역할이 다릅니다. Playwright는 테스트 케이스나 spec을 형식적으로 남겨 CI에서 반복하는 데 적합하고, agent-browser는 에이전트가 그 자리에서 빠르게 확인하는 것(애자일 지향)에 적합합니다. 로그인된 상태의 JSON (storageState / state save)은 양쪽 모두에 존재하며, Auth Vault는 agent-browser 고유의 기능으로 세션 만료 시의 재로그인 부담을 줄여주는 임의의 계층입니다. Vault가 없어도 사용할 수 있지만, 그 경우에는 Playwright와 마찬가지로 매번 로그인 절차가 필요합니다.

운영 측면에서는 Cursor 등에서 Rules나 agent-browser skills get core를 통해 절차를 CLI 버전과 맞출 수 있습니다. 필요에 따라 도메인 제한이나 Vault 등, 에이전트에게 무엇을 조작하게 할지도 설계할 수 있습니다.

agent-browser는 Playwright의 대체재가 아니라, "테스트 자산보다 지금 작동하는지를 에이전트와 빠르게 확인하고 싶을 때"의 선택지 중 하나입니다. playwright-cli / MCP와 병용하는 프로젝트도 현실적인 방안입니다.