Agent Browser은(는) 무엇을 하나요?

작업에 웹페이지 직접 조작(읽기 전용 API 데이터가 아닌)이 필요할 때 이 기술을 사용하세요. Agent Browser는 표준 CDP(Chrome DevTools Protocol)를 기반으로 하여, 에이전트가 사람처럼 웹페이지를 탐색하고, 양식을 작성하며, 버튼을 클릭하고, React/Vue 렌더링 페이지, 모달, 캡차 미리보기와 같은 복잡한 프론트엔드 상호작용을 처리할 수 있는 능력을 부여합니다.

설치

npx clawhub@latest install agent-browser

적용 시나리오

웹페이지를 열고 여러 단계의 작업 수행: 백엔드 관리 시스템에 로그인, 여러 탭 간 데이터 비교, 복잡한 업무 양식 제출.
자연어로 요소 찾기: 복잡한 CSS 셀렉터를 작성할 필요 없이 "왼쪽 상단 검색창 클릭" 또는 "'장바구니 담기' 문구가 포함된 버튼 찾기"와 같이 자연어로 직접 조작.
멀티미디어 출력 내보내기: 현재 페이지를 고화질 스크린샷, 스크롤 캡처, PDF 문서로 저장하거나, 조작 비디오를 녹화.
페이지 내 JavaScript 실행: 콘솔에 직접 사용자 정의 스크립트를 주입하여, 원래 크롤링하기 어려운 동적 데이터를 추출하거나 특정 사용자 행동을 시뮬레이션.
세션 상태 저장: 쿠키, 로컬스토리지의 영속화(retain 메커니즘)를 지원하여, 교차 세션에서 로그인 없이 접근 가능.

사용 제안

먼저 대상 페이지와 예상 결과를 명확히 설명: 명확한 Success Criteria를 설정하세요.
단계별 실행: 복잡한 작업을 검증 가능한 원자적 단계(이동 → 위치 찾기 → 조작 → 검증)로 나누세요.
계정 보안 관련: 격리된 브라우저 프로필을 우선 사용하고, 최소 권한 모드를 활성화하세요.
시각 우선: 주요 조작 전후에 screenshot을 수행하세요. 증거를 남기고, 에이전트가 스스로 오류를 수정하는 데도 도움이 됩니다.

트리거 조건 / When to Use

API 부재 시나리오: 대상 웹사이트가 공개 API를 제공하지 않고, 웹 프론트엔드 상호작용을 통해서만 데이터를 얻을 수 있을 때.
그래픽 보고서 캡처: 복잡한 대시보드에서 특정 차트를 캡처하여 분석해야 할 때.
자동 등록/로그인 프로세스: 일련의 신원 인증 또는 환경 설정 단계를 완료해야 할 때.
SEO 및 프론트엔드 성능 테스트: console을 통해 페이지 오류, 성능 지표(LCP, FID)를 읽고 진단.
동적 콘텐츠 실시간 모니터링: 실시간 주식 시세 페이지나 플래시 세일 이벤트의 재고 변동을 모니터링.

핵심 기능 / Core Capabilities

1. 의미론적 스냅샷 및 위치 찾기 (Semantic Snapshot)

조작 단계:
1. snapshot을 호출하여 접근성 트리(Accessibility Tree)를 획득.
2. ax*(접근성 참조)와 n*(DOM 참조)을 결합하여 페이지 계층 구조 이해.
3. highlight 기술을 통해 위치 정확도 검증.
모범 사례: 복잡한 페이지에서는 먼저 scroll로 하단까지 스크롤하여 레이지 로딩(Lazy Loading) 콘텐츠가 완전히 표시되도록 합니다.

2. 정밀 동작 시뮬레이션 (Action Emulation)

조작 단계:
1. act 인터페이스를 호출하여 click, type, hover, drag 등의 동작 실행.
2. clearFirst: true를 설정하여 입력 필드 내용이 비어 있도록 보장.
3. 중요한 단계에서는 slowly: true를 활성화하여 사람의 실제 클릭 빈도를 모방하고, 안티-봇 엔진에 탐지될 위험을 낮춤.
모범 사례: "제출" 버튼을 클릭한 후 즉시 wait 도구를 함께 사용하여 특정 URL이나 텍스트가 나타날 때까지 기다려 조작이 적용되었는지 확인합니다.

3. 세션 유지 및 영속화 (Session Retention)

