browser-use 딥다이브
— AI가 브라우저를 직접 손으로 조작하는 시대

1프로젝트 한줄 요약

browser-use는 LLM(대형 언어 모델)이 웹 브라우저를 자율적으로 조작할 수 있게 해주는 AI 에이전트 프레임워크입니다. OpenAI, Claude, Gemini, Ollama 등 거의 모든 LLM을 지원하며, Playwright 기반으로 실제 Chromium을 CDP(Chrome DevTools Protocol)로 제어합니다. 2.4k 이상의 프로젝트가 이 라이브러리에 의존하고 있을 만큼 사실상 표준 브라우저 에이전트 프레임워크로 자리잡았습니다.

2왜 주목받는가

2025~2026년은 AI 에이전트가 실제 작업을 수행하는 시대가 열린 해입니다. ⭐ 95,984로 오픈소스 브라우저 자동화 도구 중 가장 많은 스타를 보유하며, 멀티 LLM 지원, 루프 감지, 폴백 LLM 등 프로덕션 레벨 기능을 갖추고 있습니다.

경쟁 도구 대비 위치

3기술 스택 전체 지도

① 핵심 런타임

② LLM 통합

③ 인프라 / DevOps

4아키텍처 심화 분석

시스템 구조도

패턴 1 — 4단계 스텝 파이프라인

매 스텝마다 다음 4단계를 순차 실행합니다. Observe → Think → Act → Reflect의 ReAct 패턴을 브라우저에 특화시킨 구현입니다.

패턴 2 — DOM 직렬화 파이프라인 (핵심!)

패턴 3 — 레지스트리 패턴 (Action Registry)

@self.registry.action(description='검색 엔진에서 쿼리를 검색합니다')
async def search(query: str, engine: str = 'duckduckgo') -> ActionResult:
    await self.page.goto(f"https://duckduckgo.com/?q={query}")
    return ActionResult(extracted_content="검색 완료")

새 브라우저 액션 추가가 데코레이터 하나로 가능합니다. LLM이 JSON 형태로 액션을 출력하면 레지스트리가 해당 함수를 찾아 실행합니다.

패턴 4 — 이벤트 드리븐 아키텍처 (EventBus)

# 브라우저 이벤트 종류 (events.py)
NavigateToUrlEvent      # URL 이동
TabCreatedEvent         # 새 탭 생성
TabClosedEvent          # 탭 닫힘
AgentFocusChangedEvent  # 에이전트 포커스 변경
BrowserStartEvent       # 브라우저 시작
BrowserStopEvent        # 브라우저 종료

Watchdog 핸들러들이 비동기적으로 이벤트를 처리하므로, 브라우저 조작·스크린샷·다운로드 추적이 메인 실행 경로를 블로킹하지 않습니다.

패턴 5 — 루프 감지 (Loop Detection)

패턴 6 — 폴백 LLM 전략

5디렉토리 구조 해부

6학습 포인트 (기술별)

6.1 Chrome DevTools Protocol (CDP)

CDP는 Chrome 브라우저를 WebSocket으로 직접 제어하는 저수준 프로토콜입니다. Target.createTarget, Page.printToPDF, Runtime.evaluate 등 브라우저의 거의 모든 기능을 프로그래밍으로 다룰 수 있습니다. browser-use는 Playwright를 프로세스 관리에만 쓰고 핵심 제어는 CDP로 직접 합니다.

6.2 DOM 직렬화 및 접근성 트리

CDP DOM 스냅샷과 접근성(AX) 트리를 병합하여 LLM이 이해할 수 있는 형태로 변환하는 정교한 파이프라인을 배울 수 있습니다. 가시성 계산, iframe 재귀 탐색, 페인트 오더 필터링까지 실무에서 쓰이는 기법들이 포함되어 있습니다.

6.3 LLM 에이전트 루프 설계

ReAct(Reasoning + Acting) 패턴의 실제 구현을 볼 수 있습니다. 4단계 스텝 파이프라인, 루프 감지와 넛지 주입, 메시지 압축으로 토큰 예산 관리하는 기법이 모두 소스에 담겨 있습니다.

6.4 이벤트 드리븐 아키텍처

EventBus 패턴으로 비동기 이벤트를 발행·구독하고, Watchdog 패턴으로 브라우저 상태를 비블로킹으로 감시합니다. asyncio와 결합한 현대적인 Python 동시성 패턴의 모범 사례입니다.

6.5 Docker 컨테이너화 (비루트 사용자)

Chromium을 포함하는 Docker 이미지의 멀티 스테이지 빌드, 비루트 사용자(UID 911) 실행, 멀티 아키텍처(amd64/arm64) 빌드를 배울 수 있습니다.

7하드웨어 / 시스템 요구사항

Docker 배포 시

# Docker 실행 예시
# 노출 포트: 9242, 9222
# 볼륨: /data
# 비루트 사용자: browseruse (UID 911)
docker run -e OPENAI_API_KEY=sk-xxx browser-use/browser-use

LLM API 키 (하나 이상 필요)

• OPENAI_API_KEY — OpenAI GPT-4o 등
• ANTHROPIC_API_KEY — Claude Sonnet/Opus
• GOOGLE_API_KEY — Gemini
• BROWSER_USE_API_KEY — ChatBrowserUse 자체 모델
• Ollama 사용 시 API 키 불필요 (로컬 실행)

8직접 해볼 수 있는 실습 과제

from browser_use import Agent, BrowserSession
from langchain_openai import ChatOpenAI  # pip install langchain-openai 별도 필요 (examples extra)

agent = Agent(
    task="구글에서 '서울 오늘 날씨'를 검색하고 기온을 알려줘",
    llm=ChatOpenAI(model="gpt-4o"),
    browser_session=BrowserSession()
)
result = await agent.run()

from browser_use import Agent, Controller
controller = Controller()

@controller.action(description='현재 시간을 반환합니다')
async def get_current_time() -> str:
    from datetime import datetime
    return datetime.now().strftime('%Y-%m-%d %H:%M:%S')

agent = Agent(
    task="현재 시간을 확인하고 캘린더 이벤트를 만들어줘",
    llm=...,
    controller=controller
)

agent = Agent(
    task="...",
    llm=ChatOpenAI(model="gpt-4o", api_key="INVALID"),
    fallback_llm=ChatOpenAI(model="gpt-4o-mini"),  # 올바른 키
)

browser-use open "https://example.com/login"
browser-use type "user@example.com"   # 포커스된 요소에 타이핑
browser-use click 3                   # 요소 인덱스로 클릭 (state 명령으로 인덱스 확인)
browser-use screenshot dashboard.png

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크