How to Use Residential Proxies With Microsoft Agent Framework

Quick Answer

To use a residential proxy with Microsoft Agent Framework, configure the proxy on the custom HTTP or browser tool that opens target websites. Microsoft Agent Framework orchestrates the model, tool calls, sessions, middleware, and workflows. The network-aware tool sends its website requests through a Proxidize Residential Proxy.

The essential HTTPX configuration is:

Expose that operation as a local function tool:

The model sees the url argument, but Agent Framework injects FunctionInvocationContext at runtime. The proxy credentials stay inside the application-owned network client; they never become tool arguments or prompt content.

For a coherent multi-page research task, create a Sticky Proxidize 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. Use a Random access point for unrelated one-shot samples where broader IP diversity matters more than continuity.

There is no one global “Microsoft Agent Framework proxy” setting. Proxying HTTPX or Chromium does not automatically proxy OpenAI, Azure OpenAI, Microsoft Foundry, hosted search, MCP management traffic, checkpoint storage, or unrelated clients in the same 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: Microsoft Agent Framework behavior was checked against current Microsoft documentation and release artifacts on September 1, 2026. The complete example passed compile, import, function-schema, URL-policy, live HTTPX, live Playwright, live agent-tool-loop, session-evidence, and citation-gate checks with agent-framework 1.16.0, agent-framework-openai 1.14.1, HTTPX 0.28.1, Playwright 1.62.0, and GPT-5.6 Sol. Five fresh proxy clients observed one redacted exit fingerprint during a short window. Microsoft Agent Framework also connected to @proxidize/mcp 0.1.3 with read-only filtering and approval required, but no MCP tool or residential MCP operation was executed. No target geography was configured or verified.

Key Takeaways

• Proxy the website tool, not the framework. Put Proxidize credentials on the HTTPX, Playwright, Selenium, or other client that opens the destination.
• Keep model and website routes separate. A proxied browser does not automatically send model-provider traffic through the residential route.
• Use HTTPX first. It is simpler and usually consumes less bandwidth when the necessary content already exists in the HTTP response.
• Use Playwright when the task needs rendering. Add a browser for client-side JavaScript, browser state, or visible interactions—not merely because the application is called an agent.
• Use Sticky for one coherent work unit. Keep the exit, cookie jar, browser context, and target-side session aligned; rotate between independent jobs.
• AgentSession state is not proxy state. Saving messages or workflow progress does not preserve an exit IP, open connection, cookie jar, or browser process.
• Limit both tool loops and real network work. Use max_function_calls and max_iterations, then place semaphores, timeouts, response limits, and per-target rate controls inside the tool runtime.
• Treat website text as untrusted. Prompt instructions are not a substitute for exact destination allowlists, redirect validation, private-network blocking, tool approval, and deterministic output checks.
• MCP is the control plane. Proxidize MCP can expose approved account, usage, and access-point operations; HTTPX or Playwright still carries the target-page traffic.

What Is Microsoft Agent Framework?

Microsoft Agent Framework is Microsoft's framework for building agents and explicit agent workflows. Its current documentation groups the platform into agents, an agent harness, workflows, and integrations. It also includes model clients, function tools, sessions, context providers, middleware, telemetry, MCP integrations, human-in-the-loop patterns, checkpointing, hosting, and agent-to-agent options.

Microsoft describes Agent Framework as the direct successor to both AutoGen and Semantic Kernel. It combines AutoGen-style agent abstractions with Semantic Kernel's enterprise features and adds graph-based workflows with explicit execution paths. Microsoft publishes dedicated migration guidance for AutoGen and Semantic Kernel.

The current Python metapackage is agent-framework 1.16.0, released August 28, 2026. This guide pins the core and OpenAI integration packages separately to keep the environment smaller:

Provider-package versions do not necessarily match the metapackage version. Pin and test the combination you deploy rather than assuming every agent-framework-* package uses the same number.

What the framework does—and does not do

Microsoft's agent safety guidance makes the same important trust-boundary point: communication with tool-accessed services uses developer-chosen clients, and the framework does not manage those services' authentication, encryption, or connection details for you. That is why proxy configuration belongs in the custom tool.

