How to Use Residential Proxies With the OpenAI Agents SDK

Quick Answer

To use a residential proxy with the OpenAI Agents SDK, put the proxy configuration in the HTTP client or browser that your agent calls as a tool. The SDK's Agent object decides when to call the tool, while the tool sends its website request through a Proxidize Residential Proxy.

The request path looks like this:

The smallest useful pattern is:

That illustrates the integration, but it is not yet a production-safe fetcher. A real implementation should restrict destinations, revalidate redirects, cap response sizes, retry only transient failures, protect proxy credentials, and treat fetched page content as untrusted data. The complete example below adds those controls.

Responsible-use note: Use proxies and automated agents only for lawful, authorized work. Respect applicable laws, privacy obligations, website terms, access controls, and reasonable request rates. A proxy changes the network route; it does not grant permission to access data or guarantee that a website will accept a request.

Methodology: OpenAI implementation details were checked against first-party documentation on August 27, 2026. Proxidize product, targeting, pricing, and MCP details were checked against current first-party pages on the same date. The examples passed syntax, import, constructor, URL-policy, redirect, extraction, and bounded-retry tests with openai-agents 0.22.0 and HTTPX 0.28.1. The complete integration path was then live-tested with a random-location Residential route: authenticated HTTPS routing, two-service IP agreement, an allowlisted page fetch, sticky continuity across five fresh clients, a real gpt-5.6 function-tool run, and the MCP approval-and-resume flow with @proxidize/mcp 0.1.3 all passed. Two independent geo responses agreed on the randomly selected exit. Country targeting and Residential-specific MCP tools were documentation-validated but were not exercised by the supplied access point and account token.

Key Takeaways

• The OpenAI Agents SDK does not need a special “residential proxy mode.” Attach a custom HTTP or browser tool to the agent, then configure that tool to use Proxidize.
• Proxying the website tool does not automatically proxy the SDK's connection to the OpenAI API. These are separate network paths.
• Use rotating sessions for independent requests that benefit from IP diversity. Use sticky sessions when several requests must share one coherent identity.
• Geo-target the proxy before a run, then verify the target-visible result. IP location, browser language, cookies, account state, and the website's own logic can all affect localized content.
• Use bounded retries and backoff for timeouts, 429 responses, and transient 5xx errors. Do not blindly rotate on every failure.
• Concurrency needs limits at the agent, tool, browser, proxy, and target layers. “Unlimited concurrent connections” is not a reason to send unbounded traffic.
• MCP complements the web tool, but it serves a different purpose. Proxidize MCP can expose proxy account and access-point operations to an agent; the HTTP client or browser still carries target-site traffic.

What Is Actually Being Proxied?

An agentic application can make several different kinds of network request. Only the component configured with the residential proxy will use it.

This distinction prevents a common integration mistake: adding proxy credentials somewhere in the agent prompt does not change the route. The network-aware code must configure the HTTP client, browser, or another tool that actually opens the target connection.

Why Pair the OpenAI Agents SDK With Residential Proxies?

The OpenAI Agents SDK provides the agent loop: a model can receive a task, decide whether to call a tool, inspect the tool's result, call more tools when needed, and produce a final answer. A residential proxy provides a network route through a real residential IP.

Together, they are useful when an agent needs controlled, location-aware access to lawful public web data. Typical examples include:

• Comparing public product availability or prices across markets.
• Monitoring localized search results and landing pages.
• Collecting fresh public information for research, enrichment, or retrieval pipelines.
• Checking how a public website renders from a selected country or city.
• Monitoring public marketplace listings for brand-protection work.
• Testing a localized web experience from a residential network.

Residential proxies are usually a better fit than mobile proxies when the workload needs broad international coverage, many possible residential IPs, or country/city/ISP targeting across markets. Proxidize Mobile Proxies are the stronger fit when a workflow specifically needs real US 4G/5G carrier identity, carrier targeting, or dedicated SIM-based exits.

A residential proxy is unnecessary for every agent. If the agent only calls your own APIs, works with local files, or can use an approved first-party data feed, adding a proxy creates complexity without adding value. The same is true when a hosted search tool already meets the task's sourcing and location requirements.

Want to test this setup? Create a Proxidize Residential Proxy access point and use its generated server and credentials in the example below.

Choose the Right Web-Access Tool

