Vercel Labs의 agent-browser 사용 후기: 접근성 트리로 AI 에이전트가 브라우저를 조작하는 방법

개요

Vercel Labs에서 공개한 agent-browser (Apache-2.0)는 AI 에이전트에게 브라우저 조작을 시키기 위한 Rust 기반의 CLI 도구입니다.

이 도구는 스크린샷을 Visual Language Model (VLM, 시각 언어 모델)에 전달하는 방식이 아니라, 브라우저의 접근성(accessibility) 스냅샷을 텍스트/JSON 형태로 변환합니다. 그리고 각 요소에 @e1과 같은 참조(ref)를 부여하여, 에이전트가 이 참조 ID를 지정해 click이나 fill 등의 명령을 호출하는 방식을 채택하고 있습니다.

개발진은 Playwright MCP 대비 약 90% 적은 토큰 소비를 주장합니다.

자매 도구인 agent-desktop (역시 Apache-2.0)은 같은 아이디어를 OS 데스크톱 조작으로 확장한 것으로, 2026년 11월 5일 기준 GitHub Trending에서 신규 등록되었음에도 불구하고 하루 2,173 star의 증가세를 보였습니다.

필자는 이 agent-browser를 실제로 도입하여 Claude Code 자체를 드라이버로 사용하여 로컬 검증 페이지를 조작하며, 공식적으로 주장하는 토큰 절감 효과를 직접 측정해 보았습니다.

또한, 단순히 설치 명령어를 실행했을 때 최신 버전이 들어오지 않는 함정에도 부딪혔으므로, 이 내용까지 기록합니다.

• 출처: https://github.com/vercel-labs/agent-browser (Apache-2.0)
• 출처: https://github.com/vercel-labs/agent-desktop (Apache-2.0)
• 한국어 기사 건수(2026-11-05 기준, Zenn/Qiita/note 검색): 0건 (개인 기술 블로그에 1건이 있으나 Zenn/Qiita/note 본체에는 미검출)

npm install agent-browser

단순히 npm install agent-browser만으로는 최신 버전이 설치되지 않는다.

도입: 공식 README를 따라 도입을 시도했을 때, 첫 단계에서 난관에 부딪혔습니다.

$ npm install agent-browser
added 1 package in 866ms
$ cat node_modules/agent-browser/package.json | grep "version"
...

npm 레지스트리에서 latest 태그를 확인하면 0.41.2여야 했습니다.

$ npm view agent-browser dist-tags --json
{
"latest": "0.41.2"
...
}

버전을 지정하지 않은 npm install agent-browser를 실행하자, latest 태그인 0.41.2가 아닌 무려 14 버전이나 오래된 0.27.0이 오류나 경고 없이 설치되었습니다.

npm install agent-browser@latest와 같이 버전을 명시하면 기대했던 대로 0.41.2가 들어옵니다 (EBADENGINE이라는 경고는 나오지만, 설치 자체는 성공합니다).