What Is Actually Being Proxied?

Only the network client explicitly configured with the Proxidize endpoint uses the residential route.

This separation gives you a practical troubleshooting rule:

• A successful model response does not prove the website request was proxied.
• A successful proxy preflight does not prove the model API, MCP, or checkpoint storage used the proxy.
• A successful MCP connection does not prove that website traffic used the residential exit.

Do not place a credential-bearing proxy URL, raw password, API token, or account identifier in prompts, tool descriptions, AgentSession.state, model-visible tool results, traces, screenshots, or exception messages. Pass secrets directly to the relevant client from a secret manager or process environment.

Why Pair Microsoft Agent Framework With Residential Proxies?

A Microsoft Agent Framework application may need to inspect lawful public content as it appears from a residential connection or selected market. Common examples include:

• Comparing public prices, inventory, and promotions across regions.
• Monitoring localized search results, storefronts, and landing pages.
• Collecting fresh public evidence for RAG, evaluation, or market research.
• Testing visible language, currency, shipping options, and regional behavior.
• Reviewing public marketplace listings for brand-protection work.
• Validating an approved website 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, HTTP(S) and SOCKS5 support, and dashboard/API control. Because the integration uses standard proxy settings, the Microsoft agent tool does not need a proprietary proxy SDK.

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

A proxy is not required for every agent. If the application works with internal data, licensed datasets, local files, your own APIs, or an approved hosted search product that already returns the required evidence, a custom browser and residential route may add cost and operational complexity without improving the result.

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

Prerequisites

You need:

1. Python 3.11 or later for the exact validated package set in this guide. Agent Framework itself supports Python 3.10+, but some optional integrations may have narrower requirements.
2. A fresh model-provider key. The tested example uses an OpenAI key and OpenAIChatClient; Azure OpenAI or Microsoft Foundry can be substituted without changing the website-tool proxy boundary.
3. An active Proxidize Residential Proxy plan and a dashboard-generated access point.
4. Separate proxy server, username, and password values.
5. A short, exact allowlist of public hostnames the workflow is authorized to visit.
6. A Chromium installation for the optional Playwright path.
7. Node.js 18 or later only if you add the Proxidize MCP integration.
8. A dedicated container or virtual machine for production browser execution.

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

The full agent-framework==1.16.0 metapackage is convenient for exploration, but it installs many provider and hosting integrations. The selective packages above are a better starting point for this single-provider guide.

Create a local .env that is excluded from version control:

Keep PROXIDIZE_SERVER free of credentials. Supplying separate fields avoids accidentally printing a full credential-bearing URL and matches Playwright's proxy configuration.

Build the Proxied HTTPX Tool

HTTPX should be the default transport when the required content is present in the initial response. It starts faster than a browser, has fewer moving parts, and avoids downloading unnecessary images, fonts, video, and JavaScript.

1. Build the authenticated client

trust_env=False prevents unrelated HTTP_PROXY, HTTPS_PROXY, or ALL_PROXY variables from silently changing the route. Redirects are disabled because every redirect target must be validated before the next request.

2. Validate destinations before connecting

Do not let the model turn an open-ended URL parameter into an unrestricted server-side request primitive. At minimum:

• Accept HTTPS only.
• Require an exact hostname allowlist.
• Reject credentials embedded in target URLs.
• Reject nonstandard ports unless explicitly needed.
• Resolve the hostname and reject loopback, private, link-local, multicast, reserved, and otherwise non-global addresses.
• Revalidate every redirect.
• Limit response bytes and extracted text.

The example performs these checks in application code. Network egress controls, DNS protections, and container isolation should enforce the same policy independently in production.

3. Expose the operation as a function tool

Agent Framework can infer a function schema from a typed Python callable. Its current function-tool documentation recommends ordinary parameters for model-supplied values and framework context for runtime-only values.

The example marks this narrowly scoped, read-only, allowlisted tool as never_require. A tool that logs in, submits a form, sends a message, changes account state, uploads a file, purchases something, or performs another consequential action should use approval_mode="always_require" and a real approval loop.

