How to Use Residential Proxies With Google ADK Agents

Quick Answer

To use a residential proxy with a Google Agent Development Kit (ADK) agent, configure the proxy on the custom HTTP or browser tool that opens target websites. ADK orchestrates the model, tools, sessions, events, callbacks and workflow. The network-aware tool sends website requests through the Proxidize Residential Proxy.

The essential HTTPX connection pattern is:

ADK can expose that operation to Gemini as an ordinary Python function tool:

For a coherent task that visits several related pages, use one Sticky residential access point and keep one HTTP client or browser context for that work unit. Rotate at a clean boundary between independent jobs, users or market observations. A Random access point is better for unrelated one-shot requests that benefit from broader IP diversity.

Google ADK does not have one global residential-proxy switch. Proxying HTTPX or Chromium also does not automatically proxy the Gemini API, Google Search, MCP management calls, database checkpoints or any other client in the process.

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

Methodology: Google ADK, Agents CLI, Gemini model, function-tool, session, runtime, concurrency, callback, Google Search and MCP behavior was checked against current Google documentation on September 1, 2026. Proxidize MCP behavior was checked against the official package and repository, and product details were checked against current Proxidize pages. The exact example passed compilation, schema, mocked Runner, authenticated proxy, HTTPX, Playwright, policy and citation tests with google-adk 2.8.0, HTTPX 0.28.1 and Playwright 1.62.0. It was then live-tested with Gemini 3.6 Flash, a Proxidize Residential access point and the allowlisted IANA page. The real agent tool loop and citation gate passed, both live transports passed, and five fresh clients observed one redacted exit fingerprint.

Key Takeaways

• Proxy the website tool, not “ADK.” Put Proxidize credentials on the HTTPX, Playwright, Selenium or other network client that opens the destination.
• The model path and website path are separate. A proxied browser does not make Gemini API calls, Google-hosted search or every process dependency use the same route.
• Use HTTPX first. It is faster, simpler and usually more bandwidth-efficient when the page's required content is already in its response. Add a browser only for JavaScript, browser state or rendered interaction.
• Sticky is the safer default for a multi-page task. Preserve a consistent combination of exit IP, cookies and target-side session state, then rotate between independent work units.
• ADK session state is not proxy state. A session_id can preserve serializable agent data while the exit IP, browser context, cookies and open connections change independently.
• Bound the real network operation. ADK can run async function tools concurrently, so place a semaphore, browser lock, timeouts and per-target rate limits inside the tool runtime.
• Treat pages as untrusted evidence. Prompt instructions cannot replace destination allowlists, redirect checks, private-network blocking, action approval and output validation.
• MCP is a control plane here. Proxidize MCP can expose account, usage, location and access-point operations to ADK; HTTPX or Playwright still carries the target-page traffic.

What Is Google ADK?

Google Agent Development Kit is Google's open-source framework for building and operating agents. It provides model integrations, function tools, agent composition, sessions and state, runtime events, callbacks, evaluation and deployment paths. Python, TypeScript, Go, Java and Kotlin implementations are available; this guide uses Python because its HTTPX, Playwright and ADK interfaces make the network boundary easy to see.

ADK is the orchestration layer. It can decide when a tool should run, pass validated model arguments to the tool, persist serializable state and return tool results to the model. It does not become the network transport used inside every custom function.

ADK automatically wraps a typed Python callable in a FunctionTool when it appears in an agent's tools list. The function signature and docstring become the model-visible schema. A ToolContext parameter is injected by ADK and omitted from that schema, which lets the function update session state without asking the model to construct framework objects.

Where Agents CLI fits

Google Agents CLI is a companion developer workflow for scaffolding, building, testing, evaluating and deploying ADK agents. It is useful once an integration becomes a maintained application, but it is not required to understand or run the single-file example below.

The current CLI can be launched with uvx:

Agents CLI does not change the proxy boundary. Whether an agent was handwritten or scaffolded, the HTTP/browser implementation is still where the residential endpoint belongs.

What Is Actually Being Proxied?

