Browser Use 입문: AI로 웹페이지 열기, 버튼 클릭, 정보 추출하기

uvx browser-use install을 마친 뒤 실제로 막히는 지점은 task입니다. “사이트를 열고 봐줘”라고만 쓰면 agent는 무엇을 완료해야 하는지 알기 어렵습니다. 계속 시도하거나, 추측하거나, 너무 일찍 끝낼 수 있습니다.

Browser Use는 AI가 Chromium 브라우저를 제어해 웹 자동화를 수행하게 해주는 오픈소스 Python 라이브러리입니다. 로컬 또는 self-hosted 환경에서 실행할 수 있고 Browser Use Cloud에 의존하지 않습니다. Browser Agent 개념을 이미 이해했다면, 이 튜토리얼은 설치부터 첫 성공 task까지 안전 설정, 결과 읽기, 실패 디버깅을 순서대로 다룹니다.

Browser Use란 무엇인가: 한 문장으로 정리

Browser Use는 Python library for AI browser automation입니다. LLM Agent가 사람처럼 브라우저를 조작해 탐색, 클릭, 입력, 스크롤, 데이터 추출, 스크린샷을 수행할 수 있습니다.

위치는 로컬 또는 self-hosted 실행입니다. Browser Use Cloud에 의존하지 않습니다. 오픈소스 라이브러리와 Cloud Agent의 API는 다릅니다. 이 글은 오픈소스 입문에 집중하며, Cloud SDK의 structured output, human-in-the-loop, live preview 같은 기능은 범위에 넣지 않습니다.

아직 “Browser Agent가 무엇인가”가 궁금하다면, Browser Agent 개념 글이 공개된 뒤 먼저 읽는 것이 좋습니다. 이미 개념을 알고 있다면, 이 글은 “지금 어떻게 실행할까”에 답합니다.

설치와 준비: uv부터 API key까지

2026-06-30 기준 공식 README와 quickstart의 설치 흐름은 다음과 같습니다.

1. Python 버전 요구 사항

Browser Use에는 Python 3.11 이상이 필요합니다. 공식 quickstart 예시는 Python 3.12로 venv를 만들지만, 본인 환경에 맞게 선택할 수 있습니다.

2. uv 설치하기(권장)

uv는 Astral이 개발한 최신 Python 패키지 매니저입니다. 아직 uv가 없다면 다음처럼 설치합니다.

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

3. 프로젝트 초기화와 browser-use 설치

# 프로젝트 디렉터리 생성
mkdir my-browser-use
cd my-browser-use

# 프로젝트 초기화
uv init

# browser-use 설치(core 의존성 포함)
uv add "browser-use[core]"

# 의존성 동기화
uv sync

uv를 쓰지 않는다면 pip도 사용할 수 있습니다.

Railway - 현대적인 배포 플랫폼, 번거로운 운영 없이 몇 분 만에 라이브

지금 시작 →광고

pip install "browser-use[core]"

4. Chromium 브라우저 실행 환경 설치

Browser Use는 내부적으로 Playwright에 의존하므로 먼저 Chromium을 설치해야 합니다.

uvx browser-use install

이 명령은 Chromium을 다운로드하고 설정해 agent가 브라우저 인스턴스를 시작할 수 있게 합니다.

5. API key 설정

Browser Use는 task를 이해하고 판단하기 위해 LLM에 연결해야 합니다. 공식 quickstart는 브라우저 task에 맞게 설계된 ChatBrowserUse를 권장합니다.

프로젝트 루트에 .env 파일을 만듭니다.

# .env
BROWSER_USE_API_KEY=your_api_key_here

OpenAI, Anthropic, Google Gemini, 로컬 Ollama를 사용한다면 해당 API key를 설정합니다.

OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key
GOOGLE_API_KEY=your_google_key

첫 스크립트 작성: 최소 템플릿

최소 스크립트에는 세 부분만 있으면 됩니다. 모듈을 import하고, Agent를 만들고, task를 실행합니다.

from browser_use import Agent, Browser, ChatBrowserUse
import asyncio

