November 21st, 2026
0 reactions

Hosted agents in your own virtual network: five checks when the Agents page times out

Principal Product Manager

Over the last few weeks I have worked with several teams moving hosted agents into their own virtual network. Different industries, same five questions. This post answers each one with the commands I use to check it.

Picture a financial services team running claims agents in a locked-down network. Public access on the Foundry resource is off. The agent subnet sits in a spoke VNet. Azure Cosmos DB, Storage and Azure AI Search sit behind private endpoints, some of them in a hub VNet. All outbound traffic goes through a firewall that inspects TLS. The deployment succeeds. Then the Agents page spins and fails with a timeout.

Nothing is wrong with the agent. The network around it is missing one piece. Here is how to find it.

Start with what runs in your agent subnet

When you bring your own VNet, the delegated agent subnet is where the agent infrastructure runs: the micro VMs that run hosted agent sessions, and a single-tenant data proxy for each project. Tool calls go through that data proxy, and its outbound traffic reaches your storage, databases and Key Vault through private endpoints. The platform also signs in to Microsoft Entra ID with managed identity from that subnet before it calls your resources.

The delegated agent subnet holds hosted agent sessions and the project's data proxy. The data proxy signs in to Microsoft Entra ID through your firewall, then reaches Cosmos DB, Storage, AI Search and Key Vault through private endpoints, which need private DNS zones linked to the agent VNet.

So every check below asks one question: can the agent subnet resolve and reach what it needs?

1. Find the subnet that matters

Teams that set up networking in the portal are often not sure which subnet became the agent subnet. Ask the Foundry account:

az cognitiveservices account show \
  --name my-foundry --resource-group <rg> \
  --query "properties.networkInjections"
[
  {
    "scenario": "agent",
    "subnetArmId": "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.Network/virtualNetworks/<vnet>/subnets/agent-subnet",
    "useMicrosoftManagedNetwork": false
  }
]

Then look at that subnet:

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}"
{
  "delegations": [ "Microsoft.App/environments" ],
  "links": [ "legionservicelink" ],
  "prefix": "10.0.4.0/24",
  "routeTable": null
}

What good looks like:

  • The subnet is delegated to Microsoft.App/environments.
  • It is /27 or larger. Use /24 or larger for production.
  • It uses an RFC 1918 range: 10.0.0.0/8, 172.16.0.0/12 or 192.168.0.0/16. Every region where Agent Service is available supports 10.0.0.0/8.
  • Its range does not overlap any peered VNet.
  • It belongs to one Foundry resource only. Several Foundry resources can share a VNet, but each one needs its own agent subnet.
  • The legionservicelink service association link means the agent environment is using the subnet. You will meet it again in check 5.

One more thing to get right on day one: for hosted agents, network injection has to be part of the Foundry account when you first create it. You cannot add it to an existing account later.

2. “Listing agents timed out” means the data proxy cannot read your Cosmos DB

This is the error I see most:

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.

It comes back as 400 invalid_configuration, because the cause sits in your network or Cosmos DB setup, not in the service. In the portal, the same problem can show up as Timeout of 60000ms exceeded on the Agent pages.

The data proxy in your agent subnet could not reach your Cosmos DB account in time. The two causes I see most are DNS and the Entra sign-in in check 3. Start with DNS.

First, confirm the Cosmos DB private endpoint exists and is approved. Look for the Sql group:

az network private-endpoint list --resource-group <rg> \
  --query "[].{name:name, group:privateLinkServiceConnections[0].groupIds[0], status:privateLinkServiceConnections[0].privateLinkServiceConnectionState.status}" \
  -o table

Next, check that the privatelink.documents.azure.com zone is linked to the VNet that contains the agent subnet. A private DNS zone only answers for VNets that are linked to it.

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

Then check the records. You should see one for the account and one for each region it runs in:

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
Name               Ip
-----------------  ---------
my-cosmos          10.0.5.9
my-cosmos-westus3  10.0.5.10

If your VNet uses custom DNS servers instead of Azure DNS, make sure they forward these zones to the Azure DNS virtual server at 168.63.129.16 from a VNet that is linked to the zones. DNS servers on premises cannot reach that address, so point them at a DNS forwarder or Azure DNS Private Resolver in Azure instead. Last, from a VM in the same VNet, run nslookup <account>.documents.azure.com and confirm it returns your Cosmos DB private endpoint’s IP, not just any private IP.

