Se você construiu algo com o browser-use 0.x, prepare-se para uma mudança de arquitetura — e de padrão de configuração — no 1.0. As 24 ações de navegador deram lugar a um único REPL Python persistente, enquanto Browser() agora representa um navegador na nuvem. Este guia mostra como fixar a versão 1.0.7, fazer a primeira execução e migrar do 0.x, com base nas notas de lançamento da 1.0.7, no MIGRATING.md e no post de engenharia de 20 de novembro.
Coloque o 1.0 para rodar em 5 minutos
Comece fixando a versão. A 1.0.0 chegou em 10 de novembro de 2026, e a 1.0.7 era a tag estável em 20 de novembro; a 1.0.8rc1 estava disponível como pré-lançamento (releases). O README é explícito: nunca use >=, porque as APIs podem quebrar entre versões menores.
uv add 'browser-use==1.0.7'
# or
pip install 'browser-use==1.0.7'Os requisitos são simples: Python 3.11 ou mais recente e abaixo da 4.0 (README, PyPI). Todas as dependências são fixadas com ==, o que favorece a reprodutibilidade, mas pode causar conflitos se a sua aplicação também exigir outra versão de pydantic, mcp ou google-genai.
Faça a autenticação uma vez. Crie uma chave em cloud.browser-use.com e exporte-a ou execute o auxiliar de login:
export BROWSER_USE_API_KEY=bu_...
# or
browser-use loginO login salva as credenciais em ~/.config/browser-harness/auth.json e elas ficam disponíveis para a CLI, o servidor MCP e o browser-harness (MIGRATING.md). Em contêineres, use BROWSER_USE_AUTO_LOGIN=true. Em máquinas acessadas por SSH ou sem interface gráfica, a candidata 1.0.8 exibe um link e um código de aprovação que pode ser confirmado em outro dispositivo (notas da 1.0.8rc1).
A primeira execução cabe em três linhas:
from browser_use import Agent
result = Agent(
"Find the number of stars of the browser-use repo"
).run_sync()
print(result.final_result())Por padrão, essa execução gera cobrança: ela usa um navegador do Browser Use Cloud e o modelo padrão do gateway (README, caminhos 1 e 3, padrões do MIGRATING.md). Se quiser testar sem gastar nada na nuvem, já passe Browser('chromium') e o seu próprio llm.
O que entrou no lugar das 24 ações
No browser-use 0.x, o modelo recebia um menu e escolhia uma ação por etapa a partir de um dump do DOM. A versão 1.0 eliminou esse menu. Agora existe uma única ferramenta principal, python: um REPL persistente com os auxiliares do browser-harness e o cdp() puro já importados, construído sobre o Pydantic AI (post de engenharia):
async def python(ctx: RunContext[Session], code: str) -> list[Any]:
"""Run Python in the persistent REPL
(browser-harness helpers and raw cdp() pre-imported)."""A remoção eliminou 136.905 linhas e adicionou 29.601 em 554 arquivos; a quantidade de arquivos Python caiu de 178 para 43 (post de engenharia).
Um exemplo particularmente claro é a recuperação de uma página travada: o agente chamou Page.stopLoading, bloqueou o script preso, recarregou a página, encontrou o endpoint JSONP privado, buscou 730 datas em lotes e repetiu apenas os lotes que falharam — retornando 4.720 linhas sem uma ferramenta dedicada para nenhuma dessas tarefas (post de engenharia).
A regra mantida pela equipe foi simples: só criar um auxiliar quando o modelo não conseguir reescrevê-lo depois de ler seu código uma vez. CAPTCHA é a exceção. Instruções em texto marcaram 0/3 no hCaptcha em um pequeno teste de staging, enquanto a ferramenta dedicada solve_captcha conseguiu 6/6, porque ela ativa um mecanismo ao qual a página não tem acesso (post de engenharia).
Sobre custo e velocidade, vale ler a nota de rodapé antes de comemorar o título. O post de 20 de novembro relata que os mesmos três modelos obtiveram de 14 a 33 pontos a mais, com custo de 2,7 a 5,2 vezes menor no 1.0 em comparação com o 0.x, em um teste de 200 tarefas realizado em 8 de novembro, das quais 180 foram pontuadas. O próprio texto alerta que houve apenas uma execução por modelo e que os padrões foram alterados; portanto, o redesenho das ferramentas não pode levar todo o crédito (post de engenharia).
As comparações mais limpas são mais específicas. A versão 1.0.4 marcou 76,1 contra 76,0 da 1.0.3, enquanto o custo do modelo caiu de US$ 0,434 para US$ 0,208 por tarefa depois que a remoção de screenshots em lote preservou o cache de prompt (notas da 1.0.4). No BU Bench v2, o ultrafast do 1.0 marcou 62,5, custou US$ 0,070 e levou 650 segundos, contra 56,3, US$ 0,082 e 743 segundos do Browser Use Pi. Segundo os autores, a diferença perde relevância quando os erros do provedor são excluídos. Planeje algo mais barato e rápido — não necessariamente mais inteligente.
Padrões que mudam silenciosamente sua conta e seu navegador
Tabela compilada a partir do MIGRATING.md e das notas da versão 1.0.6. Ela representa a 1.0.7 e inclui a troca de modelo padrão ocorrida no meio da série 1.0, algo que guias antigos costumam ignorar.
| Configuração | 0.x | 1.0.7 |
|---|---|---|
llm=None | Exigia um modelo | bu-4.0 pelo gateway do Browser Use |
Preço do bu-4.0 | não se aplica | US$ 1,80 / 1 milhão de tokens de entrada, US$ 9,00 / 1 milhão de tokens de saída |
Preço do bu-fast | não se aplica | US$ 0,12 / 1 milhão de tokens de entrada, US$ 0,60 / 1 milhão de tokens de saída |
Browser() | Chromium local | Navegador do Browser Use Cloud |
| Navegador local | Padrão | Browser('chromium') explicitamente |
| Chave de API | Uma por provedor | Uma BROWSER_USE_API_KEY |
max_steps | 500 | 100 (uma etapa fica reservada para a entrega) |
| Timeout do agente | Não especificado | 1.700 segundos, sem contar inicialização e encerramento |
| Judge | Opcional | judge=True por padrão |
| Raciocínio / modo | não se aplica | reasoning='medium', mode='ultrafast' em bu-fast / bu-ultrafast |
Três armadilhas merecem destaque. A primeira é a troca do modelo padrão no meio da série 1.0: até a 1.0.5, o padrão era bu-fast, mas a 1.0.6 mudou para bu-4.0, cujo preço por token é 15 vezes maior. O próprio projeto estima o mesmo teste curto em US$ 0,022 no bu-4.0, contra US$ 0,0014 no bu-fast. Passe llm='bu-fast' explicitamente se quiser manter o perfil de custo antigo. A segunda é que um Browser() sem argumentos agora cria um navegador na nuvem por US$ 0,06 por hora de navegador, além dos custos do modelo e das buscas (README); esses navegadores não conseguem acessar localhost nem IPs privados (MIGRATING.md). A terceira: uma etapa equivale a uma requisição ao modelo e a uma célula Python. Assim, o limite menor de 100 etapas também funciona como limite de gasto; max_steps < 1 ou timeout <= 0 agora falha antes de o navegador ser iniciado (MIGRATING.md).
O judge é outro custo oculto. Depois de qualquer execução com pelo menos uma etapa, o seu próprio modelo faz uma requisição adicional de baixa complexidade usando até 120.000 caracteres do trace e, quando a visão está ativada, as quatro últimas imagens distintas, incluindo a página final. Tudo é enviado sem redação (MIGRATING.md). O resultado fica em result.judgement, com success, failure_reason, gotchas e indicadores de bot/CAPTCHA; o custo entra em result.cost_usd. Desative o recurso com judge=False ou passe judge_context com a resposta esperada. Se screenshots nunca puderem sair do seu ambiente, use use_vision=False.
Quando for necessário, fique no ambiente local
Escolha o navegador de acordo com a rede que ele precisa acessar, não por hábito. O identificador de modelo abaixo é o exemplo ilustrativo de provedor usado no trecho do README sobre navegador local (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())Use Browser('chromium') para localhost, redes privadas, viewports personalizados ou situações em que chamadas de métricas do dispositivo na nuvem não alterariam o viewport real da página. Use Browser('chrome') para controlar o Chrome já aberto, com os logins existentes. Já Browser('chrome', profile='Work') inicia uma cópia temporária com os logins, mas sem gravar alterações no Sync; no Windows, feche primeiro o Chrome original, pois ele bloqueia os cookies (MIGRATING.md). A nuvem continua sendo a opção certa quando você precisa de stealth gerenciado, proxies, tratamento de CAPTCHA ou nenhuma configuração local (README) — apenas contabilize as horas de navegador separadamente dos tokens.
Modelos personalizados continuam funcionando, mas o caminho usado importa (MIGRATING.md):
- Aliases do gateway:
bu-4.0,bu-4.0-mini,bu-4.0-pro,bu-fast,bu-ultrafast,bu-smart - Provedores:
ChatOpenAI,ChatAnthropic,ChatGoogleou strings do Pydantic AI, comogroq:llama-3.3-70b-versatile - Azure por meio de
llm='azure:<deployment>', comAZURE_OPENAI_ENDPOINT,AZURE_OPENAI_API_KEYeOPENAI_API_VERSION
Objetos de chat do LangChain usados como Agent(llm=...) agora geram TypeError, e nomes antigos do gateway, como bu-2-0, são rejeitados antes de o navegador ser iniciado. Cada agente paralelo precisa do seu próprio Browser(); compartilhar um navegador entre dois agentes gera RuntimeError. Um navegador com keep_alive=True, porém, pode ser reutilizado em sequência (MIGRATING.md).
Migre sem adivinhar: deixe o erro indicar o caminho
A versão 1.0 falha rápido de propósito. Imports removidos geram ImportError informando a substituição, argumentos não suportados de Agent(...) geram TypeError, e qualquer recurso que o 1.0 não consiga honrar falha antes de o navegador ser iniciado ou de haver cobrança (MIGRATING.md). Um grupo menor — use_vision=True, vision_detail_level, max_actions_per_step, flash_mode, max_failures, highlight_elements e flags de ajuste semelhantes — continua sendo aceito, mas é ignorado, com um aviso para cada item. Já use_vision=False continua relevante, pois impede que screenshots sejam enviados ao modelo.
Depois da inicialização, o comportamento muda: em geral, run() retorna um resultado com erro em vez de lançar uma exceção, usando status='error' e colocando os detalhes em result.error. Apenas o cancelamento continua sendo propagado. Atualize suas verificações:
# 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 Falseis_done() agora indica apenas que a execução terminou. O sucesso fica no veredito finish(result, success) do modelo, e is_successful() retorna None quando o modelo não forneceu um veredito. Os antigos auxiliares de histórico por etapa — action_names(), model_actions(), extracted_content(), save_as_playwright_script() e os demais listados entre as APIs de histórico removidas no MIGRATING.md — desapareceram. No lugar deles, consulte result.messages, result.status, result.partial, os arquivos em agent.workspace e result.judgement.
Comece com três alterações: mova max_steps de Agent(...) para agent.run(max_steps=...); substitua callbacks removidos (on_step_start, pause, stop, multi_act, save_history) por logging.getLogger('browser_use') no nível INFO ou por BROWSER_USE_LOGGING_LEVEL=warning; e reveja o escopo dos segredos. Segredos com escopo de domínio agora só são digitados em páginas compatíveis. Nomes terminados em bu_2fa_code são tratados como sementes TOTP. O antigo placeholder <secret>name</secret> gera erro e deve virar type_secret('name'). Os valores aparecem como <secret:name> nas células e nos resultados — isso é redação, não um sandbox, pois o Python escrito pelo modelo ainda pode lê-los (MIGRATING.md). Se precisar de tempo, fixe pip install 'browser-use<1' e faça a migração em uma branch.
"browser use is more a python framework for building your own browsing agent" — u/Starks1293 no r/ClaudeCode
Essa descrição combina com a forma como usuários falam do projeto em discussões no Reddit: um framework para construir agentes de navegação, frequentemente citado em sites protegidos por mecanismos ant bots e em cenários que exigem controle no nível do código. A confiabilidade ainda depende do modelo e do site; um relato de produção descreve cinco minutos e nove etapas malsucedidas em um preenchimento básico de formulário.
Antes de ir para produção: judge, segredos e uma realidade nem sempre confiável
Para usos mais avançados, o que realmente importa:
- Resultados tipados com
output_model_schema, lidos emresult.structured_output - Uploads para o workspace e
workspace/downloads, com acesso porresult.downloads - Controles de domínio (
allowed_domains,prohibited_domains,block_ip_addresses), que protegem um modelo alinhado, mas não isolam a rede web_search=Trueopcional, cobrado por busca e incluído emresult.cost_usd- CLI/MCP por meio de
browser-use --cli-mcp,browser-use skill installebrowser-use --doctor
Trate o 1.0 como um framework em rápida evolução: fixe versões exatas, adicione judge_context em tarefas longas, salve o trabalho parcial com checkpoint('titles.json', titles, partial=True) e execute tarefas não confiáveis em contêineres, pois limites de domínio e redação de segredos não equivalem a isolamento (README).
Migrar agora, fixar a versão ou continuar no 0.x?
| Situação | Faça isto |
|---|---|
| Novo projeto de agente, nuvem permitida | Comece com ==1.0.7, mantenha bu-4.0 como padrão e deixe o judge ativado |
| Jobs em lote sensíveis a custo | Passe llm='bu-fast' e judge=False; meça antes de escalar |
| Localhost / intranet / viewport personalizado | Use Browser('chromium') com seu próprio modelo; nunca um Browser() sem argumentos |
| 0.x existente em produção | Fixe browser-use<1 na branch principal e migre em uma branch usando os erros de falha rápida |
| Fluxo com muito CAPTCHA | Reserve orçamento para o solver dedicado; instruções em texto sozinhas marcaram 0/3 no teste da equipe |
Você ganha um agente capaz de bloquear um script travado ou chamar uma API privada que nunca foi encapsulada, mas perde as proteções de um menu fixo de ações. Se essa troca fizer sentido para o seu site, migre. Caso contrário, continuar com browser-use<1 enquanto você avalia a nova versão continua sendo a opção mais segura para sistemas existentes em produção.
Perguntas frequentes
O que há de novo no browser-use 1.0?
Um REPL Python persistente, com auxiliares do browser-harness e CDP puro, substitui o menu de 24 ações do 0.x e remove aproximadamente 80% da biblioteca — os arquivos Python caíram de 178 para 43. Os padrões passam a usar o Browser Use Cloud, um modelo do gateway e uma única BROWSER_USE_API_KEY.
Meu código 0.x vai quebrar?
Os principais pontos de entrada (Agent, Browser, run(), final_result()) continuam existindo, mas imports e opções removidos geram ImportError ou TypeError antes da cobrança. Além disso, max_steps foi movido para run() e Browser() agora significa nuvem. Para continuar no 0.x, fixe browser-use<1; se for migrar, comece por uma branch.
Ainda posso usar meu próprio modelo e um navegador local?
Sim. Passe provedores como ChatOpenAI, ChatAnthropic e ChatGoogle, ou uma string do Pydantic AI. Use Browser('chromium') para um navegador local novo ou Browser('chrome') para o Chrome já aberto. Navegadores na nuvem não conseguem acessar localhost.
Qual versão do Python o browser-use 1.0 exige?
Python 3.11 ou mais recente e abaixo da 4.0. As versões exatas das dependências podem entrar em conflito com outros pacotes, então comece instalando o projeto em um ambiente virtual novo.
Como desativo o judge da execução?
Passe judge=False para ignorar a requisição adicional de avaliação ou use judge_context com seus critérios de aceitação para tornar o veredito mais útil. Defina use_vision=False se screenshots do judge não puderem ser enviados.