Proxy setup for AI agent frameworks

In an AI agent framework, proxy setup starts with one question: which requests should leave through netdash? An agent makes two kinds of network requests: calls to the model provider's API, and the requests its browser or tools send to websites. Only the second kind needs an exit country or a sticky session, so that is where the netdash proxy goes. For the architecture and the choice of plan, see proxies for AI agents.

netdash is a standard HTTP proxy with username and password authentication. HTTPS sites go through a CONNECT tunnel, so the proxy URL always starts with http://. No SDK or plugin is needed: every framework below already has a place for a proxy, or runs a browser or HTTP client that has one.

Where the proxy goes in an agent

In every case the model client keeps its default network path. The examples use the Scale plan on the Americas gateway (scale-us.netdash.io:2000) or the Europe gateway (scale-eu.netdash.io:2000); the proxy format reference lists all endpoints and username parameters. The code reads your credentials from NETDASH_USERNAME and NETDASH_PASSWORD; the quickstart shows where the dashboard displays them.

Browser Use

Browser Use takes the proxy on the browser session. Browser is an alias of BrowserSession, and its proxy parameter takes a ProxySettings object with server, username, password and an optional bypass list of hosts that bypass the proxy. Browser Use passes the server to Chromium and answers the proxy's authentication request with the username and password itself, so the credentials stay out of the server URL.

import asyncio
import os

from browser_use import Agent, Browser, ChatBrowserUse
from browser_use.browser.profile import ProxySettings


async def main() -> None:
    browser = Browser(
        proxy=ProxySettings(
            server="http://scale-us.netdash.io:2000",
            # One session ID per agent run keeps the run on one exit IP
            username=f"{os.environ['NETDASH_USERNAME']}-cc-US-session-a1b2c3d4-ttl-30",
            password=os.environ["NETDASH_PASSWORD"],
            bypass="localhost,127.0.0.1",
        )
    )
    agent = Agent(
        task="Open https://api.ipify.org?format=json and report the IP address shown",
        llm=ChatBrowserUse(),  # the chat model from the Browser Use quickstart
        browser=browser,
    )
    await agent.run()


asyncio.run(main())

The model class comes from the Browser Use quickstart; swap in whichever chat model your project uses. Browser Use changes quickly, so check these parameters against the version you install. The proxy belongs to the Browser, not to the Agent.

OpenAI Agents SDK

Function tools in the OpenAI Agents SDK are plain Python functions, so the proxy goes on the HTTP client inside the tool. The tool below reuses the proxy_url() helper from the Python guide and fetches pages from Germany through the Europe gateway. For computer use, the SDK expects you to provide the computer implementation, and its example launches a Playwright browser: add proxy= to that launch.

import os
from typing import Optional

import httpx
from agents import Agent, Runner, function_tool

NETDASH_USERNAME = os.environ["NETDASH_USERNAME"]
NETDASH_PASSWORD = os.environ["NETDASH_PASSWORD"]


def proxy_url(country: str = "US", session_id: Optional[str] = None,
              ttl_minutes: int = 30, gateway: str = "scale-us.netdash.io:2000") -> str:
    """netdash proxy URL: rotating without session_id, sticky with one."""
    cc = country.upper()
    cc = "GB" if cc == "UK" else cc
    username = f"{NETDASH_USERNAME}-cc-{cc}"
    if session_id is not None:
        username += f"-session-{session_id}-ttl-{ttl_minutes}"
    return f"http://{username}:{NETDASH_PASSWORD}@{gateway}"


PROXY = proxy_url("DE", gateway="scale-eu.netdash.io:2000")


@function_tool
def fetch_page(url: str) -> str:
    """Fetch a public web page as seen from Germany and return the first 5,000 characters."""
    with httpx.Client(proxy=PROXY, timeout=30, follow_redirects=True) as client:
        response = client.get(url)
        response.raise_for_status()
        return response.text[:5000]


agent = Agent(
    name="Market researcher",
    instructions="Use fetch_page for web pages. If a page shows a challenge or an error, stop and report it.",
    tools=[fetch_page],
)

result = Runner.run_sync(agent, "What does https://example.com/ say?")
print(result.final_output)

import os

from playwright.async_api import Browser, Playwright

NETDASH_PROXY = {
    "server": "http://scale-us.netdash.io:2000",
    "username": f"{os.environ['NETDASH_USERNAME']}-cc-US-session-a1b2c3d4-ttl-30",
    "password": os.environ["NETDASH_PASSWORD"],
}


async def launch_browser(playwright: Playwright) -> Browser:
    """Use this launch in your AsyncComputer implementation, for example in
    LocalPlaywrightComputer._get_browser_and_page in the SDK's computer-use example."""
    return await playwright.chromium.launch(headless=True, proxy=NETDASH_PROXY)

The SDK's hosted tools, such as WebSearchTool, run on OpenAI's servers, so a proxy you configure locally doesn't apply to them.

LangChain

LangChain tools are Python functions with the @tool decorator, and the docstring becomes the tool's description. Put the proxy on the client inside each tool and pass the tools to create_agent. The browser tool launches Playwright with the same proxy option as the Playwright guide; with a sticky username, every call in a run leaves from the same exit IP.

