Troubleshooting Microsoft Foundry Accessing On‑Premises APIs Over Private Networking

Audience: Azure solution architects, network engineers, and AI practitioners deploying Microsoft Foundry in enterprise, network‑isolated environments.

Scenario: Foundry Agent Service must call an on‑premises (or privately hosted) API over VPN or ExpressRoute using on‑premises corporate DNS. Connectivity works from a virtual machine (VM) in the virtual network (VNet), but fails when the same call is made from a Foundry agent.

This post consolidates common field patterns observed across customer engagements and maps them directly to official Microsoft guidance. It highlights a frequently missed prerequisite for private connectivity: Project and Agent Capability Hosts.

 

The Repeating Enterprise Pattern

The architecture is familiar:

• Microsoft Foundry account and project
• Customer‑managed VNet with VPN or ExpressRoute to on‑premises
• Corporate (on‑premises) DNS used for API name resolution
• A VM in the VNet can successfully resolve and call the on‑prem API
• Foundry agents are configured to call the same API (often via an OpenAPI tool)

Despite this, the agent fails with one or more of the following:

• DNS resolution failures
• Connection timeouts
• HTTP 401 or 403 responses
• Unexpected backend or proxy URLs appearing in logs

The consistent question is:

 

Why does this work from a VM in the VNet but not from the Foundry agents?

 

 

Key Principle: Foundry Agents Do Not Automatically Run in Your VNet

This is the most important mental model to reset.

Creating a private endpoint for a Foundry Agent Service does not place agent runtime traffic into your VNet. Private endpoints are inbound constructs. Outbound connectivity from an agent only flows through your VNet when specific requirements are met.

The most critical of those requirements is a Capability Host.

 

What Is a Capability Host?

A Capability Host defines where Foundry capabilities are allowed to execute.

In private networking scenarios, the capability host:

• Binds a Foundry project or agent to a customer‑managed subnet
• Enables platform‑managed container injection into that subnet
• Ensures outbound traffic follows VNet routing, security controls, and DNS configuration

Capability Host Scope

Project Capability Host

• Associated at the project level
• Applies to all agents in the project
• Defines the customer subnet the project is allowed to use

Agent Capability Host

• Associated at the individual agent level
• Can explicitly bind or override subnet placement
• Useful when agents require different isolation boundaries

 

Key field insight: If no capability host is associated, the agent runtime is not injected into the VNet—even if VPN, ExpressRoute, private endpoints, and on‑prem DNS are correctly configured.

 

 

Capability Host Lifecycle (Conceptual)

Without the capability host step, the chain breaks and the agent executes outside the customer network boundary.

 

Why On‑Premises DNS Appears Correct—but Still Fails

DNS is where most investigations stall.

Teams typically confirm:

• On‑premises DNS resolves the API hostname
• VNet DNS settings forward queries to on‑prem DNS
• A VM in the subnet resolves and reaches the API

Yet the agent still fails.

The reason is simple:

• The VM is unquestionably inside the VNet
• The agent may not be

Without a capability host, the agent runtime does not inherit:

• VNet DNS server settings
• Corporate DNS forwarding rules
• On‑premises name resolution paths

As a result, DNS fails even though the DNS design itself is correct.

 

Secondary Symptom: HTTP 401 Errors

After subnet injection and DNS are corrected, some customers encounter HTTP 401 responses.

This typically means:

• The API is now reachable
• The request is successfully routed through the private path
• Authentication or authorization is failing

At this stage, troubleshooting moves from networking to identity:

• Validate the credential or token configured in the Foundry connection
• Confirm expected headers, audience, or auth flow
• Account for managed proxy hops in the request path

A 401 at this point is progress—it confirms private connectivity is working.

 

Permissions and Required Services for Capability Hosts

Creating capability hosts requires both the correct Azure role-based access control (RBAC) permissions and the presence of specific dependent services. These prerequisites are frequently overlooked and can silently block capability host creation or leave hosts in a failed provisioning state.

Required Permissions (RBAC)

Microsoft documentation explicitly calls out the following minimum permissions:

• Contributor role on the Microsoft Foundry account to create capability hosts.
• User Access Administrator or Owner role on the subscription or resource group to grant the Foundry project’s managed identity access to dependent Azure resources when using standard agent setup.

Without these roles, capability host creation may fail, or the host may be created without access to required downstream services. For details, see Role-based access control (RBAC) for Microsoft Foundry.

Required Azure Services and Connections

For standard and network-secured agent setups, capability hosts reference customer-owned Azure resources. The following services must exist and be connected to the Foundry project before creating the capability host:

• Azure Storage – for file uploads and artifacts
• Azure AI Search – for vector stores and retrieval
• Azure Cosmos DB – for thread and conversation storage
• Azure AI Services / Azure OpenAI – for model execution

These services must be deployed in supported regions and, for private networking scenarios, in the same region as the virtual network. Capability hosts reference these resources through project connections, not raw resource IDs .

Networking-Specific Requirements

When using private networking:

• The agent subnet must already exist and be delegated appropriately.
• The capability host must reference the correct customer subnet at creation time.
• Required private endpoints and DNS resolution must be in place for dependent services.

If networking or connections change, capability hosts cannot be updated in-place and must be deleted and recreated with the corrected configuration .

 

Practical Fix Patterns

1. Create and Associate a Project Capability Host

• Bind the project to the intended delegated agent subnet
• Verify the customerSubnet reference
• Redeploy the agent after association

This aligns directly with the Standard Setup with Private Networking model documented by Microsoft.

2. Validate Agent Placement and Network Inheritance

• Confirm the agent is associated with the expected capability host
• Verify the capability host references the correct subnet
• Ensure network and DNS settings are applied at the subnet level

The agent inherits routing and DNS behavior only after successful subnet injection.

3. Validate DNS From the Agent Subnet

• Confirm VNet DNS settings point to on‑prem DNS
• Test name resolution from a VM in the same subnet

Once injected, the agent uses the same DNS behavior as other resources in that subnet.

4. Use a Supported Foundry Experience

Be aware of documented constraints:

• End‑to‑end network isolation is not supported in the newer Foundry portal experience
• Network‑isolated agent scenarios require the classic Foundry experience, SDK, or CLI
• Hosted agents do not support full isolation

Mismatch here can make a correct network design appear broken.

A Simple Checklist

When a Foundry agent cannot reach an on‑prem API:

1. Is a **Project Capability **Host associated?
2. Is the capability host bound to the correct subnet?
3. Is on‑prem DNS reachable from that subnet?
4. Is a supported Foundry experience in use?
5. If reachable, is authentication configured correctly?

If items 1 and 2 are not satisfied, all other troubleshooting is premature.

 

Closing

Most private networking issues with Microsoft Foundry are not caused by VPNs or DNS infrastructure. They result from an incomplete understanding of **where the agent ****runtime ****actually **executes.

Capability Hosts are the control point. When they are correctly configured, Foundry agents behave exactly as described in Microsoft guidance: they inherit VNet routing, DNS, and security controls and can securely access on‑premises systems over private connectivity.

No capability host = no VNet injection = no on‑prem connectivity.

 

References

The following Microsoft‑published resources were referenced and aligned with throughout this article:

1. Network‑secured agent setup (GitHub) – Reference implementation demonstrating a network‑secured Foundry Agent Service deployment with a customer‑managed virtual network, delegated agent subnet, and private connectivity patterns. This notebook illustrates how agent runtimes inherit network behavior only after subnet injection ralacher/network-secured-agent
2. Set up private networking for Foundry Agent Service - Microsoft Foundry | Microsoft Learns .