async def main():
    # 브라우저 인스턴스 생성(디버깅 중에는 창을 표시)
    browser = Browser(headless=False)

    # LLM 인스턴스 생성
    llm = ChatBrowserUse()

    # Agent 생성
    agent = Agent(
        task="quotes.toscrape.com을 열고, 한 화면 아래로 스크롤한 뒤, 'Next' 버튼을 클릭하고 두 번째 페이지의 모든 quote 텍스트와 작성자를 추출하세요",
        llm=llm,
        browser=browser
    )

    # task 실행(스텝 수 제한)
    history = await agent.run(max_steps=20)

    # 브라우저 닫기
    await browser.close()

if __name__ == "__main__":
    asyncio.run(main())

이 스크립트는 몇 가지 일을 합니다.

1. Browser(headless=False): 브라우저 창을 보여주기 때문에 디버깅하기 쉽습니다. 디버깅이 끝나면 headless=True로 바꿀 수 있습니다.
2. ChatBrowserUse(): 공식 브라우저 모델을 사용합니다. ChatOpenAI(model="gpt-4o") 또는 다른 모델로 바꿀 수도 있습니다.
3. task는 구체적이어야 합니다. “사이트를 열고 봐줘”가 아니라 “X URL로 이동하고, 스크롤하고, Y 버튼을 클릭하고, Z 내용을 추출한다”처럼 써야 합니다. 모호한 task는 agent의 반복 시도나 조기 종료로 이어집니다.
4. max_steps=20: agent가 최대 20단계까지만 실행하도록 제한합니다. 첫 task는 10~20단계가 좋습니다. 같은 동작에서 계속 멈추는 상황을 피할 수 있습니다.

스크립트를 실행합니다.

uv run python main.py

agent를 무한히 돌리지 않기: max_steps가 안전선입니다

max_steps는 agent의 실행 단계 수를 제한합니다. 공식 기본값은 100이지만, 첫 task에서는 10~20으로 낮추는 편이 좋습니다.

제한이 필요한 이유는 다음과 같습니다.

• 클릭 실패, 느린 페이지 로딩, 팝업 가림 같은 문제 때문에 agent가 같은 동작을 반복할 수 있습니다.
• 단계 제한이 없으면 시간과 token을 계속 소비할 수 있습니다.
• 첫 task의 목표는 “완벽한 실행”이 아니라 “흐름이 동작하는지 확인”하는 것입니다. 단계 수를 줄이면 문제를 더 빨리 찾을 수 있습니다.

권장 설정입니다.

# 첫 task: 10~20단계
await agent.run(max_steps=20)

# 복잡한 task: 필요에 따라 조정하되, 초반에는 50을 넘기지 않는 편이 좋습니다
await agent.run(max_steps=50)

초보자를 위한 안전한 시작 설정

첫 task에서 주 계정의 로그인 상태를 쓰거나 agent가 임의의 사이트로 자유롭게 이동하게 두지 마세요. 안전 설정은 다음과 같습니다.

Alibaba Cloud - 개발자 클라우드 1순위, Lighthouse 서버 15% 할인

15% 할인 받기 →광고

1. headless=False 디버깅 모드

browser = Browser(headless=False)

브라우저 창을 보여주면 agent가 무엇을 하는지 볼 수 있습니다. 클릭 실패인지, 페이지가 멈춘 것인지, task 설명이 잘못된 것인지 판단하기 쉽습니다. 디버깅이 끝나면 headless=True로 바꿉니다.

2. allowed_domains로 이동 범위 제한

browser = Browser(
    headless=False,
    allowed_domains=["quotes.toscrape.com"]
)

allowed_domains는 agent가 다른 도메인으로 이동하지 못하게 합니다. task가 한 사이트에서만 끝난다면 이 제한을 넣는 것이 좋습니다.

Browser Use는 allowed_domains=["*.example.com"] 같은 서브도메인 wildcard를 지원합니다. 하지만 allowed_domains=["example.*"] 같은 TLD wildcard는 인식하지 않습니다. 고정 사이트만 다룬다면 전체 도메인을 쓰는 것이 가장 안정적입니다.

allowed_domains=["quotes.toscrape.com", "github.com"]

3. 독립 profile 사용, 주 Chrome 재사용하지 않기

browser = Browser(
    headless=False,
    user_data_dir="./browser_profile"
)