The agent needs a tool that can reach the web. Choose that tool based on what the target actually requires.

Start with an HTTP tool when it can retrieve the information reliably. Move to a browser only when the target requires JavaScript rendering or browser state. That keeps agent runs faster, cheaper, and easier to operate.

Prerequisites

You need:

1. Python 3.10 or later.
2. An OpenAI API key.
3. An active Proxidize Residential Proxy access point.
4. The access point's server, username, and password.
5. A fixed allowlist of public domains your agent is authorized to access.

Install the dependencies:

The pins above match the versions used for this guide's editorial validation. If you intentionally use newer versions, review the current OpenAI Agents SDK and HTTPX release notes before deploying.

Create a .env file locally:

Use the exact endpoint and credentials generated in your Proxidize dashboard. Do not commit .env or place credentials in an agent prompt, tool description, source URL, trace, or tool result.

The example keeps the model configurable and defaults to gpt-5.6, which OpenAI currently documents as the alias for GPT-5.6 Sol. Recheck the model choice when updating the article or SDK.

Complete Python Example

The following implementation gives the agent one read-only tool. It can fetch only explicitly allowlisted HTTPS hosts through the residential proxy. It manually validates every redirect, rejects oversized or unsupported responses, uses bounded retries, and returns extracted text instead of raw HTML.

Save it as agent_proxy.py:

Run it:

The preflight hashes the observed exit IP instead of printing it. It confirms that the proxied client can reach the public IP-check endpoint, but it does not prove that every later request used the intended route. For production monitoring, record route success, target host, status class, latency, session identifier, and geographic policy using redacted identifiers—not raw credentials or sensitive browsing data.

How the Example Works

1. The Runner Manages the Agent Loop

Runner.run() sends the task to the model. If the model selects fetch_public_page, the SDK executes the function tool, returns its structured result to the loop, and lets the agent answer or make another allowed call. max_turns=8 and the wall-clock timeout bound that loop.

2. The Function Tool Owns the Network Route

httpx.AsyncClient is created with httpx.Proxy(...), so its requests use the configured access point. trust_env=False prevents unrelated proxy environment variables from changing the route. An HTTP proxy endpoint can tunnel HTTPS targets with CONNECT; use the endpoint scheme and port shown in the Proxidize dashboard.

3. The Application, Not the Model, Controls Destinations

The model supplies a URL, but the application enforces ALLOWED_DOMAINS and revalidates each redirect. That prevents the tool from being aimed at arbitrary ports, local services, private networks, or cloud metadata endpoints. Back up the code-level allowlist with container, VPC, firewall, or proxy egress policy to address DNS and network-layer risks.

4. Tool Output Is Reduced Before the Model Sees It

Raw pages can be large, noisy, and vulnerable to indirect prompt injection. The example strips scripts and styles, caps the response at 512 KB and extracted text at 12,000 characters, and treats page text as untrusted data. Production tools should return only task-specific fields such as price, currency, stock status, location, URL, and timestamp.

5. Retries Are Bounded and Selective

The fetcher retries timeouts, connection failures, 408, 425, 429, and common transient 5xx responses with bounded backoff and jitter. It does not retry proxy authentication failures or every target error because bad credentials, policy rejections, and persistent responses will not improve through a rapid loop.

Verify That the Proxy Route Works

Do not rely on a successful 200 alone. Before giving the tool to the agent, confirm:

1. The proxy connection succeeds.
2. The access-point credentials are accepted.
3. A public IP-check service sees a valid exit IP.
4. The intended country, city, or ISP policy is reflected where relevant.
5. The real target is reachable through the same configured client.

Run preflight through the same AsyncClient captured by the function tool and log only redacted IP fingerprints. If direct and proxied observations match, look for an unconfigured second client, an environment override, or a different tool path.

Rotating vs. Sticky Residential Sessions

Rotation controls how the residential exit is selected over time. It should match the unit of work, not simply change as often as possible.

Use Sticky Sessions for Coherent Multi-Step Work

For pagination, related availability calls, or several pages viewed as one localized visitor, keep the same proxy session for the complete work unit and rotate before the next independent unit.

For this guide, use a sticky access point when one agent run may retry a request or fetch several related pages. A single independent page fetch can use rotating mode, but rotation should happen between work units—not halfway through a coherent task. Give concurrent stateful work units separate sticky sessions so they do not accidentally share one network identity.

