browser-use 0.x를 기반으로 만들었다면 1.0에서 아키텍처와 기본값이 모두 달라집니다. 24개의 브라우저 액션은 영속적인 Python REPL 하나로 통합됐고, 이제 Browser()는 클라우드 브라우저를 뜻합니다. 이 글에서는 1.0.7 버전 고정 설치부터 첫 실행, 0.x 코드 마이그레이션까지 1.0.7 릴리스 노트와 MIGRATING.md, 11월 20일 공개된 엔지니어링 글을 바탕으로 정리합니다.
5분 만에 1.0 실행하기
먼저 버전을 고정하세요. 1.0.0은 2026년 11월 10일 공개됐고, 11월 20일 기준 안정 버전은 1.0.7이었습니다. 사전 릴리스로는 1.0.8rc1이 올라와 있습니다(릴리스). 프로젝트 README도 마이너 버전 사이에 API가 깨질 수 있으니 >=를 절대 사용하지 말라고 명시합니다.
uv add 'browser-use==1.0.7'
# or
pip install 'browser-use==1.0.7'필요한 Python 버전은 3.11 이상 4.0 미만입니다(README, PyPI). 모든 의존성도 ==로 고정돼 재현성에는 유리하지만, 애플리케이션에서 다른 pydantic, mcp, google-genai 버전을 요구하면 충돌할 수 있습니다.
인증은 한 번만 하면 됩니다. cloud.browser-use.com에서 키를 만든 뒤 환경 변수로 등록하거나 로그인 헬퍼를 실행하세요.
export BROWSER_USE_API_KEY=bu_...
# or
browser-use login로그인 정보는 ~/.config/browser-harness/auth.json에 저장되며 CLI, MCP 서버, browser-harness가 함께 사용합니다(MIGRATING.md). 컨테이너에서는 BROWSER_USE_AUTO_LOGIN=true를 사용하면 됩니다. SSH나 헤드리스 환경에서는 1.0.8 릴리스 후보가 링크와 승인 코드를 출력하고, 다른 기기에서 이를 승인하는 방식으로 로그인할 수 있습니다(1.0.8rc1 노트).
첫 실행 코드는 세 줄이면 충분합니다.
from browser_use import Agent
result = Agent(
"Find the number of stars of the browser-use repo"
).run_sync()
print(result.final_result())다만 기본 설정에서는 이 실행에 비용이 발생합니다. Browser Use Cloud 브라우저와 기본 게이트웨이 모델을 사용하기 때문입니다(README Path 1 / Path 3, MIGRATING.md 기본값). 테스트에서 클라우드 비용을 아예 쓰고 싶지 않다면 처음부터 Browser('chromium')과 자체 llm을 지정하세요.
24개의 액션은 어디로 갔을까
browser-use 0.x에서는 DOM 덤프를 보고 모델이 매 단계마다 메뉴에서 액션 하나를 골랐습니다. 1.0에서는 이 메뉴가 사라졌습니다. 대신 Pydantic AI를 기반으로, browser-harness 헬퍼와 raw cdp()가 미리 임포트된 영속 REPL 형태의 핵심 python 도구 하나를 제공합니다(엔지니어링 글).
async def python(ctx: RunContext[Session], code: str) -> list[Any]:
"""Run Python in the persistent REPL
(browser-harness helpers and raw cdp() pre-imported)."""이 구조 변경 과정에서 554개 파일 기준 136,905줄이 삭제되고 29,601줄이 추가됐습니다. Python 파일 수는 178개에서 43개로 줄었습니다(엔지니어링 글).
가장 인상적인 사례는 멈춘 페이지를 복구한 과정입니다. 에이전트는 Page.stopLoading으로 로딩을 중단하고, 멈춰 있던 스크립트를 차단한 뒤 페이지를 다시 불러왔습니다. 이어 페이지 내부의 비공개 JSONP 엔드포인트를 찾아 730개의 날짜를 여러 배치로 가져왔고, 실패한 배치만 재시도해 전용 도구 없이 4,720개 행을 반환했습니다(엔지니어링 글).
팀이 세운 기준은 간단합니다. 모델이 한 번 읽고 직접 다시 작성할 수 없는 경우에만 헬퍼를 추가한다는 원칙입니다. CAPTCHA는 예외입니다. 소규모 스테이징 테스트에서 hCaptcha를 대상으로 자연어 지시만 사용했을 때는 0/3이었지만, 전용 solve_captcha 도구는 6/6을 기록했습니다. 페이지가 접근할 수 없는 솔버 스위치를 도구가 대신 켜기 때문입니다(엔지니어링 글).
비용과 속도에 관한 수치는 제목만 보고 판단하면 안 됩니다. 11월 20일 글에 따르면 11월 8일 진행한 200개 작업 중 180개를 평가한 테스트에서, 같은 세 모델이 0.x보다 1.0에서 14~33점 높은 점수를 기록했고 비용은 2.7~5.2배 낮았습니다. 다만 모델당 한 번만 실행했고 기본값도 달라졌기 때문에, 도구 재설계만으로 나온 결과라고 볼 수 없다고 글 자체가 경고합니다(엔지니어링 글).
보다 공정하게 비교할 수 있는 범위는 더 좁습니다. 1.0.4는 1.0.3의 76.0과 거의 같은 76.1점을 기록했지만, 배치 스크린샷 정리로 프롬프트 캐싱을 유지하면서 모델 비용은 작업당 $0.434에서 $0.208로 줄었습니다(1.0.4 노트). BU Bench v2에서 1.0 ultrafast는 62.5점, $0.070, 650초를 기록했고 Browser Use Pi는 56.3점, $0.082, 743초였습니다. 제공업체 오류를 제외하면 이 차이는 통계적으로 의미가 줄어든다고 작성자들은 말합니다. 예산은 더 저렴하고 빨라지는 방향으로 잡되, 자동으로 더 똑똑해진다고 기대해서는 안 됩니다.
요금과 브라우저를 조용히 바꾸는 기본값
아래 표는 MIGRATING.md와 1.0.6 릴리스 노트를 바탕으로 작성했습니다. 1.0.7 기준이며, 오래된 가이드에서 놓치기 쉬운 1.0 중반의 기본 모델 변경도 반영했습니다.
| 설정 | 0.x | 1.0.7 |
|---|---|---|
llm=None | 모델 지정 필요 | Browser Use 게이트웨이를 통한 bu-4.0 |
bu-4.0 가격 | 해당 없음 | 입력 1M 토큰당 $1.80, 출력 1M 토큰당 $9.00 |
bu-fast 가격 | 해당 없음 | 입력 1M 토큰당 $0.12, 출력 1M 토큰당 $0.60 |
Browser() | 로컬 Chromium | Browser Use Cloud 브라우저 |
| 로컬 브라우저 | 기본값 | Browser('chromium')을 명시해야 함 |
| API 키 | 제공업체별 하나씩 | BROWSER_USE_API_KEY 하나 |
max_steps | 500 | 100(결과 전달에 한 단계 예약) |
| 에이전트 타임아웃 | 지정되지 않음 | 1,700초, 시작·종료 시간 제외 |
| Judge | 선택적으로 활성화 | 기본값 judge=True |
| 추론 / 모드 | 해당 없음 | bu-fast / bu-ultrafast에서 reasoning='medium', mode='ultrafast' |
특히 세 가지 함정을 기억해야 합니다. 첫째, 1.0 중간에 기본 모델이 바뀌었습니다. 1.0.5까지는 bu-fast가 기본값이었지만, 1.0.6부터 토큰 가격이 15배 비싼 bu-4.0으로 변경됐습니다. 프로젝트가 제시한 동일한 짧은 테스트 비용은 bu-4.0에서 $0.022, bu-fast에서 $0.0014입니다. 이전 비용 수준을 유지하려면 llm='bu-fast'를 명시하세요. 둘째, 인자 없는 Browser()는 이제 브라우저 시간당 $0.06에 모델 비용과 검색별 비용이 더해지는 클라우드 브라우저를 생성합니다(README). 또한 클라우드 브라우저에서는 localhost나 비공개 IP에 접근할 수 없습니다(MIGRATING.md). 셋째, 한 단계는 모델 요청 한 번과 Python 셀 하나를 의미합니다. 따라서 100단계로 낮아진 제한은 지출 상한 역할도 합니다. 이제 max_steps < 1 또는 timeout <= 0이면 브라우저가 시작되기 전에 실패합니다(MIGRATING.md).
Judge도 놓치기 쉬운 추가 비용입니다. 한 단계 이상 실행한 모든 작업 뒤에는 자체 모델이 최대 120,000자의 실행 기록과, 비전 기능이 켜져 있다면 마지막 페이지를 포함한 서로 다른 이미지 최대 네 장을 추가로 전송받아 낮은 수준의 요청을 한 번 더 처리합니다. 이 데이터는 가공 없이 전송됩니다(MIGRATING.md). 결과는 result.judgement에 저장되며 success, failure_reason, gotchas, 봇·CAPTCHA 플래그를 포함합니다. 비용은 result.cost_usd에도 반영됩니다. judge=False로 끄거나 예상 답변을 담은 judge_context를 전달할 수 있습니다. 스크린샷이 외부로 나가면 안 된다면 use_vision=False도 설정하세요.
로컬 환경이 필요하다면 로컬로 고정하기
습관이 아니라 네트워크 요구사항을 기준으로 브라우저를 선택하세요. 아래 모델 식별자는 README의 로컬 브라우저 예제에 나온 제공업체 예시입니다(README).
from browser_use import Agent, Browser, ChatOpenAI
agent = Agent(
"Summarize the dashboard at http://localhost:3000",
llm=ChatOpenAI("gpt-6-luna"),
browser=Browser("chromium"),
)
print(agent.run_sync().final_result())localhost, 사설 네트워크, 커스텀 뷰포트가 필요하거나 클라우드의 디바이스 측정값이 실제 페이지 뷰포트를 바꾸지 못하는 경우에는 Browser('chromium')을 사용하세요. 기존 로그인 상태로 이미 열려 있는 Chrome을 조작하려면 Browser('chrome')을 사용합니다. Browser('chrome', profile='Work')는 로그인 정보가 있는 임시 복사본을 실행하지만 Sync는 변경 내용을 되돌려 쓰지 않습니다. Windows에서는 쿠키가 잠길 수 있으므로 원래 Chrome을 먼저 종료해야 합니다(MIGRATING.md). 관리형 스텔스 기능, 프록시, CAPTCHA 처리, 로컬 설정 없는 환경이 필요하다면 클라우드가 여전히 적합한 기본값입니다(README). 다만 브라우저 시간 비용과 토큰 비용은 별도로 계산하세요.
커스텀 모델도 계속 사용할 수 있지만 경로를 올바르게 선택해야 합니다(MIGRATING.md).
- 게이트웨이 별칭:
bu-4.0,bu-4.0-mini,bu-4.0-pro,bu-fast,bu-ultrafast,bu-smart - 제공업체:
ChatOpenAI,ChatAnthropic,ChatGoogle, 또는groq:llama-3.3-70b-versatile같은 Pydantic AI 문자열 - Azure:
AZURE_OPENAI_ENDPOINT,AZURE_OPENAI_API_KEY,OPENAI_API_VERSION과 함께llm='azure:<deployment>'사용
LangChain 채팅 객체를 Agent(llm=...)에 넣으면 이제 TypeError가 발생합니다. bu-2-0처럼 폐기된 게이트웨이 이름도 브라우저가 시작되기 전에 거부됩니다. 병렬로 실행하는 각 에이전트는 자신만의 Browser()가 필요합니다. 두 에이전트가 하나를 공유하면 RuntimeError가 발생하지만, keep_alive=True인 브라우저 하나를 순차적으로 재사용하는 것은 가능합니다(MIGRATING.md).
추측하지 말고 오류 메시지와 함께 마이그레이션하기
1.0은 의도적으로 빠르게 실패합니다. 삭제된 임포트는 대체 항목을 알려주는 ImportError를 발생시키고, 지원하지 않는 Agent(...) 인자는 TypeError를 냅니다. 1.0이 처리할 수 없는 항목은 브라우저가 시작되거나 비용이 발생하기 전에 오류로 알려줍니다(MIGRATING.md). 반면 use_vision=True, vision_detail_level, max_actions_per_step, flash_mode, max_failures, highlight_elements 같은 일부 튜닝 옵션은 한 번씩 경고를 출력하지만 그대로 무시됩니다. 다만 use_vision=False는 여전히 의미가 있습니다. 스크린샷이 모델에 전달되지 않도록 하기 때문입니다.
실행이 시작된 뒤에는 동작이 달라집니다. run()은 일반적으로 예외를 던지는 대신 오류 결과를 반환하며, 상태는 status='error'로 표시되고 상세 내용은 result.error에 담깁니다. 취소만 여전히 예외로 전파됩니다. 따라서 성공 여부 확인 코드도 바꿔야 합니다.
# 0.x
history = await agent.run(max_steps=500)
ok = history.is_successful()
# 1.0
result = await agent.run(max_steps=100)
ok = result.is_done() and result.success is not False이제 is_done()은 실행이 끝났다는 뜻일 뿐입니다. 성공 여부는 모델이 finish(result, success)에서 내린 판정에 들어 있고, 모델이 판정을 내리지 않았다면 is_successful()은 None을 반환합니다. MIGRATING.md의 제거된 history API에 나열된 기존 단계별 헬퍼(action_names(), model_actions(), extracted_content(), save_as_playwright_script() 등)도 사라졌습니다. 대신 result.messages, result.status, result.partial, agent.workspace 안의 파일, result.judgement를 확인하세요.
우선 세 가지부터 수정하면 됩니다. max_steps를 Agent(...)에서 agent.run(max_steps=...)으로 옮기고, 제거된 콜백(on_step_start, pause, stop, multi_act, save_history)은 INFO 수준의 logging.getLogger('browser_use') 또는 BROWSER_USE_LOGGING_LEVEL=warning으로 대체하세요. 마지막으로 시크릿의 적용 범위를 다시 잡아야 합니다. 이제 도메인 범위가 지정된 시크릿은 일치하는 페이지에서만 입력되고, 이름이 bu_2fa_code로 끝나면 TOTP 시드로 처리됩니다. 기존 <secret>name</secret> 플레이스홀더는 오류를 내므로 type_secret('name')으로 바꿔야 합니다. 셀과 결과에서 값은 <secret:name>으로 마스킹되지만, 모델이 작성한 Python이 여전히 값을 읽을 수 있으므로 이는 샌드박스가 아니라 단순한 비식별화입니다(MIGRATING.md). 시간이 더 필요하다면 pip install 'browser-use<1'로 고정하고 별도 브랜치에서 마이그레이션하세요.
"browser use is more a python framework for building your own browsing agent" — r/ClaudeCode의 u/Starks1293
Reddit에서도 비슷한 평가가 나옵니다. browser-use는 브라우징 에이전트를 직접 만드는 프레임워크로 설명되며, 봇 방어가 적용된 사이트와 코드 수준의 제어가 필요한 경우 자주 언급됩니다. 다만 안정성은 모델과 사이트에 따라 크게 달라집니다. 한 실서비스 사용 보고에서는 간단한 폼 입력에 5분이 걸렸고 9단계가 실패했다고 전합니다.
프로덕션 전 확인할 것: Judge, 시크릿, 그리고 들쭉날쭉한 성공률
고급 사용에서 중요한 기능은 다음과 같습니다.
output_model_schema를 통한 타입 지정 결과와result.structured_output에서의 조회- 워크스페이스 업로드 및
workspace/downloads, 그리고result.downloads를 통한 다운로드 확인 allowed_domains,prohibited_domains,block_ip_addresses같은 도메인 제어 기능. 단, 이는 네트워크 샌드박스가 아니라 지시를 제대로 따르는 모델을 위한 보호 장치입니다.- 선택 기능인
web_search=True. 검색별 비용이result.cost_usd에 반영됩니다. browser-use --cli-mcp,browser-use skill install,browser-use --doctor를 통한 CLI/MCP 사용
1.0은 빠르게 변하는 프레임워크로 다루는 편이 좋습니다. 정확한 버전을 고정하고, 긴 작업에는 judge_context를 추가하세요. checkpoint('titles.json', titles, partial=True)로 중간 결과를 저장하고, 신뢰할 수 없는 작업은 컨테이너에서 실행해야 합니다. 도메인 제한과 시크릿 마스킹은 격리 기능이 아니기 때문입니다(README).
지금 마이그레이션할까, 버전을 고정할까
| 상황 | 권장 대응 |
|---|---|
| 새 에이전트 프로젝트, 클라우드 사용 가능 | ==1.0.7로 시작하고 bu-4.0 기본값과 Judge를 유지 |
| 비용이 중요한 배치 작업 | llm='bu-fast'와 judge=False를 지정하고 확장 전에 측정 |
| localhost / 인트라넷 / 커스텀 뷰포트 | 자체 모델과 Browser('chromium') 사용. 인자 없는 Browser()는 사용하지 않기 |
| 기존 0.x 프로덕션 시스템 | 메인 브랜치는 browser-use<1로 고정하고, 빠른 실패 오류를 활용해 별도 브랜치에서 마이그레이션 |
| CAPTCHA가 많은 흐름 | 전용 솔버 비용을 예산에 포함. 팀 테스트에서 자연어 지시만으로는 0/3이었음 |
멈춘 스크립트를 차단하거나 직접 감싸지 않은 비공개 API를 호출할 수 있다는 장점이 생기는 대신, 고정된 액션 메뉴가 제공하던 안전장치는 사라집니다. 사이트 특성상 이 교환이 유리하다면 마이그레이션하세요. 그렇지 않다면 기존 프로덕션 시스템은 평가가 끝날 때까지 browser-use<1로 고정해 두는 편이 안전합니다.
FAQ
browser-use 1.0에서 무엇이 달라졌나요?
0.x의 24개 액션 메뉴가 browser-harness 헬퍼와 raw CDP를 포함한 영속 Python REPL 하나로 대체됐습니다. 라이브러리의 약 80%가 제거됐고 Python 파일은 178개에서 43개로 줄었습니다. 기본값도 Browser Use Cloud, 게이트웨이 모델, 단일 BROWSER_USE_API_KEY 방식으로 바뀌었습니다.
0.x 코드는 깨지나요?
Agent, Browser, run(), final_result() 같은 주요 진입점은 여전히 존재합니다. 하지만 삭제된 임포트와 옵션은 비용이 발생하기 전에 ImportError 또는 TypeError를 내고, max_steps는 run()으로 이동했으며 Browser()는 이제 클라우드를 의미합니다. 그대로 유지하려면 browser-use<1로 고정하고, 마이그레이션한다면 먼저 별도 브랜치에서 진행하세요.
자체 모델과 로컬 브라우저를 계속 사용할 수 있나요?
가능합니다. ChatOpenAI, ChatAnthropic, ChatGoogle 같은 제공업체나 Pydantic AI 문자열을 전달하고, 새 로컬 브라우저에는 Browser('chromium'), 이미 열려 있는 Chrome에는 Browser('chrome')을 사용하면 됩니다. 클라우드 브라우저에서는 localhost에 접근할 수 없습니다.
browser-use 1.0에 필요한 Python 버전은 무엇인가요?
Python 3.11 이상 4.0 미만입니다. 의존성이 정확히 고정돼 다른 패키지와 충돌할 수 있으므로, 먼저 새 가상 환경에서 설치하는 것이 좋습니다.
실행 Judge를 어떻게 끄나요?
judge=False를 전달하면 추가 판정 요청을 건너뜁니다. 또는 허용 기준을 담은 judge_context를 전달해 판정의 실용성을 높일 수 있습니다. Judge에 스크린샷을 보내면 안 된다면 use_vision=False를 설정하세요.