Only the component explicitly configured with Proxidize uses the residential route.

This gives you a simple diagnostic rule: a successful Gemini response does not prove the website used a residential route, and a successful proxy preflight does not prove Gemini, hosted Google Search or MCP used that route.

Do not put a proxy URL, password or API token in a prompt, tool description, ADK state field, trace, screenshot or tool result. Pass the proxy server, username and password directly to the network client as separate secret values.

Why Pair Google ADK With Residential Proxies?

A custom web tool may need to inspect lawful public content as it appears from a residential connection or selected market. Common examples include:

• Comparing public prices, availability or promotions across regions.
• Monitoring localized search results, landing pages or storefronts.
• Collecting fresh public evidence for market research, RAG or evaluation.
• Testing visible language, currency and regional site behavior.
• Reviewing public marketplace listings for brand-protection work.
• Validating how an approved site responds from a chosen country, city or ISP.

Proxidize Residential Proxies provide real residential IPs across 195+ countries, country/city/ISP targeting, rotating and sticky sessions, standard HTTP(S) and SOCKS5 compatibility, and dashboard/API control. Because the integration uses ordinary proxy settings, the ADK tool does not need a proprietary proxy SDK.

Residential proxies are generally the better fit for broad international coverage and global web data work. Proxidize Mobile Proxies are the narrower choice when the workflow specifically needs a real US 4G/5G carrier route, mobile carrier targeting or a dedicated SIM-based exit.

A proxy is not necessary for every ADK agent. If the agent reads local documents, calls your own APIs, uses a licensed dataset or gets the required answer from an approved provider-hosted tool, adding a browser and proxy may increase cost and complexity without improving the result.

Want to test the architecture? Create a Proxidize Residential Proxy access point and place its generated server, username and password in the environment variables below. For the broader product fit, see AI Agent Proxies for Reliable Web Access.

Prerequisites

You need:

1. Python 3.11 or later for the complete ADK, MCP and optional Agents CLI workflow shown here.
2. A fresh Google API key with access to the selected Gemini model.
3. An active Proxidize Residential Proxy plan and dashboard-generated access point.
4. Separate proxy server, username and password values.
5. A small exact allowlist of public domains the workflow is authorized to visit.
6. Node.js 18 or later only if you add the Proxidize MCP section.
7. A dedicated container or virtual machine for production browser execution.

Create a virtual environment and install the versions validated for this draft:

The mcp extra matters only for MCP. Installing base google-adk==2.8.0 is enough for the HTTPX and Playwright function tools, but it does not install the Python MCP dependency needed to import McpToolset.

google-adk 2.8.0 and google-agents-cli 1.4.2 were the current ADK and Agents CLI PyPI releases checked for this guide. gemini-3.6-flash is the stable Gemini 3.6 Flash model ID used in the tested configuration. Gemini 3.7 Flash is newer, but it returned Google's temporary high-demand 503 response on both live attempts made for this draft. Pin and retest the framework, model and network libraries together when updating the example.

Create a local .env file:

The IANA page is a safe documentation target for an initial connection test. Replace it with public pages your application is authorized to inspect, then change ALLOWED_DOMAINS to the smallest exact set that workflow needs.

Add the secret file to .gitignore before running anything:

For production, inject secrets through a secret manager or deployment platform instead of keeping a long-lived .env file. Rotate any credential that has appeared in chat, terminal history, logs, screenshots or source control.

Configure the Residential Access Point First

Create the access point in the Proxidize dashboard before changing the Python code. For a multi-page research task, start with:

• Protocol: HTTP/HTTPS for the combined HTTPX and Playwright example.
• Session behavior: Sticky for one coherent work unit.
• Location: The country, city and ISP required by the legitimate use case.
• Authentication: Generated username/password credentials or an approved IP-whitelist configuration.

Use the generated values exactly. Do not manually invent targeting or session parameters in the username unless the current dashboard or documentation explicitly gives you that format.

The example accepts the proxy in three separate fields. That avoids putting a password in a logged URL and safely handles reserved characters in credentials:

Build the HTTPX Tool First

Start with HTTPX when the required content is present in the server response. It uses less memory and bandwidth than a browser and gives you direct control over redirects, status codes, response sizes and timeouts.

That snippet demonstrates placement, not a production security boundary. The complete implementation below adds exact-host approval, HTTPS-only policy, public-IP checks, redirect revalidation, content-type and byte limits, bounded retries, output reduction and sanitized errors.

Add Playwright Only When the Page Needs It

Use a browser when the evidence depends on JavaScript rendering, browser-managed cookies, client-side requests or visible browser state. Configure the same access point at Chromium launch:

Keep one browser context for one coherent sticky work unit. Close it when that unit finishes. Creating a new ADK session does not automatically create or rotate a browser context, and restoring an ADK session does not restore an old Chromium process.

Complete Google ADK Agent Example

The following single-file implementation is intentionally read-only. The agent can fetch or render an approved page, but it cannot click, type, authenticate, download or submit anything. Application code—not the model—enforces the destination, network, response, retry, tool and citation boundaries.

Run the example

Save the file as adk_proxy_agent.py, load fresh credentials into the environment, and run:

A successful run prints a short per-process exit fingerprint followed by the agent's cited answer:

The preflight reads the raw IP only inside the process and logs an HMAC fingerprint. Because the HMAC key is random for each process, the value is useful for comparisons within one run but cannot become a durable identifier or be compared across restarts. Do not return the raw exit IP or the fingerprint to the model.

How the Complete Example Works

The implementation has seven independent safeguards:

1. Settings loads proxy fields separately, normalizes the proxy endpoint and rejects embedded credentials.
2. validate_target_url() allows HTTPS port 443 only, requires an exact hostname, resolves it and rejects private or non-global destinations.
3. ProxyWebRuntime owns one HTTPX client and one lazily created Playwright context for the work unit.
4. HTTP redirects are followed manually and revalidated before the next request. Browser requests pass through a route guard that applies the same hostname and public-address policy to page resources, and the read-only browser disables WebSockets.
5. Both transports return bounded text records marked as untrusted website content instead of exposing unlimited HTML to the model.
6. The ADK callback caps tool-call attempts, RunConfig caps model calls, a semaphore caps network operations and a separate lock serializes work on the shared browser page.
7. The final validator rejects an answer that has no HTTPS citation or cites a URL no tool successfully observed.

The DNS check reduces obvious server-side request forgery risk, but application-level resolution still has a time-of-check/time-of-use gap. A forward proxy may also resolve the hostname at the gateway rather than use the address your application checked. Use exact organization-approved hosts, require proxy-side public-destination enforcement, and isolate the worker so its direct egress can reach only required services such as the proxy gateway and model API. Browser routing hooks do not cover every possible browser protocol, so they are not a replacement for network containment.

Why the runtime is outside ADK state

HTTP clients, browser objects, locks and semaphores are process resources. They are not serializable research state and should not be written to tool_context.state. The example captures the runtime in the function-tool closures and stores only small values such as the last successful URL and transport in the ADK session.

That separation also makes lifecycle ownership clear: the runtime closes HTTPX and Playwright, while Runner.close() flushes the session service and closes toolsets such as MCP.

HTTPX or Playwright?

Choose the least expensive tool that can obtain the evidence correctly.

The agent instruction says “HTTPX first,” but prompt text is not the only control. The browser is read-only, shares the same exact allowlist, blocks image/font/media requests by default and is serialized behind a lock.

Selenium can replace Playwright if it is already part of your stack. The architecture is unchanged: configure the proxy on the browser driver, keep browser state scoped to one work unit, and enforce navigation policy outside the model.

Sticky vs. Rotating Sessions

Session behavior should match the unit of work rather than the number of agents.

“Sticky” does not mean permanent. The available duration and rotation behavior depend on the access-point configuration and current service controls. Design the job so it can restart cleanly when a lease expires.

