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 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 --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

auth login은 load로 이동한 후 로그인 양식 선택자가 나타날 때까지 기다렸다가 입력/클릭을 수행하므로, 지연되는 SPA 로그인 화면에서 더 안정적입니다.

옵션 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 close --all             # 모든 활성 세션 닫기

# 스냅샷
agent-browser snapshot -i             # 참조가 있는 대화형 요소 (권장)
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 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        # 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 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 dialog accept              # 대화상자 수락
agent-browser dialog accept "my input"   # 프롬프트 대화상자에 텍스트 입력하여 수락
agent-browser dialog dismiss             # 대화상자 거부/취소
agent-browser dialog status              # 대화상자가 현재 열려 있는지 확인

# 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"  # 요소로 범위 지정

스트리밍

모든 세션은 OS에서 할당한 포트에서 WebSocket 스트림 서버를 자동으로 시작합니다. agent-browser stream status를 사용하여 바인딩된 포트와 연결 상태를 확인하세요. stream disable로 서버를 종료하고, stream enable --port <port>로 특정 포트에서 다시 활성화할 수 있습니다.

일괄 실행

JSON 문자열 배열의 배열을 batch에 파이핑하여 단일 호출에서 여러 명령어를 실행할 수 있습니다. 이는 다단계 워크플로우를 실행할 때 명령어별 프로세스 시작 오버헤드를 방지합니다.

echo '[
  ["open", "https://example.com"],
  ["snapshot", "-i"],
  ["click", "@e1"],
  ["screenshot", "result.png"]
]' | agent-browser batch --json

# 첫 번째 오류에서 중지
agent-browser batch --bail < commands.json

중간 출력에 의존하지 않는 알려진 명령어 시퀀스가 있을 때 batch를 사용하세요. 단계 사이에 출력을 파싱해야 할 때(예: 스냅샷으로 참조를 찾은 후 상호작용)는 개별 명령어나 && 체이닝을 사용하세요.

일반적인 패턴

양식 제출

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

auth login은 상호작용 전에 사용자 이름/비밀번호/제출 선택자가 나타날 때까지 기다리며, 기본 작업 시간 제한에 연결된 시간 제한이 있습니다.

상태 유지를 사용한 인증

# 한 번 로그인하고 상태 저장
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

iframe 작업

iframe 콘텐츠는 스냅샷에 자동으로 인라인됩니다. iframe 내부의 참조는 프레임 컨텍스트를 전달하므로 직접 상호작용할 수 있습니다.

agent-browser open https://example.com/checkout
agent-browser snapshot -i
# @e1 [heading] "Checkout"
# @e2 [Iframe] "payment-frame"
#   @e3 [input] "Card number"
#   @e4 [input] "Expiry"
#   @e5 [button] "Pay"

# 직접 상호작용 — 프레임 전환 불필요
agent-browser fill @e3 "4111111111111111"
agent-browser fill @e4 "12/28"
agent-browser click @e5

# 하나의 iframe으로 스냅샷 범위 지정:
agent-browser frame @e2
agent-browser snapshot -i         # iframe 콘텐츠만
agent-browser frame main          # 메인 프레임으로 돌아가기

데이터 추출

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

자동 연결은 DevToolsActivePort, 일반적인 디버깅 포트(9222, 9229)를 통해 Chrome을 발견하고, HTTP 기반 CDP 발견이 실패하면 직접 WebSocket 연결로 대체됩니다.

색 구성표 (다크 모드 / 라이트 모드)

# 기본값: 시스템 설정을 따름 (prefers-color-scheme 미디어 쿼리)
agent-browser open https://example.com

# 라이트 모드 강제
agent-browser set color-scheme light
agent-browser snapshot -i

# 다크 모드 강제
agent-browser set color-scheme dark
agent-browser snapshot -i

참고: 이는 브라우저 자체가 선호하는 색 구성표를 재정의합니다. 일부 사이트는 자체적으로 다크 모드 전환을 제공합니다. set color-scheme은 prefers-color-scheme CSS 미디어 쿼리와 color-scheme 메타 태그에 영향을 미칩니다. 사이트 제어(예: 사이트 자체 dark mode 버튼)는 존중하지 않으며, agent-browser가 렌더링하는 방식만 변경합니다.

JavaScript 디버깅

# 로깅 강화
agent-browser open https://example.com
agent-browser console start           # console.log, 경고, 오류 캡처 시작
agent-browser console start --verbose # 네트워크 리소스 힌트 포함
agent-browser console get             # 지금까지 캡처된 메시지 보기
agent-browser console stop            # 콘솔 캡처 중지

# 페이지에서 JavaScript 평가
agent-browser evaluate document.title    # 표현식 평가 및 결과 반환
agent-browser evaluate --await fetch('/api/data').then(r => r.json())  # 비동기 함수 평가
agent-browser evaluate "someGlobalVar" --json  # 객체를 JSON으로 직렬화
agent-browser evaluate --file ./script.js  # 파일에서 스크립트 로드 및 실행
agent-browser evaluate --file ./script.js --args arg1 arg2  # 함수 인자 전달

evaluate는 페이지 컨텍스트 내에서 표현식을 실행하고 직렬화된 결과를 반환합니다. DOM 요소나 함수 참조와 같은 직렬화할 수 없는 값은 {}로 반환됩니다. 이러한 객체를 검사하려면 --json을 사용하세요.

로깅 및 구성

# 상세 로깅
agent-browser --verbose open https://example.com
agent-browser --verbose snapshot -i

# 디버그 로깅 (가장 장황함)
agent-browser --debug open https://example.com

# 헤드리스 모드 (브라우저 UI 없음, CI/CD에 적합)
agent-browser --headless open https://example.com
agent-browser --headless screenshot

AGENT_BROWSER_VERBOSE=true AGENT_BROWSER_HEADLESS=true와 같은 환경 변수를 사용하여 구성할 수도 있습니다.

페이지 찾기 (Wait 스타일리스트의 대안)

# 요소가 나타날 때까지 기다리지 않고 찾기
agent-browser find @e1                    # 단일 요소 찾기 (찾지 못하면 오류 발생)
agent-browser find @e1 --wait 5000        # 최대 5초까지 요소를 기다리며 찾기
agent-browser find @e1 --optional         # 요소가 없어도 오류 없이 반환
agent-browser find @e1 --state attached   # 특정 DOM 상태 확인

find는 스냅샷 참조를 DOM 노드로 확인합니다. 플래그 없이 사용하면 요소가 현재 존재하지 않을 때 즉시 오류가 발생합니다. --wait는 재시도 메커니즘을 추가합니다. --optional은 오류 없이 실패하여 null을 반환합니다. --state는 attached, detached, visible, hidden을 지원합니다.

확장 기능

확장은 설치된 Chrome 프로필에서 작동하므로, agent-browser install Chrome을 사용하는 경우 수동으로 설치해야 합니다. 프로필(agent-browser --profile ...)을 사용하는 경우, 확장을 한 번 설치하면 프로필이 유지되는 한 계속 사용할 수 있습니다.

기타

# 현재 브라우저 세션의 상태 지우기
agent-browser clear
agent-browser clear --cookies
agent-browser clear --local-storage
agent-browser clear --cache

# 저장된 상태 및 구성 보기
agent-browser info

이 문서는 agent-browser CLI 참조를 기반으로 합니다. 최신 업데이트 및 전체 문서는 agent-browser 문서를 참조하세요.

lunrenyi/ai-agent.sh

ai-agent.sh란 무엇인가요?

즐겨 사용하는 AI에게 물어보기

문서