In a November 21, 2026 troubleshooting guide on the Microsoft Foundry Blog, Principal Product Manager Muzz Imam documented five recurring network checks he uses with enterprise teams moving hosted agents from pilot environments into locked-down VNets. As Imam notes, the agent code itself is rarely broken in these situations—rather, one missing piece in the surrounding DNS, routing, TLS inspection, or subnet lifecycle configuration is starving the platform of connectivity. Paired with Microsoft Learn's latest Foundry networking and Private CA documentation, those five checks form a systematic playbook for enterprise cloud architects and Windows/Azure administrators.
Understand What Actually Runs in the Agent Subnet
Before touching a single Azure CLI command, you have to discard the assumption that all agent traffic follows one straight line. Under a BYO VNet setup, the delegated agent subnet hosts two distinct pieces of platform infrastructure:
- Hosted-agent micro VMs: Each hosted agent session runs inside a VM-isolated sandbox attached to the delegated subnet, and your own agent code's direct outbound HTTPS calls originate from here.
- A single-tenant data proxy: Provisioned per Foundry project inside the delegated subnet, this proxy handles tool-server calls and outbound connections to customer storage, databases, Key Vault, and search indexes over private endpoints.
- Platform identity traffic: From that same delegated subnet, the platform authenticates to Microsoft Entra ID using managed identity before calling your Azure resources.
Why does this topology matter when troubleshooting? Because testing connectivity from a standard jump-box VM—or even running Microsoft's diagnostic-agent sample—does not validate every path. Microsoft's official networking documentation explicitly cautions that a jump box only tests its own subnet's routing and NSGs, while the diagnostic agent probes the hosted micro VM's direct outbound path rather than tool calls routed through the data proxy or dependency authentication. Every timeout check therefore boils down to a precise question: can the delegated agent subnet—and specifically its data proxy and identity flow—resolve and reach what it needs?
Check 1: Verify the Delegated Agent Subnet and Its Boundaries
When teams wire up Foundry networking through the Azure portal or infrastructure-as-code templates, the first point of confusion is often confirming which subnet actually holds the agent injection configuration. You can query the Foundry account directly via the Azure CLI:
az cognitiveservices account show \
--name my-foundry --resource-group <rg> \
--query "properties.networkInjections"
Look for the entry where "scenario" is "agent" and "useMicrosoftManagedNetwork" is false, then grab the subnet path from subnetArmId and inspect the subnet itself:
az network vnet subnet show \
--resource-group <rg> --vnet-name <vnet> --name agent-subnet \
--query "{prefix:addressPrefix, delegations:delegations[].serviceName, links:serviceAssociationLinks[].name, routeTable:routeTable.id}"
In a healthy deployment, you should see "Microsoft.App/environments" under delegations, along with a populated serviceAssociationLinks list (such as legionservicelink in sample deployments, though exact link identifiers can vary) indicating that an active agent environment is bound to the subnet.
Keep these non-negotiable design rules in mind when reviewing the output:
- Day-one commitment: For hosted agents, network injection must be configured when you first create the Foundry account. You cannot bolt BYO VNet injection onto an existing Foundry account later.
- One Foundry resource per agent subnet: Multiple Foundry accounts can live inside the same VNet, but each Foundry resource requires its own dedicated delegated agent subnet.
- Subnet sizing and quotas: The minimum supported size is
/27, and you cannot resize it once assigned. Microsoft recommends/24or larger for production workloads to absorb combined IP demand across all projects in the account, project-level networking components, and temporary infrastructure during platform upgrades. While Microsoft rolled out shared subnet IPs to general availability at Ignite 2026 to boost concurrent session density, regional concurrent session quotas still apply separately. - IP address space caution: RFC 1918 ranges (
10.0.0.0/8,172.16.0.0/12,192.168.0.0/16) are universally supported, and public IP ranges are blocked. Worth noting for careful architects: Microsoft's networking-options overview permits specific RFC 6598/CGNAT space (100.64.0.0/10with certain exclusions), whereas Microsoft's networking deep-dive document still states RFC 1918 only and lists CGNAT as unsupported. Unless your design explicitly requires CGNAT and you have verified it in your target region, sticking to non-overlapping RFC 1918 ranges is the safest path.
Check 2: Trace "Listing Agents Timed Out" Back to Cosmos DB and Private DNS
According to Imam, the single most common error teams hit when loading the portal is a timeout reading the agent index:
Listing agents timed out after 8s while reading the agent index. This usually indicates the project's bring-your-own Cosmos DB endpoint is unreachable or misconfigured.
Because the breakdown lives in your network or database wiring rather than the Foundry control plane, the API surfaces it as 400 invalid_configuration, while the Foundry portal UI often renders a generic Timeout of 60000ms exceeded message on the Agent pages. Microsoft Learn's private networking guide confirms that "Timeout of 60000ms exceeded" when loading Agent pages points directly to communication failures between the Foundry project and Azure Cosmos DB.
Assuming your Entra ID sign-in isn't being intercepted (covered in Check 3), Private DNS is the prime suspect. Run through these four checks in order:
- Confirm the Cosmos DB private endpoint is approved: Look for the
Sqlgroup ID and verify anApprovedstate:
Code:az network private-endpoint list --resource-group <rg> \ --query "[].{name:name, group:privateLinkServiceConnections[0].groupIds[0], status:privateLinkServiceConnections[0].privateLinkServiceConnectionState.status}" \ -o table - Verify the Private DNS zone link: Azure Private DNS zones only resolve queries for VNets explicitly linked to them. Check
privatelink.documents.azure.com:
Code:az network private-dns link vnet list --resource-group <dns-rg> \ --zone-name privatelink.documents.azure.com \ --query "[].{name:name, vnet:virtualNetwork.id, state:virtualNetworkLinkState}" -o table - Inspect the A records: You should see records for both the global Cosmos DB account name and each region it runs in (for example,
my-cosmosandmy-cosmos-westus3):
Code:az network private-dns record-set a list --resource-group <dns-rg> \ --zone-name privatelink.documents.azure.com \ --query "[].{name:name, ip:aRecords[0].ipv4Address}" -o table - Validate resolution from inside the VNet: From a VM using the same DNS settings as the agent subnet, run
nslookup <account>.documents.azure.com(and<account>-<region>.documents.azure.com). Do not stop at confirming it returns a private IP—compare the address directly against your Cosmos DB private endpoint's IP.
If your VNet uses custom DNS servers instead of default Azure DNS, ensure conditional forwarders send these privatelink zones to Azure's virtual DNS server at 168.63.129.16 from inside a VNet that is linked to those zones. On-premises DNS servers cannot reach 168.63.129.16 directly and must forward through an Azure DNS Private Resolver or an in-Azure DNS forwarder. The exact same Private DNS checklist applies if Key Vault (privatelink.vaultcore.azure.net) or Application Insights (via an Azure Monitor Private Link Scope) resolves to public IPs from your VNet.
Check 3: Don't Expect Private CA Trust to Fix TLS Inspection on Entra Sign-In
At Ignite 2026, Microsoft introduced Private CA trust in public preview for Foundry Agent Service, allowing teams to store corporate root CA certificates in Azure Key Vault so agents can call internal APIs, MCP servers, and model gateways without disabling certificate validation. Naturally, security teams running outbound TLS-inspecting firewalls often upload their firewall's decrypting CA to Private CA trust and expect agent timeouts to vanish.
They won't—and Microsoft's Private CA documentation explains why. Private CA trust only applies to your agent code's outbound calls, tools, and model gateways; it does not cover the platform's own Microsoft Entra ID and managed identity traffic originating from the agent subnet. When a firewall decrypts and re-signs that control-plane identity traffic with an internal CA, agent listing and conversation calls fail or throw Timeout of 60000ms exceeded. Imam noted that when he reproduced this exact setup behind a decrypting proxy in a test subscription, registering the proxy's CA had no effect, whereas adding a no-decrypt rule immediately cleared the timeouts.
To fix this cleanly without weakening internal inspection policies:
- Bypass TLS inspection on your firewall for these three Microsoft Entra endpoints (replacing
{region}with your deployment region):login.microsoftonline.com{region}.login.microsoft.comcontrol-{region}.identity.azure.net
- Allow required identity egress on both firewall and NSGs: Permit those three hosts alongside the managed identity FQDNs documented in Azure Container Apps firewall guidance (or use the
AzureActiveDirectoryservice tag). If you attach a Network Security Group to the agent subnet, include a matching outbound allow rule forAzureActiveDirectory.
Keep Private CA trust enabled for its intended purpose—letting your tools and hosted agent code validate internal corporate services using your PKI—while keeping certificate and hostname verification turned on.
Check 4: Peered Hub VNets Work, but DNS Follows the Agent Subnet
In hub-and-spoke enterprise topologies, it is common to keep shared services like Cosmos DB, Storage, or AI Search behind private endpoints in a central hub VNet while isolating the Foundry agent subnet in a spoke. Microsoft supports peered VNets for this layout, with a reminder that cross-VNet data transfer charges can apply.
Two rules keep hub-and-spoke deployments from breaking silently:
- Routing vs. UDR overrides: You do not need to attach a route table to the agent subnet just to reach a peered VNet; Azure automatically injects system routes for peered address spaces. Only add a User-Defined Route (UDR) if your architecture forces egress through a firewall or Network Virtual Appliance (NVA). When you do, verify that broad UDRs (such as
0.0.0.0/0to an NVA) do not unintentionally override peering routes to your private endpoints, and ensure the firewall allows the Entra hosts from Check 3. - DNS doesn't follow peering automatically: If the spoke VNet uses Azure-provided DNS, linking
privatelink.documents.azure.comonly to the hub VNet will leave the spoke resolving public IPs. You must link each required Private DNS zone directly to the VNet containing the agent subnet, or point the spoke at custom DNS servers that forward to168.63.129.16from a linked VNet. Equally important: every peered VNet address space must be strictly unique, because overlapping ranges trigger routing failures.
Check 5: Clear DelegatedSubnetInUse After Deleting a Foundry Account
Dev and test teams spinning up and tearing down Foundry environments frequently collide with a stubborn deployment error: DelegatedSubnetInUse. Deleting a Foundry account only soft-deletes it; the underlying agent environment keeps its service association link locked onto the delegated subnet until the account is permanently purged, blocking both new deployments onto that subnet and deletion of the subnet itself.
You can check for soft-deleted accounts across your subscription with:
az cognitiveservices account list-deleted -o table
If an obsolete account is still holding the subnet, double-check the exact account name, resource group, and location returned by that table—purge is permanent—and run:
az cognitiveservices account purge \
--location <region> --resource-group <rg> --name <old-account>
Watch out for an important RBAC catch documented in Microsoft Q&A troubleshooting guidance: the caller needs the Microsoft.CognitiveServices/locations/resourceGroups/deletedAccounts/delete permission at the subscription scope. Having Contributor or Cognitive Services Contributor assigned only at the resource group or deleted resource level is not enough and will fail. (If CLI and REST purges still consistently return an HTTP 500 despite subscription-level permissions and matching coordinates, Microsoft advises opening an Azure support ticket for backend cleanup.) Alternatively, in the Azure portal, you can navigate to Manage deleted resources on the Foundry resource page to purge the account, or run the deleteCaphost.sh script when cleaning up secured standard templates.
Give the platform a few minutes to tear down the environment, then confirm the subnet lock is cleared:
az network vnet subnet show \
--resource-group <rg> --vnet-name <vnet> --name agent-subnet \
--query "serviceAssociationLinks[].name"
Once that query returns an empty list, the subnet is free for reuse.
Quick Reference and Operational Watchouts
| Failure Symptom | Primary Suspect | First Verification Step |
|---|---|---|
Listing agents timed out after 8s / 400 invalid_configuration / Timeout of 60000ms exceeded | Cosmos DB private endpoint unreachable or Private DNS resolving to public IP | Check privatelink.documents.azure.com VNet links, A records, and nslookup from VNet |
| Timeouts persist behind firewall even after adding firewall CA | Firewall performing TLS inspection on Microsoft Entra / managed identity traffic | Add no-decrypt rules for login.microsoftonline.com, {region}.login.microsoft.com, and control-{region}.identity.azure.net |
No route to host (EHOSTUNREACH) despite valid DNS | Private endpoint IP sits inside 192.168.0.0/24 | Move affected private endpoints outside 192.168.0.0/24 and update DNS |
DelegatedSubnetInUse when redeploying to a subnet | Soft-deleted Foundry account still holds serviceAssociationLinks | Run az cognitiveservices account list-deleted and purge at subscription scope |
429 subnet_exhausted or data-proxy 5xx errors | Delegated subnet IP exhaustion | Provision a new Foundry account with a larger (/24+) dedicated subnet |
Before signing off on any production BYO VNet rollout, run through four final sanity checks drawn from Microsoft's current networking guidance:
- Stay out of
192.168.0.0/24for private endpoints: Hosted agents reserve192.168.0.0/24for an internal sandbox network. Placing a private endpoint inside that block can triggerEHOSTUNREACH("No route to host") failures even whennslookupreturns the right IP. - Match regions where required: Your Foundry resource and delegated VNet must reside in the same Azure region. Data stores like Cosmos DB, Storage, and AI Search can live in other regions if needed, though cross-region bandwidth costs will apply.
- Mind the container registry cutoff: If you deploy container-based hosted agents using a private Azure Container Registry (with public access disabled), note that Microsoft's setup documentation limits private ACR pull support to Foundry projects created after June 25, 2026; projects created before that date still require public ACR network reachability for platform image pulls.
- Monitor capacity indirectly: The Azure portal does not expose IP utilization metrics for delegated agent subnets, and Foundry does not issue proactive low-IP warnings. Set alerts on HTTP
429 subnet_exhaustederrors during session creation or resume and HTTP5xxresponses from the data proxy—and if you need deeper live validation, pair the read-only Foundry Reachability Analyzer with Microsoft'sdiagnostic-agentsample inside the hosted runtime after verifying basic DNS and TLS from a non-delegated jump-box subnet.
References
- Hosted agents in your own virtual network: five checks when the Agents page times out Microsoft Foundry Blog · 2026-11-21T18:12:21+00:00
- Deep dive into Foundry Agent Service networking - Microsoft Foundry | Microsoft Learn learn.microsoft.com
- microsoft.com devblogs.microsoft.com