A security diagram shows an AI assistant routing through a firewall to cloud services, with risky connections flagged or blocked.
There is a special kind of IT frustration reserved for the deployment that passes every provisioning check, returns green across the board, and then spins endlessly until the portal UI drops a timeout error in your lap. In enterprise environments running Microsoft Foundry Agent Service inside a bring-your-own virtual network (BYO VNet), that exact scenario has become a recurring headache: public network access is disabled, dependencies like Azure Cosmos DB, Azure Storage, and Azure AI Search sit neatly behind private endpoints, outbound traffic routes through a TLS-inspecting firewall, and yet opening the Agents page in the Foundry portal stalls out completely.

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.

A security diagram shows an AI assistant routing through a firewall to cloud services, with risky connections flagged or blocked. 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:

Code:
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:

Code:
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 /24 or 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/10 with 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:

  1. Confirm the Cosmos DB private endpoint is approved: Look for the Sql group ID and verify an Approved state:
    Code:
    az network private-endpoint list --resource-group <rg> \
      --query "[].{name:name, group:privateLinkServiceConnections[0].groupIds[0], status:privateLinkServiceConnections[0].privateLinkServiceConnectionState.status}" \
      -o table
  2. 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
  3. 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-cosmos and my-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
  4. 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.com
    • control-{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 AzureActiveDirectory service tag). If you attach a Network Security Group to the agent subnet, include a matching outbound allow rule for AzureActiveDirectory.

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/0 to 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.com only 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 to 168.63.129.16 from 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:

Code:
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:

Code:
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 SymptomPrimary SuspectFirst Verification Step
Listing agents timed out after 8s / 400 invalid_configuration / Timeout of 60000ms exceededCosmos DB private endpoint unreachable or Private DNS resolving to public IPCheck privatelink.documents.azure.com VNet links, A records, and nslookup from VNet
Timeouts persist behind firewall even after adding firewall CAFirewall performing TLS inspection on Microsoft Entra / managed identity trafficAdd no-decrypt rules for login.microsoftonline.com, {region}.login.microsoft.com, and control-{region}.identity.azure.net
No route to host (EHOSTUNREACH) despite valid DNSPrivate endpoint IP sits inside 192.168.0.0/24Move affected private endpoints outside 192.168.0.0/24 and update DNS
DelegatedSubnetInUse when redeploying to a subnetSoft-deleted Foundry account still holds serviceAssociationLinksRun az cognitiveservices account list-deleted and purge at subscription scope
429 subnet_exhausted or data-proxy 5xx errorsDelegated subnet IP exhaustionProvision 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/24 for private endpoints: Hosted agents reserve 192.168.0.0/24 for an internal sandbox network. Placing a private endpoint inside that block can trigger EHOSTUNREACH ("No route to host") failures even when nslookup returns 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_exhausted errors during session creation or resume and HTTP 5xx responses from the data proxy—and if you need deeper live validation, pair the read-only Foundry Reachability Analyzer with Microsoft's diagnostic-agent sample inside the hosted runtime after verifying basic DNS and TLS from a non-delegated jump-box subnet.
 

References

  1. 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
  2. Deep dive into Foundry Agent Service networking - Microsoft Foundry | Microsoft Learn learn.microsoft.com
  3. microsoft.com devblogs.microsoft.com