Jamie-BitFlight/claude_skills

agent-browser를 이용한 브라우저 자동화

핵심 워크플로

모든 브라우저 자동화는 다음 패턴을 따릅니다:

1. 이동: agent-browser open <url>
2. 스냅샷: agent-browser snapshot -i (@e1, @e2와 같은 요소 참조 획득)
3. 상호작용: 참조를 사용하여 클릭, 입력, 선택
4. 다시 스냅샷: 탐색 또는 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

체인 연결 시점: 중간 명령의 출력을 읽을 필요가 없을 때 &&를 사용하세요 (예: 열기 + 대기 + 스크린샷). 먼저 출력을 파싱해야 하는 경우 명령을 개별적으로 실행하세요 (예: 스냅샷으로 참조를 찾은 후, 해당 참조로 상호작용).

필수 명령어

# 탐색
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 선택자로 범위 지정

# 상호작용 (스냅샷의 @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 scroll down 500         # 페이지 스크롤

# 정보 가져오기
agent-browser get text @e1            # 요소 텍스트 가져오기
agent-browser get url                 # 현재 URL 가져오기
agent-browser get title               # 페이지 제목 가져오기

# 대기
agent-browser wait @e1                # 요소 대기
agent-browser wait --load networkidle # 네트워크 유휴 상태 대기
agent-browser wait --url "**/page"    # URL 패턴 대기
agent-browser wait 2000               # 밀리초 대기

# 캡처
agent-browser screenshot              # 임시 디렉토리에 스크린샷 저장
agent-browser screenshot --full       # 전체 페이지 스크린샷
agent-browser screenshot --annotate   # 번호가 매겨진 요소 레이블이 있는 주석 스크린샷
agent-browser pdf output.pdf          # PDF로 저장

# 차이 비교 (페이지 상태 비교)
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 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 --headed open https://example.com
agent-browser highlight @e1          # 요소 강조 표시
agent-browser record start demo.webm # 세션 녹화
agent-browser profiler start         # Chrome DevTools 프로파일링 시작
agent-browser profiler stop trace.json # 중지 및 프로필 저장 (경로 선택 사항)