$ npm install agent-browser@latest
npm warn EBADENGINE Unsupported engine {
npm warn EBADENGINE package: '[email protected]',
...

원인을 파악하기 위해 각 버전의 engines 필드를 비교했습니다.

$ npm view agent-browser engines
{
 node: '>=24.0.0',
 pnpm: '>=11.0.0' }
$ npm view [email protected] engines
...

최신 0.41.2 버전은 Node 24 이상을 요구하지만, 오래된 0.27.0에는 이러한 제약이 없습니다.

--loglevel silly를 사용하여 내부 동작을 살펴보니, 버전 미지정 설치는 agent-browser@*라는 semver 범위로 처리되고 있었습니다.

$ npm install agent-browser --loglevel silly 2>&1 | grep "fetch manifest"
npm silly fetch manifest agent-browser@*

즉, *와 같은 범위 지정으로 설치할 때, npm은 현재 Node 버전의 engines.node 요구사항을 충족하지 못하는 후보들을 제외한 후 선택합니다. 따라서 Node 24 미만의 환경에서는 engines가 지정되지 않은 오래된 버전이 선택되어 버리는 것입니다.

반면, @latest

@<version>과 같이 명시적으로 지정한 경우에는 이 범위 필터를 거치지 않기 때문에, 순수하게 최신 버전이 들어옵니다.

Node 24는 2026년 시점에서도 아직 광범위하게 보급된 버전이라고 말하기 어려우며, Node 22나 20을 사용하는 독자가 적지 않을 것입니다.

공식 README에 있는 npm install -g agent-browser를 그대로 실행하면 오류나 경고 없이 오래된 버전이 설치됩니다. 따라서 도입 시에는

npm install agent-browser@latest

와 같이 버전을 명시하는 것을 권장합니다. 로컬 PC에서도 동일한 Node v22.23.4 환경에서 0.27.0이 들어오는 것을 확인했고, Node 24 계열(v24.22.2)로 전환하여 같은 명령을 실행하자 이번에는 순수하게 latest 버전인 0.41.2가 설치되는 것을 확인했습니다.

"Node 24 미만이라면 누구나 걸릴 것"이라는 가설을 실제로 두 가지 Node 버전을 전환하며 입증했습니다.

접근성 트리에서의 실제 조작 실행

이 클라우드 실행 환경의 네트워크 정책에서는 일반적인 외부 사이트(example.com, www.google.com 등)로의 연결이 거부되었기 때문에, 로컬에 일본어 폼과 링크 목록을 가진 검증용 페이지를 만들어 조작했습니다.

$ agent-browser open http://127.0.0.1:8931/
✓ 테스트용 검색 폼

snapshot 명령어를 사용하면 페이지 구조가 접근성 트리(accessibility tree) 형태로 @ref와 함께 반환됩니다.

$ agent-browser snapshot
- navigation
- link "Home" [ref=e2]
...

HTML 태그 구조나 CSS 클래스명, 스타일 정보는 포함되지 않고, "무엇이 어디에 있고 어떻게 조작할 수 있는지"라는 정보만 남아 있습니다.

이 @ref를 사용하여 fill → click을 호출하자, 실제로 폼에 입력하고 전송할 수 있었습니다.

$ agent-browser fill @e7 "AI 에이전트 비교"
✓ Done
$ agent-browser click @e8
...

전송 후에 snapshot을 다시 가져오자, JavaScript에 의한 DOM 업데이트(검색 결과 표시)가 올바르게 반영되어 있었습니다.

- textbox "키워드:" [ref=e7]: AI 에이전트 비교
- button "검색" [ref=e8]
- paragraph
...

좌표나 픽셀을 전혀 다루지 않고, 의미 있는 참조 ID만으로 클릭이나 입력이 가능하다는 점은 LLM(대규모 언어 모델)에게 매우 사용하기 쉬운 설계라고 느꼈습니다.

"약 90% 적은" 토큰 소비를 직접 측정해 보기

공식적으로는 "Playwright MCP 대비 약 90% 적은 토큰 소비"를 주장하고 있습니다.

필자 본인 자리에서는 엄격한 토크나이저를 이용한 비교까지는 할 수 없었습니다(후술할 제약 때문에 글자수로 대체했습니다). 하지만 동일 페이지에 대해 "순수 HTML"과 "agent-browser의 snapshot 출력"의 글자수를 비교해 보았습니다.

$ curl -s http://127.0.0.1:8931/ > raw_page.html
$ agent-browser snapshot > snapshot_output.txt
$ wc -c raw_page.html snapshot_output.txt
...

Python으로 글자수(바이트수가 아닌)를 세어보니 다음과 같습니다.

raw chars: 1526
snap chars: 785
reduction: 48.6%

자신이 만든 간단한 페이지에서의 실측 결과는 약 48.6%의 감소였습니다.

공식의 약 90%와는 전제가 다르며(공식은 Playwright MCP 출력 형식과의 비교이고, 이번은 원본 HTML 응답과의 비교), 검증 페이지 자체가 작고 실제 웹 애플리케이션보다 훨씬 단순하기 때문에 이 수치는 어디까지나 참고값입니다.

그럼에도 불구하고 "스타일이나 태그 구조를 깎아내고, 의미 있는 구조만 텍스트화한다"는 방향성의 효과 자체는 이 간단한 비교에서도 확인할 수 있었습니다.

자매 도구 agent-desktop: GUI 조작은 WSLg의 벽에 부딪히다

자매 도구인 agent-desktop도 도입했습니다.

클라우드 검증 환경에서는 디스플레이/AT-SPI 버스 자체가 존재하지 않아 accessibility.state: "denied"

하지만 GUI 세션을 가진 로컬 PC(Windows 11 + WSL2 + WSLg)에서 테스트했을 때는 우선 그 부분은 진전이 있었습니다.

$ agent-desktop status
{"...":"...","data":{"permissions":{"accessibility":{"state":"granted"}, ...}}}

accessibility.state가 "granted"가 되어, WSLg의 AT-SPI 버스가 기능하고 있음을 확인할 수 있었습니다.

계속해서, WSLg 위에서 Window로 표시된 Chromium(로컬 검증용 페이지를 열어둔 상태)에 대해 list-apps,
list-windows,
launch --activate
를 시도해 본 결과, 모두 동일한 오류로 멈췄습니다.

$ agent-desktop list-apps
{"ok":false,"error":{"code":"ACTION_NOT_SUPPORTED",
"message":"The native window type of accessibility frame owned by pid 39494
...

Chromium의 실행 옵션(--force-renderer-accessibility, --single-process, 프로파일을 분리한 여러 번의 재시작)을 바꿔도 해결되지 않았습니다.

agent-desktop 자체에 포함된 Linux용 skill 문서(agent-desktop skills get platform으로 볼 수 있음)를 확인해 보면, "GNOME에서 동작 확인됨"이라고 명확히 적혀 있습니다.

실제로 본 환경의 윈도우 매니저(WM)를 조사해보니, GNOME/Mutter가 아니라 Weston 기반의 경량 WM이었습니다.

$ xprop -root _NET_SUPPORTING_WM_CHECK | grep -o '0x[0-9a-f]*' | head -1 \
| xargs -I{} xprop -id {} _NET_WM_NAME
_NET_WM_NAME(UTF8_STRING) = "Weston WM"

즉, 로컬 검증의 결론은 "작동했다"도 "작동하지 않았다"도 아니었습니다. accessibility 권한과 AT-SPI 버스 연결 자체는 WSLg에서도 기능하지만, 그 이후 단계인 "네이티브 윈도우임을 증명하는" 체크가, 도구가 동작 확인되었다고 하는 GNOME과는 다른 WSLg의 경량 WM에서는 충족되지 않는다는 한 단계 깊은 결과였습니다.

GNOME을 사용하는 일반적인 Linux 데스크톱 PC라면, 이 제약에 해당하지 않을 가능성이 높습니다.

만약을 위해, 검증용 페이지가 실제로 표시되고 있는 것을 스크린샷으로 확인한 상태에서 list-apps를 재실행하여 동일한 오류가 재현되는 것도 확실히 했습니다.

로컬 HTTP 서버의 구동 미비로 일시적으로 연결 오류 화면이 표시된 경우도 있었지만, 그것과는 무관하게, 페이지가 올바르게 표시된 상태에서도 결과는 변하지 않았습니다.

요약 (Summary)

• agent-browser는 실제로
  open
  →snapshot
  →fill
  →click
  →read
  라는 일련의 동작이 문제없이 움직이며, 접근성 트리 기반의 조작성을 확인할 수 있었습니다.
• 공식 README의 설치 절차(npm install agent-browser)는 Node 24 미만의 환경에서는 오류나 경고 없이 오래된 버전이 설치되는 함정이 있습니다. @latest를 명시하는 것을 권장합니다. 로컬에서 실제로 Node 22와 24를 전환하여 이 추측을 뒷받침했습니다.
• 토큰 소비량 절감에 관해서는, 본인의 간이 비교에서는 약 48.6%(공식의 약 90%와는 전제가 다른 참고치)였지만, 방향성 자체는 확인할 수 있었습니다.
• agent-desktop은 로컬 PC(WSLg)에서 accessibility 권한이 granted가 되는 곳까지 진전했지만, 실제 GUI 앱 조작은, 도구가 GNOME을 염두에 두고 예상하는 "네이티브 윈도우 증명" 체크가 WSLg의 경량 WM(Weston)에서는 충족되지 않아, ACTION_NOT_SUPPORTED에서 멈췄습니다.

토론 (Discussion)