agent-browser를 사용한 브라우저 자동화
CLI는 CDP(Chrome DevTools Protocol)를 통해 Chrome/Chromium을 직접 사용합니다. npm i -g agent-browser, brew install agent-browser, 또는 cargo install agent-browser로 설치하세요. agent-browser install을 실행하여 Chrome을 다운로드합니다. 기존에 설치된 Chrome, Brave, Playwright 및 Puppeteer 설치가 자동으로 감지됩니다. agent-browser upgrade를 실행하여 최신 버전으로 업데이트하세요.
핵심 워크플로우
모든 브라우저 자동화는 다음 패턴을 따릅니다:
- 이동:
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 2000
agent-browser snapshot -i # 결과 확인
명령어 체이닝
명령어는 단일 셸 호출에서 &&를 사용하여 체이닝할 수 있습니다. 브라우저는 백그라운드 데몬을 통해 명령어 간에 유지되므로, 별도 호출보다 체이닝이 더 안전하고 효율적입니다.
# 한 번의 호출로 열기 + 스냅샷 체이닝 (open은 페이지 로드가 완료될 때까지 대기)
agent-browser open https://example.com && 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 screenshot
체이닝 시점: 중간 명령어의 출력을 읽지 않고 진행해도 될 때 &&를 사용하세요(예: 열기 + 대기 + 스크린샷). 먼저 출력을 파싱해야 할 때는 명령어를 개별적으로 실행하세요(예: 스냅샷으로 참조를 찾은 후 해당 참조를 사용하여 상호작용).
인증 처리
로그인이 필요한 사이트를 자동화할 때는 적합한 방법을 선택하세요:
옵션 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: Chrome 프로필 재사용 (설정 불필요)
# 사용 가능한 Chrome 프로필 목록 보기
agent-browser profiles
# 사용자의 기존 Chrome 로그인 상태 재사용
agent-browser --profile Default open https://gmail.com
옵션 3: 영구 프로필 (반복 작업용)
# 첫 실행: 수동 또는 자동화로 로그인
agent-browser --profile ~/.myapp open https://app.example.com/login
# ... 자격 증명 입력, 제출 ...
# 이후 모든 실행: 이미 인증됨
agent-browser --profile ~/.myapp open https://app.example.com/dashboard
옵션 4: 세션 이름 (쿠키 + 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
옵션 5: 인증 저장소 (자격 증명 암호화 저장, 이름으로 로그인)
echo "$PASSWORD" | agent-browser auth save myapp --url https://app.example.com/login --username user --password-stdin
agent-browser auth login myapp
auth login은 load로 이동한 후 로그인 폼 선택자가 나타날 때까지 기다렸다가 입력/클릭을 수행하므로, 지연되는 SPA 로그인 화면에서 더 안정적입니다.
옵션 6: 상태 파일 (수동 저장/로드)
# 로그인 후:
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를 참조하세요.
필수 명령어
# 배치: 2개 이상의 순차 명령어에는 항상 batch 사용. 명령어는 순서대로 실행됩니다.
agent-browser batch "open https://example.com" "snapshot -i"
agent-browser batch "open https://example.com" "screenshot"
agent-browser batch "click @e1" "wait 1000" "screenshot"
# 탐색
agent-browser open <url> # 이동 (별칭: goto, navigate)
agent-browser close # 브라우저 닫기
agent-browser close --all # 모든 활성 세션 닫기
# 스냅샷
agent-browser snapshot -i # 참조가 포함된 인터랙티브 요소 (권장)
agent-browser snapshot -i --urls # 링크의 href URL 포함
agent-browser snapshot -s "#selector" # CSS 선택자로 범위 지정
# 상호작용 (스냅샷의 @ref 사용)
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 2000 # 밀리초 대기
agent-browser wait --url "**/page" # URL 패턴이 일치할 때까지 대기
agent-browser wait --text "Welcome" # 텍스트가 나타날 때까지 대기 (부분 문자열 일치)
agent-browser wait --load networkidle # 네트워크가 유휴 상태가 될 때까지 대기 (주의: Pitfalls 참조)
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 tab list # 열린 모든 탭 목록
agent-browser tab new # 빈 새 탭 열기
agent-browser tab new https://example.com # URL을 새 탭에서 열기
agent-browser tab 2 # 인덱스(0부터 시작)로 탭 전환
agent-browser tab close # 현재 탭 닫기
agent-browser tab close 2 # 인덱스로 탭 닫기
# 네트워크
agent-browser network requests # 추적된 요청 확인
agent-browser network requests --type xhr,fetch # 리소스 유형으로 필터링
agent-browser network requests --method POST # HTTP 메서드로 필터링
agent-browser network requests --status 2xx # 상태 코드로 필터링 (200, 2xx, 400-499)
agent-browser network request <requestId> # 전체 요청/응답 세부 정보 보기
agent-browser network route "**/api/*" --abort # 일치하는 요청 차단
agent-browser network har start # HAR 녹화 시작
agent-browser network har stop ./capture.har # HAR 녹화 중지 및 파일 저장
# 뷰포트 및 기기 에뮬레이션
agent-browser set viewport 1920 1080 # 뷰포트 크기 설정 (기본값: 1280x720)
agent-browser set viewport 1920 1080 2 # 2배 레티나 (동일 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 stream enable # 자동 선택된 포트에서 런타임 WebSocket 스트리밍 시작
agent-browser stream enable --port 9223 # 특정 localhost 포트 바인딩
agent-browser stream status # 활성화 상태, 포트, 연결 및 화면 캐스팅 확인
agent-browser stream disable # 런타임 스트리밍 중지 및 .stream 메타데이터 파일 제거
# 클립보드
agent-browser clipboard read # 클립보드에서 텍스트 읽기
agent-browser clipboard write "Hello, World!" # 클립보드에 텍스트 쓰기
agent-browser clipboard copy # 현재 선택 복사
agent-browser clipboard paste # 클립보드에서 붙여넣기
# 대화상자 (alert, confirm, prompt, beforeunload)
# 기본적으로 alert 및 beforeunload 대화상자는 자동으로 수락되어 에이전트를 차단하지 않습니다.
# confirm 및 prompt 대화상자는 여전히 명시적인 처리가 필요합니다.
# 자동 처리를 비활성화하려면 --no-auto-dialog (또는 AGENT_BROWSER_NO_AUTO_DIALOG=1)를 사용하세요.
agent-browser dialog accept # 대화상자 수락
agent-browser dialog accept "my input" # 프롬프트 대화상자를 텍스트로 수락
agent-browser dialog dismiss # 대화상자 해제/취소
agent-browser dialog status # 대화상자가 현재 열려 있는지 확인
# 차이점 비교 (페이지 상태 비교)
agent-browser diff snapshot # 현재 vs 마지막 스냅샷 비교
agent-browser diff snapshot --baseline before.txt # 현재 vs 저장된 파일 비교
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" # 요소로 범위 지정
# 채팅 (AI 자연어 제어)
agent-browser chat "open google.com and search for cats" # 단일 명령 실행
agent-browser chat # 대화형 REPL 모드
agent-browser -q chat "summarize this page" # 조용한 모드 (텍스트만, 도구 호출 없음)
agent-browser -v chat "fill in the login form" # 자세한 모드 (명령어 출력 표시)
agent-browser --model openai/gpt-4o chat "take a screenshot" # 모델 재정의
스트리밍
모든 세션은 OS가 할당한 포트에서 WebSocket 스트림 서버를 자동으로 시작합니다. agent-browser stream status를 사용하여 바인딩된 포트와 연결 상태를 확인하세요. stream disable을 사용하여 종료하고, stream enable --port <port>로 특정 포트에서 다시 활성화할 수 있습니다.
배치 실행
2개 이상의 명령어를 순차적으로 실행할 때는 항상 batch를 사용하세요. Batch는 명령어를 순서대로 실행하므로, 종속 명령어(예: 이동 후 스크린샷)가 올바르게 작동합니다. 각 따옴표로 묶인 인수는 별도의 명령어입니다.
# 이동 후 스냅샷
agent-browser batch "open https://example.com" "snapshot -i"
# 이동, 스냅샷, 스크린샷을 한 번에
agent-browser batch "open https://example.com" "snapshot -i" "screenshot"
# 클릭, 대기, 스크린샷
agent-browser batch "click @e1" "wait 1000" "screenshot"
# 첫 번째 오류에서 중지하려면 --bail 사용
agent-browser batch --bail "open https://example.com" "click @e1" "screenshot"
다음 명령어를 결정하기 전에 출력을 읽어야 하는 경우에만 단일 명령어(batch 아님)를 사용하세요. 예를 들어, 클릭할 항목을 결정하기 위해 참조를 읽어야 하는 경우 snapshot -i를 단일 명령어로 실행해야 합니다. 스냅샷을 읽은 후에는 나머지 단계를 batch로 묶으세요.
프로그래밍 방식 사용을 위한 stdin 모드도 지원됩니다:
echo '[["open","https://example.com"],["screenshot"]]' | agent-browser batch --json
agent-browser batch --bail < commands.json
효율성 전략
이러한 패턴은 도구 호출과 토큰 사용량을 최소화합니다.
--urls를 사용하여 재탐색 방지. 페이지의 링크를 방문해야 할 때는 snapshot -i --urls를 사용하여 모든 href URL을 미리 가져오세요. 그런 다음 참조를 클릭하고 다시 탐색하는 대신 각 URL을 직접 open하세요.
한 번 스냅샷하고 여러 번 작업 수행. 동일한 페이지를 다시 스냅샷하지 마세요. 단일 스냅샷에서 필요한 모든 정보(참조, URL, 텍스트)를 추출한 다음 나머지 작업을 batch로 묶으세요.
다중 페이지 워크플로우 (예: "N개 사이트 방문하여 각각 스크린샷"):
# 1. 한 번의 호출로 모든 URL 가져오기
agent-browser batch "open https://news.ycombinator.com" "snapshot -i --urls"
# 출력을 읽어 URL을 추출한 후 각각 직접 방문:
# 2. 대상 사이트당 하나의 batch
agent-browser batch "open https://github.com/example/repo" "screenshot"
agent-browser batch "open https://example.com/article" "screenshot"
agent-browser batch "open https://other.com/page" "screenshot"
이 방법은 14번 이상의 도구 호출 대신 4번의 도구 호출을 사용합니다. 사이트 사이를 방문할 때 목록 페이지로 다시 돌아가지 마세요.
일반적인 패턴
양식 제출
# 이동 및 양식 구조 가져오기
agent-browser batch "open https://example.com/signup" "snapshot -i"
# 스냅샷 출력을 읽어 양식 참조 식별 후 입력 및 제출
agent-browser batch "fill @e1 \"Jane Doe\"" "fill @e2 \"[email protected]\"" "select @e3 \"California\"" "check @e4" "click @e5" "wait 2000"
인증 저장소를 사용한 인증 (권장)
# 자격 증명을 한 번 저장 (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