Tutorial de Browser Use: abra páginas, clique em botões e extraia dados com um agente de IA

Depois de rodar uvx browser-use install, o verdadeiro ponto de bloqueio costuma ser a task. Se você escreve apenas “abra o site e dê uma olhada”, o agente não sabe o que precisa concluir. Ele pode ficar tentando, chutar ações ou terminar cedo demais.

Browser Use é uma biblioteca Python open source que permite à IA controlar um navegador Chromium para automação web. Ela roda localmente ou em um ambiente self-hosted, sem depender do Browser Use Cloud. Se você já entende o conceito de Browser Agent, este tutorial vai da instalação à primeira tarefa bem-sucedida, incluindo configuração segura, leitura de resultados e depuração.

O que é Browser Use: em uma frase

Browser Use é uma Python library for AI browser automation. Ela permite que um LLM Agent opere o navegador como uma pessoa: navegar, clicar, digitar, rolar, extrair dados e tirar capturas.

O foco é execução local ou self-hosted, sem depender do Browser Use Cloud. A biblioteca open source e o Cloud Agent têm APIs diferentes. Este guia usa a entrada open source; recursos do Cloud SDK como structured output, human-in-the-loop e live preview ficam fora do escopo.

Se você ainda está perguntando “o que é um Browser Agent?”, comece pelo artigo conceitual quando ele for publicado. Se o conceito já está claro, este guia responde à pergunta prática: como colocar isso para rodar agora?

Instalação e preparação: do uv à chave de API

Em 2026-06-30, o README oficial e o quickstart descrevem este caminho:

1. Requisito de versão do Python

Browser Use exige Python 3.11 ou superior. O exemplo do quickstart oficial cria um venv com Python 3.12, mas você pode escolher conforme seu ambiente.

2. Instalar uv (recomendado)

uv é um gerenciador moderno de pacotes Python desenvolvido pela Astral. Se você ainda não tem 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. Inicializar o projeto e instalar browser-use

# Criar o diretório do projeto
mkdir my-browser-use
cd my-browser-use

# Inicializar o projeto
uv init

# Instalar browser-use com dependências core
uv add "browser-use[core]"

# Sincronizar dependências
uv sync

Se você não usa uv, pip também funciona:

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

pip install "browser-use[core]"

4. Instalar o ambiente Chromium

Browser Use depende do Playwright por baixo, então instale o Chromium primeiro:

uvx browser-use install

Esse comando baixa e configura o Chromium para que o agente consiga iniciar uma instância do navegador.

5. Configurar a chave de API

Browser Use precisa se conectar a um LLM para entender tarefas e tomar decisões. O quickstart oficial recomenda ChatBrowserUse, um modelo projetado para tarefas de navegador.

Crie um arquivo .env na raiz do projeto:

# .env
BROWSER_USE_API_KEY=your_api_key_here

Se você usa OpenAI, Anthropic, Google Gemini ou Ollama local, preencha a chave correspondente:

OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key
GOOGLE_API_KEY=your_google_key

Escrever o primeiro script: modelo mínimo

O script mínimo precisa de três partes: importar módulos, criar o Agent e executar a tarefa.

from browser_use import Agent, Browser, ChatBrowserUse
import asyncio

async def main():
    # Criar uma instância do navegador (visível durante a depuração)
    browser = Browser(headless=False)

    # Criar a instância LLM
    llm = ChatBrowserUse()

    # Criar o Agent
    agent = Agent(
        task="Abra quotes.toscrape.com, role uma tela para baixo, clique no botão 'Next' e extraia todas as quotes e autores da segunda página",
        llm=llm,
        browser=browser
    )

    # Executar a tarefa com limite de passos
    history = await agent.run(max_steps=20)

    # Fechar o navegador
    await browser.close()

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

Esse script faz algumas coisas:

1. Browser(headless=False): mostra a janela do navegador e facilita a depuração. Depois, você pode mudar para headless=True.
2. ChatBrowserUse(): usa o modelo oficial para navegador. Você também pode trocar por ChatOpenAI(model="gpt-4o") ou outro modelo.
3. task precisa ser concreta: não escreva “abra o site e olhe”. Escreva “navegue até X URL, role, clique no botão Y, extraia o conteúdo Z”. Tarefas vagas causam loops ou encerramento cedo.
4. max_steps=20: limita o agente a no máximo 20 ações. Para a primeira tarefa, 10 a 20 passos ajudam a depurar sem deixar o agente preso na mesma ação.