max_invocations belongs to the lifetime of the tool object, not automatically to one user request. This guide creates fresh tool instances for each work unit. In a long-running service, prefer Agent Framework's per-request max_function_calls control and an application-owned job budget; do not reuse a singleton tool until its lifetime counter eventually disables it.

Add Playwright When Rendering Is Required

Use Playwright when the required content appears only after client-side JavaScript, the task needs browser state, or the target requires an actual rendered interaction. Keep the same policy boundary: the application chooses the allowed destination, and Chromium carries the proxied website traffic.

The browser example also:

• Uses one browser context per coherent work unit.
• Serializes access to its single page with an asyncio.Lock.
• Intercepts requests and rejects non-allowlisted hosts.
• Blocks downloads, service workers, WebSockets, images, fonts, and media.
• Applies a navigation timeout and bounded retry policy.
• Validates the final page URL before accepting evidence.
• Truncates the visible body text returned to the model.

Blocking heavy resources lowers residential bandwidth usage, but it can change page behavior. Test each approved target and allow only the resource types and domains it genuinely requires.

HTTPX vs Playwright

Do not automatically fall back from HTTPX to a browser for every error. A 403, 429, authorization failure, or disallowed redirect is not proof that JavaScript is the missing ingredient. Categorize the failure first.

Create the Microsoft Agent Framework Agent

The Microsoft OpenAI integration provides OpenAIChatClient for the Responses API and recommends it for new work. OpenAIChatCompletionClient remains available for Chat Completions compatibility. The current provider details are documented in the official agent-framework-openai package README.

The complete example gives OpenAI's SDK a separate httpx.AsyncClient(trust_env=False). That makes the route explicit: model traffic is direct, while only the website tools use Proxidize. If your organization must route model traffic through a separate enterprise egress gateway, configure that client independently rather than reusing residential credentials.

Sticky vs Rotating Residential Sessions

The Python proxy configuration is identical for Sticky and Random access points. Session behavior is selected in the Proxidize dashboard or Session Builder, and the application uses the generated credentials unchanged.

Sticky mode is not a permanent-IP guarantee. Residential peers are inherently dynamic and can disappear, reconnect, or receive a new ISP lease. Define what the application should do if the observed exit changes:

• Continue when IP continuity is merely a preference.
• Restart the work unit when target-side consistency matters.
• Quarantine partial results when the requested geography becomes uncertain.
• Preserve provenance so observations from different exits are not silently merged.

Cookies, agent state, and proxy state are independent

A resumed Microsoft workflow can remember which URLs were pending while starting with a new browser process and a different residential peer. Agent sessions can be serialized, and workflow checkpoints can capture execution progress, but neither captures a live network connection or browser process.

Geo-Target a Microsoft Agent Work Unit

Proxidize Residential Proxies support country, city, and ISP targeting across 195+ countries. Configure the intended location in the dashboard or Session Builder and copy the generated endpoint and credentials. Do not let the model invent username suffixes or rewrite proxy credentials.

For multi-market work, keep a fixed application-owned mapping:

The model may request one approved market code. Application code resolves that code to a secret record after validating authorization. The prompt never receives the underlying username or password.

Verify the result, not only the requested selector

A requested geography is an input, not proof. Record the minimum evidence your policy requires:

1. The requested country, city, or ISP.
2. A redacted or access-controlled observation of the exit route.
3. An approved geolocation result when needed.
4. The country, store, currency, language, delivery region, or inventory shown by the target itself.
5. Cookies, account settings, query parameters, or saved preferences that may override IP-based localization.

IP-geolocation databases can disagree or lag behind network changes. The target's visible behavior is normally the business outcome that matters.

Align browser locale and timezone with the intended scenario when appropriate, but do not claim these values prove physical location:

No geography was selected in this article's live test, so the test proves the route and tool integration—not country, city, or ISP targeting.

Control Concurrency at Every Layer

Concurrency is not one setting. Bound every layer that can multiply work:

