Configuração de Proxy para Uso em Navegador: IPs de Saída por Sessão

Procure um proxy para uso em navegador e o Google lhe apresenta a caixa de diálogo de configurações do Chrome. Esta é a outra questão: roteando a biblioteca de agentes de IA para uso em navegador através de IPs residenciais autenticados, um por agente.

Procure por proxy para uso em navegador e o Google lhe apresenta a caixa de diálogo de configurações do Chrome, a API de extensão chrome.proxy e um tutorial de arquivo PAC corporativo. Nada disso é o que você estava procurando. Você quer rotear browser-use - a biblioteca Python com 108k estrelas no GitHub que permite a um LLM controlar um navegador real - através de um proxy autenticado, para que seu agente não sobrecarregue um alvo a partir do IP do seu escritório. Este é o guia: onde o parâmetro realmente está, por que ele para de funcionar silenciosamente após uma atualização, como dar a cada agente paralelo seu próprio IP de saída e o que acontece com uma tarefa longa quando o IP muda sob ela.

Onde o parâmetro de proxy para uso em navegador realmente está

O proxy é uma propriedade da sessão do navegador, não do agente. Na biblioteca atual, Browser é um alias para BrowserSession - a documentação é explícita que são exatamente a mesma classe - então qualquer tutorial que você encontrar usando um nome se aplica ao outro. O parâmetro é proxy, e a documentação o tipifica como ProxySettings com quatro campos: server, bypass, username e password. Um dicionário equivalente funciona, que é o que a maioria das pessoas passa:

import asyncio
from browser_use import Agent, Browser
# llm = ...  your model of choice; see the browser-use docs for the import

PROXY = {
    "server": "http://gate.quantumproxies.io:8000",  # scheme is mandatory
    "username": "USER",
    "password": "PASS",
    "bypass": "localhost,127.0.0.1",                  # keep local calls off the proxy
}

browser = Browser(proxy=PROXY, headless=False)

async def main():
    agent = Agent(
        task="Open https://api.ipify.org?format=json and report the IP you see",
        llm=llm,
        browser_session=browser,
    )
    await agent.run()

asyncio.run(main())

Dois detalhes que as pessoas erram. Primeiro, as credenciais pertencem aos campos username e password, não devem ser colocadas no server - o Chromium não responderá a um desafio de autenticação de proxy a partir de uma senha embutida na URL, e o browser-use não tem diálogo para digitá-la. Segundo, server precisa de um esquema. gate.quantumproxies.io:8000 não é uma URL de proxy; http://gate.quantumproxies.io:8000 é. Se as credenciais estão lhe causando problemas, whitelist o IP do seu servidor para remover usuário:senha da equação completamente - o gateway reconhece o chamador e o navegador nunca vê um 407.

Por que sua configuração de proxy para uso em navegador não faz nada silenciosamente

A página mais visitada sobre este tópico após a documentação é a issue #2445 do GitHub, registrada em julho de 2025: um proxy que funcionava na versão 0.1.45 parou de surtir efeito na 0.5.4, e a única pista era o agente relatando alegremente DNS_PROBE_FINISHED_NXDOMAIN em seu próprio resumo. Esse modo de falha - o agente narrando um erro de rede como se fosse um fato sobre o site - é a assinatura de um proxy que está meio configurado. Trabalhe com esta lista antes de gastar mais tokens:

Você passou proxy= para uma sessão que o agente nunca recebeu. Crie um Browser, passe esse objeto exato e não deixe que uma sessão padrão seja criada sem seu conhecimento.
Você configurou cdp_url. Conectar-se a um Chrome já em execução significa que o proxy pertence às flags de inicialização desse navegador (--proxy-server=...), não à sua configuração de sessão - o browser-use não pode adaptá-lo.
Uma variável de ambiente global HTTP_PROXY ou HTTPS_PROXY está competindo com a configuração da sessão, ou pior, roteando silenciosamente suas chamadas de API do LLM através de uma largura de banda medida.
O próprio proxy está inativo. Teste-o fora do agente primeiro - não custa nada e elimina metade do espaço de busca.

import requests

PROXY_URL = "http://USER:PASS@gate.quantumproxies.io:8000"
r = requests.get(
    "https://api.ipify.org?format=json",
    proxies={"http": PROXY_URL, "https": PROXY_URL},
    timeout=20,
)
print(r.status_code, r.text)   # must NOT be your own IP

