---
title: "Browser Use com proxy: como configurar o agente de IA"
description: "O Browser Use permite que um LLM controle um navegador real pelo Python. Configure o agente com proxy autenticado, confira o IP de saída e limite os sites."
url: https://proxynet.io/pt-br/blog/browser-use-proxy
date: 2026-10-05
author: "Acar Diveroli"
category: "Integração, IA"
lang: pt-BR
---
# 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.
> **Nota: Resposta rápida**
>
> O Browser Use é uma biblioteca Python de código aberto (licença MIT) que permite que um modelo de linguagem controle um navegador Chromium: o modelo lê a página, escolhe ações como clicar ou digitar, e a biblioteca as executa. Instale com `uv pip install browser-use` e baixe o Chromium com `uvx browser-use install`. O proxy pertence ao navegador: `Browser(proxy=ProxySettings(server="http://pr.proxynet.io:8000", username="user", password="pass"))`. Credenciais dentro do endereço do servidor falham, assim como SOCKS5 com senha. Use uma sessão fixa em tarefas de várias etapas e marcadores (placeholders) em `sensitive_data` para que as senhas nunca cheguem ao modelo.
## 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](https://github.com/browser-use/browser-use) 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](https://pypi.org/project/browser-use/) 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](/pt-br/blog/how-ai-agents-work); os navegadores com um agente embutido, em [O que é um navegador com IA?](/pt-br/blog/what-is-an-ai-browser).
## 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:
```text
[587]
It's Only the Himalayas
£45.17
[597]
In stock
[604]
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:
```bash
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:
```bash
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](https://docs.browser-use.com/open-source/development/monitoring/telemetry) 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:
```python
"""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](https://docs.browser-use.com/open-source/customize/browser/all-parameters) lista quatro campos:
| Campo | O que recebe |
|---|---|
| `server` | `http://host:port` ou `socks5://host:port`, sem credenciais |
| `username` | Usuário do proxy, por exemplo o que o Gerador de endpoints mostra |
| `password` | Senha do proxy |
| `bypass` | Hosts que não passam pelo proxy, separados por vírgula |
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):
```text
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](https://chromium.googlesource.com/chromium/src/+/HEAD/net/docs/proxy.md), 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](/pt-br/blog/proxy-authentication-methods), e os protocolos, em [Diferença entre SOCKS e HTTP proxy](/pt-br/blog/socks-vs-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:
```python
"""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.
| Tarefa | Sessão | Por quê |
|---|---|---|
| Fazer login e depois agir em várias páginas | Fixa, 10-30 minutos | Muitos sites vinculam a sessão a um IP; um endereço novo no meio da tarefa pode exigir um novo login |
| Ler uma página independente a cada execução | Rotativa | Cada execução pode receber uma saída nova; nada passa de uma para outra |
| Vários agentes em paralelo | Um `Browser` por agente | Cada navegador tem as próprias configurações de proxy e a própria sessão |
| Um endereço que os seus próprios sistemas liberam em uma lista de permitidos | ISP estático | O IP continua o mesmo por dias |
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](https://proxynet.io/pt-br/sticky-proxy), [Proxies rotativos](https://proxynet.io/pt-br/rotating-proxy), [Proxies ISP](https://proxynet.io/pt-br/static-isp-residential-proxy) e, quando uma verificação precisa de uma conexão residencial em um país específico, [Proxies residenciais](https://proxynet.io/pt-br/residential-proxy). Como a rotação funciona está explicado em [O que é rotação de IP e como ela funciona?](/pt-br/blog/ip-rotation-explained).
## 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:
```text
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?](/pt-br/blog/playwright-mcp). O padrão mais amplo está em [Acesso seguro à web para LLMs](/pt-br/blog/llm-safe-web-access).
## 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 `x_pass`, o log mostrou "Typed " e, quando a página repetiu o nome de usuário, o modelo recebeu `Signed in as x_user`. 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](https://genai.owasp.org/llmrisk/llm01-prompt-injection/) 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:
```python
"""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.
| | Browser Use | Playwright MCP |
|---|---|---|
| Quem roda o ciclo do agente | A biblioteca, no seu código Python | O assistente que você já usa (Claude Code, Cursor) |
| Proxy com senha | Campos do `ProxySettings` | `launchOptions.proxy` em um arquivo de configuração |
| Limite de domínios | `allowed_domains` | `--allowed-origins` |
| Indicado para | Agentes dentro do seu próprio serviço | Trabalho pontual a partir de um assistente de programação |
A instalação e as flags do Playwright MCP estão em [O que é Playwright MCP?](/pt-br/blog/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](/pt-br/localization)).
- **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](/pt-br/app-testing)).
- **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](/pt-br/blog/static-vs-dynamic-pages)). Para tarefas recorrentes, um script simples sai mais barato ([Playwright com proxy](/pt-br/blog/playwright-proxy)).
- **Texto limpo para um modelo em vez de um navegador:** quando o agente só precisa ler, veja [O que é Crawl4AI?](/pt-br/blog/crawl4ai-proxy).
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](/pt-br/blog/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?](/pt-br/blog/ai-shopping-agents-blocked). Os recursos de stealth e de CAPTCHA anunciados para o Browser Use Cloud ficam fora deste guia, e não os recomendamos.
## Erros comuns
| O que você vê | Por quê | O que fazer |
|---|---|---|
| `net::ERR_NO_SUPPORTED_PROXIES` | Credenciais escritas em `server` | Mova-as para `username` e `password` |
| `net::ERR_TOO_MANY_RETRIES` | Usuário ou senha do proxy errados; o proxy continua respondendo `407` | Copie as credenciais de novo no painel |
| `net::ERR_PROXY_CONNECTION_FAILED` | Host ou porta errados, ou tráfego de saída bloqueado | Teste o mesmo endereço com cURL |
| `ERR_SOCKS_CONNECTION_FAILED` | `socks5://` com senha | Use o endpoint HTTP, ou SOCKS5 com whitelist de IP |
| `blocked by security policy` | A URL está fora de `allowed_domains` | Adicione o domínio ou deixe-o bloqueado |
| O agente faz login de novo no meio da tarefa | Uma saída rotativa trocou o IP durante a tarefa | Use uma sessão fixa |
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
| Necessidade | Recomendação |
|---|---|
| Uma primeira execução do agente por proxy | `ProxySettings` com o endpoint HTTP, usuário e senha; depois, o script de eco de IP |
| Uma tarefa de várias etapas com login | Sessão fixa mais longa que a tarefa |
| Execuções independentes de uma única página | Sessão rotativa |
| Manter o agente em um só site | `allowed_domains`, mais uma lista de permitidos para o tráfego de saída fora do agente |
| Ações que mudam algo | Um callback de aprovação que possa chamar `agent.stop()` |
## 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](/pt-br/proxy).