Microsoft's current function-tool source explicitly recommends FunctionInvocationConfiguration["max_function_calls"] as the per-request alternative to lifetime-scoped max_invocations, and the Python changelog records when that control was added. max_iterations and max_function_calls solve different problems: an iteration is a model/tool round trip, not necessarily one outbound request. Use both, then control the actual operation inside the tool:

The example disables multiple tool calls in one provider response to make the demonstration easy to audit. Production workloads can allow parallel calls after implementing per-job, per-host, and global limits.

Keep retries bounded and idempotent

Retry only failures that may be transient:

• Connection timeouts and transport interruptions.
• 429 responses when the target's policy permits retrying.
• Selected 5xx responses.

Use exponential backoff, jitter, a small maximum delay, and a hard attempt limit. Honor a reasonable Retry-After value. Do not automatically retry:

• Authentication failures.
• Disallowed destinations or redirects.
• Unsupported content types.
• Responses larger than the configured cap.
• Purchases, messages, uploads, account changes, or other non-idempotent actions.

A different exit IP is not a universal retry strategy. Repeating a bad request through more residential peers can increase cost and target load without correcting the cause.

Use Proxidize MCP as a Control Plane

Microsoft Agent Framework supports local and remote MCP integrations. Its current MCP guide provides MCPStdioTool, MCPStreamableHTTPTool, and other transports. Proxidize's official @proxidize/mcp package exposes tools based on the active subscriptions visible to the supplied API token.

The architecture remains two separate paths:

Use MCP for approved account or infrastructure operations, such as checking a subscription, viewing usage, or listing locations. It does not automatically transport target-page traffic.

Start with a read-only allowlist and require approval:

Do not expose credential-returning settings or access-point tools to the model unless the application has a carefully designed redaction layer and a genuine requirement. Keep create, update, password, whitelist, rotate, and delete operations out of the initial tool set. If a later workflow needs a mutation, add the smallest tool possible, require human approval, validate every argument, and audit the result.

The live validation for this guide proved the Agent Framework-to-MCP connection, authentication-based subscription discovery, tool allowlisting, analytics opt-out, and approval configuration. The supplied token did not advertise residential MCP management tools, so no residential MCP operation is claimed. No MCP function was executed.

Keep Agent, Workflow, Browser, and Proxy State Separate

An AgentSession can carry conversation history and application state between agent calls:

Do not put secrets, raw proxy URLs, or unredacted exit details in this serialized state. Treat session storage as a separate trust boundary with tenant authorization, retention rules, and access controls.

For explicit multi-step work, a workflow can preserve executor state and pending messages in checkpoints. The correct resume sequence is:

Do not assume that restoring a checkpoint resurrects the same IP or browser context. If network continuity is a hard requirement, store a policy-safe lease identifier and reacquire/verify the corresponding access point before resuming.

Protect the Agent From Prompt Injection and SSRF

Website content is tool output and must be treated as untrusted. A page can contain text such as “ignore your instructions,” hidden content, malicious links, or attempts to make the agent reveal secrets or invoke another tool.

Microsoft's Agent Safety documentation recommends treating model-selected function arguments as untrusted, using allowlists, requiring approval for high-risk tools, keeping system messages developer-controlled, and validating model output. Apply those controls mechanically:

1. Use an exact destination allowlist. Do not accept arbitrary model-generated domains.
2. Block private and non-global addresses. Protect loopback, link-local, cloud metadata, internal services, and private networks.
3. Revalidate redirects and browser subrequests. The first URL can redirect or load content from a different host.
4. Keep secrets out of model context. The tool owns credentials; the model never needs them.
5. Separate read and write tools. This guide exposes only read-only page observation.
6. Require approval for consequences. Use approval_mode="always_require" for mutations, communications, downloads, purchases, and sensitive access.
7. Limit response size and type. Reject unexpected binaries and excessive bodies.
8. Disable unnecessary browser capabilities. Block downloads, WebSockets, service workers, and heavy assets unless required.
9. Validate outputs. The example accepts final citations only when a successful tool result observed that exact URL.
10. Add infrastructure controls. Container isolation, network egress policy, least-privilege secrets, and audit logs should reinforce application checks.

