Proxies residenciais para agentes LangChain, CrewAI e AutoGen

Um framework de agentes facilita dar a um modelo uma ferramenta web. Ele não facilita chegar à web. Na primeira vez que um agente LangChain, CrewAI ou AutoGen busca páginas em algum volume, ele começa a acumular erros 403, páginas de CAPTCHA e conteúdo do país errado, e o modelo resume tudo isso tranquilamente como se fosse real. Rotear as ferramentas web do agente por proxies feitos para agentes de IA resolve a parte do acesso, mas só se você os conectar no lugar certo.

Este guia trata justamente dessa conexão. Ele mostra como enviar as ferramentas web de cada framework por um proxy residencial, como manter a API do modelo fora do proxy e como escolher sessões fixas ou rotativas para cada tarefa. Se você ainda está escolhendo um tipo de proxy, comece pela nossa comparação dos melhores proxies para agentes de IA que navegam na web; este post parte do princípio de que você já escolheu um.

Regra número um: o proxy vai nas ferramentas, não no processo

O jeito mais rápido de adicionar um proxy é exportar HTTPS_PROXY e reiniciar. Não faça isso em um processo de agente. Os SDKs da OpenAI, da Anthropic e da maioria dos outros provedores de modelos leem as mesmas variáveis de ambiente, então cada chamada ao modelo também passaria pela rede residencial. Isso adiciona latência a cada etapa de raciocínio, gasta tráfego de proxy com tokens e não traz nada em troca, porque as APIs de modelos não bloqueiam você por IP.

Defina o proxy explicitamente no cliente HTTP ou no navegador que cada ferramenta usa. Todo o resto continua na sua conexão normal. Se uma biblioteca só lê variáveis de ambiente, adicione os hosts do modelo ao NO_PROXY.

A URL do proxy

Com o gateway da Shifter, a segmentação e as sessões ficam no nome de usuário. Um único endpoint, p.shifter.io:443, cobre todos os países:

import os, uuid

USER = os.environ["SHIFTER_USER"]
PASSWORD = os.environ["SHIFTER_PASS"]

def proxy_url(country: str = "us", session: str | None = None, ttl: int = 600) -> str:
    """Rotating by default; pass a session id to keep one exit IP for a task."""
    username = f"{USER}-country-{country}"
    if session:
        username += f"-sid-{session}-ttl-{ttl}"
    return f"http://{username}:{PASSWORD}@p.shifter.io:443"

def new_session() -> str:
    return uuid.uuid4().hex[:12]

Todos os exemplos abaixo reutilizam essa função auxiliar.

LangChain

A maioria dos agentes LangChain lê a web de uma de duas formas: um document loader para recuperação, ou um toolkit de navegador para agentes que clicam e digitam.

Document loaders. O WebBaseLoader aceita um dicionário proxies e o usa em todas as páginas que busca:

from langchain_community.document_loaders import WebBaseLoader

proxy = proxy_url(country="de")
loader = WebBaseLoader(
    ["https://shop.example/de/product/123"],
    proxies={"http": proxy, "https": proxy},
)
docs = loader.load()

A rotação combina com loaders: cada página é independente, então um IP novo por requisição distribui a carga.

Toolkits de navegador. O toolkit do Playwright controla um navegador real. Inicie você mesmo o navegador com o proxy e entregue-o ao toolkit:

from langchain_community.agent_toolkits import PlayWrightBrowserToolkit
from playwright.sync_api import sync_playwright

session = new_session()
playwright = sync_playwright().start()
browser = playwright.chromium.launch(proxy={
    "server": "http://p.shifter.io:443",
    "username": f"{USER}-country-us-sid-{session}-ttl-1800",
    "password": PASSWORD,
})
tools = PlayWrightBrowserToolkit.from_browser(sync_browser=browser).get_tools()

Aqui o id de sessão faz diferença. Um agente que navega abre páginas, lê, clica e volta. Se o IP dele mudasse entre as etapas, o site veria um visitante pulando de uma cidade para outra no meio da sessão, que é exatamente o que as defesas contra bots procuram. Um id de sessão por execução do agente mantém uma única saída durante toda a tarefa.

CrewAI