import os

import httpx
from langchain.agents import create_agent
from langchain.tools import tool

PROXY = (
    f"http://{os.environ['NETDASH_USERNAME']}-cc-US:{os.environ['NETDASH_PASSWORD']}"
    "@scale-us.netdash.io:2000"
)


@tool
def fetch_page(url: str) -> str:
    """Fetch a public web page as seen from the United States and return the first 5,000 characters."""
    with httpx.Client(proxy=PROXY, timeout=30, follow_redirects=True) as client:
        response = client.get(url)
        response.raise_for_status()
        return response.text[:5000]


# model: a "provider:model" string or a chat model instance, as in the LangChain docs
agent = create_agent(model="PROVIDER:MODEL", tools=[fetch_page])
result = agent.invoke({"messages": [{"role": "user", "content": "Summarize https://example.com/"}]})
print(result["messages"][-1].content_blocks)

import os

from langchain.tools import tool
from playwright.sync_api import sync_playwright

NETDASH_PROXY = {
    "server": "http://scale-us.netdash.io:2000",
    "username": f"{os.environ['NETDASH_USERNAME']}-cc-US-session-a1b2c3d4-ttl-30",
    "password": os.environ["NETDASH_PASSWORD"],
}


@tool
def read_page(url: str) -> str:
    """Open a page in a headless browser and return its visible text (first 5,000 characters)."""
    with sync_playwright() as p:
        browser = p.chromium.launch(proxy=NETDASH_PROXY)
        try:
            page = browser.new_page()
            page.goto(url, timeout=30_000)
            return page.inner_text("body")[:5000]
        finally:
            browser.close()

The browser tool uses Playwright's sync API, which suits an agent you call with invoke(). In an async agent or a notebook, write the tool with Playwright's async API instead.

Playwright MCP

Any MCP client that starts Playwright MCP can give its browser a netdash proxy the same way. Playwright MCP's --proxy-server option takes a server address only, so the credentials go in its config file under browser.launchOptions.proxy, which the README documents as options passed to Playwright's browser launch. Start the server with --isolated so the browser profile stays in memory, and keep the config file outside the repository, readable only by you.

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--isolated", "--config", "/path/to/playwright-mcp.json"]
    }
  }
}

{
  "browser": {
    "launchOptions": {
      "proxy": {
        "server": "http://scale-us.netdash.io:2000",
        "username": "USERNAME-cc-US-session-a1b2c3d4-ttl-30",
        "password": "PASSWORD"
      }
    }
  }
}

We checked this config file with Playwright MCP 0.0.83 and Chrome 155 against a local test gateway: with --isolated and with a persistent profile, the gateway received the username and password on plain-HTTP requests and on the CONNECT for HTTPS pages. The file location and top-level key of the MCP client configuration differ by client. The full walkthrough for Claude Code and Cursor, with claude mcp add, a shared .mcp.json and a check of the exit IP, is in Claude Code with Playwright MCP.

Keep model API calls out of your AI agent framework proxy setup

Don't export HTTPS_PROXY for the agent process. A global HTTPS_PROXY applies to every request the process makes, including calls to model APIs and package registries. Those requests would go through netdash and count against your balance. Set the proxy on the client that fetches websites instead.

A model SDK built on an HTTP library that honors proxy variables picks the variable up without being asked. Check yours:

The same check applies to coding agents: Claude Code, for example, reads HTTPS_PROXY for its own API traffic. The Claude Code guide shows how to keep netdash out of it.

Sessions, countries and parallel agents

• One session ID per run. Derive 8 letters and digits from the run ID, for example hashlib.sha256(run_id.encode()).hexdigest()[:8] in Python, and use it in -session-{id}-ttl-30. The run keeps one exit IP for the TTL while that IP stays available, and runs with different IDs get different sessions.
• One country per run. The username carries one country code. A run that needs two markets needs two browsers or clients. Use GB for the United Kingdom, not UK, and the -eu gateway for exits in Europe; see country targeting.
• Pace per site. netdash sets no per-account concurrency limit, so the limit that matters is the website's. Cap concurrent requests per site, and give each run a budget.
• TTL longer than the task. The dashboard presets are 15 minutes, 30 minutes, 12 hours and 7 days; the sessions docs explain them.

Responsible use for agents

An agent decides on its own which pages to open, so put the limits in its instructions and its code. Tell it to stop and hand the task to a person when a site shows a challenge, a login wall or an error, instead of trying again. Keep it to public pages and APIs the project is permitted to use, and give it no credentials for sites it shouldn't sign in to.

Errors and fixes

Keep NETDASH_USERNAME and NETDASH_PASSWORD in a .env file or your secret manager, never in source control or in a chat with an assistant.

Next steps

• Claude Code and Playwright MCP

  Credentials in .env, per-client configuration and an authenticated Playwright MCP browser.

• Sticky and rotating sessions

  Session IDs, TTLs in minutes and the dashboard presets.

• Proxies for AI agents

  Where netdash fits in an agent architecture, and how to choose exits and sessions.

Also useful: cloud browser proxy setup, the Playwright and Python guides, browser automation with netdash and country targeting.

Stuck? See troubleshooting or email support with your username (without the password) and the error message.