agent-browser

Overview

What is agent-browser?

agent-browser는 AI 에이전트와 셸 기반 워크플로를 위해 설계된 커맨드라인 브라우저 자동화 도구입니다. Chrome DevTools Protocol(CDP)을 통해 Chrome 또는 Chromium에 직접 연결하므로, 터미널이나 에이전트 런타임에서 실제 브라우저 상호작용을 스크립트로 제어할 수 있습니다.

agent-browser를 사용하면 다음 작업을 수행할 수 있습니다.

• 웹 페이지 열기 및 탐색 (agent-browser open <url>)
• 구조화된 스냅샷으로 인터랙티브 요소 발견
• 버튼 클릭, 링크 이동, 폼 상호작용
• 입력 필드 채우기, 텍스트 입력, 키 입력
• 페이지 구조와 가능한 액션을 파악하기 위한 스냅샷 생성
• 세션 관리 및 로그인 상태 유지
• OAuth 및 사람의 도움이 필요한 2FA를 포함한 인증 플로 처리
• 지리적 테스트나 사내 네트워크용 프록시 사용
• 프로파일링을 위한 성능 트레이스 수집
• 디버깅·문서화를 위한 브라우저 세션 동영상 녹화

Who is agent-browser for?

agent-browser는 다음과 같은 경우에 특히 잘 맞습니다.

• 실제 브라우저를 제어해야 하는 AI 에이전트나 자동화 프레임워크를 운영할 때
• Chrome/Chromium 워크플로를 CLI 중심으로 자동화하고 싶을 때
• 간결한 @refs로 LLM 친화적인 강력한 요소 타깃팅이 필요할 때
• 로그인 플로, 폼 제출, 다단계 웹 앱 플로를 자동화할 때
• 재현 가능한 테스트, 데모, 디버깅 세션을 영상이나 트레이스로 남기고 싶을 때

특히 다음과 같은 시나리오에 유용합니다.

• 브라우저 자동화: 스크립트 기반 탐색, 클릭, 폼 입력
• 워크플로 자동화: "로그인 → 이동 → 리포트 내보내기" 같은 엔드 투 엔드 시퀀스
• 테스트 자동화: 웹 앱의 스모크 테스트, 회귀 테스트, 성능 프로파일링

When agent-browser is and is not a good fit

다음과 같은 경우에는 agent-browser 사용을 추천합니다.

• 로컬에서 CLI를 실행할 수 있고 Chrome 또는 Chromium에 접근할 수 있을 때
• AI 에이전트가 제어할 수 있는 결정론적이고 스크립트 가능한 브라우저 동작이 필요할 때
• 세션, 쿠키, 인증을 세밀하게 제어해야 할 때

반대로 다음 상황에서는 적합하지 않을 수 있습니다.

• 호스트에 Chrome/Chromium을 설치하거나 실행할 수 없을 때
• 단순한 HTML 또는 HTTP 요청만 필요할 때 (순수 HTTP 클라이언트나 스크레이퍼가 더 간단할 수 있음)
• 다른 브라우저 자동화 라이브러리에 강하게 결합된 언어·런타임에서 헤드리스 브라우저 제어가 필요한 경우

How to Use

Installation options

agent-browser는 여러 설치 방법을 지원합니다. 사용 환경에 맞는 방식을 선택하세요.

• npm (Node.js)

  npm i -g agent-browser
  

• Homebrew (macOS/Linux)

  brew install agent-browser
  

• Rust / Cargo

  cargo install agent-browser
  

CLI 설치 후, 내장 Chrome 설정을 실행합니다.

agent-browser install

이 명령은 호환되는 Chrome/Chromium 빌드를 다운로드하고 연결합니다. 새 버전이 나오면 다음으로 업데이트할 수 있습니다.

agent-browser upgrade

agent-browser를 에이전트 플랫폼의 스킬로 사용하는 경우, 다음과 같이 추가할 수도 있습니다.

npx skills add https://github.com/vercel-labs/agent-browser --skill agent-browser

리포지토리의 SKILL.md 파일에서 최신 스킬 연동 방법을 확인하세요.

Core browser automation workflow

모든 agent-browser 워크플로는 open → snapshot → interact → re-snapshot이라는 간단한 루프를 따릅니다.

1. 페이지로 이동하기

   agent-browser open https://example.com/form
   

2. 요소를 찾기 위한 스냅샷 생성
   인터랙티브 스냅샷 모드를 사용하면 @refs가 포함된 클릭/입력 가능 요소 목록을 간결하게 얻을 수 있습니다.

   agent-browser snapshot -i
   

   (단순화한) 출력 예:

   @e1 [input type="email"]
   @e2 [input type="password"]
   @e3 [button] "Submit"
   

3. refs를 이용해 상호작용하기

   agent-browser fill @e1 "user@example.com"
   agent-browser fill @e2 "password123"
   agent-browser click @e3
   

4. 대기 후 다시 스냅샷 찍기

   agent-browser wait --load networkidle
   agent-browser snapshot -i
   