Execute o script:

uv run python main.py

Não deixe o agente rodar para sempre: max_steps é a linha de segurança

max_steps limita quantos passos o agente pode executar. O valor oficial padrão é 100, mas na primeira tarefa vale baixar para 10-20.

Por que isso importa:

• O agente pode encontrar um clique falho, carregamento lento, popup ou elemento oculto e repetir a mesma ação.
• Sem limite, ele pode gastar tempo e tokens sem avançar.
• O objetivo da primeira tarefa é validar o ciclo, não concluir um workflow complexo com perfeição. Um limite menor revela o primeiro problema mais rápido.

Configuração recomendada:

# Primeira tarefa: 10-20 passos
await agent.run(max_steps=20)

# Tarefa complexa: aumente quando necessário, mas evite passar de 50 no começo
await agent.run(max_steps=50)

Configuração segura para iniciantes

Não comece usando sua conta principal logada, nem deixe o agente navegar livremente por qualquer site. Uma configuração inicial segura inclui:

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

1. Modo de depuração headless=False

browser = Browser(headless=False)

Assim a janela do navegador fica visível. Você consegue ver se o agente clicou no lugar errado, se a página travou ou se a descrição da tarefa está vaga. Depois de depurar, mude para headless=True.

2. Limitar a navegação com allowed_domains

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

allowed_domains impede que o agente navegue para outros domínios. Se a tarefa envolve apenas um site, mantenha essa restrição.

Browser Use aceita wildcards de subdomínio, como allowed_domains=["*.example.com"], mas não aceita wildcards de TLD. allowed_domains=["example.*"] não será reconhecido. Para um site fixo, o mais estável é escrever o domínio completo:

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

3. Usar um perfil isolado, não o Chrome principal

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

O agente cria um perfil separado do navegador. Ele não acessa cookies, sessão ou dados sensíveis do seu Chrome principal. Este primeiro tutorial usa apenas páginas públicas.

4. Não usar disable_security

O parâmetro disable_security desativa políticas de segurança do navegador. A documentação oficial marca isso como não recomendado. Se outro tutorial mencionar esse parâmetro, pule essa parte.

Ler resultados: o navegador se mover não basta

agent.run() retorna um AgentHistoryList. Você pode usar vários métodos helper para ler o resultado e o processo:

history = await agent.run(max_steps=20)

# Resultado final
result = history.final_result()
print("Resultado final:", result)

# Conteúdo extraído
extracted = history.extracted_content()
print("Conteúdo extraído:", extracted)

# Lista de erros
errors = history.errors()
print("Erros:", errors)

# Se houve erros
if history.has_errors():
    print("A tarefa encontrou erros")

# Lista de URLs visitadas
urls = history.urls()
print("URLs visitadas:", urls)

# Caminhos das capturas de tela
screenshots = history.screenshot_paths()
print("Capturas:", screenshots)

# Nomes das ações executadas
actions = history.action_names()
print("Ações:", actions)

# Total de passos
steps = history.number_of_steps()
print("Passos:", steps)

Um erro comum no começo é ver a janela do navegador se mover e assumir que a tarefa deu certo. Se final_result() estiver vazio, o agente pode ter parado cedo ou entendido a tarefa errado. Se errors() tiver conteúdo, leia esses erros antes de mexer no prompt.

Primeira tarefa: abrir, clicar, extrair

Use quotes.toscrape.com como primeiro cenário. É um site público feito para prática de scraping, não exige login e tem estrutura simples.

Tarefa 1: abrir e rolar

agent = Agent(
    task="Abra quotes.toscrape.com e role uma tela para baixo",
    llm=ChatBrowserUse(),
    browser=Browser(headless=False, allowed_domains=["quotes.toscrape.com"])
)
history = await agent.run(max_steps=10)
print("URLs visitadas:", history.urls())

Tarefa 2: clicar em um botão

agent = Agent(
    task="Abra quotes.toscrape.com e clique no botão 'Next' no rodapé da página",
    llm=ChatBrowserUse(),
    browser=Browser(headless=False, allowed_domains=["quotes.toscrape.com"])
)
history = await agent.run(max_steps=10)
print("Sucesso:", history.is_successful())

Tarefa 3: extrair conteúdo

