agent-browser는 AI 에이전트를 위해 설계된 브라우저 자동화 CLI 도구입니다. 이 도구의 핵심 목표는 AI 에이전트가 웹 페이지와 상호작용하는 과정을 효율적이고 안정적으로 만드는 것입니다.

핵심 방법론 (Core Methodology)

agent-browser의 가장 중요한 특징은 "Ref-based" 시스템입니다. 이는 AI 에이전트가 웹 요소를 식별하고 상호작용하는 방식을 최적화합니다.

1. Compact Accessibility Tree Snapshot: snapshot -i와 같은 명령어를 실행하면, agent-browser는 현재 웹 페이지의 "compact accessibility tree"를 반환합니다. 이는 전체 DOM (Document Object Model)이 아닌, AI 에이전트가 이해하기 쉽고 필요한 핵심 정보(예: 제목, 링크, 버튼 등)만을 포함하는 간결한 텍스트 기반 트리 구조입니다.
2. 고유한 Ref 할당: 이 접근성 트리에 있는 각 인터랙티브 요소에는 @e1, @e2와 같은 고유한 "ref" (reference)가 할당됩니다. 이 ref는 특정 DOM 요소를 가리키는 안정적인 식별자 역할을 합니다.
3. Ref 기반 상호작용: AI 에이전트는 이 ref를 사용하여 click @e2와 같은 명령을 통해 특정 요소를 정확하고 결정론적으로(deterministically) 선택하고 상호작용할 수 있습니다.

이 ref-기반 방법론은 다음과 같은 기술적 이점을 제공합니다:

• Context-efficient: AI 에이전트의 컨텍스트 윈도우 내에서 필요한 토큰 수를 최소화합니다. 일반적인 전체 DOM은 3000-5000 토큰을 차지할 수 있는 반면, agent-browser의 텍스트 출력은 200-400 토큰으로 대폭 줄여 LLM(Large Language Model)의 비용과 추론 시간을 절감합니다.
• Deterministic: ref는 스냅샷 시점에 특정 요소에 고정되므로, 요소의 위치나 속성이 동적으로 변해도 스냅샷에 기반한 상호작용은 항상 동일한 요소를 지향합니다. 이는 AI 에이전트의 동작 예측 가능성을 높입니다.
• Fast: ref를 사용하면 AI 에이전트가 매번 DOM을 재탐색하거나 복잡한 CSS 셀렉터나 XPath를 생성할 필요가 없습니다. 이미 식별된 ref를 통해 직접 상호작용하므로 처리 속도가 빠릅니다.
• AI-friendly: LLM은 정형화된 JSON 대신 간결한 텍스트 기반의 ref 출력을 자연스럽게 파싱하고 이해할 수 있습니다.

아키텍처 (Architecture)

agent-browser는 최적의 성능을 위해 "클라이언트-데몬(Client-daemon)" 아키텍처를 채택하고 있습니다.

4. Rust CLI: 명령어 라인 인터페이스(CLI)는 Rust로 개발되어 있습니다. 이는 명령어를 빠르게 파싱하고 데몬과 통신하는 역할을 합니다. Rust는 높은 성능과 메모리 안전성을 제공하여 CLI의 응답성을 보장합니다.
5. Node.js Daemon (기본): 기본적으로 agent-browser는 Playwright 브라우저 인스턴스를 관리하는 Node.js 데몬을 사용합니다. Playwright는 Chromium, Firefox, WebKit과 같은 다양한 브라우저 엔진을 제어할 수 있는 강력한 자동화 라이브러리입니다. 이 데몬은 백그라운드에서 실행되며 브라우저 작업을 수행합니다.
6. Native Daemon (실험적): 실험적으로 --native 옵션을 통해 순수 Rust로 구현된 네이티브 데몬도 제공됩니다. 이 데몬은 Node.js 없이 직접 CDP(Chrome DevTools Protocol)를 사용하여 브라우저를 제어합니다. 이는 Node.js 의존성을 제거하고 잠재적으로 더 빠른 성능을 제공할 수 있습니다.

데몬은 한 번 시작되면 백그라운드에서 지속적으로 실행되며, 여러 명령어 호출 사이에서도 상태를 유지합니다. 이를 통해 매번 브라우저를 새로 시작하는 오버헤드를 줄일 수 있습니다.

기타 특징 (Other Features)

• 포괄적인 명령어 세트: 내비게이션, 폼 입력, 스크린샷 캡처, 네트워크 요청, 스토리지 관리 등 50가지 이상의 다양한 브라우저 자동화 명령어를 지원합니다.
• 세션 관리: 여러 개의 독립적인 브라우저 인스턴스를 생성하고 관리할 수 있어, 각 세션이 서로의 인증 정보나 상태에 영향을 주지 않도록 합니다.
• 크로스 플랫폼: macOS (ARM64, x64), Linux (ARM64, x64), Windows (x64) 등 다양한 운영체제를 지원하며, 네이티브 바이너리를 제공하여 설치 및 실행이 용이합니다.
• AI 에이전트 호환성: Claude Code, Cursor, GitHub Copilot, OpenAI Codex, Google Gemini 등 셸 명령어를 실행할 수 있는 모든 AI 에이전트와 원활하게 연동됩니다.