Do not rotate blindly after every 403. A 403 can mean authorization policy, website terms, account state, a missing header, a blocked path or an anti-automation decision. Repeatedly changing IPs can waste bandwidth and hide the real cause. Record the sanitized failure, stop within budget and review the target policy before deciding whether another legitimate job should use a new session.

For a deeper treatment, see Proxy Sessions for AI Agents: Rotation, Stickiness, Identity, and Cost.

ADK Session State vs. Proxy and Browser State

These systems have separate identities and lifetimes:

InMemorySessionService is appropriate for the runnable tutorial but loses its data when the process stops. Use an appropriate persistent ADK session service for production. Keep session values serializable and update them through tool_context.state so ADK can record state deltas correctly.

Even with persistent ADK state, a resumed job needs an explicit network recovery strategy:

1. Recreate or lease the intended proxy endpoint.
2. Restore authorized browser storage from a protected store if the workflow genuinely requires it.
3. Verify that the restored browser identity and current proxy exit are compatible.
4. Revalidate the destination and task budget.
5. Continue only if the result still represents one coherent observation.

Never serialize a live browser, HTTP client, credential, semaphore or raw proxy URL into ADK state.

Geo-Targeting Correctly

Set country, city and ISP targeting in the Proxidize access point or current supported credential-generation workflow. Writing “browse from New York” in the ADK instruction changes model intent, not network geography.

An IP location is only one localization signal. A target may also consider:

• Browser locale and accepted languages.
• Time zone.
• Cookies and prior regional choices.
• Account country or delivery address.
• URL path, subdomain or query parameters.
• Currency and storefront selection.
• Target-side experimentation or personalization.

Align the signals that are legitimate and necessary for the test. The example exposes BROWSER_LOCALE and BROWSER_TIMEZONE so they can be configured deliberately instead of silently spoofed by the model.

Verify the outcome at two levels:

1. Confirm that the network tool used the intended proxy route without logging the raw exit IP.
2. Confirm what the destination itself displays—country, currency, language, inventory, price or another relevant market signal.

An IP lookup alone does not prove that the target produced the intended localized experience.

Retries Without Runaway Rotation

Retries belong inside the network tool because that layer can see the method, response status, exception and target policy.

The complete example retries only an idempotent GET after:

• A timeout or transport failure in the HTTPX path.
• 429, 500, 502, 503 or 504.
• A bounded delay, using a short numeric Retry-After value when present or capped exponential backoff with jitter.

It does not retry arbitrary 4xx responses. It caps attempts, redirects, response bytes, returned text and total model/tool calls. In production, also add a per-target retry budget and circuit breaker across processes so ten agent workers do not each retry the same outage independently.

Use a fresh proxy session only at a deliberate job boundary. A retry policy should not quietly turn every error into IP rotation.

Control Concurrency at Every Layer

Current Python ADK can execute async function tools concurrently when the model emits multiple calls. That makes async I/O useful, but it also means the model-visible tool count is not the same as actual safe outbound concurrency.

ADK's tool_thread_pool_config is relevant to synchronous tool execution and live-agent worker pools. It is not a substitute for a semaphore or distributed rate limiter around the real HTTP/browser operation.

Use both framework- and network-level limits. If the same service runs 20 agent invocations, each with a local semaphore of two, the potential fleet total is still 40 operations. Apply a shared per-target limit at the queue or gateway when aggregate load matters.

Google Search vs. Your Own Proxied Tool

ADK supports Google's built-in Search tool, but it has a different execution boundary from a local function tool.

Use hosted search when it already satisfies the task and policy. Use your custom proxied tool when you need a controlled target list, a selected network geography, target-visible browser state or application-owned evidence validation. Do not treat one as if it automatically inherits the network configuration of the other.

Add Proxidize MCP as a Control Plane

Google ADK can consume Model Context Protocol servers through McpToolset. Proxidize's official @proxidize/mcp package exposes account and subscription-aware proxy-management tools.

For a read-only starting point, create a filtered toolset:

Then add the toolset alongside the page tools:

