This article is mostly written by Claude Code

agent-browser Architecture & Use Case Analysis Report

Project: vercel-labs/agent-browser Version: 0.25.3 | License: Apache-2.0 Analysis Date: 2026-04-09

1. Executive Summary

agent-browser는 Vercel Labs에서 개발한 AI 에이전트를 위한 브라우저 자동화 CLI입니다. Rust로 작성된 네이티브 바이너리로, Chrome DevTools Protocol(CDP)을 통해 브라우저를 직접 제어합니다. Node.js 런타임 없이 동작하며, LLM이 웹을 탐색하고 조작할 수 있도록 설계된 접근성 트리(Accessibility Tree) 기반의 요소 참조(Ref) 시스템이 핵심입니다.

핵심 가치:

AI 에이전트가 웹을 "읽고 조작"할 수 있는 표준 인터페이스 제공
네이티브 Rust 성능 (Node.js 대비 빠른 시작, 낮은 메모리)
로컬/클라우드 브라우저 모두 지원하는 Provider 추상화
보안 기능 내장 (도메인 화이트리스트, 액션 정책, 암호화된 인증 저장소)

2. High-Level Architecture

┌─────────────────────────────────────────────────────────┐
│                    User / AI Agent                       │
│              (Claude Code, LLM, Script)                  │
└──────────────────────┬──────────────────────────────────┘
                       │ CLI Commands / JSON
                       ▼
┌─────────────────────────────────────────────────────────┐
│                   CLI Layer (Rust)                        │
│  main.rs → commands.rs → flags.rs → connection.rs        │
│  - 명령어 파싱 (170+ commands)                            │
│  - IPC 소켓 통신 (Unix Domain Socket / TCP)               │
│  - 출력 포맷팅 (text / JSON)                              │
└──────────────────────┬──────────────────────────────────┘
                       │ IPC (Unix Socket)
                       ▼
┌─────────────────────────────────────────────────────────┐
│                 Daemon Layer (Rust)                       │
│  daemon.rs → actions.rs (314KB, 핵심 비즈니스 로직)        │
│  ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐  │
│  │ BrowserMgr  │ │  RefMap      │ │  StreamServer    │  │
│  │ (browser.rs)│ │ (element.rs) │ │  (stream/)       │  │
│  └──────┬──────┘ └──────────────┘ └──────────────────┘  │
│  ┌──────┴──────┐ ┌──────────────┐ ┌──────────────────┐  │
│  │ Snapshot    │ │  State       │ │  Recording       │  │
│  │(snapshot.rs)│ │ (state.rs)   │ │ (recording.rs)   │  │
│  └──────┬──────┘ └──────────────┘ └──────────────────┘  │
│  ┌──────┴──────┐ ┌──────────────┐ ┌──────────────────┐  │
│  │ Interaction │ │  Network     │ │  Auth Vault      │  │
│  │(interact.rs)│ │ (network.rs) │ │  (auth.rs)       │  │
│  └─────────────┘ └──────────────┘ └──────────────────┘  │
└──────────────────────┬──────────────────────────────────┘
                       │ CDP WebSocket
                       ▼
┌─────────────────────────────────────────────────────────┐
│              CDP Client (cdp/client.rs)                   │
│  - Async WebSocket (tokio-tungstenite)                   │
│  - Message routing & event broadcasting                  │
│  - Session scoping (browser/page level)                  │
│  - Keepalive (30s ping)                                  │
└──────────┬──────────────────┬───────────────────────────┘
           │                  │
     ┌─────▼─────┐    ┌──────▼──────┐
     │  Chrome   │    │ Lightpanda  │    ┌──────────────┐
     │ (local)   │    │  (local)    │    │ Cloud        │
     │ cdp/      │    │ cdp/        │    │ Providers    │
     │ chrome.rs │    │lightpanda.rs│    │(providers.rs)│
     └───────────┘    └─────────────┘    └──────────────┘
                                          - Browserbase
                                          - Browserless
                                          - Browser Use
                                          - Kernel
                                          - AgentCore(AWS)

3. 모노레포 구조

