Цена для ранних подписчиков (до 25 декабря) сохраняется, пока подписка активна: Go за $10/мес. (обычно $20), Plus с Opus 5.5 всего за $30/мес. (обычно $50)Оформить подписку →

Browser-Use 1.0: настройка и миграция

Если вы строили проект на browser-use 0.x, переход на 1.0 меняет не только API, но и саму архитектуру. Вместо 24 отдельных браузерных действий появляется один постоянный Python REPL, а вызов Browser() теперь запускает облачный браузер. В этом руководстве разберем фиксацию версии 1.0.7, первый запуск и перенос кода с 0.x — по описанию релиза 1.0.7, файлу MIGRATING.md и инженерной публикации от 20 ноября.

Запускаем 1.0 за пять минут

Сначала зафиксируйте версию. Версия 1.0.0 вышла 10 ноября 2026 года, а к 20 ноября стабильной была уже 1.0.7; при этом 1.0.8rc1 оставалась предварительным релизом (список релизов). В README отдельно сказано: не используйте >=, поскольку API может ломаться при переходе между минорными версиями.

bash
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, затем либо экспортируйте его, либо запустите помощник входа:

bash
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-серверах и headless-машинах кандидат в релиз 1.0.8 выводит ссылку и код подтверждения — подтвердить вход можно с другого устройства (заметки к 1.0.8rc1).

Первый запуск занимает всего три строки:

python
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 и модель шлюза по умолчанию (README, Path 1 / Path 3, настройки по умолчанию в MIGRATING.md). Если для проверки вы не хотите тратить деньги на облако, сразу добавьте Browser('chromium') и передайте собственную модель через llm.

Что пришло на смену 24 действиям