Os agentes do CrewAI usam ferramentas, e a abordagem mais limpa é uma pequena ferramenta personalizada com o seu próprio cliente HTTP:

import requests
from crewai.tools import BaseTool

class FetchPage(BaseTool):
    name: str = "fetch_page"
    description: str = "Fetch a public web page as seen from a given country."

    def _run(self, url: str, country: str = "us") -> str:
        proxy = proxy_url(country=country)
        r = requests.get(url, proxies={"http": proxy, "https": proxy}, timeout=30)
        r.raise_for_status()
        return r.text[:20000]

Dê a ferramenta aos agentes que pesquisam e deixe-a de fora dos agentes que só escrevem ou revisam. Uma crew com cinco agentes raramente precisa dos cinco no proxy.

Deixar o modelo escolher o country é útil em crews de pesquisa de mercado: o agente pesquisador pode comparar o que uma página mostra nos Estados Unidos, na Alemanha e no Japão sem nenhum código extra. Mantenha a lista de países permitidos na descrição da ferramenta para que o modelo não invente códigos.

AutoGen

No AgentChat do AutoGen, uma ferramenta é uma função Python comum, então o proxy vai no cliente dentro dela. Um cliente assíncrono se encaixa no event loop do AutoGen:

import httpx
from autogen_agentchat.agents import AssistantAgent

async def fetch_page(url: str, country: str = "us") -> str:
    """Fetch a public web page through a residential IP in the given country."""
    async with httpx.AsyncClient(proxy=proxy_url(country=country), timeout=30) as client:
        r = await client.get(url, follow_redirects=True)
        r.raise_for_status()
        return r.text[:20000]

researcher = AssistantAgent(
    name="researcher",
    model_client=model_client,  # your model client, not proxied
    tools=[fetch_page],
)

O cliente do modelo é criado separadamente e nunca vê o proxy, que é exatamente o objetivo da regra número um.

Fixa ou rotativa, conforme a tarefa

Quem decide isso não é o framework, e sim a tarefa. Uma regra prática simples:

Tarefa do agente	Sessão	Por quê
Buscar muitas páginas independentes	Rotativa	Distribui as requisições, sem estado para manter
Navegação em várias etapas, formulários, carrinhos	Fixa, um id por execução	O site espera um único visitante
Fluxos com login ao longo de horas	ISP Proxies	Uma cidade e um ISP durante todo o período de cobrança
Comparar países	Rotativa, um país por chamada	Cada chamada é um mercado à parte

Para se aprofundar nos prós e contras, veja nosso guia de decisão sobre quando alternar IPs de proxy. Para sessões longas com login, os ISP Proxies mantêm a mesma cidade e o mesmo ISP durante todo o período de cobrança, o que combina com agentes que mantêm uma conta aberta.

Torne as falhas visíveis para o modelo

Agentes são ruins em perceber que foram bloqueados. Uma página de CAPTCHA é só mais um texto para resumir. Dois pequenos hábitos evitam respostas erradas:

• Lance uma exceção em respostas 403 e 429 em vez de devolver o corpo. O framework repassa o erro ao modelo, que pode tentar de novo ou relatar o problema, em vez de raciocinar sobre uma página de bloqueio.
• Tente de novo com uma sessão nova, não com a mesma. Se uma sessão fixa for bloqueada, gere um novo id de sessão para a nova tentativa. Repetir pela mesma saída geralmente traz a mesma resposta.

Limite as novas tentativas. Três tentativas por URL são mais do que suficientes; além disso, você está pagando por tráfego que o alvo já decidiu recusar.

Controle de custos

Agentes podem entrar em loop. Um planejador que fica relendo a mesma página vai gastar tráfego de proxy tão rápido quanto gasta tokens. Corte o corpo das páginas antes que cheguem ao modelo, como os exemplos acima fazem, mantenha em cache as páginas buscadas durante a execução e registre os bytes por chamada de ferramenta, para que um agente descontrolado apareça em um dashboard antes de aparecer em uma fatura.

Perguntas frequentes

Conclusão

Dê o proxy às ferramentas, não ao processo. Use rotação quando as páginas forem independentes, uma sessão fixa por execução quando o agente se comportar como um visitante, e deixe os bloqueios evidentes o bastante para que o modelo não os confunda com conteúdo.