AI 에이전트가 셸 명령으로 브라우저를 직접 조작하게 하는 도구
웹 페이지를 텍스트로 변환해 AI가 읽고, 그 텍스트에 포함된 참조 번호를 이용해 특정 요소를 클릭하거나 입력하는 작업을 수행합니다. 이는 AI 에이전트가 웹 페이지를 탐색하고 상호작용하는 과정을 단순한 셸 명령의 연속으로 만들어 줍니다. 각 명령은 짧은 셸 호출로 처리되며, 브라우저는 명령 사이에도 열려 있어 연속적인 작업이 가능합니다.
페이지를 텍스트로 읽고 참조 번호로 조작
도구는 snapshot 명령을 통해 현재 페이지를 접근성 트리 형태로 압축된 텍스트로 반환합니다. 이때 각 요소에는 @e1과 같은 참조 번호가 부여됩니다. AI 에이전트는 이 참조 번호를 사용해 click이나 fill 같은 명령을 실행하며, 실행 후 다시 스냅샷을 찍어 결과를 확인하는 루프를 돌립니다. 페이지가 이동하거나 DOM이 변경되면 참조 번호가 무효화되므로, 새로운 스냅샷을 찍어야 합니다. 숨겨진 요소나 다른 요소에 가려진 대상은 클릭이 실패하며, 이를 해결하려면 가리는 요소를 먼저 제거하고 재시도해야 합니다.
백그라운드 데몬과 브라우저 엔진 선택
명령은 첫 실행 시 시작되는 백그라운드 데몬으로 전달되며, 이 데몬이 Chrome DevTools Protocol을 통해 브라우저를 제어합니다. 각 --session은 독립적인 데몬과 브라우저를 가지며, 1시간 동안 명령이 없으면 헤드리스 브라우저를 닫고 종료됩니다. 기본 브라우저는 Chrome for Testing이지만, --cdp 옵션으로 실행 중인 Chrome에 연결하거나 --engine으로 Lightpanda, Obscura 엔진을 선택할 수 있습니다. iOS 시뮬레이터의 Mobile Safari를 구동하거나 Browserbase, Browserless 같은 클라우드 브라우저 제공업체와도 연동할 수 있습니다.
에이전트 하네스와의 연동 방식
CLI에는 버전과 일치하는 스킬이 포함되어 있어, agent-browser skills get core 명령으로 핵심 루프와 참조 번호 사용법을 에이전트에 전달할 수 있습니다. npx skills add vercel-labs/agent-browser 명령으로 스킬을 에이전트 하네스에 설치하면, 설치된 스킬이 항상 현재 CLI 버전의 지침을 로드하도록 설계되어 있습니다. MCP 클라이언트를 사용하는 경우 agent-browser mcp 명령으로 stdio 기반 MCP 서버를 시작할 수도 있습니다. 이는 에이전트가 브라우저 자동화 작업을 수행할 때 필요한 지침을 동적으로 가져오게 하여 버전 불일치 문제를 방지합니다.
설치와 플랫폼 지원 범위
npm을 통해 전역 설치하거나 Homebrew, 또는 npx로 즉시 실행할 수 있습니다. Linux 환경에서는 --with-deps 옵션으로 시스템 라이브러리도 함께 설치할 수 있습니다. macOS(ARM64, x64), Linux(ARM64, x64, glibc 및 musl), Windows(x64)용 네이티브 바이너리가 제공되며, npm 패키지가 호스트에 맞는 바이너리를 자동으로 선택합니다. 소스에서 빌드하려면 Node.js 24 이상, pnpm 11 이상, Rust가 필요합니다.
사용 전 확인해야 할 사항
이 도구는 AI 에이전트가 웹과 상호작용하는 환경을 구축하는 데 적합하며, 특히 반복적인 브라우저 자동화 작업이 필요한 시나리오에서 유용합니다. 참조 번호는 스냅샷 시점의 페이지 상태를 반영하므로, 동적 콘텐츠가 많은 페이지에서는 스냅샷 갱신 주기를 고려해야 합니다. 라이선스는 Apache-2.0이며, 보안 관련 설정은 인증 볼트, 도메인 허용 목록, 액션 정책을 통해 관리됩니다.
