Proxy Config Skill

Proxy Configuration Skill

You manage residential proxy providers. Providers are configured with a JSON url_template that controls how geo/session parameters are encoded into the proxy URL.

Setup Workflow

To add a new proxy provider, make these tool calls in order:

Step 1: Add the provider

Call proxy_config with operation: "add_provider". The url_template field is a JSON string.

Most residential proxy providers use username-based parameter encoding with dash separators. Use this default template unless the provider docs show otherwise:

Copy code
proxy_config({
  "operation": "add_provider",
  "name": "smartproxy",
  "gateway_host": "gate.smartproxy.com",
  "gateway_port": 7777,
  "url_template": "{\"param_field\":\"username\",\"username_prefix\":\"{username}\",\"username_param_separator\":\"-\",\"param_separator\":\"-\",\"param_keys\":{\"country\":\"country-{v}\",\"city\":\"city-{v}\",\"state\":\"state-{v}\",\"session_id\":\"session-{v}\",\"session_duration\":\"sessTime-{v}\"},\"country_case\":\"lower\",\"city_separator\":\"_\"}"
})

Step 2: Set credentials

Copy code
proxy_config({
  "operation": "set_credentials",
  "name": "smartproxy",
  "username": "the_username",
  "password": "the_password"
})

Step 3: Test

Copy code
proxy_config({
  "operation": "test_provider",
  "name": "smartproxy"
})

If test returns "success": true, the provider is ready. If it fails, check credentials and gateway host/port.

Making Proxied Requests

Once a provider is configured:

Copy code
proxy_request({
  "url": "https://example.com/page",
  "proxyCountry": "US"
})

The system auto-selects the best healthy provider. To force a specific one:

Copy code
proxy_request({
  "url": "https://example.com/page",
  "proxyProvider": "smartproxy",
  "proxyCountry": "US",
  "sessionType": "sticky"
})

url_template Reference

The url_template JSON controls how the system builds the proxy URL. It determines how username/password strings are constructed with geo and session parameters.

Fields:

• param_field: Where params go. "username" (80% of providers), "password", or "none".
• username_prefix: Template for username base. {username} is replaced with actual username.
• username_param_separator: Separator between username and first param (e.g. "-").
• param_separator: Separator between params (e.g. "-").
• param_keys: Object mapping param names to format strings. {v} is replaced with the value.
  • country: e.g. "country-{v}" produces country-us
  • city: e.g. "city-{v}" produces city-new_york
  • state: e.g. "state-{v}" produces state-california
  • session_id: e.g. "session-{v}" produces session-abc123
  • session_duration: e.g. "sessTime-{v}" produces sessTime-10
• country_case: "lower" or "upper" for country codes.
• city_separator: Replaces spaces in city/state names (e.g. "_" makes new_york).

Result for username encoding with country US: http://myuser-country-us:mypass@gate.provider.com:7777

Result for password encoding with country US: http://myuser:mypasscountry-us@gate.provider.com:7777

Common Provider Templates

DataImpulse (username-based, dash separator)

Gateway: gw.dataimpulse.com:823

jsonCopy code
{"param_field":"username","username_prefix":"{username}","username_param_separator":"__","param_separator":"__","param_keys":{"country":"country-{v}","city":"city-{v}","session_id":"session-{v}","session_duration":"sessionduration-{v}"},"country_case":"lower","city_separator":"_"}

Decodo/Smartproxy (username-based, dash separator)

Gateway: gate.smartproxy.com:7777

jsonCopy code
{"param_field":"username","username_prefix":"{username}","username_param_separator":"-","param_separator":"-","param_keys":{"country":"country-{v}","city":"city-{v}","state":"state-{v}","session_id":"session-{v}","session_duration":"sessTime-{v}"},"country_case":"lower","city_separator":"_"}

Bright Data (username-based, dash separator)

Gateway: brd.superproxy.io:22225

jsonCopy code
{"param_field":"username","username_prefix":"{username}","username_param_separator":"-","param_separator":"-","param_keys":{"country":"country-{v}","city":"city-{v}","state":"state-{v}","session_id":"session-{v}"},"country_case":"lower","city_separator":"_"}

IPRoyal (password-based)

Gateway: geo.iproyal.com:12321

jsonCopy code
{"param_field":"password","username_prefix":"{username}","param_separator":"_","param_keys":{"country":"country-{v}","city":"city-{v}","session_id":"session-{v}","session_duration":"sessionduration-{v}"},"country_case":"lower","city_separator":"_"}

Custom/Generic (no encoding)

For providers that don't encode params in credentials:

jsonCopy code
{"param_field":"none"}

If Provider Uses Unfamiliar Format

Use python_code to reverse-engineer the template from the provider's example URL:

pythonCopy code
import json

# Example from provider docs:
# Username: user123-cc-US-city-NewYork-sess-abc123
# Password: pass456
# Host: proxy.example.com:8080

template = {
    "param_field": "username",
    "username_prefix": "{username}",
    "username_param_separator": "-",
    "param_separator": "-",
    "param_keys": {
        "country": "cc-{v}",
        "city": "city-{v}",
        "session_id": "sess-{v}"
    },
    "country_case": "upper",
    "city_separator": ""
}

# Verify it produces the right URL
username = "user123"
params = []
params.append(template["param_keys"]["country"].replace("{v}", "US"))
params.append(template["param_keys"]["city"].replace("{v}", "NewYork"))
params.append(template["param_keys"]["session_id"].replace("{v}", "abc123"))
param_str = template["param_separator"].join(params)
result = f"{username}{template['username_param_separator']}{param_str}"
print(f"Built username: {result}")
assert result == "user123-cc-US-city-NewYork-sess-abc123", f"Mismatch: {result}"

output = json.dumps(template)
print(f"Template: {output}")

Then pass the output as the url_template string to proxy_config(add_provider).

All proxy_config Operations

Optional fields for add_provider/update_provider: enabled (bool), priority (int, lower=preferred), cost_per_gb (float).

proxy_request Parameters

Transparent Proxy on HTTP Nodes

The httpRequest and httpScraper nodes have built-in proxy support. Set useProxy: true and the proxy service handles everything -- provider selection, geo-targeting, and session type are all managed from the proxy service configuration (provider priorities, routing rules, default country).

When the AI Agent uses http_request as a tool, it can set useProxy: true in the tool arguments. No other proxy fields needed.

When to use which:

• Use http_request with useProxy: true for proxied requests (simple, proxy service handles routing)
• Use proxy_request tool only when you need explicit control over retries and failover

Notes

• Always run test_provider after setting up a new provider
• If the user does not know their credentials, they need to get them from their proxy provider dashboard
• If test fails: check credentials, gateway host/port, and that the url_template matches the provider's format
• Use proxy_status to check provider health before making requests
• sessionType: "sticky" keeps the same IP across requests (good for scraping sessions)
• sessionType: "rotating" gets a new IP each request (good for anonymity)