이 패턴을 사용하면 AI 에이전트가 전체 DOM 대신 압축된 구조 뷰를 기반으로 추론할 수 있어, 컨텍스트 사용량을 크게 줄일 수 있습니다.

Command reference basics

agent-browser는 다양한 명령을 제공합니다(자세한 목록은 references/commands.md 참조).

• Navigation

  agent-browser open <url>
  agent-browser back
  agent-browser forward
  agent-browser reload
  agent-browser close
  

• Snapshot and refs

  agent-browser snapshot          # 전체 트리
  agent-browser snapshot -i       # 인터랙티브 요소만 (권장)
  agent-browser snapshot -c       # 컴팩트 출력
  agent-browser snapshot -d 3     # 최대 깊이 제한
  agent-browser snapshot -s "#main"  # 특정 CSS 셀렉터 범위로 제한
  

• Interactions

  agent-browser click @e1
  agent-browser dblclick @e1
  agent-browser hover @e1
  agent-browser focus @e1
  agent-browser fill @e2 "text"
  agent-browser type @e2 "text"
  agent-browser press Enter
  

@refs가 어떻게 생성되고 얼마 동안 유효한지에 대한 자세한 내용은 references/snapshot-refs.md를 참고하세요.

Working with sessions and authentication

agent-browser는 인증이 필요한 브라우징과 멀티 세션 작업을 위한 기능을 기본 제공하며, 로그인 플로, 다중 계정 테스트, 권한별 사용자 구분 등에 유용합니다.

• Named sessions (자세한 내용은 references/session-management.md):

  # "auth" 세션: 로그인 플로
  agent-browser --session auth open https://app.example.com/login
  
  # "public" 세션: 별도 브라우징
  agent-browser --session public open https://example.com
  

  각 세션은 쿠키, 스토리지, 캐시, 방문 기록이 서로 분리되어 있습니다.

• Session state persistence:

  # 쿠키와 스토리지 저장
  agent-browser state save ./auth-state.json
  
  # 나중에 복원
  agent-browser state load ./auth-state.json
  agent-browser open https://app.example.com/dashboard
  

• Authentication patterns (자세한 내용은 references/authentication.md):

  • 이미 로그인된 Chrome(디버그 모드)에서 쿠키를 가져오기
  • 스냅샷과 fill/click을 이용해 일반적인 로그인 폼을 순차적으로 진행
  • 쿠키 기반 인증, HTTP 기본 인증, 토큰 갱신 처리

복잡한 OAuth나 2FA 플로의 경우 초기 설정 단계에는 사람이 개입해야 할 수 있지만, 일단 인증 상태를 저장해 두면 이후에는 agent-browser가 해당 상태를 재사용할 수 있습니다.

Proxy support and network configuration

지리적 위치 기반 테스트, 레이트 리밋 회피, 사내 네트워크 등으로 인해 프록시를 사용해야 한다면 references/proxy-support.md에 정리된 옵션을 사용할 수 있습니다.

• CLI 플래그로 HTTP/HTTPS 프록시 설정

  agent-browser --proxy "http://proxy.example.com:8080" open https://example.com
  

• 환경 변수 설정

  export HTTP_PROXY="http://proxy.example.com:8080"
  export HTTPS_PROXY="https://proxy.example.com:8080"
  agent-browser open https://example.com
  

• SOCKS 프록시

  export ALL_PROXY="socks5://proxy.example.com:1080"
  agent-browser open https://example.com
  

Profiling and performance tracing

테스트 자동화나 성능 분석이 필요하다면, agent-browser로 Chrome 성능 트레이스(caputre)를 수집할 수 있습니다(references/profiling.md 참조).

# 프로파일링 시작
agent-browser profiler start

# 시나리오 실행
agent-browser open https://example.com
agent-browser click @e1
agent-browser wait 1000

# 중지 및 트레이스 저장
agent-browser profiler stop ./trace.json

생성된 trace.json은 Chrome DevTools(Performance 탭) 또는 호환 뷰어에서 열어 JavaScript 실행, 렌더링, 사용자 타이밍 이벤트를 분석할 수 있습니다.

Video recording for debugging and documentation

agent-browser는 브라우저 세션을 동영상으로 녹화할 수 있으므로, 실패한 자동화 시나리오 디버깅이나 가이드 문서 제작에 유용합니다(references/video-recording.md 참조).

# 녹화 시작
agent-browser record start ./demo.webm

# 액션 수행
agent-browser open https://example.com
agent-browser snapshot -i
agent-browser click @e1

# 녹화 종료
agent-browser record stop

이렇게 생성된 .webm 파일은 문서에 삽입하거나 팀원과 공유하거나 버그 리포트에 첨부할 수 있습니다.

Using templates for common workflows

리포지토리의 templates/ 디렉터리에는 반복 가능한 워크플로를 빠르게 구성할 수 있는 셸 스크립트 템플릿이 포함되어 있습니다.