The safest application model is:

Proxy and browser continuity are separate: a sticky IP does not preserve cookies or local storage, and a persistent browser does not force a rotating access point to keep its exit.

For a deeper treatment of work-unit leases, identity continuity, and rotation boundaries, read Proxy Sessions for AI Agents.

Use Rotation Between Independent Observations

Use rotation when observations should not share state. A new connection can still receive a previously used IP, so treat rotation as a selection policy rather than a unique-IP guarantee.

Configure sticky or rotating behavior in the Proxidize dashboard's Session Builder or access-point settings. Keep the generated access-point credentials intact rather than guessing undocumented username parameters.

Geo-Target an Agent Run

Geo-targeting lets a research job request an exit associated with a selected market. Proxidize Residential Proxies support country, city, and ISP targeting. The dashboard and Session Builder are the source of truth for the exact configuration available to your account.

For country targeting, Proxidize's public documentation shows a username suffix in this form:

Use a lowercase two-letter ISO country code and generate or copy the final credential from the dashboard. For city and ISP targeting, use the available dashboard controls instead of inventing a string format.

If you change the location of a sticky access point, refresh its session ID and copy the newly generated credentials before retesting. Editing a selector on credentials that already hold a sticky assignment may leave the current exit in place. Always verify the new route before starting the agent run.

Verify the target-visible outcome after geolocation. Websites may also use browser locale, cookies, account settings, query parameters, device context, session history, and their own IP databases. A US exit alone does not prove that a page returned the intended US store, currency, taxes, or inventory; validate the fields that matter to the task.

For multi-market collection, generate one approved access point per geographic policy and select it in application code from a fixed mapping:

The model can request a supported market such as us or de; it should never construct arbitrary proxy credentials. The application maps the validated market to a secret stored outside the prompt.

Retry Without Destroying Session Consistency

A good retry policy distinguishes the proxy layer, target layer, and application layer.

Retries within a sticky task should reuse its client and session. For state-changing tools, use idempotency keys, explicit approval, and narrower retry rules so a retry cannot duplicate an action.

Control Concurrency at Every Layer

Three ceilings matter most:

1. OpenAI API capacity: model rate limits, token use, and the maximum number of simultaneous runs.
2. Application capacity: open sockets, browser memory, CPU, connection pools, queue depth, and tool timeouts.
3. Target capacity and policy: the rate a website can reasonably accept and the rate your authorization permits.

The complete example uses both an HTTP connection limit and asyncio.Semaphore(4). In production, add a per-domain rate limiter, a bounded queue, a global run limit, and backpressure. Start conservatively, measure latency and error rates, and increase capacity only when the target policy and system telemetry support it.

Use both concurrency controls. ToolExecutionConfig(max_function_tool_concurrency=4) limits how many local function-tool calls the Agents SDK executes at once within a run. The semaphore and per-domain rate limiter constrain the outbound work those tools perform, including work across multiple simultaneous runs. Neither control replaces the other.

For stateful parallel jobs, do not let several workers accidentally share one sticky identity and cookie jar. Give each work unit its own lease:

Use a separate browser context—or a separate browser when the proxy cannot be changed per context—for each isolated browser identity. Close it in finally or with an async context manager so failures do not leak tabs, sockets, or sessions.

Proxidize Residential plans support unlimited concurrent connections, but that describes the proxy product boundary. It does not remove target rate limits, machine constraints, OpenAI limits, bandwidth costs, or the need for respectful collection.

Use a Residential Proxy With Playwright

HTTP clients cannot render client-side JavaScript. When the information appears only after browser execution, use a browser tool and configure the browser process with the same access point.

Install Playwright and Chromium:

The core proxy configuration is:

This snippet shows browser proxy configuration, but production hardening still needs request interception. Validate every main-frame navigation and block requests to non-approved origins, private networks, download endpoints, and unnecessary third-party resources. A page can redirect through JavaScript or load subresources without using HTTP Location headers, so validating only the starting URL is insufficient.

Also decide whether a task needs images, fonts, analytics scripts, video, and other large assets. Blocking unneeded resources reduces bandwidth and speeds up browser runs. Do not block assets that are necessary to calculate the page state you are measuring.

Add Proxidize Through MCP

