Browser Use com proxy: como configurar o agente de IA

No seu notebook, o agente do Browser Use faz sem problemas um pedido de teste na loja do ambiente de homologação. Em um servidor na nuvem, a mesma tarefa abre o site a partir de um endereço de datacenter em outro país: a loja mostra outra moeda, e o firewall do ambiente de homologação, que só deixa entrar IPs conhecidos, recusa o agente. Você adiciona um proxy como http://user:pass@pr.proxynet.io:8000, e agora todas as páginas falham com net::ERR_NO_SUPPORTED_PROXIES.

Este guia mostra como o Browser Use funciona, a instalação, um proxy com usuário e senha, a verificação do IP de saída, as sessões fixas e rotativas, os limites de domínio, os segredos e uma etapa de aprovação humana. Testamos todos os scripts com browser-use 0.13.10 e Python 3.13 por meio de um proxy local de teste que exige senha. Como não havia chave de API de nenhum LLM na máquina de teste, um script escrito de antemão deu as respostas do modelo; o navegador, o proxy, o filtro de domínios e o mascaramento dos segredos funcionaram de verdade.

O que é o Browser Use?#

O Browser Use é uma biblioteca Python que transforma um modelo de linguagem em um agente de navegador. Você descreve a tarefa em palavras simples, e o modelo decide os cliques, o que digitar e a rolagem da página. O repositório no GitHub o descreve como "Agents that use the browser" (agentes que usam o navegador); a licença é MIT, e a versão mais recente no PyPI hoje é a 0.13.10, publicada em 4 de setembro de 2026, para Python 3.11 ou mais recente.

A versão 0.13.10 conversa com o Chromium diretamente pelo Chrome DevTools Protocol (CDP); o Playwright não está entre as dependências. O modelo pode vir da OpenAI, da Anthropic, do Google, de um servidor local do Ollama ou dos modelos hospedados do próprio Browser Use. O Browser Use Cloud, um serviço pago separado com navegadores hospedados, não faz parte deste guia.

Como um agente planeja e usa ferramentas em geral está explicado em Agentes de IA: planejamento, ferramentas e memória; os navegadores com um agente embutido, em O que é um navegador com IA?.

Como funciona um agente do Browser Use?#

Uma execução de agent.run() passa por estas etapas:

1. O navegador inicia com um perfil temporário novo. O proxy é passado ao Chromium como parâmetro de inicialização.
2. Uma URL presente na tarefa é aberta diretamente, sem chamada ao modelo.
3. A página vira texto. Cada elemento que o agente pode usar recebe um número, junto com o texto visível. Com use_vision=True (o padrão), uma captura de tela é adicionada.
4. O modelo responde em JSON: uma avaliação da última etapa, uma memória curta, o próximo objetivo e até cinco ações, como navigate, click, input, scroll, extract ou done.
5. A biblioteca executa as ações, confere cada URL nova com as suas regras de domínio e preenche os segredos onde o modelo escreveu um marcador.
6. O ciclo se repete até que o modelo chame done ou que max_steps se esgote.

Em uma livraria de prática, o estado do navegador que o nosso modelo de teste recebeu tinha linhas como estas:

[587]<a title=It's Only the Himalayas />
	It's Only the Himalayas
£45.17
[597]<i />
In stock
[604]<button type=submit />
	Add to basket

Para colocar esse livro no carrinho, o modelo responderia {"click": {"index": 604}}. Como a página chega como texto, use_vision=False também funciona e mantém as capturas de páginas sensíveis longe do provedor do modelo.

Como instalar o Browser Use?#

O guia de início rápido oficial usa o uv:

pip install uv
uv venv --python 3.12
source .venv/bin/activate        # Windows: .venv\Scripts\activate
uv pip install browser-use
uvx browser-use install          # baixa o Chromium

Nós instalamos com um simples pip install browser-use==0.13.10 em um ambiente virtual com Python 3.13, e também funcionou. Depois, coloque as chaves em um arquivo .env ao lado do seu script:

OPENAI_API_KEY=...
PROXY_SERVER=http://pr.proxynet.io:8000
PROXY_USERNAME=user
PROXY_PASSWORD=pass
ANONYMIZED_TELEMETRY=false

A última linha importa. O Browser Use envia telemetria de uso por padrão, e a página de telemetria do projeto diz que ela pode incluir as instruções da tarefa, as URLs visitadas, o histórico de ações e os resultados finais. Se as suas tarefas mencionam clientes ou sites internos, desative-a.

Duas coisas nos surpreenderam na máquina de teste com Windows. Sem executable_path, o Browser Use escolheu o Google Chrome instalado, mas com um perfil temporário novo, e não com o seu perfil do dia a dia. Na primeira inicialização, ele também baixou três extensões, entre elas um bloqueador de anúncios, direto da Chrome Web Store e por fora do proxy; enable_default_extensions=False as desativa.