agent = Agent(
    task="Abra quotes.toscrape.com e extraia todos os textos das quotes e seus autores da primeira página",
    llm=ChatBrowserUse(),
    browser=Browser(headless=False, allowed_domains=["quotes.toscrape.com"])
)
history = await agent.run(max_steps=15)
extracted = history.extracted_content()
print("Conteúdo extraído:", extracted)

Tarefa 4: combinar passos

agent = Agent(
    task="Abra quotes.toscrape.com, clique no botão 'Next' e extraia todos os textos das quotes e seus autores da segunda página",
    llm=ChatBrowserUse(),
    browser=Browser(headless=False, allowed_domains=["quotes.toscrape.com"])
)
history = await agent.run(max_steps=20)
print("Resultado final:", history.final_result())
print("Erros:", history.errors())

Onde olhar quando falhar

Quando o agente retorna resultado vazio, mostra erro ou fica travado, siga esta lista:

1. Falha no clique

• Verifique se history.errors() contém “click failed” ou “element not found”
• Adicione um fallback de teclado à tarefa: “se o clique falhar, use Tab para focar o botão e pressione Enter”
• Veja history.screenshot_paths() para saber se o elemento estava visível

2. Extração vazia

• Verifique history.urls() para confirmar que a página abriu
• Veja history.screenshot_paths() para entender o estado da página
• Confirme se a tarefa está clara: “extraia todos os textos das quotes e seus autores”, não “olhe o conteúdo”

3. Página travada

• Verifique se allowed_domains bloqueou uma navegação
• Verifique a conexão e o tempo de carregamento
• Reduza max_steps ou adicione comportamento de timeout: “se a página não carregar em 10 segundos, volte para a página inicial”

4. Resultado incompleto

• Verifique se max_steps interrompeu cedo demais
• Veja history.number_of_steps() para saber quantos passos foram usados
• Ajuste a descrição e divida a tarefa em subtarefas

5. Falha geral da tarefa

• Verifique se a chave de API em .env está correta
• Confirme se o modelo é compatível: ChatBrowserUse, OpenAI, Anthropic, Google Gemini ou Ollama local
• Veja se a tarefa está abstrata demais: troque “abra o site e olhe” por ações concretas

Beta Agent vs API estável: duas entradas

Em 2026-06-30, o README oficial descreve duas rotas de importação do Agent:

API estável

from browser_use import Agent, Browser

Essa é a entrada estável. Se você já usava Browser Use, pode continuar nesse caminho.

Railway - Plataforma de deploy moderna, sem ops complexas, no ar em minutos

Começar agora →Anúncio

API beta (0.13)

from browser_use.beta import Agent, BrowserProfile, ChatBrowserUse

Esse é o beta agent 0.13, sustentado por Rust core e browser harness. O README oficial diz que usuários existentes podem continuar com a API estável, enquanto novos usuários podem testar a beta.

Se não tiver certeza de qual usar, confira o README oficial atual. Este guia usa exemplos estáveis; a API beta pode ser diferente.

Open source vs Cloud: saiba onde está a fronteira

Este guia usa a biblioteca open source do Browser Use localmente.

Browser Use Cloud é um serviço hospedado com outra API:

• O Cloud SDK atualmente usa API v3
• Cloud oferece structured output, human-in-the-loop, live preview, persistent profiles e outros recursos de produção
• O SDK Python/TypeScript do Cloud não é compatível com a API da biblioteca open source

Quando considerar Cloud:

• Deploy em produção ou runtime hospedado
• Necessidades avançadas como stealth, CAPTCHA e proxies, que este guia não cobre
• Múltiplas contas, perfis persistentes e colaboração em equipe

Este guia fica na entrada local. Uso de Cloud e preços entram em outro artigo.

Próximos passos

Este tutorial cobre a entrada local no Browser Use: instalação, chaves de API, script mínimo, abrir uma página, clicar em um botão, extrair informações e depurar falhas.

Bons próximos passos:

• Publicado: guia prático de automação de navegador com OpenClaw, Computer-Use Agent: deixe a IA operar seu computador, guia de plugins MCP
• Temas futuros: Playwright MCP com Claude, Codex e Cursor; engenharia com Stagehand; escolha de ferramentas Browser Use; sessões e autenticação; infraestrutura em nuvem; conformidade e segurança
• Documentação oficial: quickstart, prompting guide, browser config

Primeiro faça uma tarefa funcionar em quotes.toscrape.com ou em uma página pública do GitHub. Depois pense em sessões autenticadas e Cloud.