agent-browser/
├── cli/                    # Rust 핵심 애플리케이션 (3.3MB)
│   ├── Cargo.toml          # Rust 의존성 매니페스트
│   ├── build.rs            # CDP 프로토콜 타입 코드 생성
│   └── src/
│       ├── main.rs         # 엔트리포인트
│       └── native/
│           ├── daemon.rs   # 비동기 이벤트 루프, 상태 관리
│           ├── actions.rs  # 명령 실행 엔진 (314KB, 100+ 액션)
│           ├── browser.rs  # 브라우저 프로세스 관리
│           ├── snapshot.rs # 접근성 트리 추출
│           ├── element.rs  # Ref → DOM 요소 매핑
│           ├── interaction.rs  # click, fill, type 등 저수준 액션
│           ├── state.rs    # 세션 상태 (쿠키, localStorage)
│           ├── network.rs  # 네트워크 추적, HAR, 도메인 필터링
│           ├── auth.rs     # 암호화된 인증 저장소
│           ├── recording.rs # ffmpeg 기반 녹화
│           ├── policy.rs   # 액션 허용/거부/확인 정책
│           ├── providers.rs # 클라우드 브라우저 프로바이더
│           ├── cdp/        # Chrome DevTools Protocol 클라이언트
│           ├── stream/     # WebSocket 스트리밍 서버
│           └── webdriver/  # iOS Safari 자동화 (Appium)
├── packages/
│   └── dashboard/          # Next.js 16 실시간 모니터링 대시보드
│       ├── React 19 + Tailwind CSS 4 + Radix UI
│       ├── jotai (상태 관리)
│       └── Vercel AI SDK (AI 채팅)
├── docs/                   # Next.js 문서 사이트 (28+ MDX 페이지)
├── skills/                 # Claude Code 스킬 정의
│   ├── agent-browser/      # 핵심 브라우저 자동화 워크플로우
│   ├── agentcore/          # AWS Bedrock 연동
│   ├── slack/              # Slack 자동화
│   ├── electron/           # Electron 앱 자동화
│   ├── dogfood/            # 내부 테스트
│   └── vercel-sandbox/     # Vercel Sandbox 연동
├── examples/               # 예제 구현
├── benchmarks/             # 성능 벤치마크
├── bin/                    # 플랫폼별 바이너리 shim
└── scripts/                # 빌드 유틸리티

빌드 타겟 (7개 플랫폼):

OS	Architecture	비고
macOS	arm64 (Apple Silicon)	네이티브 빌드
macOS	x64 (Intel)	크로스 컴파일
Linux	arm64 (musl)	Docker 빌드
Linux	arm64 (gnu)	Docker 빌드
Linux	x64 (musl)	Docker 빌드
Linux	x64 (gnu)	Docker 빌드
Windows	x64	Docker 크로스 컴파일

4. 핵심 기술 스택

4.1 Runtime & Language

기술	용도
Rust	CLI 및 데몬 전체 (네이티브 바이너리)
Tokio	비동기 런타임 (멀티스레드)
TypeScript/React	대시보드 UI
Next.js 16	대시보드 프레임워크

4.2 Browser Automation

기술	용도
CDP (Chrome DevTools Protocol)	브라우저 제어의 핵심 프로토콜
Chrome for Testing	공식 자동화 채널 브라우저
Lightpanda	경량 Rust 기반 헤드리스 브라우저 (10x 빠름)
WebDriver/Appium	iOS Safari 모바일 자동화

4.3 Networking & Security

기술	용도
tokio-tungstenite	WebSocket 클라이언트/서버
reqwest	HTTP 클라이언트
AES-256-GCM	상태 파일 및 인증 정보 암호화
rustls	TLS (시스템 인증서 사용)

4.4 AI Integration

기술	용도
Vercel AI Gateway	LLM 프록시 (다중 모델 지원)
Vercel AI SDK	대시보드 채팅 UI
Claude Code Skills	AI 에이전트 워크플로우 정의

5. 핵심 설계 패턴

5.1 Client-Daemon Architecture

[CLI 프로세스]  ──IPC──▶  [Daemon 프로세스]  ──CDP──▶  [Browser]
  (명령 파싱)              (상태 유지)                  (Chrome)
  (출력 포맷팅)            (세션 관리)
  (수명: 명령 단위)        (수명: 세션 단위)

