AI Ajanları için Proxy Kurulumu: browser-use, Crawl4AI ve MCP

Bir bulut VM'inde çalışan AI ajanı internete bir datacenter IP'sinden çıkar. Siteler her şeyden önce bu IP'yi görür; sonuçta ajan yanlış ülkenin sonuçlarını alır, kendisinin yol açmadığı hız limitlerine takılır ya da çıkamadığı bir CAPTCHA döngüsüne düşer. AI ajanları için iyi bir proxy kurulumu, çıkış (egress) sorununu prompt'ta değil tarayıcı yapılandırmasında çözer. Çok adımlı görevler baştan sona tek bir sticky IP'de kalır, paralel istekler ise rotasyonla dağıtılır. Aşağıda browser-use, Crawl4AI ve bir MCP sunucusu için çalışan yapılandırmalar, maliyet kontrolleri ve en sık karşılaşılan hata senaryoları var.

AI ajanları için proxy kurulumu neden script'lerden daha önemli

Ajanların proxy'ye ihtiyaç duymasının nedenleri scraper'larınkiyle aynıdır: coğrafya, hız limitleri ve IP itibarı. Ama ihtiyaç daha acildir, çünkü ajanlar gözetimsiz çalışır ve yeniden deneme kararlarını kendileri verir. Engellenen bir script durur. Engellenen bir ajan ise tekrar dener, görevi başka sözcüklerle ifade eder, yeni bir sekme açıp yine dener; her deneme bant genişliğine ve LLM token'ına mal olur.

• Coğrafya. Fiyatlar, arama sonuçları, stok durumu ve yasal bildirimler ülkeye göre değişir. Bir US-East VM'inden Alman bir müşteri için fiyat karşılaştıran ajan yanlış veri topluyor demektir. Proxy kullanıcı adında ülke hedeflemek, ajanın mantığına dokunmadan bunu çözer. Mekanizmayı coğrafi hedefli proxy'ler nasıl çalışır yazısı anlatıyor.
• Bulut çıkış IP'lerinin itibarı. AWS, GCP, Azure ve Hetzner aralıkları herkese açıktır ve IP itibar servisleri bunları tüketici erişimi olarak değil hosting olarak puanlar. Birçok site bu aralıklara, istek nasıl görünürse görünsün, ilk bakışta challenge gösterir veya hızlarını kısar. Bu puanlamanın nasıl işlediğini IP itibarı incelememizde ele aldık.
• Paylaşılan hız limitleri. Tek bir NAT gateway arkasındaki birkaç ajan tek bir genel IP'yi paylaşır. Her biri tek başına nazik davranır, ama birlikte agresif tek bir istemci gibi görünürler.

Proxy'nin çözmediği şey şu: residential bir IP, otomatik bir tarayıcıyı insan gibi göstermez. Davranış ve fingerprint tespiti yine çalışır; bunun nasıl olduğunu sitelerin AI tarayıcı ajanlarını nasıl tespit ettiğini anlatan tamamlayıcı yazımız gösteriyor. Proxy'leri doğru ve coğrafi olarak isabetli veri almak ve yükü adil dağıtmak için kullanın. Otomasyona kapısını açıkça kapatmış bir siteyi aşmak için kullanmayın.

Sticky oturum mu, rotasyon mu: karar projeye göre değil, göreve göre

Pratik kural: görev durum taşıyorsa IP'yi sabitleyin; taşımıyorsa döndürün. Giriş → gezinme → sepete ekleme → ödeme akışı baştan sona tek bir çıkış IP'sinde kalmalıdır, çünkü birçok site oturum çerezlerini, CSRF token'larını veya risk puanlarını oturumu açan IP'ye bağlar. Akışın ortasında IP değişirse çoğu zaman oturumunuz kapanır ya da yeniden challenge alırsınız. Birbirinden bağımsız sayfa istekleri ise tam tersidir: bunları IP'lere yaymak her birini IP başına limitlerin altında tutar.

