{"id":3470,"date":"2026-11-21T10:12:21","date_gmt":"2026-11-21T18:12:21","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/foundry\/?p=3470"},"modified":"2026-11-21T10:12:21","modified_gmt":"2026-11-21T18:12:21","slug":"hosted-agents-private-network-setup","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/foundry\/hosted-agents-private-network-setup\/","title":{"rendered":"Hosted agents in your own virtual network: five checks when the Agents page times out"},"content":{"rendered":"<p>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.<\/p>\n<p>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.<\/p>\n<p>Nothing is wrong with the agent. The network around it is missing one piece. Here is how to find it.<\/p>\n<h2>Start with what runs in your agent subnet<\/h2>\n<p>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.<\/p>\n<p><img decoding=\"async\" src=\"https:\/\/devblogs.microsoft.com\/foundry\/wp-content\/uploads\/sites\/89\/2026\/11\/agent-subnet-traffic.webp\" alt=\"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.\" \/><\/p>\n<p>So every check below asks one question: can the agent subnet resolve and reach what it needs?<\/p>\n<h2>1. Find the subnet that matters<\/h2>\n<p>Teams that set up networking in the portal are often not sure which subnet became the agent subnet. Ask the Foundry account:<\/p>\n<pre><code class=\"language-bash\">az cognitiveservices account show \\\r\n  --name my-foundry --resource-group &lt;rg&gt; \\\r\n  --query \"properties.networkInjections\"<\/code><\/pre>\n<pre><code class=\"language-json\">[\r\n  {\r\n    \"scenario\": \"agent\",\r\n    \"subnetArmId\": \"\/subscriptions\/&lt;sub&gt;\/resourceGroups\/&lt;rg&gt;\/providers\/Microsoft.Network\/virtualNetworks\/&lt;vnet&gt;\/subnets\/agent-subnet\",\r\n    \"useMicrosoftManagedNetwork\": false\r\n  }\r\n]<\/code><\/pre>\n<p>Then look at that subnet:<\/p>\n<pre><code class=\"language-bash\">az network vnet subnet show \\\r\n  --resource-group &lt;rg&gt; --vnet-name &lt;vnet&gt; --name agent-subnet \\\r\n  --query \"{prefix:addressPrefix, delegations:delegations[].serviceName, links:serviceAssociationLinks[].name, routeTable:routeTable.id}\"<\/code><\/pre>\n<pre><code class=\"language-json\">{\r\n  \"delegations\": [ \"Microsoft.App\/environments\" ],\r\n  \"links\": [ \"legionservicelink\" ],\r\n  \"prefix\": \"10.0.4.0\/24\",\r\n  \"routeTable\": null\r\n}<\/code><\/pre>\n<p>What good looks like:<\/p>\n<ul>\n<li>The subnet is delegated to <code>Microsoft.App\/environments<\/code>.<\/li>\n<li>It is \/27 or larger. Use \/24 or larger for production.<\/li>\n<li>It uses an RFC 1918 range: <code>10.0.0.0\/8<\/code>, <code>172.16.0.0\/12<\/code> or <code>192.168.0.0\/16<\/code>. Every region where Agent Service is available supports <code>10.0.0.0\/8<\/code>.<\/li>\n<li>Its range does not overlap any peered VNet.<\/li>\n<li>It belongs to one Foundry resource only. Several Foundry resources can share a VNet, but each one needs its own agent subnet.<\/li>\n<li>The <code>legionservicelink<\/code> service association link means the agent environment is using the subnet. You will meet it again in check 5.<\/li>\n<\/ul>\n<p>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.<\/p>\n<h2>2. &#8220;Listing agents timed out&#8221; means the data proxy cannot read your Cosmos DB<\/h2>\n<p>This is the error I see most:<\/p>\n<pre><code class=\"language-text\">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.<\/code><\/pre>\n<p>It comes back as <code>400 invalid_configuration<\/code>, 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 <code>Timeout of 60000ms exceeded<\/code> on the Agent pages.<\/p>\n<p>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.<\/p>\n<p>First, confirm the Cosmos DB private endpoint exists and is approved. Look for the <code>Sql<\/code> group:<\/p>\n<pre><code class=\"language-bash\">az network private-endpoint list --resource-group &lt;rg&gt; \\\r\n  --query \"[].{name:name, group:privateLinkServiceConnections[0].groupIds[0], status:privateLinkServiceConnections[0].privateLinkServiceConnectionState.status}\" \\\r\n  -o table<\/code><\/pre>\n<p>Next, check that the <code>privatelink.documents.azure.com<\/code> zone is linked to the VNet that contains the agent subnet. A private DNS zone only answers for VNets that are linked to it.<\/p>\n<pre><code class=\"language-bash\">az network private-dns link vnet list --resource-group &lt;dns-rg&gt; \\\r\n  --zone-name privatelink.documents.azure.com \\\r\n  --query \"[].{name:name, vnet:virtualNetwork.id, state:virtualNetworkLinkState}\" -o table<\/code><\/pre>\n<p>Then check the records. You should see one for the account and one for each region it runs in:<\/p>\n<pre><code class=\"language-bash\">az network private-dns record-set a list --resource-group &lt;dns-rg&gt; \\\r\n  --zone-name privatelink.documents.azure.com \\\r\n  --query \"[].{name:name, ip:aRecords[0].ipv4Address}\" -o table<\/code><\/pre>\n<pre><code class=\"language-text\">Name               Ip\r\n-----------------  ---------\r\nmy-cosmos          10.0.5.9\r\nmy-cosmos-westus3  10.0.5.10<\/code><\/pre>\n<p>If your VNet uses custom DNS servers instead of Azure DNS, make sure they forward these zones to the Azure DNS virtual server at <code>168.63.129.16<\/code> 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 <code>nslookup &lt;account&gt;.documents.azure.com<\/code> and confirm it returns your Cosmos DB private endpoint&#8217;s IP, not just any private IP.<\/p>\n<p>The same fix applies when Key Vault or Application Insights resolve to public IPs from your VNet. Key Vault needs the <code>privatelink.vaultcore.azure.net<\/code> 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.<\/p>\n<h2>3. Your private CA does not cover the platform&#8217;s Entra sign-in<\/h2>\n<p>Teams with a firewall that decrypts and re-signs TLS often register the firewall&#8217;s CA with private CA trust (public preview) and expect the timeouts to stop. They do not, and that is expected. From the docs:<\/p>\n<blockquote><p>Private CA trust doesn&#8217;t apply to the platform&#8217;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&#8217;s CA.<\/p><\/blockquote>\n<p>When I reproduced this in a test subscription, with the agent subnet&#8217;s Entra traffic routed through a decrypting proxy, registering the proxy&#8217;s CA made no difference. A no-decrypt rule for the Entra hosts fixed it.<\/p>\n<p>The fix has two parts:<\/p>\n<ul>\n<li>Exclude <code>login.microsoftonline.com<\/code>, <code>{region}.login.microsoft.com<\/code> and <code>control-{region}.identity.azure.net<\/code> from TLS inspection.<\/li>\n<li>Allow those hosts on the firewall, plus the managed identity FQDNs from the <a href=\"https:\/\/learn.microsoft.com\/azure\/container-apps\/use-azure-firewall#application-rules\">Azure Container Apps firewall guidance<\/a> or the <code>AzureActiveDirectory<\/code> service tag. If you put an NSG on the agent subnet, add a matching outbound rule for the <code>AzureActiveDirectory<\/code> service tag.<\/li>\n<\/ul>\n<p>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&#8217;s certificates, with certificate checks still on. I covered that in the <a href=\"https:\/\/devblogs.microsoft.com\/foundry\/hosted-agents-foundry-agent-service-ignite-2026\/\">hosted agents Ignite 2026 post<\/a>.<\/p>\n<h2>4. Resources in a peered hub VNet work, but DNS follows the agent subnet<\/h2>\n<p>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.<\/p>\n<p>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.<\/p>\n<p>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 <code>168.63.129.16<\/code> from a linked VNet. And keep every peered range unique, because overlapping ranges cause routing failures.<\/p>\n<h2>5. &#8220;DelegatedSubnetInUse&#8221; after you deleted an account<\/h2>\n<p>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 <code>DelegatedSubnetInUse<\/code>, and the subnet cannot be deleted.<\/p>\n<p>List soft-deleted accounts in the subscription:<\/p>\n<pre><code class=\"language-bash\">az cognitiveservices account list-deleted -o table<\/code><\/pre>\n<p>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:<\/p>\n<pre><code class=\"language-bash\">az cognitiveservices account purge \\\r\n  --location &lt;region&gt; --resource-group &lt;rg&gt; --name &lt;old-account&gt;<\/code><\/pre>\n<p>Give the platform some time to clean up, then check that the link is gone:<\/p>\n<pre><code class=\"language-bash\">az network vnet subnet show \\\r\n  --resource-group &lt;rg&gt; --vnet-name &lt;vnet&gt; --name agent-subnet \\\r\n  --query \"serviceAssociationLinks[].name\"<\/code><\/pre>\n<p>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.<\/p>\n<h2>What to watch for<\/h2>\n<ul>\n<li>Keep private endpoint addresses out of <code>192.168.0.0\/24<\/code> for hosted agents. That range overlaps an internal sandbox network, and connections can fail with &#8220;No route to host&#8221; even when DNS is right.<\/li>\n<li>The Foundry resource and the VNet must be in the same region. Cosmos DB, Storage and Search can be in other regions.<\/li>\n<li>The portal does not show IP use for the delegated subnet. Watch for <code>429 subnet_exhausted<\/code> on session create or resume, and 5xx errors from the data proxy.<\/li>\n<li>For hands-on DNS, TCP and TLS checks from inside the network, <a href=\"https:\/\/learn.microsoft.com\/azure\/foundry\/agents\/how-to\/troubleshoot-hosted-agent-networking\">Troubleshoot hosted agent virtual network connectivity<\/a> walks through them from a jump box.<\/li>\n<\/ul>\n<h2>Docs<\/h2>\n<ul>\n<li><a href=\"https:\/\/learn.microsoft.com\/azure\/foundry\/agents\/how-to\/virtual-networks\">Set up private networking for Foundry Agent Service<\/a><\/li>\n<li><a href=\"https:\/\/learn.microsoft.com\/azure\/foundry\/agents\/concepts\/agents-networking-deep-dive\">Deep dive into Foundry Agent Service networking<\/a><\/li>\n<li><a href=\"https:\/\/learn.microsoft.com\/azure\/foundry\/agents\/how-to\/troubleshoot-hosted-agent-networking\">Troubleshoot hosted agent virtual network connectivity<\/a><\/li>\n<li><a href=\"https:\/\/learn.microsoft.com\/azure\/foundry\/agents\/how-to\/private-certificate-authority\">Connect agents to services that use a private certificate authority<\/a><\/li>\n<li><a href=\"https:\/\/learn.microsoft.com\/azure\/dns\/private-dns-overview\">What is Azure Private DNS?<\/a><\/li>\n<li><a href=\"https:\/\/learn.microsoft.com\/azure\/virtual-network\/virtual-networks-udr-overview\">Azure virtual network traffic routing<\/a><\/li>\n<\/ul>\n<p>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.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>The five questions teams ask most when they run hosted agents in their own virtual network: which subnet is the agent subnet, why listing agents times out, why a TLS-inspecting firewall still breaks after you add your CA, how peered VNets and DNS fit, and why a subnet stays in use after you delete an account.<\/p>\n","protected":false},"author":220871,"featured_media":3471,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[206,207,122,157,110,208],"class_list":["post-3470","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-microsoft-foundry","tag-byo-vnet","tag-dns","tag-foundry-agent-service","tag-hosted-agents","tag-private-networking","tag-tls-inspection"],"acf":[],"blog_post_summary":"<p>The five questions teams ask most when they run hosted agents in their own virtual network: which subnet is the agent subnet, why listing agents times out, why a TLS-inspecting firewall still breaks after you add your CA, how peered VNets and DNS fit, and why a subnet stays in use after you delete an account.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/foundry\/wp-json\/wp\/v2\/posts\/3470","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/foundry\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/foundry\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/foundry\/wp-json\/wp\/v2\/users\/220871"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/foundry\/wp-json\/wp\/v2\/comments?post=3470"}],"version-history":[{"count":1,"href":"https:\/\/devblogs.microsoft.com\/foundry\/wp-json\/wp\/v2\/posts\/3470\/revisions"}],"predecessor-version":[{"id":3474,"href":"https:\/\/devblogs.microsoft.com\/foundry\/wp-json\/wp\/v2\/posts\/3470\/revisions\/3474"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/foundry\/wp-json\/wp\/v2\/media\/3471"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/foundry\/wp-json\/wp\/v2\/media?parent=3470"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/foundry\/wp-json\/wp\/v2\/categories?post=3470"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/foundry\/wp-json\/wp\/v2\/tags?post=3470"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}