В browser-use 0.x модель получала меню: на каждом шаге нужно было выбрать одно действие из DOM-снимка. В версии 1.0 этого меню больше нет. Вместо него модель получает один основной инструмент python — постоянный REPL со встроенными помощниками browser-harness и заранее импортированным низкоуровневым cdp(). Всё это построено на Pydantic AI (инженерная публикация):

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)."""

В результате из проекта удалили 136 905 строк и добавили 29 601 строку в 554 файлах, а число Python-файлов сократилось со 178 до 43 (инженерная публикация).

Хороший пример — восстановление после зависшей страницы. Агент вызвал Page.stopLoading, заблокировал застрявший скрипт, перезагрузил страницу, обнаружил ее приватный JSONP-эндпоинт, затем получил 730 дат партиями и повторил только неудачные запросы. В итоге он вернул 4 720 строк — без отдельного инструмента для каждого из этих действий (инженерная публикация).

Команда придерживается простого правила: добавлять помощника стоит только тогда, когда модель не может самостоятельно переписать нужную логику, прочитав ее один раз. Исключение — CAPTCHA. В небольшом staging-тесте текстовые инструкции получили результат 0/3 на hCaptcha, тогда как специализированный инструмент solve_captcha справился в 6 случаях из 6: он включает переключатель решателя, недоступный самой странице (инженерная публикация).

С заявлениями о стоимости и скорости лучше смотреть не только на заголовок, но и на сноску. В публикации от 20 ноября говорится, что те же три модели в версии 1.0 набрали на 14–33 балла больше при стоимости в 2,7–5,2 раза ниже, чем в 0.x. Тест включал 200 задач, из которых оценивались 180, и проводился 8 ноября. Авторы отдельно предупреждают: для каждой модели был выполнен всего один прогон, а настройки изменились, поэтому приписывать весь результат одной лишь переработке инструментов нельзя (инженерная публикация).

Более показательные сравнения уже. Версия 1.0.4 получила 76,1 балла против 76,0 у 1.0.3, а стоимость модели снизилась с $0.434 до $0.208 за задачу после удаления лишних скриншотов из пакета при сохранении кэширования промптов (заметки к 1.0.4). В BU Bench v2 режим 1.0 ultrafast показал 62,5 балла, $0.070 и 650 секунд против 56,3 балла, $0.082 и 743 секунд у Browser Use Pi. Авторы отмечают, что после исключения ошибок провайдера разница перестает быть статистически значимой. Рассчитывайте на меньшую стоимость и более высокую скорость, но не на автоматический рост качества.

Настройки по умолчанию, которые незаметно меняют браузер и счет

Таблица составлена по MIGRATING.md и заметкам к релизу 1.0.6. Она отражает состояние 1.0.7 и смену модели по умолчанию в середине ветки 1.0, о которой часто умалчивают старые руководства.

Настройка0.x1.0.7
llm=NoneМодель нужно было указатьbu-4.0 через шлюз Browser Use
Цена bu-4.0н/д$1.80 / 1 млн входных токенов, $9.00 / 1 млн выходных
Цена bu-fastн/д$0.12 / 1 млн входных токенов, $0.60 / 1 млн выходных
Browser()Локальный ChromiumОблачный браузер Browser Use
Локальный браузерПо умолчаниюНужно явно указать Browser('chromium')
API-ключПо одному на провайдераОдин BROWSER_USE_API_KEY
max_steps500100 (один шаг зарезервирован под выдачу результата)
Тайм-аут агентаНе задан1 700 секунд без учета запуска и завершения
Проверяющий агентВключался вручнуюПо умолчанию judge=True
Рассуждения / режимн/дreasoning='medium', mode='ultrafast' для bu-fast / bu-ultrafast
Gateway model price per 1M tokens, bu-4.0 versus bu-fast

Особенно важны три нюанса. Во-первых, модель по умолчанию изменилась уже внутри ветки 1.0: до версии 1.0.5 использовалась bu-fast, но в 1.0.6 ее заменили на bu-4.0, которая стоит в 15 раз дороже за токены. В собственном примере проекта короткий тест обходится в $0.022 на bu-4.0 против $0.0014 на bu-fast. Если нужен прежний уровень расходов, укажите llm='bu-fast' явно. Во-вторых, простой вызов Browser() теперь создает облачный браузер по цене $0.06 за час работы, не считая стоимости модели и отдельных поисковых запросов (README). Облачные браузеры не имеют доступа к localhost и приватным IP-адресам (MIGRATING.md). В-третьих, один шаг — это один запрос к модели и одна ячейка Python. Поэтому новый лимит в 100 шагов одновременно ограничивает и расходы; значения max_steps < 1 или timeout <= 0 теперь вызывают ошибку еще до запуска браузера (MIGRATING.md).

Проверяющий агент — еще одна скрытая статья расходов. После любого запуска хотя бы с одним шагом ваша модель делает дополнительный низкозатратный запрос: ей передается до 120 000 символов трассировки и, если включено зрение, последние четыре уникальных изображения, включая финальную страницу. Данные отправляются без редактирования (MIGRATING.md). Результат доступен в result.judgement и содержит поля success, failure_reason, gotchas, а также флаги бота и CAPTCHA. Стоимость учитывается в result.cost_usd. Отключить проверку можно через judge=False, а сделать ее полезнее — передав ожидаемый ответ в judge_context. Если скриншоты не должны покидать ваш контур, установите use_vision=False.

Когда локальный браузер обязателен

Выбирайте браузер исходя из требований к сети, а не по привычке. Идентификатор модели в примере ниже — это условный провайдер из локального примера в README (README):

python
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())

Используйте Browser('chromium') для localhost, приватных сетей и нестандартных размеров окна, а также везде, где вызовы device metrics из облака не должны подменять фактический viewport страницы. Browser('chrome') позволяет управлять уже открытым Chrome с существующими авторизациями. Вариант Browser('chrome', profile='Work') запускает временную копию с логинами, но изменения Sync в нее не записываются. В Windows перед этим нужно закрыть исходный Chrome, иначе он заблокирует cookies (MIGRATING.md). Облако остается удобным выбором для управляемого stealth-режима, прокси, обработки CAPTCHA и запуска без локальной настройки (README), но часы работы браузера нужно считать отдельно от токенов.

Собственные модели по-прежнему поддерживаются, но способ подключения имеет значение (MIGRATING.md):

  • Псевдонимы шлюза: bu-4.0, bu-4.0-mini, bu-4.0-pro, bu-fast, bu-ultrafast, bu-smart
  • Провайдеры: ChatOpenAI, ChatAnthropic, ChatGoogle или строки Pydantic AI вроде groq:llama-3.3-70b-versatile
  • Azure через llm='azure:<deployment>' с переменными AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_KEY и OPENAI_API_VERSION

Объекты чата 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. Исключение — отмена, которая по-прежнему передается наружу. Проверки нужно обновить:

python
# 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, если модель не вынесла вердикт. Старые помощники для истории по шагам — action_names(), model_actions(), extracted_content(), save_as_playwright_script() и остальные API из списка удаленных в MIGRATING.md — исчезли. Вместо них используйте result.messages, result.status, result.partial, файлы в agent.workspace и result.judgement.

Начните с трех изменений. Перенесите max_steps из Agent(...) в agent.run(max_steps=...). Удаленные callbacks — on_step_start, pause, stop, multi_act, save_history — замените на logging.getLogger('browser_use') с уровнем INFO или на BROWSER_USE_LOGGING_LEVEL=warning. Наконец, пересмотрите работу с секретами. Теперь секреты с областью действия домена подставляются только на соответствующих страницах; имена, оканчивающиеся на bu_2fa_code, считаются TOTP-семенами; старый placeholder <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" — u/Starks1293 на r/ClaudeCode

Так browser-use описывают и пользователи на Reddit: это скорее фреймворк для создания собственных браузерных агентов, особенно полезный на сайтах с защитой от ботов и там, где нужен контроль на уровне кода. Но надежность по-прежнему зависит от модели и конкретного сайта. В одном отчете о продакшене базовое заполнение формы заняло пять минут и закончилось девятью неудачными шагами.

Перед продакшеном: проверка, секреты и реальная надежность

Для продвинутых сценариев важны следующие возможности:

  • Типизированные результаты через output_model_schema, доступные в result.structured_output
  • Загрузка файлов в workspace и каталог workspace/downloads с результатами в result.downloads
  • Ограничения доменов (allowed_domains, prohibited_domains, block_ip_addresses), которые ограничивают действия согласованной модели, но не изолируют сеть
  • Поиск в интернете через web_search=True, включаемый вручную и оплачиваемый за каждый запрос через result.cost_usd
  • CLI/MCP через browser-use --cli-mcp, browser-use skill install и browser-use --doctor

Относитесь к 1.0 как к быстро меняющемуся фреймворку: фиксируйте точные версии, добавляйте judge_context для длинных задач, сохраняйте промежуточные результаты через checkpoint('titles.json', titles, partial=True) и запускайте непроверенные задачи в контейнерах. Ограничения доменов и маскирование секретов не заменяют изоляцию (README).

Переходить сейчас, фиксировать версию или остаться на 0.x?

СитуацияЧто делать
Новый агент, облако подходитНачните с ==1.0.7, оставьте bu-4.0 по умолчанию и не отключайте проверку
Пакетные задачи с жестким бюджетомПередайте llm='bu-fast' и judge=False, затем измерьте результат перед масштабированием
Localhost / интранет / нестандартный viewportИспользуйте Browser('chromium') и собственную модель; простой Browser() не подойдет
Существующий продакшен на 0.xОставьте в основной ветке browser-use<1, а миграцию выполняйте в отдельной ветке, ориентируясь на ранние ошибки
Сценарий с большим количеством CAPTCHAЗаложите бюджет на специализированный решатель: одни текстовые инструкции в тесте команды дали результат 0/3

Вы получаете агента, который способен остановить зависший скрипт или вызвать приватный API, для которого вы никогда не писали отдельный инструмент. Но взамен исчезают ограничения фиксированного меню действий. Если такой компромисс подходит вашему сайту, мигрируйте. В противном случае для уже работающих продакшен-систем безопаснее пока зафиксировать browser-use<1 и спокойно оценить переход.

FAQ

Что нового в browser-use 1.0?

Один постоянный Python REPL со вспомогательными функциями browser-harness и низкоуровневым CDP заменяет меню из 24 действий в 0.x. Библиотека стала примерно на 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.

Какая версия Python нужна browser-use 1.0?

Python 3.11 или новее, но ниже 4.0. Точные версии зависимостей могут конфликтовать с другими пакетами, поэтому сначала установите browser-use в новое виртуальное окружение.

Как отключить проверку запуска?

Передайте judge=False, чтобы пропустить дополнительный запрос проверки, или используйте judge_context с критериями приемки, чтобы сделать вердикт полезнее. Установите use_vision=False, если скриншоты проверки нельзя отправлять модели.