Runner.close() closes attached toolsets, including their MCP session. If you create or use an McpToolset outside a runner-owned agent, call its asynchronous close() method yourself.

The Proxidize API token is not the same secret as the proxy username/password. The MCP package expects the raw token in PROXIDIZE_API_TOKEN; do not include the literal Bearer authentication-scheme prefix. Keep the token out of prompts, ADK state, source code, command-line arguments and repository configuration.

The package discovers active subscriptions at startup and registers only relevant tools. A residential account can expose read operations such as usage, locations and settings, plus mutation tools for access points, allowlists and routing. Start with the narrow filter above.

The filter deliberately omits residential_get_usage and residential_list_access_points. In the current package, their declared result schema can include an access-point password even though the operation itself is read-only. “Read-only” means a tool does not mutate state; it does not mean its result is safe to expose to a model or trace. If an agent needs balance data, put a server-side sanitizing wrapper in front of the operation and return only the non-secret fields the task requires.

If an agent genuinely needs a state-changing tool, isolate it in a separate workflow, set ADK's require_confirmation=True, implement the confirmation/resume path, validate every argument and retain an audit record.

Most importantly, MCP does not carry page bytes:

An MCP call can inspect or change proxy configuration. The subsequent target request still needs the generated proxy server and authentication in HTTPX or Playwright.

Security and Prompt-Injection Controls

Every retrieved page is untrusted input. It can contain text that tells the model to reveal secrets, ignore policy, visit another host, download a file or take an external action. Treat that text as evidence—not authority.

The complete example keeps policy outside the model:

• Exact hostname allowlist; no suffix or wildcard matching.
• HTTPS port 443 only.
• Public-address resolution before requests.
• Redirect revalidation.
• Browser subresource routing policy, blocked service workers and disabled WebSockets.
• Read-only tools with no click, type, authentication, upload or download capability.
• Separate proxy credentials that are never returned to Gemini.
• Bounded response bytes and extracted text.
• Tool-call, model-call, retry and concurrency limits.
• Final citation validation against successfully observed URLs.

For production, add:

• Container or VM isolation for every browser worker.
• Network egress rules that block internal services and cloud metadata endpoints and prevent the worker from bypassing the intended proxy.
• Proxy-side public-destination policy, because the gateway may perform its own DNS resolution.
• Separate browser contexts between users, tenants and independent jobs.
• Domain-specific authorization and rate policy.
• Malware scanning and file quarantine if downloads are ever enabled.
• Human confirmation for account changes, purchases, messages, publishing or other consequential actions.
• Redacted tracing, short retention and access controls for tool results.
• A credential manager with rotation and least-privilege service accounts.

Do not expose arbitrary URL fetching to an untrusted user without a server-side policy. A model instruction such as “visit only safe sites” is not an SSRF defense.

Troubleshooting

407 Proxy Authentication Required

Confirm the proxy server, username and password came from the same active access point. Keep credentials in separate fields. Check whether the access point expects username/password authentication or source-IP whitelisting. Do not add Bearer to proxy credentials or to the Proxidize MCP environment token.

403 Forbidden

Do not assume a new IP is the correct fix. Confirm that the path is public and permitted, review target terms and authorization, check required headers/cookies/account state, reduce request rate and inspect the target's visible response. The example intentionally does not retry a 403.

429 Too Many Requests

Respect Retry-After, lower per-target concurrency and add a shared rate limit across agent workers. Rotation is not permission to exceed a target's reasonable limits.

net::ERR_TUNNEL_CONNECTION_FAILED in Playwright

Test the same access point with the built-in HTTPX preflight. Then verify the proxy protocol, endpoint, port and authentication mode. A route can succeed for one destination and fail for another, so test the exact approved target rather than only an IP-check service.

HTTPX works but Playwright fails

Install the matching Chromium build with python -m playwright install chromium. Confirm Playwright receives server, username and password separately. Review the browser route guard: dynamic sites often use additional first-party API or CDN hosts that must be explicitly allowlisted.

Playwright returns little or no text

