为 LangChain、CrewAI 和 AutoGen 智能体配置住宅代理

借助智能体框架，给模型配一个网页工具很容易，但这并不意味着网页也容易访问。LangChain、CrewAI 或 AutoGen 智能体一旦开始批量抓取页面，就会不断收到 403、CAPTCHA 验证页以及错误国家的内容，而模型会把这些统统当作真实内容欣然总结。让智能体的网页工具通过专为 AI 智能体打造的代理转发，可以解决访问问题，但前提是接入的位置要正确。

本指南讲的就是如何接入。它会介绍如何让每个框架的网页工具走住宅代理、如何让模型 API 不经过代理，以及如何按任务选择粘性会话或轮换会话。如果你还在挑选代理类型，可以先阅读我们对适合网页浏览型 AI 智能体的最佳代理的对比；本文假设你已经选好了。

第一条规则：代理工具，而不是整个进程

添加代理最快的方法是导出 HTTPS_PROXY 然后重启。不要在智能体进程中这样做。OpenAI、Anthropic 以及大多数其他模型 SDK 都会读取相同的环境变量，这样每一次模型调用也都会经过住宅网络。这会给每个推理步骤增加延迟，把代理流量浪费在 token 上，而且毫无收益，因为模型 API 不会按 IP 封禁你。

请在每个工具所用的 HTTP 客户端或浏览器上显式设置代理，其余一切都走你的常规连接。如果某个库只读取环境变量，请把模型的主机名加入 NO_PROXY。

代理 URL

使用 Shifter 网关时，定位和会话参数都写在用户名中。一个端点 p.shifter.io:443 即可覆盖所有国家：

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]

下面的每个示例都会复用这个辅助函数。

LangChain

大多数 LangChain 智能体通过以下两种方式之一读取网页：用于检索的文档加载器，或者用于点击和输入操作的浏览器工具包。

文档加载器。 WebBaseLoader 接受一个 proxies 字典，并在抓取每个页面时使用它：

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()

轮换很适合加载器：每个页面彼此独立，每次请求换一个新 IP 可以分散负载。

浏览器工具包。 Playwright 工具包驱动的是真实浏览器。你需要自己用代理启动浏览器，再把它交给工具包：

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()

这里会话 ID 很关键。浏览型智能体会导航、阅读、点击，然后返回。如果它的 IP 在步骤之间发生变化，网站就会看到一个访客在会话途中从一个城市跳到另一个城市，而这正是反爬虫机制重点检测的行为。每次智能体运行使用一个会话 ID，就能让整个任务保持同一个出口。

CrewAI

CrewAI 智能体通过工具工作，最简洁的做法是编写一个自带 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]

把这个工具交给负责调研的智能体，而只负责撰写或审核的智能体则不需要。一个由五个智能体组成的 crew，很少需要五个智能体都走代理。

让模型自行选择 country 对市场调研类 crew 很有用：调研智能体无需任何额外代码，就能对比同一页面在美国、德国和日本显示的内容。请在工具描述中列出允许使用的国家，避免模型自己编造代码。

AutoGen

在 AutoGen 的 AgentChat 中，工具就是一个普通的 Python 函数，所以代理设置在函数内部的客户端上。异步客户端与 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],
)

模型客户端是单独创建的，完全不会接触到代理，这正是第一条规则的意义所在。

按任务选择粘性会话或轮换

这不由框架决定，而由任务决定。一个简单的经验法则：

智能体任务	会话	原因
抓取大量相互独立的页面	轮换	分散请求，无需保持状态
多步骤浏览、表单、购物车	粘性，每次运行一个 ID	网站预期只有一个访客
持续数小时的登录工作流	ISP Proxies	整个计费周期内保持同一城市和 ISP
对比不同国家	轮换，每次调用一个国家	每次调用对应一个市场

想深入了解其中的取舍，请参阅我们的代理 IP 轮换决策框架。对于长时间的登录会话，ISP Proxies 会在整个计费周期内保持同一城市和 ISP，非常适合需要保持账户登录状态的智能体。

让模型能看到失败

智能体很难察觉自己被拦截了。CAPTCHA 页面对它来说只是又一段需要总结的文本。两个小习惯可以避免错误答案：

• 遇到 403 和 429 时抛出异常，而不是返回页面内容。 框架会把错误传回给模型，模型可以重试或报告错误，而不是基于拦截页面进行推理。
• 用新会话重试，而不是沿用原来的会话。 如果粘性会话遇到拦截，请为重试生成一个新的会话 ID。在同一个出口上重试，通常只会得到同样的结果。

限制重试次数。每个 URL 尝试三次就足够了；再多的话，你就是在为目标网站已经决定拒绝的流量付费。

成本控制

智能体可能会陷入循环。一个反复读取同一页面的规划器，消耗代理流量的速度和消耗 token 一样快。在页面内容送达模型之前进行截断（如上面的示例所示），在单次运行期间缓存已抓取的页面，并记录每次工具调用的字节数，这样失控的智能体会先出现在监控面板上，而不是先出现在账单上。

常见问题

总结

把代理交给工具，而不是整个进程。页面相互独立时使用轮换，智能体像访客一样操作时每次运行使用一个粘性会话，并让拦截足够显眼，使模型不会把它们误认为内容。