Como executar um agente por meio de um proxy?#

O proxy é uma configuração do Browser, e o agente recebe esse navegador. Este script abre uma página de categoria e lê três livros, saindo só pelo proxy e só para um domínio:

"""Executa um agente do Browser Use por meio de um proxy autenticado, limitado a um único site."""
import asyncio
import os

from dotenv import load_dotenv

load_dotenv()  # lê OPENAI_API_KEY, PROXY_* e ANONYMIZED_TELEMETRY do .env

from browser_use import Agent, Browser, ChatOpenAI
from browser_use.browser import ProxySettings

browser = Browser(
    headless=True,
    proxy=ProxySettings(
        server=os.environ["PROXY_SERVER"],  # http://pr.proxynet.io:8000
        username=os.environ["PROXY_USERNAME"],
        password=os.environ["PROXY_PASSWORD"],
    ),
    allowed_domains=["books.toscrape.com"],
    enable_default_extensions=False,
)

agent = Agent(
    task=(
        "Abra https://books.toscrape.com/catalogue/category/books/travel_2/index.html "
        "e liste o título e o preço dos três primeiros livros."
    ),
    llm=ChatOpenAI(model="gpt-4.1-mini"),
    browser=browser,
    use_vision=False,
)


async def main():
    history = await agent.run(max_steps=10)
    print("result:", history.final_result())
    print("pages: ", [u for u in history.urls() if u])
    print("steps: ", history.number_of_steps())


asyncio.run(main())

O ProxySettings é importado de browser_use.browser, não do pacote principal. A página de parâmetros do navegador lista quatro campos:

Por baixo dos panos, o Browser Use inicia o Chromium com --proxy-server e responde ele mesmo ao desafio 407 do proxy via CDP. O nosso proxy de teste registrou exatamente isso para a página do livro (resumido, sem os horários):

407 CONNECT books.toscrape.com:443 (no credentials)
200 CONNECT books.toscrape.com:443 user=user

O usuário e a senha do proxy não apareceram em nada do que o modelo recebeu.

Por que user:pass na URL do proxy falha?#

Porque o Chromium ignora as credenciais escritas dentro da configuração de proxy. Segundo a documentação de proxy do Chromium, o Chrome não usa nenhuma credencial embutida nas configurações de proxy. Com server="http://user:pass@…" e sem campos separados, toda navegação do nosso teste terminou com net::ERR_NO_SUPPORTED_PROXIES. Coloque as credenciais em username e password.

O SOCKS5 tem outro limite: o Chromium não suporta nenhum método de autenticação para SOCKS5. O nosso servidor SOCKS5 de teste viu o navegador oferecer apenas "no authentication" (sem autenticação), e a página falhou com ERR_SOCKS_CONNECTION_FAILED. Para SOCKS5, adicione o IP do seu servidor à whitelist de IP no painel (até 10 endereços) e use, sem usuário, a porta SOCKS5 que o Gerador de endpoints mostra. O DNS passa então a ser resolvido no lado do proxy. Os dois métodos de acesso são comparados em Autenticação de proxy: user:pass ou whitelist de IP, e os protocolos, em Diferença entre SOCKS e HTTP proxy.

Como verificar o IP de saída do agente?#

Verifique antes da primeira tarefa real, sem nenhum modelo no ciclo. Este script usa o mesmo ProxySettings, abre uma página que devolve o IP do visitante e imprime o que o site viu:

"""Abre uma página de eco de IP pelo proxy antes de qualquer agente rodar."""
import asyncio
import os

from browser_use import Browser
from browser_use.browser import ProxySettings


async def main():
    browser = Browser(
        headless=True,
        proxy=ProxySettings(
            server=os.environ["PROXY_SERVER"],
            username=os.environ["PROXY_USERNAME"],
            password=os.environ["PROXY_PASSWORD"],
        ),
    )
    await browser.start()
    try:
        page = await browser.new_page("https://httpbin.org/ip")
        await asyncio.sleep(2)  # espera a página carregar
        print(await page.evaluate("() => document.body.innerText"))
    finally:
        await browser.kill()


asyncio.run(main())

Ele imprime o JSON do httpbin com um campo origin. Por um endpoint da Proxynet, esse é o IP de saída, não o seu. Rode duas vezes: um usuário rotativo pode mostrar dois endereços diferentes, e um de sessão fixa, o mesmo endereço nas duas vezes.

O log do nosso proxy também mostrou as requisições do próprio Chrome para serviços do Google e o carregamento do logo do Browser Use na página inicial em branco; se você paga o tráfego do proxy por GB, elas também contam.

Rotativa ou fixa: de qual sessão um agente precisa?#