조작 단계:
1. retain: true를 사용하여 중요한 탭을 표시.
2. 표시된 탭은 에이전트 세션이 종료된 후에도 자동으로 닫히지 않아, 추후 재방문이 용이.
모범 사례: 사용자가 수동으로 QR 코드를 스캔하여 로그인해야 하는 경우, retain을 활성화하고 사용자가 스캔을 완료한 후 에이전트가 다시 제어권을 넘겨받도록 합니다.

4. 예외 포착 및 진단 (Errors & Requests)

조작 단계:
1. 실시간으로 errors 목록을 읽어 JS 실행 중단 여부 식별.
2. requests 네트워크 요청을 모니터링하여 특정 API 데이터 패킷을 가로채고 분석(XHR/Fetch의 Response 포함).

일반 명령/템플릿 / Common Patterns

웹 정보 수집 워크플로우 템플릿 (Scraping Workflow)

### 작업 목표
[목표 설명: X 웹사이트에서 상위 10개 제품의 가격과 리뷰 수집]

### 조작 단계 (Action Sequence)
1. **Navigate**: `https://example.com/products`에 접속.
2. **Wait**: `.product-list`를 포함하는 요소가 로드될 때까지 대기.
3. **Scroll**: 페이지 하단까지 스크롤하여 페이징 트리거.
4. **Snapshot**: 모든 `n`級 참조의 텍스트 콘텐츠 획득.
5. **Console**: 스크립트 `Array.from(document.querySelectorAll('.price')).map(e => e.innerText)` 주입.
6. **Screenshot**: 전체 목록 영역을 캡처하여 `output/products.png`에 저장.

### 예상 결과
- JSON 데이터 요약.
- 스크린샷 증거.

빠른 열기 및 탭 유지 예시

// 예시: GitHub를 열고 세션을 유지하여 자동 소멸되지 않도록 함
const tab = await mcp_call({
  name: 'browser_open',
  arguments: {
    targetUrl: "https://github.com",
    profile: "chrome"
  }
});
await mcp_call({
  name: 'browser_retain',
  arguments: {
    targetId: tab.targetId,
    retain: true
  }
});

고급 응용 시나리오 / Advanced Use Cases

1. 자동화 UI 회귀 테스트

에이전트가 정기적으로 개발 환경 웹페이지를 열고, 핵심 기능 페이지를 캡처하여 MEMORY.md의 "기준 스크린샷"과 비교하여 UI 어긋남이나 스타일 누락을 식별합니다.

2. 교차 플랫폼 데이터 "운반"

A 시스템의 보고서 데이터를 읽고, 자동으로 B 시스템에 로그인하여 각 레코드를 수동으로 입력함으로써 API 없이 시스템 통합을 구현합니다.

경계 및 한계 / Boundaries

캡차 차단 (CAPTCHA): 복잡한 이미지 또는 퍼즐 캡차는 여전히 수동 개입이 필요합니다. (question 기술을 통해 스크린샷을 사용자에게 전송 가능).
리소스 오버헤드 (Resources): 브라우저를 시작(특히 여러 개)하는 것은 CPU와 메모리를 매우 많이 소모합니다.
드라이버 호환성: 일부 헤드리스 환경에서는 GPU 가속에 의존하는 애니메이션이나 WebGL이 비정상적으로 렌더링될 수 있습니다.
안티-크롤링 탐지 (Anti-Bot): 동작이 지나치게 기계적이거나 IP 소재지가 비정상적일 경우, 대상 웹사이트가 차단을 트리거할 수 있습니다. 프록시(Proxy)와 함께 사용하는 것이 좋습니다.
시간 초과 위험: 네트워크 속도가 매우 느리거나 서버 응답이 지연될 경우, 적절한 timeoutMs를 설정해야 합니다.

모범 사례 요약

실패 재시도 전략: 탐색 실패나 요소를 찾을 수 없는 경우를 대비하여 2-3회 자동 재시도 메커니즘을 설계하세요.
환경 일관성: 뷰포트(Viewport) 크기를 일관되게 유지하여 반응형 레이아웃으로 인한 요소 위치 변동을 방지하세요.
정리: retain이 활성화된 경우가 아니라면, 작업 종료 후 즉시 사용하지 않는 탭을 close하세요.
시크릿 모드: 민감한 작업을 처리할 때는 incognito 모드를 우선 사용하세요.
로그 추적 가능성: 모든 browser console 오류 로그를 기록하세요. 이것이 디버깅의 첫 번째 단서입니다.

Agent Browser

Agent Browser란 무엇인가요?

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

문서