2026년 11월 6일 GitHub Trending(전체·Rust)에 vercel-labs/agent-browser가 다시 올랐습니다. 스타 약 4.6만, 최신 태그 v0.41.2(2026-11-03), 라이선스 Apache-2.0. 같은 Labs 라인의 agent-desktop이 OS 창의 접근성 트리로 ‘컴퓨터 유즈’를 풀었다면, 이 저장소는 웹 브라우저에 같은 철학을 이식합니다. 픽셀 좌표가 아니라 Accessibility.getFullAXTree에서 뽑은 @eN 참조로 클릭하고, 브라우저는 세션 데몬 뒤에 살아 남습니다.
이 글은 초보 튜토리얼이 아닙니다. 아키텍처(CLI→데몬→CDP→AXTree), 저장소 레이아웃, 보안 옵트인 모델, skills/MCP, 유사 도구와의 역할 분담, 그리고 이 박스에서 실제로 돌린 open→snapshot→click→screenshot 타임라인을 실무자 기준으로 정리합니다.
한 줄 정의와 왜 지금 뜨는가
agent-browser는 AI 에이전트가 셸 한 줄 = 브라우저 한 행동으로 Chrome(기본)·Lightpanda·Obscura·클라우드 브라우저를 조종하게 하는 네이티브 Rust CLI입니다. 첫 명령이 백그라운드 데몬을 띄우고, 이후 명령은 Unix 도메인 소켓(Windows는 별도)으로 같은 브라우저에 붙습니다. 에이전트 관점의 핵심 루프는 고정입니다.
agent-browser open <url>
agent-browser snapshot -i # interactive only → @e1, @e2…
agent-browser click @e1
agent-browser snapshot -i # DOM/내비 후 재스냅샷
0.41.x 라인의 최근 변화도 ‘에이전트 친화’ 쪽입니다. 0.41.2는 skills get <name> --ref <ref>로 스킬 조각을 부분 로드하고, 설치된 Chrome이 Stable보다 뒤처지면 CVE 개수를 경고만 띄웁니다(명령은 막지 않음). 0.41.0은 MCP 도구 카탈로그를 단일 소스로 맞추고, mcp call로 단발 MCP 호출을 가능하게 했습니다.
| 항목 | 값 (이 글 기준) |
|---|---|
| 저장소 | vercel-labs/agent-browser |
| 버전 | 0.41.2 (Git tag / Cargo / CLI –version 일치) |
| 라이선스 | Apache-2.0 |
| 핵심 언어 | Rust (cli/), npm 래퍼·docs·dashboard는 JS/TS |
| 기본 엔진 | Chrome for Testing (CDP) |
| 대체 엔진 | Lightpanda, Obscura, iOS Simulator Safari, Browserbase/Browserless/Kernel/AgentCore 등 |
| 에이전트 진입점 | skills get core, MCP stdio, WebMCP, plugins |
아키텍처: 왜 ‘매번 브라우저를 안 띄우는가’
AGENTS.md와 cli/src/native/를 기준으로 보면 계층은 네 겹입니다.
- CLI 프로세스 — 인자 파싱, 세션 이름 검증, 스킬/MCP/설치 서브커맨드.
- 세션 데몬 —
daemon.rs. 세션마다 PID·version 파일과 소켓을 만들고, idle(기본 1시간) 후 헤드리스 브라우저를 정리합니다. 디버그 시 stderr를 세션 로그로 리다이렉트하고, 평소에는 부모 CLI가 파이프를 닫아도 데몬이 죽지 않도록/dev/null로 돌립니다. - CDP 클라이언트 —
tokio+tokio-tungstenite(rustls). Chrome DevTools Protocol로 탭·입력·네트워크·추적을 다룹니다. - 스냅샷/액션 —
snapshot.rs가Accessibility.enable후Accessibility.getFullAXTree를 받아 트리를 압축 텍스트로 직렬화하고, 각 노드에@eNref와 CDP objectId 매핑을 유지합니다. iframe은 자식 프레임을 재귀 스냅샷해 부모 출력에 끼워 넣습니다.
| 모듈 (cli/src/native) | 역할 | 실무 포인트 |
|---|---|---|
| daemon.rs | 세션 수명·소켓·idle | 하네스가 셸을 매번 새로 열면 --session을 명령마다 넘겨야 함 |
| snapshot.rs | AXTree → 텍스트+ref | 내비/DOM 변화 후 ref 재사용 금지(동일 문서 갱신은 일부 유지) |
| actions.rs | 명령 실행·브라우저 수명 | 클릭 실패 시 ‘성공 위장’ 없이 숨김/가림/비활성 보고 |
| cdp/ | 프로토콜 클라이언트 | --cdp/--auto-connect로 기존 Chrome 부착 가능 |
| policy.rs | 액션 allow/deny/confirm | 로드 실패 시 close 외 전부 deny(안전 실패) |
| providers.rs | 클라우드 브라우저 | allowlist와 attach/profile 조합은 거절되는 경우 많음 |
이 구조의 트레이드오프는 분명합니다. 장점은 에이전트 컨텍스트에 픽셀·스크린샷 토큰을 덜 넣고, Playwright 스크립트를 ‘짜는’ 대신 관찰→행동 루프를 유지할 수 있다는 점입니다. 대가는 AXTree에 안 잡히는 캔버스/커스텀 위젯, 그리고 접근성 레이블이 빈 페이지에서는 ref 밀도가 떨어진다는 점입니다. 이때는 find role|text|testid나 CSS/XPath로 우회하고, 필요하면 screenshot/record로 시각 증거를 남깁니다.
저장소 레이아웃
| 경로 | 내용 |
|---|---|
cli/ |
Rust 바이너리 본체(Cargo.toml version=0.41.2) |
cli/src/native/ |
데몬·스냅샷·CDP·보안·녹화·E2E |
bin/agent-browser.js |
npm 진입점(플랫폼 바이너리 선택) |
skill-data/ |
core·electron·slack·dogfood·vercel-sandbox·agentcore 등 |
packages/@agent-browser/ |
eve/sandbox 등 확장 패키지 |
docs/ |
agent-browser.dev 문서 사이트 |
evals/ |
에이전트 평가 케이스 |
benchmarks/ |
성능 벤치 |
보안 모델: 기본은 열려 있고, 프로덕션에서 잠근다
문서 Security 페이지의 문장은 직설적입니다. 내비게이션·액션·출력 제한은 옵트인입니다. LLM이 브라우저를 몰고 다닐 때의 위협 모델(자격 증명 유출, 페이지 프롬프트 인젝션, 비허용 도메인 탈출, 파괴적 액션, 컨텍스트 홍수)에 맞춰 기능을 켜는 설계입니다.
| 기능 | 플래그/메커니즘 | 막는 것 | 한계(문서 명시) |
|---|---|---|---|
| Auth Vault | auth save/login, 암호화 키 |
비밀번호가 LLM 컨텍스트·데몬 IPC에 안 흐름 | 플러그인은 별도 로컬 실행 파일 — 신뢰할 배포본만 |
| Domain allowlist | --allowed-domains |
내비·서브리소스·WS·EventSource·beacon, WebRTC 억제 | OS 방화벽이 아님; cloud attach/profile과 병행 제한 |
| Action policy | --action-policy |
eval/download 등 deny·confirm | 파일 로드 실패 시 거의 전부 deny |
| Confirm gating | --confirm-actions |
위험 액션 승인 | 60초 타임아웃·비 TTY면 자동 deny |
| Content boundaries | --content-boundaries |
페이지 텍스트 vs 도구 출력 구분 | 오케스트레이터가 마커를 존중해야 함 |
| Max output | --max-output |
거대 DOM이 컨텍스트를 삼키는 것 | 정보 손실 가능 |
| Chrome version check | Stable 블로그 대조 | 구버전 CVE 경고 | 차단 없음; AGENT_BROWSER_NO_VERSION_CHECK=1로 끌 수 있음 |
프로젝트 루트 ./agent-browser.json 자동 탐색은 headed·json·뷰포트류 등 제한된 키만 받습니다. 정책·경로·연결 같은 민감 키는 무시하고 경고합니다. 고급 설정은 ~/.agent-browser/config.json 또는 명시 --config로 가져가라는 뜻입니다.
에이전트 통합: skills가 버전을 잠근다
CLI에 스킬이 같이 실립니다. npx skills add vercel-labs/agent-browser로 하네스에 넣는 스킬은 얇은 스텁이고, 실제 지침은 설치된 바이너리의 agent-browser skills get core를 부르게 되어 있습니다. 그래서 문서와 CLI 버전이 어긋나는 문제를 줄입니다. 0.41.2의 --ref는 명령 레퍼런스·템플릿만 골라 읽어 컨텍스트 비용을 깎습니다.
| 스킬 | 용도 |
|---|---|
| core | 스냅샷-ref 루프, 폼, 탭, 세션, 트러블슈팅 |
| electron | VS Code·Slack 등 Electron 앱 |
| slack | 슬랙 워크스페이스 UI 자동화 |
| dogfood | 탐색적 QA·버그 찾기 |
| vercel-sandbox | Sandbox 마이크로VM 안에서 Chrome 구동 |
| agentcore | AWS Bedrock AgentCore 클라우드 브라우저 |
| derive-client | 브라우저 트래픽으로 내부 API 역설계 |
| webmcp-gen | 실험적 WebMCP 도구 생성·검증 |
MCP는 agent-browser mcp(stdio)와 mcp call <tool> '<json>'(단발) 두 경로가 있습니다. 0.41.0 이후 MCP 인자로 글로벌 플래그(--allowed-domains 등)를 몰래 실어 보내는 경로가 막혔습니다 — 도구 스키마와 CLI 파서가 겹치던 공격면입니다.
설치·실행·평가 (박스 실측 포함)
배포 채널은 npm·Homebrew·GitHub Release 바이너리입니다. 이 박스에서는 npm idealTree 오류가 있어 공식 linux-x64 바이너리 0.41.2를 받아 검증했습니다.
# 바이너리 직접 (이번 실측)
curl -sSL -o agent-browser \
https://github.com/vercel-labs/agent-browser/releases/download/v0.41.2/agent-browser-linux-x64
chmod +x agent-browser
./agent-browser --version # → agent-browser 0.41.2
# 일반 경로
npm install -g agent-browser
agent-browser install # Chrome for Testing
# Linux: agent-browser install --with-deps
doctor는 이 환경에서 9 pass / 0 warn / 0 fail이었습니다. Headless launch + about:blank 0.90초, Chrome for Testing CDN 도달 84ms. install --with-deps의 apt 단계는 미러 오류로 중단됐지만, 이미 있는 헤드리스 Chrome으로 본 기능 스모크는 통과했습니다.
./agent-browser open https://example.com
# ⚠ Chrome 155… behind stable 157… fixes 639 CVEs … (차단 없음)
# ✓ Example Domain
./agent-browser snapshot -i
# - link "Learn more" [ref=e1]
./agent-browser click @e1
./agent-browser get url
# https://www.iana.org/help/example-domains
./agent-browser screenshot smoke-example.png
./agent-browser close
| 단계 | 결과 | 측정 |
|---|---|---|
| –version | 0.41.2 | 즉시 |
| doctor | 9 pass / 0 fail | 포함 launch 0.90s |
| open example.com | Example Domain | wall ≈ 0.81s (재실행) |
| snapshot -i | [ref=e1] 링크 1개 |
wall ≈ 0.012s |
| click @e1 | IANA help로 이동 | 성공 |
| screenshot | 81KB PNG 저장 | 성공 |
| 전체 파이프라인(첫 실행) | open→…→close | ≈ 1.6s |
| skills (바이너리만) | 스킬 디렉터리 없음 | AGENT_BROWSER_SKILLS_DIR로 클론의 skill-data 지정 시 9개 목록 정상 |
![박스 실측(2026-11-06 KST): example.com snapshot [ref=e1] → click → iana.org, doctor 9 pass](https://blog.123qwe.co.kr/wp-content/uploads/2026/11/mw-os-agent-browser-20261106-05-box-smoke.png)
평가(evals) 디렉터리와 cargo test(엔진 독립) / cargo test e2e -- --ignored(실 Chrome) 경로가 문서화되어 있습니다. 이 글의 박스는 네트워크·시간 제약상 전체 e2e 스위트 대신 릴리스 바이너리 + 실 페이지 스모크 + doctor를 채택했습니다. CI에서 엔진을 바꿀 때는 Obscura E2E가 환경 변수를 격리하고, 무시된 테스트는 일반 cargo test에 섞이지 않는다는 점도 AGENTS.md에 명시되어 있습니다.
유사 도구와 역할 분담
| 도구 | 계층 | 관찰 단위 | 에이전트 인터페이스 | 언제 고르나 |
|---|---|---|---|---|
| agent-browser | 브라우저 자동화 CLI | 웹 AXTree @ref | CLI·MCP·skills | 웹 앱·폼·QA·스크래핑성 탐색 |
| vercel-labs/agent-desktop | 컴퓨터 유즈 CLI | OS 접근성 트리 | CLI | 네이티브 창·데스크톱 앱 |
| lightpanda-io/browser | 헤드리스 브라우저 엔진 | 자체 렌더/CDP | 엔진·임베드 | Chrome 대체 런타임 자체 |
| Playwright / Puppeteer | 스크립트 SDK | DOM·셀렉터 | 코드 작성 | 고정 회귀 테스트·CI 시나리오 |
| browser-use 등 에이전트 프레임워크 | 오케스트레이션 | 다양 | Python/에이전트 루프 | 계획·도구 선택까지 포함한 앱 |
| 클라우드 (Browserbase 등) | 원격 브라우저 | CDP 세션 | provider 플러그인 | 로컬 Chrome 없이 스케일 |
agent-browser는 Lightpanda를 경쟁 제품이 아니라 --engine 옵션으로 품습니다. 엔진을 고르는 문제와, 에이전트에게 ‘어떤 관찰·행동 API를 줄 것인가’ 문제는 층이 다릅니다. 마찬가지로 Playwright를 대체한다기보다, 에이전트가 매 스텝 셸로 개입하는 루프에 맞춘 인터페이스입니다. 회귀 테스트 스위트를 이미 Playwright로 잠가 둔 팀은 그 자리를 굳이 옮길 필요가 없고, LLM 하네스에 브라우저를 붙일 때 후보가 됩니다.
실무 체크리스트와 주의점
| 상황 | 권장 |
|---|---|
| 병렬 에이전트 | session id --scope worktree 후 모든 명령에 --session |
| 프로덕션/고객 데이터 | --allowed-domains + action policy + vault. 기본 설정 금지 |
| 동의 배너·오버레이 | 클릭 실패를 신뢰하고, 가린 요소를 먼저 처리한 뒤 재스냅샷 |
| 캔버스/WebGL UI | AX 한계 → find/eval/스크린샷 병행, 자동화 난이도 상승 가정 |
| 구형 Chrome | CVE 경고를 무시하지 말고 agent-browser install로 갱신 |
| 바이너리만 배포 | 스킬 경로를 AGENT_BROWSER_SKILLS_DIR로 명시하거나 npm 패키지 사용 |
| allowlist + attach | --cdp/profile/restore와 동시 사용은 거절될 수 있음 — 설계상 |
0.41.x에서 바뀐 운영 포인트
| 버전 | 실무 영향 |
|---|---|
| 0.41.0 | eve MCP 도구명을 CLI MCP 카탈로그에 정렬; mcp call 단발 실행; MCP 인자로 글로벌 플래그 주입 차단 |
| 0.41.1 | 쿠키 SameSite/HttpOnly 존중; MCP 셀렉터 대기 오해 수정; 스킬의 unpin npx 권한 제거 |
| 0.41.2 | skills --ref 부분 로드; Chrome Stable 대비 CVE 경고; 세션 재시작 시 페이지 보존; bare open이 프로파일/인자를 잃지 않도록 수정 |
| 관측 모드 | 명령 | 토큰/비용 감각 | 적합한 때 |
|---|---|---|---|
| interactive snapshot | snapshot -i |
최저 | 클릭·입력 루프 |
| full AX snapshot | snapshot |
중 | 정적 텍스트·다국어 본문 확인 |
| read | read [url] |
중 | 에이전트 가독 텍스트만 필요할 때 |
| screenshot / pdf | screenshot, pdf |
고(이미지) | 시각 회귀·증거 보관 |
| record + contact sheet | record start/stop |
고 | 디버깅·데모·감사 |
| diff | diff snapshot|screenshot|url |
중 | 변경 감지·A/B |
포지셔닝 한 줄
agent-browser는 ‘브라우저를 스크립트로 고정’하는 도구가 아니라, 에이전트가 짧게 보고 짧게 손대는 웹 조작면을 CDP와 접근성 트리로 표준화한 CLI입니다. 0.41.2 기준으로 스킬 부분 로드·Chrome CVE 경고·세션 안정성 쪽이 다듬어져 있고, 박스 실측에서도 예제 도메인 클릭 루프는 1–2초 안에 닫혔습니다. 웹 태스크에는 이 도구, 네이티브 GUI에는 agent-desktop, 엔진 자체를 교체할 필요가 있으면 Lightpanda/Obscura — 이 삼각 배치가 현재 Vercel Labs·주변 생태계에서 읽히는 실무 지도입니다.