스크래핑

snapshot 명령은 요소 상호작용을 위한 참조를 포함하는 압축된 접근성 트리(접근성 트리)를 반환합니다.

옵션

출력 크기를 줄이기 위해 필터링:

agent-browser snapshot                    # 전체 접근성 트리
agent-browser snapshot -i                 # 상호작용 가능한 요소만 (권장)
agent-browser snapshot -i -C              # 커서로 상호작용 가능한 요소 포함
agent-browser snapshot -c                 # 압축 모드 (비어 있는 요소 제거)
agent-browser snapshot -d 3               # 깊이를 최대 3 레벨로 제한
agent-browser snapshot -s "#main"         # CSS 선택자 범위 지정
agent-browser snapshot -i -c -d 5         # 옵션 조합

옵션	설명
`-i, --interactive`	상호작용 가능한 요소만 (버튼, 링크, 입력란)
`-C, --cursor`	커서로 상호작용 가능한 요소 포함 (cursor:pointer, onclick, tabindex)
`-c, --compact`	비어 있는 구조적 요소 제거
`-d, --depth`	트리 깊이 제한
`-s, --selector`	CSS 선택자 범위 지정

커서로 상호작용 가능한 요소

많은 현대 웹 애플리케이션은 표준 버튼이나 링크 대신 커스텀 클릭 가능한 요소(예: div, span)를 사용합니다.
-C 플래그는 다음 기준으로 이러한 요소를 탐지합니다:

cursor: pointer CSS 스타일
onclick 속성 또는 이벤트 핸들러
tabindex 속성 (키보드 포커스 가능)

agent-browser snapshot -i -C
# 출력에 포함됨:
# @e1 [button] "제출"
# @e2 [link] "자세히 보기"
# 커서로 상호작용 가능한 요소:
# @e3 [clickable] "메뉴 항목" [cursor:pointer, onclick]
# @e4 [clickable] "카드" [cursor:pointer]

출력 형식

기본 텍스트 출력은 압축되어 있으며, 인공지능에 친화적입니다:

agent-browser snapshot -i
# 출력:
# @e1 [heading] "예제 도메인" [level=1]
# @e2 [button] "제출"
# @e3 [input type="email"] placeholder="이메일"
# @e4 [link] "자세히 보기"

참조 사용

스크래핑에서 얻은 참조는 명령어와 직접 매핑됩니다:

agent-browser click @e2      # 제출 버튼 클릭
agent-browser fill @e3 "[email protected]"  # 이메일 입력란 채우기
agent-browser get text @e1        # 제목 텍스트 가져오기

참조 생명주기

페이지가 변경되면 참조가 무효화됩니다. 항상 이동 후 또는 DOM 업데이트 후 다시 스크래핑하세요:

agent-browser click @e4      # 새 페이지로 이동
agent-browser snapshot -i    # 최신 참조 획득
agent-browser click @e1      # 새로운 참조 사용

주석이 추가된 스크린샷

텍스트 스크래핑과 함께 시각적 맥락을 제공하기 위해, screenshot --annotate를 사용하여 상호작용 가능한 요소 위에 번호가 붙은 레이블을 겹쳐 표시할 수 있습니다. 각 레이블 [N]은 참조 @eN에 대응합니다:

agent-browser screenshot --annotate ./page.png
# -> 스크린샷 저장됨: ./page.png
#    [1] @e1 button "제출"
#    [2] @e2 link "홈"
#    [3] @e3 textbox "이메일"
agent-browser click @e2

주석이 추가된 스크린샷은 참조를 캐시하므로, 바로 요소와 상호작용할 수 있습니다. 이는 텍스트 스크래핑만으로는 충분하지 않은 경우에 유용합니다 — 레이블이 없는 아이콘, 캔버스 콘텐츠, 또는 시각적 레이아웃 검증 등에 적합합니다.

최선의 실천 방법

출력을 작동 가능한 요소로 줄이기 위해 -i 사용
페이지가 변경된 후에는 반드시 다시 스크래핑하여 최신 참조 획득
특정 페이지 섹션에 대해 -s로 범위 설정
복잡한 페이지에서는 -d로 깊이 제한
참조와 함께 시각적 맥락이 필요한 경우 screenshot --annotate 사용

JSON 출력

스크립트 내에서 프로그래밍적으로 파싱하기 위한 경우:

agent-browser snapshot --json
# {"success":true,"data":{"snapshot":"...","refs":{"e1":{"role":"heading","name":"제목"},...}}}

참고: JSON 형식은 텍스트 출력보다 더 많은 토큰을 사용합니다. 인공지능 에이전트에 최선의 선택은 기본 텍스트 형식입니다.