O proxy pertence ao navegador, então cada etapa de uma tarefa sai pelo mesmo endereço de proxy. O que muda é o IP de saída por trás desse endereço.

Na Proxynet, você escolhe sessão rotativa ou fixa, país e cidade no Gerador de endpoints, com duração da sessão fixa de 1 a 60 minutos; o usuário gerado já traz essas escolhas, então cole-o em PROXY_USERNAME sem alterar nada. Escolha uma duração um pouco maior que a sua tarefa mais longa. Produtos: Proxies de sessão fixa, Proxies rotativos, Proxies ISP e, quando uma verificação precisa de uma conexão residencial em um país específico, Proxies residenciais. Como a rotação funciona está explicado em O que é rotação de IP e como ela funciona?.

Como limitar aonde o agente pode ir?#

allowed_domains recebe uma lista de padrões: example.com, *.example.com para subdomínios e http*://example.com para os dois esquemas. Curingas no domínio de nível superior são rejeitados. prohibited_domains funciona ao contrário; quando os dois estão definidos, a lista de permitidos vence.

Permitimos só a nossa loja local e fizemos o modelo de teste tentar sair por dois caminhos. Um navigate direto para outro host devolveu isto ao modelo, com about:blank como página atual:

Navigation failed: Navigation to http://partner.test:28140/ blocked by security policy

Um link da loja que redirecionava para esse mesmo host também terminou em about:blank, e o modelo nunca viu o texto dessa página. Mas o log do próprio site de teste mostrou que o navegador tinha requisitado as duas páginas fora da lista antes que a verificação as substituísse, e uma imagem do host não permitido carregou normalmente dentro de uma página permitida. Na 0.13.10, o filtro controla o que o agente lê e sobre o que age, não o que o navegador envia.

Para um limite real, restrinja o tráfego de saída fora do agente: um firewall ou uma lista de permitidos no lado do proxy, um contêiner ou uma conta de usuário separados e nenhum acesso a endereços internos. O Playwright MCP tem a mesma ressalva com as flags de origem, como explicado em O que é Playwright MCP?. O padrão mais amplo está em Acesso seguro à web para LLMs.

Como manter as credenciais longe do modelo?#

Nunca escreva uma senha na tarefa. A tarefa vai para o provedor do modelo a cada etapa e, se você não desativar, para a telemetria. O Browser Use tem um mecanismo de marcadores para isso, o sensitive_data: você passa os valores reais no código, o modelo só vê nomes como x_user e x_pass, e a biblioteca digita o valor real no campo depois que o modelo responde.

No nosso teste, a ação do modelo foi <secret>x_pass</secret>, o log mostrou "Typed <sensitive>" e, quando a página repetiu o nome de usuário, o modelo recebeu Signed in as <secret>x_user</secret>. Os valores reais não apareceram em nenhuma entrada do modelo. Três hábitos completam a proteção:

• Vincule os segredos a um domínio, para que um marcador só seja preenchido no site ao qual pertence.
• Use use_vision=False em páginas em que uma captura de tela poderia mostrar o valor.
• Não entregue ao agente o seu perfil do Chrome do dia a dia (Browser.from_system_chrome()) em tarefas que leem páginas externas: toda sessão logada nele fica ao alcance do agente.

Como adicionar uma etapa de aprovação humana?#

A injeção de prompt indireta é um texto em uma página que o modelo toma como instrução. A entrada LLM01 da OWASP lista a aprovação humana para ações de alto risco entre as defesas. O Browser Use chama register_new_step_callback depois que o modelo escolhe as ações e antes que elas rodem, então o callback pode parar o agente:

"""Agente do Browser Use com lista de permitidos, marcadores para segredos e aprovação humana."""
import asyncio
import os

from dotenv import load_dotenv

load_dotenv()

from browser_use import Agent, Browser, ChatOpenAI
from browser_use.browser import ProxySettings

SITE = "https://shop.example.com"
READ_ONLY = {"navigate", "scroll", "find_text", "extract", "screenshot", "go_back", "wait", "done"}

browser = Browser(
    headless=True,
    proxy=ProxySettings(
        server=os.environ["PROXY_SERVER"],
        username=os.environ["PROXY_USERNAME"],
        password=os.environ["PROXY_PASSWORD"],
    ),
    allowed_domains=["shop.example.com"],
    enable_default_extensions=False,
)


def approve(browser_state, model_output, step):
    """Roda depois que o modelo escolhe as ações e antes que elas sejam executadas."""
    planned = [action.model_dump(exclude_none=True) for action in model_output.action]
    if all(next(iter(a)) in READ_ONLY for a in planned):
        return
    print(f"Step {step} wants to run: {planned}")
    if input("Allow? [y/N] ").strip().lower() != "y":
        agent.stop()