Se isso imprimir um IP estrangeiro, as credenciais e o gateway estão bem e o problema está na configuração da sessão. Se imprimir seu próprio endereço, ou um 407, corrija isso primeiro. Nosso verificador de IP gratuito informa como a saída parece do outro lado - ASN, tipo e reputação - que é a segunda coisa a verificar quando as páginas carregam, mas todas são um CAPTCHA.

Lista de verificação que combina sintomas de proxy para uso em navegador (erros de DNS, vazamento de IP real, configuração que funcionava em uma versão mais antiga) com as correções a serem verificadas — A configuração geralmente parece correta. A falha quase sempre é a sessão que o agente realmente recebeu, o esquema ausente ou uma variável de ambiente global.

Um proxy por sessão, para que agentes paralelos não compartilhem um IP de saída

Esta é a razão pela qual o parâmetro está na sessão em vez de em uma configuração global. Execute dez agentes através de um Browser compartilhado e o alvo verá dez vezes o tráfego de um endereço, que é a maneira mais rápida de queimar um IP residencial. Construa a sessão dentro da coroutine em vez disso, e dê a cada uma seu próprio identificador de sessão fixa para que o gateway a fixe em uma única saída durante a vida útil da tarefa:

import asyncio, secrets
from browser_use import Agent, Browser

def session_proxy(sid: str, country: str = "us"):
    return {
        "server": "http://gate.quantumproxies.io:8000",
        "username": f"USER-country-{country}-session-{sid}",
        "password": "PASS",
    }

async def run_task(task: str, country: str):
    sid = secrets.token_hex(3)                  # e.g. a1b2c3
    browser = Browser(
        proxy=session_proxy(sid, country),
        user_data_dir=None,                     # incognito: no shared cookies
        allowed_domains=["*.example.com"],      # keep the agent on target
    )
    agent = Agent(task=task, llm=llm, browser_session=browser)
    return await agent.run()

async def main():
    await asyncio.gather(
        run_task("Find the price of SKU-1", "us"),
        run_task("Find the price of SKU-1", "de"),
        run_task("Find the price of SKU-1", "gb"),
    )

asyncio.run(main())

Três flags estão fazendo um trabalho real ali. user_data_dir=None executa em modo incógnito, para que os agentes não herdem os cookies uns dos outros e silenciosamente mesclem duas identidades em um perfil. allowed_domains restringe a navegação a uma lista de padrões - note que curingas na posição de TLD, como example.*, são rejeitados de propósito, e listas com mais de cem entradas são otimizadas em conjuntos com correspondência de padrões desativada. E o identificador de sessão no nome de usuário é o que torna o IP de saída estável; os nomes exatos das flags para país e sessão estão no seu painel, mas a forma é a mesma em todos os lugares.

Escolhendo o país de saída por tarefa

Agentes que compram, comparam preços ou verificam disponibilidade estão errados por padrão se navegarem a partir do país errado. Como o proxy é por sessão, o país é um argumento por tarefa - troque country-us por country-de e a mesma tarefa retorna preços alemães. Escolha entre os mais de 200 países no pool, e mantenha o resto do navegador coerente com isso: passe um idioma correspondente através de args (o Chromium aceita --lang=de-DE) em vez de deixar um IP de saída alemão solicitar páginas em inglês dos EUA. Para superfícies apenas móveis e as saídas de maior confiança, IPs móveis se comportam de forma diferente novamente, porque o NAT do operador coloca milhares de usuários reais atrás do mesmo endereço.

Dê a cada agente seu próprio IP de saída residencial

Fluxo mostrando uma fila de tarefas se expandindo para uma sessão de uso em navegador por agente, cada uma com sua própria sessão de proxy fixa, para que o site alvo veja IPs residenciais distintos — Construa a sessão dentro da tarefa, não fora dela. Um Browser por agente, uma sessão fixa por Browser, um IP por identidade.

O que acontece quando o IP gira no meio da tarefa

Agentes são lentos de uma maneira que scrapers não são. Entre a pausa padrão de 0,5s após cada ação, um tempo mínimo de espera de estado de página de 0,25s e uma espera de inatividade de rede de 0,5s, o uso em navegador gasta mais de um segundo por etapa antes que o modelo tenha dito qualquer coisa - e a viagem de ida e volta do modelo geralmente leva vários segundos a mais. Uma tarefa de quinze etapas, portanto, dura de um a dois minutos no relógio de parede. Se seu IP de saída gira por solicitação, o site verá um endereço diferente em cada uma dessas etapas: o login cai, o carrinho esvazia e o agente relata que o botão de checkout desapareceu.

