Using NinjaProxy with AI Agents

AI agents make repeated outbound requests, revisit the same sites, and often mix API calls with browser automation. That combination hits rate limits faster, increases block risk, and can break multi-step workflows when the target sees a new IP on each step.

Guardrail: use the exact endpoint shown in your portal. Public docs use placeholders like <HTTP_ENDPOINT> and <ROTATING_HTTP_ENDPOINT> because live host and port values are account-specific.

Why AI agents need proxies

• Agents make repeated requests that can trigger per-IP rate limits or outright blocks.
• Browser-based agents are easier to flag when all traffic comes from one obvious datacenter route.
• Multi-step tasks such as login, cart flows, or account settings need a stable session identity.
• Long-running agents need deliberate control over retries, concurrency, and route reuse.

Which proxy type fits which agent workflow

Session control for multi-step workflows

When an agent needs to preserve login state or maintain a consistent identity during a run, keep the gateway endpoint the same and add structured session controls to the username. That is the current public pattern for sticky behavior on rotating gateways.

<USERNAME>--session-agent-login-01--duration-600--provider-res

The session token pins the route for that workflow, while duration bounds how long the gateway should try to keep it stable. Use a fresh session token when the next task should look like a different browsing run.

Example: proxy-aware Python agent

This pattern works for lightweight agent loops, tool-calling systems, or LangChain-style workers that fetch pages before extracting or reasoning over the result.

import requests

PROXY_URL = "http://<USERNAME>:<API_KEY>@<HTTP_ENDPOINT>"
proxies = {
    "http": PROXY_URL,
    "https": PROXY_URL,
}

def fetch(url: str) -> str:
    response = requests.get(url, proxies=proxies, timeout=20)
    response.raise_for_status()
    return response.text

research_html = fetch("https://example.com/")
print(research_html[:200])

Swap <HTTP_ENDPOINT> for the assigned endpoint from Portal → Proxy IPs, or for your rotating gateway endpoint if the workflow needs route-level controls.

Example: Playwright agent with sticky session behavior

Playwright-based browsing agents often need one stable identity across login, navigation, and follow-up actions. Keep the endpoint fixed and put the sticky-session controls in the username field.

from playwright.sync_api import sync_playwright

proxy_username = "<USERNAME>--session-agent-login-01--duration-600--provider-res"

with sync_playwright() as p:
    browser = p.chromium.launch(
        proxy={
            "server": "http://<ROTATING_HTTP_ENDPOINT>",
            "username": proxy_username,
            "password": "<API_KEY>",
        }
    )

    page = browser.new_page()
    page.goto("https://example.com/login")
    page.fill('input[name="email"]', "[email protected]")
    page.fill('input[name="password"]', "super-secret")
    page.click('button[type="submit"]')
    page.wait_for_load_state("networkidle")
    page.goto("https://example.com/account")
    print(page.title())
    browser.close()

Official MCP resources

NinjaProxy publishes official MCP-oriented resources today as public docs and a bootstrap manifest. Use those resources when your editor or assistant can preload documentation, and avoid third-party MCP listings unless they are explicitly confirmed by the official docs.

• MCP guide
• mcp.json bootstrap manifest
• llms.txt

Related docs

• Python integration for requests, httpx, aiohttp, Scrapy, and Playwright examples.
• Authentication for username + API key, whitelist mode, and username control syntax.
• Troubleshooting for auth failures, timeouts, block responses, and sticky-session mistakes.
• Rotating proxies for routed gateway behavior, sticky sessions, and routing overrides.
• MCP guide for the official AI bootstrap path.