agent = Agent(
    task=f"Faça login em {SITE}/login com o usuário x_user e a senha x_pass e depois abra a oferta do parceiro.",
    llm=ChatOpenAI(model="gpt-4.1-mini"),
    browser=browser,
    sensitive_data={"http*://shop.example.com": {"x_user": os.environ["SHOP_USER"], "x_pass": os.environ["SHOP_PASS"]}},
    use_vision=False,
    register_new_step_callback=approve,
)


async def main():
    history = await agent.run(max_steps=8)
    print("done:  ", history.is_done())
    print("errors:", [e for e in history.errors() if e])


asyncio.run(main())

Rodamos o script na nossa loja local, com o domínio trocado. A etapa de login pediu confirmação primeiro; depois de "y", o agente digitou os dois valores e clicou. Um clique posterior pediu confirmação de novo e, depois de "n", o log mostrou "Agent stopping", o clique nunca foi executado e is_done() retornou False. Qualquer ação fora do conjunto somente leitura, inclusive digitar, agora espera por uma pessoa.

Browser Use ou Playwright MCP?#

Os dois permitem que um modelo use um navegador; a diferença está em quem roda o ciclo.

A instalação e as flags do Playwright MCP estão em O que é Playwright MCP?.

Casos de uso#

• Verificações de localização no seu próprio site: que idioma, moeda e aviso de cookies um visitante de um país específico recebe (testes de localização).
• Testes exploratórios do seu próprio app: percorrer um fluxo de cadastro ou de checkout em homologação a partir de locais diferentes (testes de aplicativos).
• Leituras pontuais de uma página com JavaScript: alguns valores de uma página pública renderizada no navegador (páginas estáticas e dinâmicas). Para tarefas recorrentes, um script simples sai mais barato (Playwright com proxy).
• Texto limpo para um modelo em vez de um navegador: quando o agente só precisa ler, veja O que é Crawl4AI?.

Um agente que navega por você continua gerando tráfego automatizado. O Browser Use 0.13.10 não lê o robots.txt (não encontramos código para isso no pacote), então leia você mesmo o robots.txt e os termos do site, use uma API oficial quando houver, fique em poucas páginas em ritmo humano e pare quando um site disser não. Por que os sites diferenciam visitantes automatizados está explicado em Por que os sites bloqueiam agentes de compras com IA?. Os recursos de stealth e de CAPTCHA anunciados para o Browser Use Cloud ficam fora deste guia, e não os recomendamos.

Erros comuns#

Dois hábitos causam problemas sem mostrar nenhum erro: tratar allowed_domains como firewall e rodar uma versão não fixada. A API mudou entre versões, então fixe a versão que você testou (browser-use==0.13.10) e leia as notas de versão antes de atualizar.

Guia de decisão#

Perguntas frequentes#

O Browser Use é gratuito?#

A biblioteca é gratuita sob a licença MIT. Você paga as chamadas ao modelo, pelo menos uma por etapa, e o tráfego do proxy. O Browser Use Cloud e os modelos hospedados são cobrados à parte.

O Browser Use ainda usa o Playwright?#

Não para controlar o navegador. A versão 0.13.10 controla o Chromium pelo Chrome DevTools Protocol; o comando de instalação usa o downloader do Playwright para baixar o Chromium, e o estado de login salvo usa o formato de arquivo do Playwright.

Posso usar um modelo local em vez de uma API?#

A página de modelos suportados mostra ChatOllama(model="llama3.1:8b") para um servidor local do Ollama. Não testamos um modelo local.

Dois agentes podem usar países diferentes ao mesmo tempo?#

Sim, com dois objetos Browser, cada um com o próprio ProxySettings. Um navegador tem um único proxy para todas as abas.

O Browser Use respeita o robots.txt?#

Não por conta própria; a versão 0.13.10 não verifica o robots.txt. Leia o arquivo antes de entregar um site ao agente.

Um proxy impede que os sites bloqueiem o meu agente?#

Não. Um proxy muda o endereço de onde a requisição sai; o comportamento do navegador e o ritmo continuam os mesmos. Ritmo lento, páginas permitidas e a API oficial são o caminho duradouro.

Em resumo#

O Browser Use dá a um modelo de linguagem um navegador Chromium de verdade e roda o ciclo do agente no seu próprio código Python. Configure o proxy no navegador com ProxySettings e os campos username e password separados; credenciais na URL e SOCKS5 com senha falham no Chromium. Verifique o IP de saída antes da primeira tarefa, use uma sessão fixa em tudo o que tiver login e trate allowed_domains como um filtro para o agente, não como uma fronteira de rede. Guarde os segredos em sensitive_data, desative a telemetria e deixe que uma pessoa aprove as ações que mudam algo. Saídas adequadas para o seu agente estão nos nossos serviços de proxy.