The same fix applies when Key Vault or Application Insights resolve to public IPs from your VNet. Key Vault needs the privatelink.vaultcore.azure.net zone. Application Insights goes through an Azure Monitor Private Link Scope, which has its own private DNS zones. In each case the zone has to exist, hold the records and be linked to the agent VNet.

3. Your private CA does not cover the platform’s Entra sign-in

Teams with a firewall that decrypts and re-signs TLS often register the firewall’s CA with private CA trust (public preview) and expect the timeouts to stop. They do not, and that is expected. From the docs:

Private CA trust doesn’t apply to the platform’s own Microsoft Entra ID and managed identity traffic from the agent subnet. If a firewall TLS-inspects that traffic, agent operations such as listing agents or conversations can fail or time out, even after you add the firewall’s CA.

When I reproduced this in a test subscription, with the agent subnet’s Entra traffic routed through a decrypting proxy, registering the proxy’s CA made no difference. A no-decrypt rule for the Entra hosts fixed it.

The fix has two parts:

  • Exclude login.microsoftonline.com, {region}.login.microsoft.com and control-{region}.identity.azure.net from TLS inspection.
  • Allow those hosts on the firewall, plus the managed identity FQDNs from the Azure Container Apps firewall guidance or the AzureActiveDirectory service tag. If you put an NSG on the agent subnet, add a matching outbound rule for the AzureActiveDirectory service tag.

Keep private CA trust on for what it is built for: letting tools, model gateways and your own agent code call internal services that use your company’s certificates, with certificate checks still on. I covered that in the hosted agents Ignite 2026 post.

4. Resources in a peered hub VNet work, but DNS follows the agent subnet

Can Cosmos DB, Storage or Search sit in a peered VNet? Yes. The docs say peered virtual networks are supported, and note that data transfer costs can increase.

Do you need a route table on the agent subnet for peering? No. When you peer two VNets, Azure adds a system route for each address range of the other VNet. Add a route table only if your design sends traffic through a firewall. If it does, check two things: that your user-defined routes do not override the peering routes to your private endpoints by mistake, and that the firewall allows the Entra hosts from check 3.

What trips teams up is DNS. If the spoke uses Azure DNS, a zone linked only to the hub does not resolve in the spoke. Link each private DNS zone to the VNet that holds the agent subnet, or point that VNet at DNS servers that forward to 168.63.129.16 from a linked VNet. And keep every peered range unique, because overlapping ranges cause routing failures.

5. “DelegatedSubnetInUse” after you deleted an account

Dev and test teams often create and delete Foundry accounts on the same subnet. Deleting an account soft-deletes it, and its agent environment keeps the subnet until the account is purged. The next account on that subnet fails with DelegatedSubnetInUse, and the subnet cannot be deleted.

List soft-deleted accounts in the subscription:

az cognitiveservices account list-deleted -o table

If an old account is still there and you are done with it, purge it. Purge is permanent, so check the name first. It needs Cognitive Services Contributor, or Contributor assigned at the subscription level:

az cognitiveservices account purge \
  --location <region> --resource-group <rg> --name <old-account>

Give the platform some time to clean up, then check that the link is gone:

az network vnet subnet show \
  --resource-group <rg> --vnet-name <vnet> --name agent-subnet \
  --query "serviceAssociationLinks[].name"

An empty list means the subnet is free. For dev loops, the simpler habit is one agent subnet per account, or purge before you reuse.

What to watch for

  • Keep private endpoint addresses out of 192.168.0.0/24 for hosted agents. That range overlaps an internal sandbox network, and connections can fail with “No route to host” even when DNS is right.
  • The Foundry resource and the VNet must be in the same region. Cosmos DB, Storage and Search can be in other regions.
  • The portal does not show IP use for the delegated subnet. Watch for 429 subnet_exhausted on session create or resume, and 5xx errors from the data proxy.
  • For hands-on DNS, TCP and TLS checks from inside the network, Troubleshoot hosted agent virtual network connectivity walks through them from a jump box.

Docs

If your team hit something on this path that is not here, tell me in the comments. The next post will come from those answers.

Author

Muzz Imam
Principal Product Manager

Muzz Imam is a Principal Product Manager on Microsoft Foundry, where he works on the agent platform: hosted agents, network egress controls, private CA trust, deploying agents to your own AKS clusters, and cost control. He spends most of his time with customers taking agents from pilot to production.

0 comments