agent-browser

설치

글로벌 설치 (권장)

최대 성능을 위해 네이티브 Rust 바이너리를 설치합니다:

npm install -g agent-browser
agent-browser install  # Chromium 다운로드

이 방법이 가장 빠릅니다 — 명령어는 네이티브 Rust CLI를 통해 직접 실행되며, 마이크로초 단위의 파싱 오버헤드만 발생합니다.

빠른 시작 (설치 없이 사용)

글로벌 설치 없이도 npx로 바로 실행할 수 있습니다:

npx agent-browser install   # 처음에만 다운로드 (Chromium)
npx agent-browser open example.com

참고: npx는 노드.js를 거쳐서 Rust CLI에 도달하기 때문에 글로벌 설치보다 눈에 띄게 느립니다. 정기적인 사용을 원한다면 글로벌 설치를 권장합니다.

프로젝트 설치 (로컬 종속성)

package.json에서 버전을 고정하고자 하는 프로젝트에 적합합니다:

npm install agent-browser
npx agent-browser install

그런 다음 npx 또는 package.json 스크립트를 통해 사용하세요:

npx agent-browser open example.com

Homebrew (macOS)

brew install agent-browser
agent-browser install  # Chromium 다운로드

소스에서 빌드

git clone https://github.com/vercel-labs/agent-browser
cd agent-browser
pnpm install
pnpm build
pnpm build:native
./bin/agent-browser install
pnpm link --global

Linux 종속성

Linux에서는 시스템 종속성을 설치해야 합니다:

agent-browser install --with-deps
# 또는 수동으로: npx playwright install-deps chromium

사용자 지정 브라우저

포함된 Chromium 대신 사용자 지정 브라우저 실행 파일을 사용할 수 있습니다:

  • 서버리스 - @sparticuz/chromium 사용 (~50MB 대비 ~684MB)
  • 시스템 브라우저 - 기존의 Chrome 설치 사용
  • 사용자 정의 빌드 - 수정된 브라우저 빌드 사용
# 플래그를 통해
agent-browser --executable-path /path/to/chromium open example.com

# 환경 변수를 통해
AGENT_BROWSER_EXECUTABLE_PATH=/path/to/chromium agent-browser open example.com

서버리스 예제

import chromium from '@sparticuz/chromium';
import { BrowserManager } from 'agent-browser';

export async function handler() {
  const browser = new BrowserManager();
  await browser.launch({
    executablePath: await chromium.executablePath(),
    headless: true,
  });
  // ... 브라우저 사용
}

AI 에이전트 설정

agent-browser는 어떤 AI 에이전트와도 즉시 호환됩니다. 더 풍부한 컨텍스트를 제공하려면 다음과 같이 설정하세요.

AI 코드 보조 (권장)

귀하의 AI 코드 보조 도구용 스킬을 설치하세요:

npx skills add vercel-labs/agent-browser

Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Goose, OpenCode, Windsurf 등과 호환됩니다. 스킬은 리포지토리에서 가져와 자동으로 최신 상태로 유지됩니다.

node_modules 내의 SKILL.md를 복사하지 마세요 — 새로운 기능이 추가될 때마다 이 파일은 오래된 상태가 됩니다. 항상 npx skills add를 사용하거나 리포지토리 버전을 참조하세요.

AGENTS.md / CLAUDE.md

지침 파일에 다음을 추가하세요:

## 브라우저 자동화

웹 자동화에 `agent-browser`를 사용하세요. 모든 명령어를 확인하려면 `agent-browser --help`를 실행하세요.

핵심 워크플로우:
1. `agent-browser open <url>` - 페이지로 이동
2. `agent-browser snapshot -i` - 참조(@e1, @e2)와 함께 상호작용 가능한 요소 가져오기
3. `agent-browser click @e1` / `fill @e2 "text"` - 참조를 사용하여 상호작용
4. 페이지 변경 후 다시 스냅샷 찍기