CLI는 각 명령마다 새 프로세스로 실행되며 데몬에 IPC로 연결
데몬은 세션 동안 상주하며 브라우저 연결, RefMap, 네트워크 상태 등을 유지
Unix Domain Socket (macOS/Linux) 또는 TCP (Windows)로 통신

5.2 Ref-Based Element Selection (AI 최적화)

이 프로젝트의 가장 독특한 설계입니다. LLM이 DOM을 효율적으로 이해하고 조작하도록 설계되었습니다.

1. snapshot 명령 실행
   └─▶ Accessibility.getFullAXTree (CDP)
       └─▶ AXNode 트리 수신
           └─▶ 인터랙티브 노드 필터링 (button, link, textbox, checkbox...)
               └─▶ @e1, @e2, @e3... Ref 할당
                   └─▶ RefMap에 저장 (backend_node_id 매핑)

2. 에이전트가 @e3 클릭 요청
   └─▶ RefMap에서 @e3 → backend_node_id 조회
       └─▶ DOM.getBoxModel로 좌표 계산
           └─▶ Input.dispatchMouseEvent 실행

장점:

CSS 셀렉터 대비 토큰 효율성 극대화 (@e1 vs #main-content > div:nth-child(2) > button.submit)
접근성 트리 기반이므로 시각적으로 보이지 않는 요소도 탐지 (숨겨진 라디오/체크박스 등)
크로스 프레임 자동 해결 (iframe 내부 요소도 @eN으로 직접 접근)

5.3 Provider Abstraction

// providers.rs - 추상 인터페이스
Provider → connect() → CDP WebSocket URL 반환

// 구현체
├── Local Chrome    (chrome.rs)
├── Lightpanda      (lightpanda.rs)
├── Browserbase     (REST API → CDP URL)
├── Browserless     (REST API → CDP URL)
├── Browser Use     (REST API v2 → CDP URL)
├── Kernel          (REST API → CDP URL)
└── AgentCore       (AWS Bedrock SigV4 → CDP URL)

모든 프로바이더가 CDP WebSocket URL을 반환하는 동일한 인터페이스를 따르므로, 로컬 Chrome과 클라우드 브라우저 간 전환이 플래그 하나(-p <provider>)로 가능합니다.

5.4 Streaming & Observability

[Daemon] ──CDP events──▶ [StreamServer] ──WebSocket──▶ [Dashboard UI]
                              │
                              ├── Page.screencastFrame (실시간 뷰포트)
                              ├── Activity Feed (명령 실행 로그)
                              ├── Console Output (브라우저 콘솔)
                              └── AI Chat (Vercel AI Gateway 프록시)

대시보드 정적 에셋은 rust-embed로 Rust 바이너리에 임베딩되어, 별도 파일 없이 단일 바이너리로 서빙됩니다.

5.5 Security Model (Layered Defense)

┌─────────────────────────────────────┐
│  Layer 1: Domain Allowlist           │  AGENT_BROWSER_ALLOWED_DOMAINS
│  - 허용된 도메인만 탐색 가능           │  - 서브리소스 요청도 차단
├─────────────────────────────────────┤
│  Layer 2: Action Policy              │  AGENT_BROWSER_ACTION_POLICY
│  - allow/deny/confirm 액션 제어       │  - JSON 정책 파일
├─────────────────────────────────────┤
│  Layer 3: Content Boundaries         │  AGENT_BROWSER_CONTENT_BOUNDARIES
│  - 페이지 콘텐츠를 nonce로 격리        │  - LLM 프롬프트 인젝션 방어
├─────────────────────────────────────┤
│  Layer 4: Output Limits              │  AGENT_BROWSER_MAX_OUTPUT
│  - 출력 크기 제한                     │  - 컨텍스트 플러딩 방지
├─────────────────────────────────────┤
│  Layer 5: Encrypted State            │  AGENT_BROWSER_ENCRYPTION_KEY
│  - AES-256-GCM 암호화                │  - 인증 정보, 세션 상태
└─────────────────────────────────────┘

6. 핵심 데이터 구조

// DaemonState - 중앙 상태 관리 허브
pub struct DaemonState {
    pub browser: Option<BrowserManager>,     // 브라우저 프로세스 관리
    pub ref_map: RefMap,                     // @e1 → 요소 매핑
    pub routes: Vec<RouteEntry>,             // 네트워크 인터셉션 규칙
    pub policy: Option<ActionPolicy>,        // 액션 제한 정책
    pub recording_state: RecordingState,     // 활성 녹화 상태
    pub tracing_state: TracingState,         // 성능 추적 상태
    pub stream_server: Option<StreamServer>, // WebSocket 서버
    pub iframe_sessions: HashMap<FrameId, SessionId>, // 크로스프레임 세션
}

// RefMap - AI 에이전트의 핵심 인터페이스
pub struct RefMap {
    map: HashMap<String, RefEntry>,  // "@e1" → { backend_node_id, role, name }
}

// StorageState - 세션 영속화
pub struct StorageState {
    pub cookies: Vec<Cookie>,
    pub origins: Vec<OriginStorage>,  // origin별 localStorage + sessionStorage
}

7. 동시성 모델

Session 1                    Session 2
┌──────────────────┐        ┌──────────────────┐
│ DaemonState #1   │        │ DaemonState #2   │
│ (순차 명령 실행)  │        │ (순차 명령 실행)  │
│                  │        │                  │
│ Background Tasks:│        │ Background Tasks:│
│ - Recording      │        │ - Recording      │
│ - Fetch intercept│        │ - Dialog handler │
│ - Dialog handler │        │ - Streaming      │
│ - Streaming      │        │                  │
└──────────────────┘        └──────────────────┘
        │                           │
        └─────────┬─────────────────┘
                  │
          Tokio Runtime (multi-threaded)

세션 내부: 단일 스레드 순차 명령 실행 (일관성 보장)
세션 간: 완전 독립 병렬 실행
백그라운드: 녹화, 스트리밍, 다이얼로그 핸들링, Fetch 인터셉션은 별도 tokio task

8. AI 에이전트 연동 패턴

8.1 Snapshot → Ref → Action 루프 (핵심 패턴)

AI Agent
  │
  ├─▶ agent-browser open https://example.com
  │
  ├─▶ agent-browser snapshot -i
  │     └─ 응답: @e1 [textbox] "Email", @e2 [textbox] "Password", @e3 [button] "Login"
  │
  ├─▶ (LLM이 트리를 읽고 판단)
  │
  ├─▶ agent-browser fill @e1 "user@test.com"
  ├─▶ agent-browser fill @e2 "secret123"
  ├─▶ agent-browser click @e3
  │
  ├─▶ agent-browser snapshot -i  (페이지 변경 후 재스냅샷)
  │     └─ 새로운 refs 반환
  │
  └─▶ (반복...)

8.2 Chat 모드 (자연어 제어)

# 단일 명령 모드
agent-browser chat "open google.com and search for cats"

# 대화형 REPL 모드
agent-browser chat

Vercel AI Gateway를 통해 다양한 LLM 모델 지원
기본 모델: anthropic/claude-sonnet-4.6
시스템 프롬프트에 skills/ 디렉토리의 SKILL.md 내용 자동 주입
LLM이 자연어를 agent-browser 명령으로 변환하여 실행

8.3 Claude Code Plugin

// .claude-plugin/marketplace.json
// Claude Code에서 "agent-browser" 스킬로 자동 로드
// Bash(agent-browser:*) 허용 패턴으로 안전한 실행

SKILL.md 파일이 Claude Code의 시스템 프롬프트로 주입되어, Claude가 웹 자동화 방법을 "알고" 있는 상태에서 사용자 요청을 처리합니다.

9. Use Case 분석

9.1 AI 에이전트의 웹 자동화

시나리오: LLM 기반 에이전트가 웹사이트와 상호작용

# 에이전트가 주문 상태 확인
agent-browser --session order-check open https://shop.example.com
agent-browser snapshot -i
# LLM: @e1은 로그인 폼, @e2는 이메일, @e3은 비밀번호, @e4는 제출 버튼
agent-browser batch "fill @e2 'user@example.com'" "fill @e3 'pass'" "click @e4"
agent-browser wait --url "**/dashboard"
agent-browser snapshot -i
# LLM: @e8에 주문 내역 테이블, @e9~@e15에 최근 주문 항목들
agent-browser get text @e9

적합한 이유:

접근성 트리 기반이므로 시각적 레이아웃 변경에 강건
JSON 출력으로 LLM이 구조화된 데이터를 바로 파싱
세션 영속화로 반복 로그인 불필요

9.2 웹 스크레이핑 & 데이터 추출

시나리오: 여러 페이지에서 구조화된 데이터 추출

# URL 목록을 먼저 수집
agent-browser batch "open https://news.ycombinator.com" "snapshot -i --urls"
# 각 URL을 직접 방문하여 데이터 추출
agent-browser batch "open https://article-1.com" "snapshot -i --json"
agent-browser batch "open https://article-2.com" "snapshot -i --json"

장점:

--urls 플래그로 한 번에 모든 링크 URL 획득 (불필요한 탐색 제거)
batch 명령으로 다수 명령을 단일 호출로 실행
병렬 세션(--session)으로 동시 스크레이핑 가능

9.3 E2E 테스트 자동화

시나리오: CI/CD 파이프라인에서 웹 앱 E2E 테스트

# 헤드리스 모드로 빠른 테스트
agent-browser open https://staging.example.com/login
agent-browser snapshot -i
agent-browser batch "fill @e1 '$TEST_USER'" "fill @e2 '$TEST_PASS'" "click @e3"
agent-browser wait --url "**/dashboard"
agent-browser diff snapshot  # 기대 상태와 비교

# 시각적 회귀 테스트
agent-browser screenshot baseline.png
# ... 코드 변경 후 ...
agent-browser diff screenshot --baseline baseline.png
# 차이 이미지 + 불일치 비율 반환

장점:

diff snapshot으로 접근성 트리 변경 감지 (git diff 스타일)
diff screenshot으로 픽셀 단위 시각 비교
diff url로 스테이징 vs 프로덕션 직접 비교
Lightpanda 엔진으로 10x 빠른 헤드리스 테스트

9.4 모바일 웹 테스팅

시나리오: iOS Safari에서 모바일 웹 앱 테스트

agent-browser -p ios --device "iPhone 16 Pro" open https://m.example.com
agent-browser -p ios snapshot -i
agent-browser -p ios tap @e1
agent-browser -p ios swipe up
agent-browser -p ios screenshot mobile-test.png

장점:

실제 iOS 시뮬레이터/디바이스에서 테스트
데스크톱과 동일한 snapshot → ref → action 워크플로우
모바일 전용 제스처 (tap, swipe) 지원

9.5 인증이 필요한 자동화

시나리오: 로그인 상태가 필요한 반복 작업

# 방법 1: Auth Vault (가장 안전 - 암호화 저장)
echo "$PASSWORD" | agent-browser auth save myapp \
  --url https://app.example.com/login \
  --username user --password-stdin
agent-browser auth login myapp  # 자동 로그인

# 방법 2: 기존 Chrome 프로필 재사용 (설정 불필요)
agent-browser --profile Default open https://gmail.com

# 방법 3: 세션 영속화 (자동 쿠키 저장/복원)
agent-browser --session-name myapp open https://app.example.com

보안 특징:

Auth Vault: AES-256-GCM으로 자격증명 암호화 저장
LLM에 비밀번호가 노출되지 않음 (vault가 직접 폼 작성)
상태 파일 암호화 옵션 제공

9.6 실시간 모니터링 & 디버깅

시나리오: AI 에이전트의 브라우저 행동을 실시간 관찰

agent-browser dashboard start          # 포트 4848에서 대시보드 시작
agent-browser open https://example.com  # 자동으로 대시보드에 표시

# 대시보드 기능:
# - 실시간 브라우저 뷰포트 스트리밍
# - 명령 실행 활동 피드
# - 브라우저 콘솔 출력
# - AI 채팅 (Vercel AI Gateway)

9.7 클라우드 브라우저 스케일링

시나리오: 대량 병렬 웹 작업을 클라우드에서 실행

# Browserbase 클라우드 사용
agent-browser -p browserbase open https://example.com

# AWS Bedrock AgentCore 사용
agent-browser -p agentcore open https://example.com

# 프로바이더 전환은 플래그 하나로 완료
# 코드 변경 없이 로컬 ↔ 클라우드 전환

10. 경쟁 도구 대비 차별점

특성	agent-browser	Playwright	Puppeteer	Selenium
언어	Rust (네이티브)	Node.js/Python	Node.js	Java/Python/JS
AI 최적화	접근성 트리 Ref 시스템	없음	없음	없음
CLI 우선	핵심 인터페이스	API 우선	API 우선	API 우선
LLM 채팅	내장 (AI Gateway)	없음	없음	없음
모바일	iOS Safari (Appium)	WebKit/Chromium	Chrome만	다수
경량 엔진	Lightpanda 지원	없음	없음	없음
클라우드 프로바이더	5개 내장	없음 (별도 설정)	없음	Grid
보안 정책	도메인/액션 정책 내장	없음	없음	없음
실시간 대시보드	내장 (바이너리 임베딩)	Trace Viewer (사후)	없음	없음

핵심 차별화: agent-browser는 "AI 에이전트가 웹을 사용하는 도구"로서 설계된 반면, 기존 도구들은 "개발자가 테스트를 작성하는 도구"로 설계되었습니다. 이 관점 차이가 접근성 트리 기반 Ref 시스템, CLI 우선 인터페이스, 보안 정책 레이어 등의 설계 결정을 이끌었습니다.

11. 기술적 인사이트

11.1 CDP 프로토콜 타입 자동 생성

build.rs가 cdp-protocol/*.json 스펙 파일을 파싱하여 Rust 타입을 자동 생성합니다. 이를 통해 CDP 프로토콜 업데이트 시 수동 타입 작성 없이 빌드 스크립트만 실행하면 됩니다.

11.2 Dashboard Binary Embedding

rust-embed 크레이트를 사용하여 빌드된 Next.js 정적 에셋을 Rust 바이너리에 직접 임베딩합니다. 별도 파일 배포 없이 단일 바이너리로 대시보드를 서빙할 수 있습니다.

11.3 Cross-Frame Ref Resolution

iframe 내부 요소도 @eN ref로 직접 접근 가능합니다. 내부적으로 Target.attachToTarget으로 각 iframe에 대한 별도 CDP 세션을 생성하고, iframe_sessions HashMap으로 관리합니다. 이를 통해 에이전트가 프레임 전환을 의식하지 않아도 됩니다.

11.4 Content Boundaries (Prompt Injection 방어)

페이지 콘텐츠를 nonce가 포함된 마커로 감싸서 LLM이 "도구 출력"과 "페이지 콘텐츠"를 구분할 수 있게 합니다. 악의적 웹사이트가 접근성 트리를 통해 LLM 프롬프트를 조작하려는 시도를 방어합니다.

12. 결론

agent-browser는 "AI 에이전트를 위한 웹 브라우저 인터페이스" 라는 명확한 비전 아래, Rust의 성능과 안전성을 기반으로 구축된 프로덕션 수준의 도구입니다.

아키텍처적 강점:

Client-Daemon 분리로 세션 상태 유지와 명령 실행의 깔끔한 분리
접근성 트리 기반 Ref 시스템으로 AI 에이전트에 최적화된 인터페이스
Provider 추상화로 로컬/클라우드 투명한 전환
다층 보안 모델로 AI 에이전트의 안전한 웹 접근
단일 바이너리 배포 (대시보드 에셋 임베딩 포함)

활용 가치가 높은 시나리오:

LLM 기반 자율 에이전트의 웹 작업 수행
AI 보조 웹 스크레이핑 및 데이터 추출
CI/CD 파이프라인의 E2E/시각적 회귀 테스트
클라우드 브라우저를 활용한 대규모 병렬 웹 자동화
모바일 웹 테스팅 (iOS Safari)

Generated by architecture analysis of vercel-labs/agent-browser v0.25.3