The page may render after DOMContentLoaded, require an authorized cookie, depend on a blocked resource host or place content outside the body text. Add a bounded, target-specific readiness condition. Do not replace it with an unbounded sleep or allow every third-party domain.

The target shows the wrong country or currency

Confirm access-point targeting, then align legitimate browser locale, time zone, cookies, account/store settings and target URL. Verify what the destination displays. An IP lookup alone is not enough.

An ADK session resumed but the website session did not

ADK restored serializable agent state, not the old process, HTTP connection, browser context, cookies or sticky lease. Recreate those resources deliberately and decide whether the task can still continue coherently.

ImportError: cannot import name 'McpToolset'

Install ADK's optional MCP dependency:

Base google-adk does not install the Python mcp package in this version.

Proxidize MCP says PROXIDIZE_API_TOKEN is required

Pass a fresh dashboard API token to the child MCP process as the raw PROXIDIZE_API_TOKEN value. Do not prefix the value with Bearer, and do not confuse it with the residential access point's username or password.

The agent loops or spends too much

Lower RunConfig(max_llm_calls), the callback's tool budget, retries, response size and per-run URL count. Add a queue deadline and fleet-level cost/traffic budget. Prompt instructions alone are not a stopping guarantee.

Common Mistakes

• Setting a proxy-related value on the ADK agent and assuming every dependency inherits it.
• Sending proxy credentials to Gemini in the prompt or tool result.
• Using a Random access point halfway through a cookie-dependent browser workflow.
• Treating an ADK session_id as a proxy session identifier.
• Restoring ADK state and assuming the old browser or sticky exit still exists.
• Letting the model choose arbitrary destinations.
• Following redirects before validating their new host and IP range.
• Returning unlimited raw HTML to the model.
• Retrying all 4xx responses or rotating on every 403.
• Launching one shared browser context for unrelated users or tenants.
• Using Proxidize MCP credentials as page-proxy credentials, or vice versa.
• Assuming Google Search uses the proxy configured on local HTTPX.
• Relying on a local semaphore as the only limit in a multi-replica deployment.
• Publishing a tutorial with real keys, tokens, usernames, passwords or raw exit IPs.

Production Checklist

Before deploying an ADK web agent:

• Replace every credential used during development and inject secrets securely.
• Keep Google, Proxidize API and proxy-access credentials separate.
• Pin and retest ADK, model, HTTPX, Playwright, Chromium, MCP and Node versions.
• Use exact approved destination hosts and server-side URL policy.
• Add egress firewall rules for private, link-local, metadata and internal ranges.
• Revalidate every redirect and browser subresource request.
• Use HTTPX before a browser when static content is sufficient.
• Scope one browser context and sticky proxy work unit to one user/job.
• Align geo, locale, time zone and authorized session state deliberately.
• Cap model calls, tool calls, retries, redirects, bytes, text, time and concurrency.
• Add a fleet-wide per-target rate limiter and circuit breaker.
• Validate final citations against successful tool evidence.
• Require human approval for consequential actions and MCP mutations.
• Redact secrets, raw exit IPs and sensitive page data from logs/traces.
• Monitor bandwidth, failure rate, latency and target-specific outcomes.
• Confirm the workflow complies with laws, privacy duties and website terms.

Conclusion

Google ADK and residential proxies solve different parts of the agent stack. ADK controls model reasoning, tool invocation, sessions and workflow. HTTPX or Playwright opens the website. Proxidize supplies the target-facing residential route, targeting and session behavior.

The reliable pattern is:

Start with HTTPX, add a browser only when the page requires it, keep sticky network and browser state aligned for one coherent work unit, and rotate between independent jobs. Use MCP for narrow control-plane operations—not as a substitute for the website data path.

Next steps:

• Explore Proxidize Residential Proxies.
• See AI Agent Proxies for Reliable Web Access.
• View Proxidize pricing.
• Read the OpenAI Agents SDK proxy guide.
• Build a LangGraph web research agent with residential proxies.
• Use Claude Browser Use with residential proxies.