A solução é uma sessão fixa cuja janela exceda confortavelmente a duração da sua tarefa no pior caso, não a média. Cronometre algumas execuções reais, pegue a mais lenta e adicione margem - agentes tentam novamente, e uma tentativa novamente dobra o relógio. Quando uma tarefa realmente precisa sobreviver a qualquer janela fixa, divida-a: faça login e exporte o estado, depois retome em uma nova sessão com os cookies que você salvou via storage_state. E se você está escolhendo entre rotação por solicitação e fixo, nosso checklist de infraestrutura para agentes de IA cobre o restante da camada em torno dessa decisão.

Mantenha o proxy fora de suas chamadas LLM

Este custa dinheiro real e quase ninguém percebe. Definir HTTPS_PROXY como uma variável de ambiente para fazer o proxy "aplicar-se em todos os lugares" também roteia cada chamada de API de modelo através do seu gateway residencial - prompts e respostas, em cada etapa, cobrados por gigabyte pelo privilégio de dar a volta longa. Configure o proxy apenas no Browser e deixe o ambiente do processo em paz. Enquanto você está contando bytes, note que o browser-use carrega o uBlock Origin por padrão através de enable_default_extensions: deixe-o ativado, porque cada solicitação de anúncio que ele mata é uma que você não paga. A aritmética completa está em nossa análise de quanto um agente de IA custa em largura de banda, e a versão de scraping clássico do trade-off está em navegador sem cabeça vs solicitações HTTP.

Perguntas frequentes

Como configuro um proxy no browser-use?

Passe proxy= quando você construir o Browser (também exportado como BrowserSession), depois entregue esse objeto ao Agent. O valor carrega server com um esquema http:// explícito, além de username, password e uma lista opcional de bypass. Não há configuração de proxy a nível de agente - ele pertence à sessão.

Por que minha configuração de proxy para uso em navegador não está funcionando?

Em ordem de probabilidade: o agente está rodando em uma sessão diferente da que você configurou, server está sem seu esquema, você configurou cdp_url então o navegador foi lançado em outro lugar sem flags de proxy, ou uma variável de ambiente de proxy global está anulando você. Verifique o proxy com um cliente HTTP simples primeiro - um erro de DNS dentro do log do agente geralmente significa que nenhum proxy está anexado.

Cada agente de uso em navegador pode usar um IP diferente?

Sim, e você deveria. Crie o Browser dentro de cada coroutine de tarefa com suas próprias credenciais de proxy em vez de compartilhar uma instância. Adicionar um identificador de sessão único ao nome de usuário do gateway fixa cada agente a uma saída distinta durante sua execução, então dez agentes paralelos parecem dez usuários em vez de um muito ocupado.

Qual tipo de proxy é mais adequado para agentes de uso em navegador?

Residencial rotativo para pesquisa e verificações de preços onde cada tarefa é independente, residencial fixo para qualquer coisa com login ou carrinho, e móvel quando o alvo é hostil ou apenas móvel. IPs de datacenter são bons para alvos internos e páginas desprotegidas, e são muito mais baratos por gigabyte - o que importa, porque um agente de navegador move muitos gigabytes.

Um proxy impede que o uso em navegador seja detectado?

Não. Um proxy corrige apenas a camada de IP; a impressão digital de um Chromium automatizado é um problema separado, assim como o comportamento de um agente que clica com precisão de milissegundos. Saídas residenciais confiáveis removem o sinal mais fácil, mas combine-as com uma construção de navegador orientada para stealth se o alvo tiver uma gestão de bots séria.

Nada aqui é exótico: o proxy é uma propriedade da sessão, e as duas coisas que o quebram são um esquema ausente e uma sessão que você nunca entregou. Acerte isso, dê a cada agente paralelo sua própria saída fixa e mantenha o gateway longe de suas chamadas de API de modelo. Para uma visão mais ampla, veja nosso mapa de frameworks anti-detecção e proxies autenticados.

Execute o browser-use em mais de 90M de IPs residenciais em mais de 200 países