agent-browser로 브라우저 자동화
CLI는 CDP를 통해 Chrome/Chromium을 직접 사용합니다. npm i -g agent-browser, brew install agent-browser, 또는 cargo install agent-browser로 설치하세요. agent-browser install을 실행하여 Chrome을 다운로드하세요.
핵심 워크플로우
모든 브라우저 자동화는 다음 패턴을 따릅니다:
- 이동:
agent-browser open <url> - 스냅샷:
agent-browser snapshot -i(요소 참조@e1,@e2등 획득) - 상호작용: 참조를 사용하여 클릭, 입력, 선택
- 재스냅샷: 이동 또는 DOM 변경 후, 새 참조 획득
agent-browser open https://example.com/form
agent-browser snapshot -i
# 출력: @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Submit"
agent-browser fill @e1 "[email protected]"
agent-browser fill @e2 "password123"
agent-browser click @e3
agent-browser wait --load networkidle
agent-browser snapshot -i # 결과 확인
명령어 체인닝
명령어는 단일 셸 호출에서 &&로 연결할 수 있습니다. 브라우저는 백그라운드 데몬을 통해 명령어 간에 지속되므로, 체인닝은 분리된 호출보다 안전하고 효율적입니다.
# 한 번의 호출로 열기 + 대기 + 스냅샷 체인
agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser snapshot -i
# 여러 상호작용 체인
agent-browser fill @e1 "[email protected]" && agent-browser fill @e2 "password123" && agent-browser click @e3
# 이동 및 캡처
agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser screenshot page.png
체인할 시기: 중간 명령의 출력을 먼저 읽을 필요가 없을 때 &&를 사용하세요(예: 열기 + 대기 + 스크린샷). 출력을 먼저 파싱해야 할 때는 명령어를 분리하여 실행하세요(예: 스냅샷으로 참조 발견 후 해당 참조로 상호작용).
인증 처리
로그인이 필요한 사이트를 자동화할 때는 다음 접근 방식 중 적합한 것을 선택하세요:
옵션 1: 사용자 브라우저에서 인증 가져오기 (일회성 작업에 가장 빠름)
# 사용자의 실행 중인 Chrome에 연결 (이미 로그인되어 있음)
agent-browser --auto-connect state save ./auth.json
# 해당 인증 상태 사용
agent-browser --state ./auth.json open https://app.example.com/dashboard
상태 파일에는 세션 토큰이 일반 텍스트로 포함되어 있습니다. .gitignore에 추가하고 더 이상 필요하지 않으면 삭제하세요. 저장 시 암호화하려면 AGENT_BROWSER_ENCRYPTION_KEY를 설정하세요.
옵션 2: 영구 프로필 (반복 작업에 가장 간단함)
# 첫 실행: 수동 또는 자동화로 로그인
agent-browser --profile ~/.myapp open https://app.example.com/login
# ... 자격 증명 입력, 제출 ...
# 이후 모든 실행: 이미 인증됨
agent-browser --profile ~/.myapp open https://app.example.com/dashboard
옵션 3: 세션 이름 (쿠키 + localStorage 자동 저장/복원)
agent-browser --session-name myapp open https://app.example.com/login
# ... 로그인 흐름 ...
agent-browser close # 상태 자동 저장
# 다음 번: 상태 자동 복원
agent-browser --session-name myapp open https://app.example.com/dashboard
옵션 4: 인증 볼트 (자격 증명 암호화 저장, 이름으로 로그인)
echo "$PASSWORD" | agent-browser auth save myapp --url https://app.example.com/login --username user --password-stdin
agent-browser auth login myapp
옵션 5: 상태 파일 (수동 저장/로드)
# 로그인 후:
agent-browser state save ./auth.json
# 이후 세션에서:
agent-browser state load ./auth.json
agent-browser open https://app.example.com/dashboard
OAuth, 2FA, 쿠키 기반 인증 및 토큰 갱신 패턴은 references/authentication.md를 참조하세요.
필수 명령어
# 이동
agent-browser open <url> # 이동 (별칭: goto, navigate)
agent-browser close # 브라우저 닫기
# 스냅샷
agent-browser snapshot -i # 참조가 있는 상호작용 요소 (권장)
agent-browser snapshot -i -C # 커서 상호작용 요소 포함 (onclick, cursor:pointer가 있는 div)
agent-browser snapshot -s "#selector" # CSS 선택자로 범위 지정
# 상호작용 (스냅샷의 @refs 사용)
agent-browser click @e1 # 요소 클릭
agent-browser click @e1 --new-tab # 클릭하고 새 탭에서 열기
agent-browser fill @e2 "text" # 지우고 텍스트 입력
agent-browser type @e2 "text" # 지우지 않고 텍스트 입력
agent-browser select @e1 "option" # 드롭다운 옵션 선택
agent-browser check @e1 # 체크박스 체크
agent-browser press Enter # 키 누르기
agent-browser keyboard type "text" # 현재 포커스에 입력 (선택자 없음)
agent-browser keyboard inserttext "text" # 키 이벤트 없이 삽입
agent-browser scroll down 500 # 페이지 스크롤
agent-browser scroll down 500 --selector "div.content" # 특정 컨테이너 내 스크롤
# 정보 가져오기
agent-browser get text @e1 # 요소 텍스트 가져오기
agent-browser get url # 현재 URL 가져오기
agent-browser get title # 페이지 제목 가져오기
agent-browser get cdp-url # CDP WebSocket URL 가져오기
# 대기
agent-browser wait @e1 # 요소 대기
agent-browser wait --load networkidle # 네트워크 유휴 상태 대기
agent-browser wait --url "**/page" # URL 패턴 대기
agent-browser wait 2000 # 밀리초 대기
agent-browser wait --text "Welcome" # 텍스트가 나타날 때까지 대기 (부분 일치)
agent-browser wait --fn "!document.body.innerText.includes('Loading...')" # 텍스트가 사라질 때까지 대기
agent-browser wait "#spinner" --state hidden # 요소가 사라질 때까지 대기
# 다운로드
agent-browser download @e1 ./file.pdf # 요소를 클릭하여 다운로드 트리거
agent-browser wait --download ./output.zip # 다운로드 완료 대기
agent-browser --download-path ./downloads open <url> # 기본 다운로드 디렉터리 설정
# 뷰포트 및 장치 에뮬레이션
agent-browser set viewport 1920 1080 # 뷰포트 크기 설정 (기본값: 1280x720)
agent-browser set viewport 1920 1080 2 # 2x 레티나 (동일 CSS 크기, 더 높은 해상도 스크린샷)
agent-browser set device "iPhone 14" # 장치 에뮬레이션 (뷰포트 + 사용자 에이전트)
# 캡처
agent-browser screenshot # 임시 디렉터리에 스크린샷
agent-browser screenshot --full # 전체 페이지 스크린샷
agent-browser screenshot --annotate # 번호가 매겨진 요소 레이블이 있는 주석 스크린샷
agent-browser screenshot --screenshot-dir ./shots # 사용자 정의 디렉터리에 저장
agent-browser screenshot --screenshot-format jpeg --screenshot-quality 80
agent-browser pdf output.pdf # PDF로 저장
# 클립보드
agent-browser clipboard read # 클립보드에서 텍스트 읽기
agent-browser clipboard write "Hello, World!" # 클립보드에 텍스트 쓰기
agent-browser clipboard copy # 현재 선택 항목 복사
agent-browser clipboard paste # 클립보드에서 붙여넣기
# Diff (페이지 상태 비교)
agent-browser diff snapshot # 현재 스냅샷과 마지막 스냅샷 비교
agent-browser diff snapshot --baseline before.txt # 현재 스냅샷과 저장된 파일 비교
agent-browser diff screenshot --baseline before.png # 시각적 픽셀 차이
agent-browser diff url <url1> <url2> # 두 페이지 비교
agent-browser diff url <url1> <url2> --wait-until networkidle # 사용자 정의 대기 전략
agent-browser diff url <url1> <url2> --selector "#main" # 요소로 범위 지정
일반적인 패턴
양식 제출
agent-browser open https://example.com/signup
agent-browser snapshot -i
agent-browser fill @e1 "Jane Doe"
agent-browser fill @e2 "[email protected]"
agent-browser select @e3 "California"
agent-browser check @e4
agent-browser click @e5
agent-browser wait --load networkidle
인증 볼트를 사용한 인증 (권장)
# 자격 증명을 한 번 저장 (AGENT_BROWSER_ENCRYPTION_KEY로 암호화)
# 권장: 셸 히스토리 노출을 피하기 위해 stdin으로 암호 전달
echo "pass" | agent-browser auth save github --url https://github.com/login --username user --password-stdin
# 저장된 프로필을 사용하여 로그인 (LLM이 암호를 볼 수 없음)
agent-browser auth login github
# 프로필 목록/표시/삭제
agent-browser auth list
agent-browser auth show github
agent-browser auth delete github
상태 지속성을 사용한 인증
# 한 번 로그인하고 상태 저장
agent-browser open https://app.example.com/login
agent-browser snapshot -i
agent-browser fill @e1 "$USERNAME"
agent-browser fill @e2 "$PASSWORD"
agent-browser click @e3
agent-browser wait --url "**/dashboard"
agent-browser state save auth.json
# 이후 세션에서 재사용
agent-browser state load auth.json
agent-browser open https://app.example.com/dashboard
세션 지속성
# 브라우저 재시작 간 쿠키와 localStorage 자동 저장/복원
agent-browser --session-name myapp open https://app.example.com/login
# ... 로그인 흐름 ...
agent-browser close # ~/.agent-browser/sessions/에 상태 자동 저장
# 다음 번, 상태가 자동으로 로드됨
agent-browser --session-name myapp open https://app.example.com/dashboard
# 저장된 상태 암호화
export AGENT_BROWSER_ENCRYPTION_KEY=$(openssl rand -hex 32)
agent-browser --session-name secure open https://app.example.com
# 저장된 상태 관리
agent-browser state list
agent-browser state show myapp-default.json
agent-browser state clear myapp
agent-browser state clean --older-than 7
데이터 추출
agent-browser open https://example.com/products
agent-browser snapshot -i
agent-browser get text @e5 # 특정 요소 텍스트 가져오기
agent-browser get text body > page.txt # 모든 페이지 텍스트 가져오기
# 파싱을 위한 JSON 출력
agent-browser snapshot -i --json
agent-browser get text @e1 --json
병렬 세션
agent-browser --session site1 open https://site-a.com
agent-browser --session site2 open https://site-b.com
agent-browser --session site1 snapshot -i
agent-browser --session site2 snapshot -i
agent-browser session list
기존 Chrome에 연결
# 원격 디버깅이 활성화된 실행 중인 Chrome 자동 발견
agent-browser --auto-connect open https://example.com
agent-browser --auto-connect snapshot
# 또는 명시적 CDP 포트 사용
agent-browser --cdp 9222 snapshot
색상 구성 (다크 모드)
# 플래그를 통한 영구 다크 모드 (모든 페이지와 새 탭에 적용)
agent-browser --color-scheme dark open https://example.com
# 또는 환경 변수 사용
AGENT_BROWSER_COLOR_SCHEME=dark agent-browser open https://example.com
# 또는 세션 중 설정 (이후 명령어에 지속됨)
agent-browser set media dark
뷰포트 및 반응형 테스트
# 사용자 정의 뷰포트 크기 설정 (기본값은 1280x720)
agent-browser set viewport 1920 1080
agent-browser screenshot desktop.png
# 모바일 너비 레이아웃 테스트
agent-browser set viewport 375 812
agent-browser screenshot mobile.png
# 레티나/HiDPI: 2x 픽셀 밀도에서 동일한 CSS 레이아웃
# 스크린샷은 논리적 뷰포트 크기로 유지되지만 콘텐츠는 더 높은 DPI로 렌더링됨
agent-browser set viewport 1920 1080 2
agent-browser screenshot retina.png
# 장치 에뮬레이션 (한 번에 뷰포트 + 사용자 에이전트 설정)
agent-browser set device "iPhone 14"
agent-browser screenshot device.png
scale 매개변수(3번째 인수)는 CSS 레이아웃을 변경하지 않고 window.devicePixelRatio를 설정합니다. 레티나 렌더링을 테스트하거나 더 높은 해상도의 스크린샷을 캡처할 때 사용하세요.
시각적 브라우저 (디버깅)
agent-browser --headed open https://example.com
agent-browser highlight @e1 # 요소 강조 표시
agent-browser inspect # 활성 페이지에 대해 Chrome DevTools 열기
agent-browser record start demo.webm # 세션 녹화
agent-browser profiler start # Chrome DevTools 프로파일링 시작
agent-browser profiler stop trace.json # 중지 및 프로필 저장 (경로 선택 사항)
환경 변수를 통해 헤드 모드를 활성화하려면 AGENT_BROWSER_HEADED=1을 사용하세요. 브라우저 확장 프로그램은 헤드 및 헤드리스 모드 모두에서 작동합니다.
로컬 파일 (PDF, HTML)
# file:// URL로 로컬 파일 열기
agent-browser --allow-file-access open file:///path/to/document.pdf
agent-browser --allow-file-access open file:///path/to/page.html
agent-browser screenshot output.png
iOS 시뮬레이터 (Mobile Safari)
# 사용 가능한 iOS 시뮬레이터 목록
agent-browser device list
# 특정 장치에서 Safari 실행
agent-browser -p ios --device "iPhone 16 Pro" open https://example.com
# 데스크톱과 동일한 워크플로우 - 스냅샷, 상호작용, 재스냅샷
agent-browser -p ios snapshot -i
agent-browser -p ios tap @e1 # 탭 (클릭의 별칭)
agent-browser -p ios fill @e2 "text"
agent-browser -p ios swipe up # 모바일 특화 제스처
# 스크린샷 촬영
agent-browser -p ios screenshot mobile.png
# 세션 종료 (시뮬레이터 종료)
agent-browser -p ios close
요구 사항: macOS에 Xcode, Appium (npm install -g appium && appium driver install xcuitest)
실제 장치: 사전 구성된 경우 실제 iOS 장치에서도 작동합니다. xcrun xctrace list devices의 UDID와 함께 --device "<UDID>"를 사용하세요.
보안
모든 보안 기능은 옵트인입니다. 기본적으로 agent-browser는 탐색, 작업 또는 출력에 어떠한 제한도 두지 않습니다.
콘텐츠 경계 (AI 에이전트에 권장)
--content-boundaries를 활성화하면 페이지에서 가져온 출력을 마커로 감싸서 LLM이 도구 출력과 신뢰할 수 없는 페이지 콘텐츠를 구분하는 데 도움을 줍니다:
export AGENT_BROWSER_CONTENT_BOUNDARIES=1
agent-browser snapshot
# 출력:
# --- AGENT_BROWSER_PAGE_CONTENT nonce=<hex> origin=https://example.com ---
# [접근성 트리]
# --- END_AGENT_BROWSER_PAGE_CONTENT nonce=<hex> ---
도메인 허용 목록
탐색을 신뢰할 수 있는 도메인으로 제한합니다. *.example.com과 같은 와일드카드는 베어 도메인 example.com도 일치시킵니다. 허용되지 않은 도메인에 대한 하위 리소스 요청, WebSocket 및 EventSource 연결도 차단됩니다. 대상 페이지가 의존하는 CDN 도메인을 포함하세요:
export AGENT_BROWSER_ALLOWLIST="https://example.com,https://*.example.com,https://cdn.example.com"
agent-browser open https://example.com/login
허용 목록이 설정되면 허용 목록의 URL로만 이동할 수 있습니다. 하위 리소스(스크립트, 스타일, 이미지 등)도 차단됩니다.
읽기 전용 모드
읽기 전용 모드는 모든 상호작용 명령어(클릭, 입력, 선택, 체크 등)를 차단합니다. 탐색, 스크린샷, 텍스트 가져오기 등은 계속 작동합니다:
export AGENT_BROWSER_READONLY=1
agent-browser open https://example.com
agent-browser snapshot -i
agent-browser click @e1 # 오류: 읽기 전용 모드에서는 상호작용이 허용되지 않음
설치
# npm으로 설치
npm install -g agent-browser
# Homebrew로 설치
brew install agent-browser
# Cargo로 설치
cargo install agent-browser
# Chrome 다운로드 (agent-browser가 설치한 Chrome을 사용하려면)
agent-browser install
agent-browser install은 별도의 Chrome/Chromium 바이너리를 다운로드하여 npx agent-browser open과 같은 사용과 충돌하지 않도록 합니다.
AGENT_BROWSER_CHROME 환경 변수를 설정하거나 agent-browser set chrome /path/to/chrome을 실행하여 경로를 구성할 수 있습니다.
도움말
# 모든 명령어 및 옵션 보기
agent-browser --help
# 특정 명령어에 대한 도움말
agent-browser open --help