Backconnect gateway ile modlar arasında kullanıcı adını değiştirerek geçersiniz. USERNAME-sid-abc123-ttl-10m, o oturum kimliğini kullandığınız sürece aynı çıkış IP'sini korur. Düz USERNAME rotasyon yapar. USERNAME-country-US ülkeyi sabitler. Oturum ömürlerini sticky ve rotasyonlu oturumlar rehberi daha ayrıntılı anlatıyor.

browser-use: güncel API'de proxy yapılandırması

browser-use, Browser üzerinde (BrowserSession'ın takma adı) server, username, password ve bypass alanlarına sahip bir proxy=ProxySettings(...) argümanı alır. Kimlik bilgileri tarayıcıya gider, LLM context'ine asla girmez. Arka planda browser-use, Chromium'u --proxy-server ile başlatır ve proxy'nin kimlik doğrulama isteğini CDP üzerinden (Fetch.authRequired) yanıtlar; yani kimlik bilgilerini URL'ye koymanız hiç gerekmez. Import yoluna dikkat edin: ProxySettings paket kökünde değil, browser_use.browser içinde yer alır (bkz. tarayıcı parametreleri başvurusu ve profile.py).

import asyncio
import os
import uuid

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

PROXY_USER = os.environ["PROXYHAT_USER"]
PROXY_PASS = os.environ["PROXYHAT_PASS"]


async def run_checkout_test() -> None:
    # Akışın tamamı için tek sticky oturum kimliği: giriş -> sepet -> ödeme tek çıkış IP'sinde kalır.
    session_id = uuid.uuid4().hex[:12]

    browser = Browser(
        headless=True,
        proxy=ProxySettings(
            server="http://gate.proxyhat.com:8080",
            username=f"{PROXY_USER}-sid-{session_id}-ttl-10m",
            password=PROXY_PASS,
            bypass="localhost,127.0.0.1",
        ),
        # Ajanı test edilen sitede tutar; sensitive_data'nın nereye yazılabileceğini de sınırlar.
        allowed_domains=["https://staging.example-shop.com"],
        # Chromium bayrağı: görselleri hiç indirme.
        args=["--blink-settings=imagesEnabled=false"],
    )

    agent = Agent(
        task="Log in with x_user / x_pass, add the cheapest USB-C cable to the cart, "
             "stop at the payment page and report the order total.",
        llm=ChatOpenAI(model=os.environ["OPENAI_MODEL"]),
        browser=browser,
        # Model değerleri değil, yalnızca x_user / x_pass yer tutucularını görür.
        sensitive_data={
            "https://staging.example-shop.com": {
                "x_user": os.environ["SHOP_USER"],
                "x_pass": os.environ["SHOP_PASS"],
            }
        },
        use_vision=False,   # her adımda ekran görüntüsü yok: daha az token
        max_failures=2,     # varsayılan 5; her hata yeni bir sayfa yükleme turu demek
    )
    history = await agent.run(max_steps=25)   # varsayılan 500
    print(history.final_result())


asyncio.run(run_checkout_test())

Bu kalıpla ilgili notlar:

• Kimlik doğrulamalı proxy'lerde HTTP portunu kullanın. Chromium'un ağ yığını belgeleri SOCKSv5 için hiçbir kimlik doğrulama yönteminin desteklenmediğini belirtiyor; dolayısıyla kimlik bilgili socks5://…:1080, Chromium tabanlı her ajanda başarısız olur. http://gate.proxyhat.com:8080 kullanın.
• Proxy kimlik bilgileri sensitive_data değildir. sensitive_data, ajanın sayfalara yazması gereken değerler içindir. Proxy kimlik bilgileri, modelin hiç görmediği ProxySettings içine gider. "Ajan bilsin diye" bir proxy URL'sini task dizesine yapıştırmayın.
• allowed_domains göründüğünden daha önemlidir. Domain'leri kısıtlamadan sensitive_data geçirirseniz browser-use bir uyarı loglar; çünkü aksi halde prompt injection içeren bir sayfa, ajanı gizli bilgileri başka bir yere yazmaya ikna edebilir.
• Bulut modu farklı bir çıkış noktasıdır. Browser(use_cloud=True), tarayıcıyı kendi proxy'leriyle Browser Use Cloud üzerinde çalıştırır. Sizin ProxySettings ayarlarınız yalnızca kendi başlattığınız yerel veya cdp_url tarayıcısı için geçerlidir.
• Varsayılan eklentiler bant genişliği kazandırır. enable_default_extensions varsayılan olarak açıktır ve uBlock Origin Lite ile bir çerez banner'ı işleyicisi yükler; böylece reklam ve izleyicilerin çoğu trafiğinizden düşmez.

Crawl4AI: tarama başına proxy, rotasyon ve sticky oturumlar

Crawl4AI'da proxy'yi her tarama için CrawlerRunConfig üzerinde ayarlayın; ya proxy_config olarak ya da bir proxy_rotation_strategy aracılığıyla. Proxy belgeleri, eski BrowserConfig proxy argümanını kullanımdan kaldırılmış olarak işaretliyor ve proxy'lerin istek başına yapılandırılmasını öneriyor. Sticky davranış için proxy_session_id, stratejideki bir proxy'yi o kimliği paylaşan her taramaya sabitler.

Backconnect gateway tek bir host'tur; dolayısıyla "proxy listesi", oturum kullanıcı adlarından oluşan bir liste demektir. Her oturum kimliği kendi çıkış IP'sine sahip bir slot'tur ve round-robin URL'leri slot'lara dağıtır:

import asyncio
import os
import uuid

from crawl4ai import (AsyncWebCrawler, BrowserConfig, CacheMode,
                      CrawlerRunConfig, ProxyConfig, RoundRobinProxyStrategy)

USER = os.environ["PROXYHAT_USER"]
PASS = os.environ["PROXYHAT_PASS"]


def slot() -> ProxyConfig:
    # Slot başına bir sticky oturum: her slot tek bir çıkış IP'sini korur.
    sid = uuid.uuid4().hex[:10]
    return ProxyConfig(
        server="http://gate.proxyhat.com:8080",
        username=f"{USER}-sid-{sid}-ttl-10m",
        password=PASS,
    )


strategy = RoundRobinProxyStrategy([slot() for _ in range(8)])

browser_cfg = BrowserConfig(
    headless=True,
    text_mode=True,   # görselleri ve diğer ağır içerikleri kapatmaya çalışır
    avoid_ads=True,   # yaygın reklam/izleyici domain'lerini engeller
)

bulk_cfg = CrawlerRunConfig(
    proxy_rotation_strategy=strategy,   # her URL için sıradaki slot
    cache_mode=CacheMode.BYPASS,
    check_robots_txt=True,
    max_retries=1,
)


async def main(urls: list[str]) -> None:
    async with AsyncWebCrawler(config=browser_cfg) as crawler:
        results = await crawler.arun_many(urls, config=bulk_cfg)
        for r in results:
            print(r.url, r.success, len(r.markdown or ""))

        # Durum taşıyan akış: her adımda aynı proxy slot'u VE aynı tarayıcı sayfası.
        step_cfg = bulk_cfg.clone(proxy_session_id="acct-42", session_id="acct-42")
        await crawler.arun("https://example.com/login", config=step_cfg)
        await crawler.arun("https://example.com/account/orders", config=step_cfg)


asyncio.run(main(["https://example.com/a", "https://example.com/b"]))

İki ayar kolayca karıştırılır. session_id aynı tarayıcı sayfasını arun() çağrıları boyunca korur, proxy_session_id ise aynı proxy'yi. Durum taşıyan bir akış ikisine de ihtiyaç duyar. Sticky slot'lar yerine coğrafi olarak sabitlenmiş rotasyon için USERNAME-country-US kullanıcı adına sahip tek bir ProxyConfig kullanın.

Yeniden deneme katlanması tuzağı: proxy_config, sırayla denenecek proxy'lerden oluşan bir liste de kabul eder ve async_webcrawler.py içindeki yeniden deneme döngüsü her denemede listenin tamamını dolaşır. Bu yüzden engellenmiş bir URL (max_retries + 1) × len(list) kereye kadar çekilebilir. 10 yedek proxy ve max_retries=3 ile bu, zaten hiç yüklenmeyecek tek bir URL için 40 tam sayfa yüklemesi eder. Listeyi kısa tutun ve max_retries değerini bilinçli olarak ayarlayın.

Bir MCP asistanına proxy üzerinden web erişimi vermek

İki seçeneğiniz var: Microsoft'un Playwright MCP sunucusunu yapılandırmasında proxy ile çalıştırmak ya da proxy üzerinden sayfa çekip metin döndüren küçük bir MCP aracı yazmak. Asistanın tıklaması ve yazı yazması gerekiyorsa ilkini kullanın. Yalnızca sayfa okuması gerekiyorsa ikincisini kullanın; çağrı başına çok daha ucuzdur.

Seçenek 1: kimlik doğrulamalı proxy ile Playwright MCP

@playwright/mcp paketinde --proxy-server ve --proxy-bypass bayrakları var (README). Kimlik bilgisi gerektiren bir proxy için bunun yerine JSON yapılandırma dosyasını kullanın. Dosyadaki browser.launchOptions doğrudan Playwright'a aktarılır; Playwright'ın proxy seçeneği de ayrı username ve password alanları alır:

{
  "browser": {
    "browserName": "chromium",
    "isolated": true,
    "launchOptions": {
      "headless": true,
      "proxy": {
        "server": "http://gate.proxyhat.com:8080",
        "username": "USERNAME-sid-mcp01-ttl-10m",
        "password": "PASSWORD"
      }
    }
  },
  "capabilities": ["core"]
}

npx @playwright/mcp@latest --config ./playwright-mcp.json --image-responses omit

Bu dosyayı repoya koymayın ve yalnızca sunucuyu çalıştıran kullanıcının okuyabileceği şekilde tutun. Buradaki oturum kimliği, asistan oturumunun tamamının tek bir IP'yi paylaşması demektir; bu da "giriş yap ve X'i yap" senaryosuna uyar. Yeni bir IP istediğinizde yeni bir kimlikle yeniden başlatın. --image-responses omit, ekran görüntülerinin modele geri gönderilmesini engeller. "isolated": true (--isolated bayrağı) profili bellekte tutar, böylece çerezler görevler arasında sızmaz. README ayrıca --allowed-origins ve --blocked-origins bayraklarının bir güvenlik sınırı olmadığını belirtiyor. Bunları koruma değil, temizlik önlemi olarak görün.

Seçenek 2: resmi MCP Python SDK ile minimal bir proxy'li fetch aracı

Python SDK'nın v2 sürümü FastMCP'nin adını MCPServer olarak değiştirdi (geçiş kılavuzu). v1 için from mcp.server.fastmcp import FastMCP ile yazılmış kodun yeni import'a geçmesi gerekiyor. Aşağıda gateway üzerinden sayfa çeken, yanıt boyutunu sınırlayan ve proxy URL'sini çıktısına asla koymayan salt okunur bir araç var:

import os
import re

import httpx
from mcp.server import MCPServer

mcp = MCPServer("proxied-fetch")

_USER = os.environ["PROXYHAT_USER"]
_PASS = os.environ["PROXYHAT_PASS"]
_MAX_BYTES = 1_500_000
_COUNTRY = re.compile(r"^[A-Za-z]{2}$")
_SESSION = re.compile(r"^[A-Za-z0-9]{1,24}$")


def _proxy(country: str | None, session: str | None) -> str:
    user = _USER
    # Modelin verdiği değerleri doğrulayın: bunlar proxy kullanıcı adının içine giriyor.
    if session:
        if not _SESSION.match(session):
            raise ValueError("session must be 1-24 alphanumerics")
        user = f"{_USER}-sid-{session}-ttl-10m"
    elif country:
        if not _COUNTRY.match(country):
            raise ValueError("country must be a 2-letter code")
        user = f"{_USER}-country-{country.upper()}"
    return f"http://{user}:{_PASS}@gate.proxyhat.com:8080"


@mcp.tool()
async def fetch_page(url: str, country: str | None = None, session: str | None = None) -> str:
    """Fetch a public http(s) page through a residential proxy and return its text.

    country: optional 2-letter exit country. session: optional ID to reuse one exit IP.
    """
    if not url.startswith(("http://", "https://")):
        return "error: only http(s) URLs are allowed"
    try:
        async with httpx.AsyncClient(proxy=_proxy(country, session), timeout=30,
                                     follow_redirects=True) as client:
            async with client.stream("GET", url) as resp:
                body = b""
                async for chunk in resp.aiter_bytes():
                    body += chunk
                    if len(body) > _MAX_BYTES:
                        break
        text = body.decode(resp.encoding or "utf-8", errors="replace")
        return f"HTTP {resp.status_code} {resp.url}\n\n{text[:200_000]}"
    except ValueError as e:
        return f"error: {e}"
    except httpx.HTTPError as e:
        # Yalnızca exception türü: bazı mesajlar proxy URL'sini tekrar edebilir.
        return f"error: fetch failed ({type(e).__name__})"


if __name__ == "__main__":
    mcp.run(transport="stdio")

Aracı MCP istemcinize stdio sunucusu olarak kaydedin. PROXYHAT_USER ve PROXYHAT_PASS değerlerini araç argümanlarıyla değil, istemcinin env bloğuyla geçirin. Örneğin Claude Code'da bu, claude mcp add --env PROXYHAT_USER=… --env PROXYHAT_PASS=… --transport stdio proxied-fetch -- python server.py şeklindedir. --transport bayrağını son --env ile sunucu adı arasında tutun; aksi halde CLI sunucu adını başka bir env çifti olarak okur. Regex kontrolleri boşuna değil: prompt injection içeren bir sayfa modelin aracı tuhaf argümanlarla çağırmasına yol açabilir ve kontrol edilmeyen girdi, proxy kullanıcı adınıza rastgele metin yazılmasına izin verir. JavaScript gerektiren sayfalar için seçenek 1'i kullanın; tarayıcı katmanını kendiniz kuruyorsanız Playwright ile rotasyonlu proxy rehberimize bakın.

Maliyet kontrolü: ajanlar bant genişliğini script'lerin yapmadığı şekillerde tüketir

Residential trafik gigabayt başına faturalandırılır ve bir ajan tam sayfalar yükler, çoğu zaman da adım başına birkaç kez. En büyük farkı yaratan kontroller, kabaca önem sırasıyla şunlar:

1. Modelin okumayacağı şeyleri yüklemeyin. Görseller, video, fontlar ve reklam script'leri modern bir sayfanın ağırlığının büyük kısmını oluşturur. Crawl4AI'da text_mode=True ve avoid_ads=True, browser-use'da imagesEnabled=false bayrağını veya uBlock'u kullanın; sayfa sunucu tarafında render ediliyorsa tarayıcı yerine bir fetch aracı kullanın.
2. Yeniden denemeleri iki yerde sınırlayın. Framework yeniden denemeleri (max_failures, max_retries) ile ajan düzeyindeki yeniden planlama birbirini katlar. 403 aldıktan sonra "farklı bir yaklaşım deneyen" bir ajan çoğu zaman yalnızca aynı engellenmiş sayfayı yeniden yükler. max_steps değerini, takılan bir çalıştırmanın ucuza sonlanacağı kadar düşük ayarlayın.
3. Durum taşıyan akışlarda context'leri yeniden kullanın. Yeni bir browser context; yeni çerezler, yeni bir challenge ve önbelleğe alınmış her varlığın yeniden indirilmesi demektir. Tek bir görev içinde context'i (ve sticky IP'yi) canlı tutun.
4. Engelleme sinyallerinde durun. CAPTCHA sayfasını, bir bot yönetimi sağlayıcısından gelen 403'ü veya 429'u, bir insana raporlanan son durum olarak ele alın. Ajanın yeniden deneyerek bunu aşmaya çalışmasına izin vermeyin. Geri çekilmenin gerekçesini CAPTCHA yönetimi rehberimiz anlatıyor.
5. Aylık değil, görev başına ölçün. Ajan çalıştırması başına bayt sayısını loglayın. Ani bir artış genellikle daha büyük bir iş değil, bir döngü anlamına gelir.

Tasarım aşamasında hesaba katılması gereken hata senaryoları

Ajan-proxy olaylarının çoğu dört nedenden birinden kaynaklanır: CAPTCHA döngüsü, yeniden deneme katlanması, sessizce IP değiştiren bir oturum ya da kimlik bilgilerinin model context'ine sızması.

• CAPTCHA döngüleri. Görsel yeteneği açık ajanlar bir challenge'ı "çözmeye" çalışır, başarısız olur, sayfayı yeniler ve yeniden dener. Challenge sayfalarını (bilinen iframe host'ları, "Just a moment…" gibi başlıklar) tespit edin ve çalıştırmayı sonlandırın. Challenge'ları ölçekli olarak yanıtlamak meşru bir pipeline'ın yapacağı bir şey değildir; residential bir IP'den gelen tekrarlı başarısızlıklar da o IP'nin itibarını onu kullanan herkes için zedeler.
• Yeniden deneme katlanması. Yukarıda anlatıldı: framework yeniden denemeleri × proxy yedek listeleri × ajanın yeniden planlaması. Yalnızca hataları değil, URL başına toplam deneme sayısını izleyin.
• Sessiz oturum kopmaları. Sticky oturum TTL'i dolduğunda sona erer; upstream eş çevrimdışı olursa daha erken de bitebilir. Bu durumda sonraki istek yeni bir IP'den çıkar. Akışın ortasındaki bir istek aniden giriş sayfasına yönlendiriliyorsa IP'nin değiştiğini varsayın. Ajanın doğaçlama yapmasına izin vermek yerine akışı yeni bir oturum kimliğiyle yeniden başlatın.
• LLM context'indeki kimlik bilgileri. Modele ulaşan her şey loglara, trace'lere, değerlendirme veri setlerine veya prompt injection ile tetiklenen bir sızdırma isteğine girebilir. Proxy kimlik bilgilerini tarayıcının veya HTTP istemcisinin okuduğu ortam değişkenlerinde tutun. Bunları görev dizelerine, sistem prompt'larına veya araç çıktısına koymayın ve exception mesajlarını döndürmeden önce temizleyin. Playwright MCP'nin secrets seçeneği bilinen dizeleri araç yanıtlarından maskeleyebilir, ama kendi README'si bunu bir güvenlik özelliği değil, kolaylık olarak tanımlıyor.

Ajanı suçlamadan önce proxy'yi tek başına test edin: yapılandırdığınız kullanıcı adı varyantını proxy checker üzerinden çalıştırın ve çıkış ülkesi ile IP türünün beklediğiniz gibi olduğunu doğrulayın. Ajan iş yükleri için IP türlerinin daha geniş bir karşılaştırması için AI ajanları ve LLM web veri toplama için en iyi proxy'ler yazısına bakın.

Bu kurulumun çözmediği şeyler

Proxy, trafiğin nereden geldiğini değiştirir, nasıl davrandığını değil. Bir ajanın davranışsal bot tespitini geçmesini sağlamaz ve robots.txt'sinde veya kullanım koşullarında otomasyonu engelleyen bir siteye erişim izni de değildir. Kişisel veri toplamayı yasal hale de getirmez. Bir site API, veri akışı veya imzalı ajan programı sunuyorsa, bu yollar genellikle her türlü proxy yapılandırmasından daha ucuz ve daha güvenilirdir. Residential IP'leri iyi oldukları işler için kullanın: doğru coğrafya, adil yük dağılımı ve bir bulut aralığının itibarını devralmamak.