Agent는 별도의 브라우저 profile을 만듭니다. 주 Chrome의 로그인 상태, Cookie, 민감한 데이터에 접근하지 않습니다. 이 첫 튜토리얼은 공개 페이지만 사용하고 로그인 상태를 다루지 않습니다.

4. disable_security를 사용하지 않기

disable_security는 브라우저 보안 정책을 비활성화합니다. 공식 문서도 이 옵션을 권장하지 않는다고 표시합니다. 다른 튜토리얼에서 이 파라미터를 보더라도 건너뛰세요.

결과 읽기: “브라우저가 움직였다”만으로는 부족합니다

agent.run()은 AgentHistoryList 타입을 반환합니다. 여러 helper 메서드로 결과와 과정을 확인할 수 있습니다.

history = await agent.run(max_steps=20)

# 최종 결과
result = history.final_result()
print("최종 결과:", result)

# 추출한 내용
extracted = history.extracted_content()
print("추출 내용:", extracted)

# 오류 목록
errors = history.errors()
print("오류:", errors)

# 오류가 있었는지 확인
if history.has_errors():
    print("task 실행 중 오류가 발생했습니다")

# 방문한 URL 목록
urls = history.urls()
print("방문한 URL:", urls)

# 스크린샷 경로 목록
screenshots = history.screenshot_paths()
print("스크린샷:", screenshots)

# 실행한 action 이름
actions = history.action_names()
print("action:", actions)

# 총 단계 수
steps = history.number_of_steps()
print("실행 단계 수:", steps)

초보자가 자주 하는 실수는 브라우저 창이 움직인 것만 보고 성공으로 판단하는 것입니다. final_result()가 비어 있으면 agent가 너무 일찍 종료했거나 task 설명을 잘못 이해했을 수 있습니다. errors()에 내용이 있다면, prompt를 바꾸기 전에 해당 오류를 먼저 읽어야 합니다.

첫 task: 열기, 클릭, 추출

첫 task 환경으로 quotes.toscrape.com을 사용합니다. 스크래핑 연습용 공개 사이트라 로그인 요구가 없고 구조도 단순합니다.

task 1: 열고 스크롤하기

agent = Agent(
    task="quotes.toscrape.com을 열고 한 화면 아래로 스크롤하세요",
    llm=ChatBrowserUse(),
    browser=Browser(headless=False, allowed_domains=["quotes.toscrape.com"])
)
history = await agent.run(max_steps=10)
print("방문한 URL:", history.urls())

task 2: 버튼 클릭하기

agent = Agent(
    task="quotes.toscrape.com을 열고 페이지 하단의 'Next' 버튼을 클릭하세요",
    llm=ChatBrowserUse(),
    browser=Browser(headless=False, allowed_domains=["quotes.toscrape.com"])
)
history = await agent.run(max_steps=10)
print("성공 여부:", history.is_successful())

task 3: 내용 추출하기

agent = Agent(
    task="quotes.toscrape.com을 열고 첫 페이지의 모든 quote 텍스트와 작성자를 추출하세요",
    llm=ChatBrowserUse(),
    browser=Browser(headless=False, allowed_domains=["quotes.toscrape.com"])
)
history = await agent.run(max_steps=15)
extracted = history.extracted_content()
print("추출 내용:", extracted)

task 4: 조합하기

agent = Agent(
    task="quotes.toscrape.com을 열고 'Next' 버튼을 클릭한 뒤, 두 번째 페이지의 모든 quote 텍스트와 작성자를 추출하세요",
    llm=ChatBrowserUse(),
    browser=Browser(headless=False, allowed_domains=["quotes.toscrape.com"])
)
history = await agent.run(max_steps=20)
print("최종 결과:", history.final_result())
print("오류:", history.errors())

실패 후 어디를 볼 것인가: 디버깅 체크리스트

Agent가 빈 결과를 반환하거나, 오류를 내거나, 멈춘다면 다음 순서로 확인합니다.

1. 클릭 실패

• history.errors()에 “click failed” 또는 “element not found”가 있는지 확인합니다
• task에 키보드 fallback을 추가합니다. “클릭에 실패하면 Tab으로 버튼을 찾고 Enter를 누른다”
• history.screenshot_paths()를 확인해 요소가 보였는지 판단합니다

2. 추출 내용이 비어 있음