로컬 파일 (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 기기에서 작동합니다. --device "<UDID>"를 사용하세요. UDID는 xcrun xctrace list devices에서 얻을 수 있습니다.

차이 비교 (변경 확인)

작업을 수행한 후 diff snapshot을 사용하여 의도한 효과가 있었는지 확인하세요. 이 명령은 현재 접근성 트리를 세션에서 마지막으로 찍은 스냅샷과 비교합니다.

# 일반적인 워크플로: 스냅샷 -> 작업 -> 차이
agent-browser snapshot -i          # 기준 스냅샷 찍기
agent-browser click @e2            # 작업 수행
agent-browser diff snapshot        # 변경 사항 확인 (마지막 스냅샷과 자동 비교)

시각적 회귀 테스트 또는 모니터링을 위해:

# 기준 스크린샷 저장 후 나중에 비교
agent-browser screenshot baseline.png
# ... 시간이 지나거나 변경 사항이 적용된 후 ...
agent-browser diff screenshot --baseline baseline.png

# 스테이징 vs 프로덕션 비교
agent-browser diff url https://staging.example.com https://prod.example.com --screenshot

diff snapshot 출력은 git diff와 유사하게 +는 추가, -는 제거를 나타냅니다. diff screenshot은 변경된 픽셀이 빨간색으로 강조 표시된 차이 이미지와 불일치 비율을 생성합니다.

타임아웃 및 느린 페이지

로컬 브라우저의 기본 Playwright 타임아웃은 60초입니다. 느린 웹사이트나 큰 페이지의 경우 기본 타임아웃에 의존하지 말고 명시적 대기를 사용하세요:

# 네트워크 활동이 안정될 때까지 대기 (느린 페이지에 가장 적합)
agent-browser wait --load networkidle

# 특정 요소가 나타날 때까지 대기
agent-browser wait "#content"
agent-browser wait @e1

# 특정 URL 패턴까지 대기 (리디렉션 후 유용)
agent-browser wait --url "**/dashboard"

# JavaScript 조건까지 대기
agent-browser wait --fn "document.readyState === 'complete'"

# 최후의 수단으로 고정 시간(밀리초) 대기
agent-browser wait 5000

일관되게 느린 웹사이트를 다룰 때는 open 후에 wait --load networkidle을 사용하여 페이지가 완전히 로드된 후 스냅샷을 찍도록 하세요. 특정 요소가 느리게 렌더링되는 경우 wait <selector> 또는 wait @ref로 직접 기다리세요.

세션 관리 및 정리

여러 에이전트 또는 자동화 작업을 동시에 실행할 때는 항상 명명된 세션을 사용하여 충돌을 방지하세요:

# 각 에이전트는 자체 격리된 세션을 가짐
agent-browser --session agent1 open site-a.com
agent-browser --session agent2 open site-b.com

# 활성 세션 확인
agent-browser session list

작업이 끝나면 항상 브라우저 세션을 닫아 프로세스 누수를 방지하세요:

agent-browser close                    # 기본 세션 닫기
agent-browser --session agent1 close   # 특정 세션 닫기

이전 세션이 제대로 닫히지 않은 경우 데몬이 계속 실행 중일 수 있습니다. 새 작업을 시작하기 전에 agent-browser close를 사용하여 정리하세요.

참조 수명 주기 (중요)

참조(@e1, @e2 등)는 페이지가 변경되면 무효화됩니다. 다음 후에는 항상 다시 스냅샷을 찍으세요:

• 탐색하는 링크나 버튼 클릭
• 양식 제출
• 동적 콘텐츠 로드 (드롭다운, 모달)

agent-browser click @e5              # 새 페이지로 이동
agent-browser snapshot -i            # 반드시 다시 스냅샷
agent-browser click @e1              # 새 참조 사용

주석 스크린샷 (비전 모드)

--annotate를 사용하여 상호작용 가능한 요소 위에 번호가 매겨진 레이블이 오버레이된 스크린샷을 찍으세요. 각 레이블 [N]은 참조 @eN에 매핑됩니다. 또한 참조를 캐시하므로 별도의 스냅샷 없이 요소와 즉시 상호작용할 수 있습니다.

agent-browser screenshot --annotate
# 출력에는 이미지 경로와 범례가 포함됩니다:
#   [1] @e1 button "Submit"
#   [2] @e2 link "Home"
#   [3] @e3 textbox "Email"
agent-browser click @e2              # 주석 스크린샷의 참조를 사용하여 클릭

다음과 같은 경우 주석 스크린샷을 사용하세요:

• 페이지에 레이블이 없는 아이콘 버튼이나 시각적 전용 요소가 있는 경우
• 시각적 레이아웃이나 스타일을 확인해야 하는 경우
• 캔버스 또는 차트 요소가 있는 경우 (텍스트 스냅샷에 보이지 않음)
• 요소 위치에 대한 공간적 추론이 필요한 경우

시맨틱 로케이터 (참조 대안)

참조를 사용할 수 없거나 신뢰할 수 없는 경우 시맨틱 로케이터를 사용하세요:

agent-browser find text "Sign In" click
agent-browser find label "Email" fill "[email protected]"
agent-browser find role button click --name "Submit"
agent-browser find placeholder "Search" type "query"
agent-browser find testid "submit-btn" click

JavaScript 평가 (eval)

eval을 사용하여 브라우저 컨텍스트에서 JavaScript를 실행하세요. 셸 따옴표는 복잡한 표현식을 손상시킬 수 있습니다. 문제를 피하려면 --stdin 또는 -b를 사용하세요.

# 간단한 표현식은 일반 따옴표로 작동
agent-browser eval 'document.title'
agent-browser eval 'document.querySelectorAll("img").length'

# 복잡한 JS: heredoc과 함께 --stdin 사용 (권장)
agent-browser eval --stdin <<'EVALEOF'
JSON.stringify(
  Array.from(document.querySelectorAll("img"))
    .filter(i => !i.alt)
    .map(i => ({ src: i.src.split("/").pop(), width: i.width }))
)
EVALEOF

# 대안: base64 인코딩 (모든 셸 이스케이프 문제 방지)
agent-browser eval -b "$(echo -n 'Array.from(document.querySelectorAll("a")).map(a => a.href)' | base64)"

이것이 중요한 이유: 셸이 명령을 처리할 때 내부 큰따옴표, ! 문자 (히스토리 확장), 백틱, $()가 agent-browser에 도달하기 전에 JavaScript를 손상시킬 수 있습니다. --stdin 및 -b 플래그는 셸 해석을 완전히 우회합니다.

경험 법칙:

• 한 줄, 중첩 따옴표 없음 -> 작은따옴표로 일반 eval 'expression' 사용 가능
• 중첩 따옴표, 화살표 함수, 템플릿 리터럴 또는 여러 줄 -> eval --stdin <<'EVALEOF' 사용
• 프로그래밍 방식/생성된 스크립트 -> base64로 eval -b 사용

설정 파일

프로젝트 루트에 agent-browser.json을 생성하여 영구 설정을 지정하세요:

{
  "headed": true,
  "proxy": "http://localhost:8080",
  "profile": "./browser-data"
}

우선 순위 (낮음에서 높음): ~/.agent-browser/config.json < ./agent-browser.json < 환경 변수 < CLI 플래그. 사용자 정의 설정 파일의 경우 --config <path> 또는 AGENT_BROWSER_CONFIG 환경 변수를 사용하세요 (파일이 없거나 유효하지 않으면 오류와 함께 종료). 모든 CLI 옵션은 camelCase 키에 매핑됩니다 (예: --executable-path -> "executablePath"). 부울 플래그는 true/false 값을 허용합니다 (예: --headed false는 설정을 재정의함). 사용자 및 프로젝트 설정의 확장은 병합되며, 대체되지 않습니다.

심층 문서

참조 문서	사용 시기
references/commands.md	모든 옵션이 포함된 전체 명령 참조
references/header.md	헤더리스 브라우저 및 상태 유지 참조
references/diff.md	diff 명령에 대한 자세한 내용
references/session.md	고급 세션 관리
references/ios.md	iOS 시뮬레이터 자동화