• templates/form-automation.sh – 폼 입력 및 제출을 구조화된 패턴으로 자동화
• templates/authenticated-session.sh – 로그인 및 세션 상태 유지 예제
• templates/capture-workflow.sh – 여러 단계를 스냅샷 또는 녹화하는 워크플로 패턴

이 스크립트들을 복사해 환경, CI 잡, 에이전트 파이프라인에 맞게 수정하여 사용할 수 있습니다.

FAQ

단순 HTTP 클라이언트와 비교했을 때 agent-browser는 어떤 문제를 해결해 주나요?

agent-browser는 CDP를 통해 실제 Chrome/Chromium 인스턴스를 제어합니다. 따라서 다음과 같은 작업이 가능합니다.

• 클라이언트 사이드 렌더링 및 복잡한 JavaScript 처리
• 브라우저 API에 의존하는 싱글 페이지 앱(SPA) 제어
• 클릭, 타이핑, 키 입력과 같은 실제 사용자 상호작용
• 시각적 타이밍, 렌더링 동작, 성능 트레이스 분석

단순히 엔드포인트에서 HTML이나 JSON만 가져오면 되는 경우에는 HTTP 클라이언트만으로 충분할 수 있습니다. 하지만 실제 사용자가 브라우저에서 행동하는 것과 유사한 작업이 필요하다면 agent-browser가 훨씬 적합합니다.

agent-browser에서 사용할 Chrome 또는 Chromium은 어떻게 설치하나요?

먼저 npm, Homebrew, Cargo 중 하나로 CLI를 설치한 뒤 다음 명령을 실행합니다.

agent-browser install

이 명령은 agent-browser가 CDP를 통해 제어할 수 있는 호환 Chrome/Chromium 빌드를 다운로드하고 설정합니다. 새 버전이 릴리스되면 다음으로 업데이트합니다.

agent-browser upgrade

agent-browser가 이미 로그인된 브라우저 세션을 재사용할 수 있나요?

가능합니다. references/authentication.md에는 --remote-debugging-port 옵션으로 Chrome을 실행하고, 이미 로그인된 세션의 쿠키를 가져오는 방법이 설명되어 있습니다. 쿠키를 가져온 후에는 agent-browser state save로 인증 상태를 저장해 두었다가, 전체 로그인 플로를 반복하지 않고 나중에 다시 복원할 수 있습니다.

agent-browser는 CI나 자동화 테스트 환경에 적합한가요?

네. agent-browser는 Chrome/Chromium을 사용할 수 있는 환경이라면 CI 같은 자동화 환경에서도 잘 동작하는 CLI 도구입니다. 예를 들어 다음과 같이 활용할 수 있습니다.

• 테스트 스위트 내에서 엔드 투 엔드 플로를 실행
• 빌드 중 성능 트레이스를 수집
• 실패한 시나리오의 동영상을 녹화

CI에서는 빌드 이미지에 맞는 설치 방식(npm, Homebrew, Cargo)을 선택한 뒤, 셸 스크립트나 에이전트 프레임워크를 이용해 플로를 스크립팅하면 됩니다.

agent-browser는 복잡한 페이지를 다루는 AI 에이전트에 어떤 도움을 주나요?

agent-browser는 전체 DOM을 그대로 덤프하는 대신, 링크·버튼·입력 필드 등 중요한 요소에 안정적인 @refs를 부여한 컴팩트 스냅샷을 제공합니다. 이를 통해 토큰 사용량을 크게 줄이면서 AI 에이전트가 다음과 같은 작업을 쉽게 할 수 있습니다.

• 페이지 구조 파악
• ref를 기준으로 원하는 요소 선택
• 정확한 click, fill, press 명령 전송

references/snapshot-refs.md에는 refs 생성 방식, 갱신 타이밍, 견고한 자동화를 위한 베스트 프랙티스가 정리되어 있습니다.

agent-browser는 프록시 및 사내 네트워크 환경을 지원하나요?

지원합니다. CLI 플래그(--proxy) 또는 환경 변수(HTTP_PROXY, HTTPS_PROXY, ALL_PROXY)를 통해 HTTP, HTTPS, SOCKS 프록시를 설정할 수 있습니다. references/proxy-support.md에서 기본 설정 방법, 인증 프록시, 우회 규칙, 트러블슈팅 팁을 확인할 수 있습니다.

리포지토리에서 무엇부터 보면 좋을까요?

agent-browser를 더 깊이 이해하고 싶다면 다음 순서로 살펴보는 것을 추천합니다.

• 전체 개요와 빠른 시작은 SKILL.md
• 모든 명령과 옵션은 references/commands.md
• 인증·세션·스냅샷·프로파일링·영상 녹화 등은 references/authentication.md, references/session-management.md, references/snapshot-refs.md, references/profiling.md, references/video-recording.md
• 실제 워크플로 스크립트 예제는 templates/ 디렉터리 – 자신의 유즈 케이스에 맞춰 바로 수정·재사용할 수 있습니다.