• history.urls()로 페이지가 실제로 열렸는지 확인합니다
• history.screenshot_paths()로 페이지 상태를 봅니다
• task가 구체적인지 확인합니다. “모든 quote 텍스트와 작성자를 추출한다”처럼 써야지, “내용을 본다”만으로는 부족합니다

3. 페이지 멈춤

• allowed_domains가 이동을 막았는지 확인합니다
• 네트워크 연결과 페이지 로딩 시간을 확인합니다
• max_steps를 낮추거나 task에 timeout 동작을 넣습니다. “페이지가 10초 안에 로드되지 않으면 홈으로 돌아간다”

4. 결과가 불완전함

• max_steps가 너무 일찍 멈춘 것은 아닌지 확인합니다
• history.number_of_steps()로 실제 실행 단계 수를 봅니다
• task 설명을 조정하고 여러 작은 하위 task로 나눕니다

5. 전체 실패

• .env의 API key가 올바른지 확인합니다
• 모델이 지원되는지 확인합니다. ChatBrowserUse, OpenAI, Anthropic, Google Gemini, 로컬 Ollama
• task 설명이 너무 추상적인지 확인합니다. “사이트를 열고 봐줘”를 구체적인 action으로 바꿉니다

Beta Agent vs 안정 버전: 두 가지 진입점

2026-06-30 기준 공식 README는 두 가지 Agent import path를 제공합니다.

안정 버전

from browser_use import Agent, Browser

이것이 안정 버전 진입점입니다. 이전부터 Browser Use를 사용했다면 이 경로를 계속 사용할 수 있습니다.

KiloClaw - 기업용 매니지드 OpenClaw, AI Agent 오케스트레이션 및 스마트 라우팅

시작하기 →광고

Beta 버전(0.13)

from browser_use.beta import Agent, BrowserProfile, ChatBrowserUse

이것은 Rust core와 browser harness를 기반으로 하는 0.13 beta agent입니다. 공식 README는 기존 사용자는 안정 버전을 계속 사용할 수 있고, 신규 사용자는 beta를 시도할 수 있다고 설명합니다.

어느 쪽을 써야 할지 모르겠다면 현재 공식 README를 확인하세요. 이 가이드는 안정 버전 예제를 사용하며, beta API는 다를 수 있습니다.

오픈소스 vs Cloud: 경계 이해하기

이 가이드는 Browser Use 오픈소스 라이브러리를 로컬에서 사용합니다.

Browser Use Cloud는 API가 다른 호스팅 서비스입니다.

• Cloud SDK는 현재 API v3를 사용합니다
• Cloud는 structured output, human-in-the-loop, live preview, persistent profiles 등을 제공합니다
• Cloud의 Python/TypeScript SDK는 오픈소스 라이브러리 API와 호환되지 않습니다

Cloud를 고려할 때입니다.

• 프로덕션 배포 또는 호스팅 실행 환경
• stealth, CAPTCHA, proxy 같은 고급 기능이 필요할 때. 이 글에서는 다루지 않습니다
• 여러 계정, 지속 profile, 팀 협업이 필요할 때

이 글은 로컬 입문에 집중합니다. Cloud 사용 방식과 가격은 후속 글에서 다룹니다.

다음 단계: 더 읽어볼 것

이 튜토리얼은 Browser Use 오픈소스 라이브러리의 로컬 입문을 다뤘습니다. 설치, API key, 최소 스크립트, 페이지 열기, 버튼 클릭, 정보 추출, 실패 디버깅까지의 흐름입니다.

다음으로 시도해볼 만한 주제입니다.

• 공개됨: OpenClaw 브라우저 자동화 실전 가이드, Computer-Use Agent: AI가 컴퓨터를 조작하게 하기, MCP 플러그인 가이드
• 후속 주제: Playwright MCP를 Claude, Codex, Cursor에 연결하기, Stagehand 엔지니어링, Browser Use 도구 선택, 로그인 상태와 인증, 클라우드 인프라, 컴플라이언스와 보안
• 공식 문서: quickstart, prompting guide, browser config

먼저 quotes.toscrape.com 또는 GitHub 공개 페이지에서 첫 task를 통과시킨 뒤, 로그인 상태와 Cloud를 고려하는 것이 좋습니다.