The Model Context Protocol integration provides a standard way for an agent application to discover and call tools exposed by an MCP server. The Proxidize MCP server can give an authorized agent access to supported account, residential access-point, usage, analytics, and other plan-scoped operations.

Keep the control and data paths separate:

MCP manages supported proxy resources; the custom HTTP or browser tool still carries target traffic. The server discovers tools from the authenticated account's active subscriptions. Current residential examples include residential_get_usage, residential_list_locations, residential_get_settings, and residential_list_access_points; discover the actual list at runtime.

The OpenAI Agents SDK can connect to a local stdio MCP server. Proxidize publishes its server as @proxidize/mcp, which requires Node.js 18 or later and a Proxidize API token.

Set PROXIDIZE_API_TOKEN to the raw token copied from the dashboard. Do not include a literal Bearer  prefix; the MCP package constructs the authorization header.

require_approval="always" pauses every MCP action. Production code must surface the interruption to an authorized reviewer and resume with the decision. For unattended read-only monitoring, define and test a narrow tool-and-argument allowlist. Keep state-changing administration approval-gated and log only redacted action metadata.

The current Proxidize MCP page says the package sends anonymous operational analytics such as tool names, latency, and error rates, while excluding tool parameters and responses. Set PROXIDIZE_DISABLE_ANALYTICS=1 or DO_NOT_TRACK=1 in the MCP process environment if your policy requires opting out, and verify the current behavior before deployment.

Hosted MCP vs. Local MCP

The transport determines where connections, credentials, discovery, and approvals run.

Local stdio is the natural fit for the current Proxidize package. Keep its API token in the child process environment and out of agent-visible text.

Treat the child process's standard-error stream as sensitive operational output. During the live test, @proxidize/mcp 0.1.3 logged subscription-discovery identifiers at startup. Do not forward raw MCP process logs into prompts, public build logs, or user-facing error messages.

Production Security Checklist

Treat an agent's web-tool boundary like a small security-sensitive service.

Restrict Destinations

• Enforce exact hostnames, HTTPS, approved ports, and redirect revalidation in code.
• Reject URL credentials.
• Block private, loopback, link-local, metadata, and internal DNS destinations.
• Back application validation with firewall, VPC, or proxy egress rules.

Minimize Tool Capability

• Prefer read-only tools and separate fetching, parsing, and state-changing actions.
• Require approval for purchases, messages, submissions, account changes, or destructive operations.
• Return narrow structured fields instead of arbitrary pages.
• Cap bytes, extracted text, redirects, retries, turns, concurrency, and wall-clock time.

Treat Web Content as Untrusted

• Treat page content as evidence, never as instructions that override application policy.
• Validate every tool argument in deterministic code.
• Quarantine unexpected instructions or exfiltration attempts and corroborate high-impact conclusions.

Protect Credentials and Personal Data

• Store credentials in a secret manager or protected environment variables, never in URLs, prompts, traces, screenshots, or model-visible results.
• Redact proxy IPs and session identifiers unless operationally necessary.
• Collect personal or sensitive data only when lawful, necessary, and appropriately controlled.
• Set retention and access policies for page text, screenshots, traces, and analytics.

Observe the Right Metrics

• Success, status classes, retries, and latency by approved target.
• Proxy authentication, connection, geo-validation, and sticky-session failures.
• Response-size and rate-limit events.
• Bandwidth and cost per completed work unit.
• Agent turns, token use, timeouts, and approval interruptions.

Agents SDK tracing can include model and tool events, so minimize tool output before it enters a run. Never return secrets or unnecessary raw content.

Common Mistakes

Troubleshooting

Deployment Checklist

Before moving an OpenAI agent with residential proxy access into production, confirm all of the following:

• The use case is lawful, authorized, and reviewed against relevant terms and rate guidance.
• Secrets stay outside prompts, source control, URLs, and tool output.
• Exact destination and egress allowlists are enforced, including redirects and browser navigation.
• Preflight and target-visible geo checks pass without logging raw exit IPs.
• Sticky sessions align with work-unit and browser-state boundaries.
• Retry, redirect, response-size, turn, concurrency, and wall-clock budgets are bounded.
• Tool output is structured, minimized, and treated as untrusted.
• Logs and traces exclude credentials and unnecessary sensitive data.
• MCP tools use least privilege and appropriate approvals.
• Alerts cover route, authentication, geo, rate-limit, and cost failures.
• A kill switch can stop new work promptly.