Microsoft also documents an experimental Python-only information-flow system called FIDES. It can complement these controls in workflows where untrusted content must be prevented from steering sensitive sink tools. It is not a replacement for destination validation, network isolation, or human approval.

Complete Live-Tested Example

The following single-file example includes:

• Separate model and website HTTP clients.
• HTTPX and Playwright transports through the same Proxidize access point.
• Exact-host HTTPS allowlisting and public-address checks.
• Manual redirect validation.
• Bounded retries, response sizes, tool calls, and network concurrency.
• Optional short-window exit-continuity and Playwright smoke tests.
• AgentSession evidence tracking.
• Final citation validation against URLs a tool actually observed.
• Clean client, browser, and Playwright shutdown.

Run the default HTTPX agent path:

Run the Playwright smoke test and observe five fresh proxy connections:

Expected output contains no raw exit IP or credential:

The exit fingerprint uses a new random HMAC key each process, so it can compare samples inside one run without becoming a durable identifier across runs.

Live-Test Results

The exact example was validated on September 1, 2026.

Use an approved, stable test page before adding production destinations. Then add one target at a time and record its redirect behavior, resource domains, rate policy, expected output, and compliance review.

Common Mistakes

Putting the proxy on the model client

That changes the model-provider route, not necessarily the target website route. Configure the proxy on the HTTP or browser tool that opens the destination.

Using one global proxy environment variable

Global HTTP_PROXY or HTTPS_PROXY values can route model calls, telemetry, package downloads, MCP, and internal services unintentionally. Use explicit clients and trust_env=False when you need a clear boundary.

Treating an AgentSession as a browser session

AgentSession preserves agent-side state. It does not preserve cookies, local storage, browser processes, TCP connections, or the residential exit.

Reusing one Sticky session across unrelated tenants

Sticky state should follow one coherent work unit. Sharing it can mix cookies, target-side sessions, localization, and provenance between jobs.

Letting the model choose arbitrary URLs

A generic URL-fetch tool can become an SSRF path. Use exact hostnames, public-address validation, redirect checks, and infrastructure egress controls.

Using max_iterations as the only budget

An iteration is not guaranteed to equal one function or one network request. Also set max_function_calls and bound the actual network work.

Reusing max_invocations on a singleton tool forever

The counter belongs to the tool instance. Create tools per job or use a per-request/application budget for long-running services.

Retrying every failure with a new IP

Do not treat rotation as a generic error handler. Fix policy, authentication, parsing, or rate problems at their source and retry only bounded idempotent reads.

Giving MCP the entire account surface

Begin with a read-only allowed_tools list. Add mutation tools only when the workflow truly needs them, and require approval plus deterministic validation.

Logging full proxy URLs

A full URL can contain both username and password. Log only a credential-free endpoint label and the minimum redacted diagnostic evidence required by policy.

Troubleshooting

Conclusion

Microsoft Agent Framework does not need to be “put behind” a residential proxy. The reliable architecture is narrower and easier to audit:

Use HTTPX for ordinary page retrieval, add Playwright only when rendering or browser state is necessary, keep one Sticky access point per coherent work unit, validate the target-visible location, and bound tool loops separately from real network concurrency. Preserve agent and workflow state independently from proxy and browser state. Use MCP as a tightly filtered control plane, not as a substitute for the data path.

To continue building the AI-agent integration cluster:

• Explore Proxidize Residential Proxies
• See AI Agent Proxies for Reliable Web Access
• Use Residential Proxies With the OpenAI Agents SDK
• Build a LangGraph Web Research Agent With Residential Proxies
• Use Claude Browser Use With Residential Proxies
• Use Residential Proxies With Google ADK Agents
• Design Proxy Sessions for AI Agents
• Compare Cloud Browsers for AI Agents

For production volume, view pricing, generate a dedicated access point for the approved work unit, or talk to Sales about higher volume, support, and custom routing requirements.