Set up private networking for Foundry Agent Service

Foundry Agent Service offers a Standard Setup with private networking environment. This setup creates an isolated network environment that enables secure access to data while maintaining full control over your network infrastructure.

By default, the Standard Setup with private networking ensures:

• No public egress: Foundational infrastructure provides the right authentication and security for your agents and tools, without requiring trusted service bypass.
• Subnet integration: You provide a delegated subnet from your virtual network. The platform connects agent compute to this subnet, enabling local communication with your Azure resources within the same virtual network.
• Private resource access: If your resources are marked as private and nondiscoverable from the internet, the platform network can still access them when the necessary credentials and authorization are in place.

If you don't have an existing virtual network, the Standard Setup with private networking flow can provision the necessary network infrastructure for you.

Prerequisites

• An Azure subscription - Create one for free.

• The permissions described in Permissions. Provisioning and runtime use two different identities, and each needs its own roles.

• Python 3.10 or later

• Register providers. The following providers must be registered:

  • Microsoft.KeyVault
  • Microsoft.CognitiveServices
  • Microsoft.Storage
  • Microsoft.MachineLearningServices
  • Microsoft.Search
  • Microsoft.Network
  • Microsoft.App
  • Microsoft.ContainerService
  • To use Bing Search tool: Microsoft.Bing

     az provider register --namespace 'Microsoft.KeyVault'
     az provider register --namespace 'Microsoft.CognitiveServices'
     az provider register --namespace 'Microsoft.Storage'
     az provider register --namespace 'Microsoft.MachineLearningServices'
     az provider register --namespace 'Microsoft.Search'
     az provider register --namespace 'Microsoft.Network'
     az provider register --namespace 'Microsoft.App'
     az provider register --namespace 'Microsoft.ContainerService'
     # only to use Grounding with Bing Search tool
     az provider register --namespace 'Microsoft.Bing'
  

Permissions

The provisioning identity depends on the deployment path. Capability settings that you submit through ARM REST or Bicep use the caller identity. Portal deployments and calls to the legacy capability host REST API continue to use the project managed identity for provisioning.

Caller permissions for provisioning

For a deployment that uses capability settings with API version 2026-07-15-preview, the caller can be an interactive user, a CI/CD service principal, or a workload identity. In addition to the permissions needed to deploy the account and network resources, capability settings require only the following roles. Azure AI Search doesn't require a caller role.

A caller that can create the Foundry account but lacks Storage Blob Data Contributor or Cosmos DB Operator fails capability settings provisioning.

Runtime access after deployment

The project managed identity is what running agents use to reach Azure Cosmos DB, Azure AI Search, and Azure Storage. Grant it data-plane roles on each resource before agents run. The caller roles in the previous table enable capability settings provisioning only. They don't replace the roles the project managed identity needs at runtime. For portal and legacy capability host REST API deployments, the project managed identity also performs provisioning. For the per-resource role list, see Standard agent setup.

After the environment is configured, assign each team member who creates or edits agents the built-in Foundry User RBAC role on the project. The minimum permissions are agents/*/read, agents/*/action, and agents/*/delete.

Configure a network-secured environment

You can create this setup in the Azure portal or deploy it by using Bicep or Terraform.

At a high level, the deployment involves these steps:

1. Choose the target Azure region for your Foundry resources.
2. Decide whether to bring your own VNet and subnet, or use auto-provisioned networking.
3. If you bring your own VNet, gather your VNet and subnet resource IDs.
4. Create the setup in the Azure portal, or deploy it by using Bicep or Terraform.
5. Verify the deployment (see Verify the deployment).

The setup provisions the following resources (unless you bring your own):

• A Foundry account and Foundry project.
• A gpt-4o model deployment.
• Azure Storage, Azure Cosmos DB, and Azure AI Search for storing files, threads, and vector data.
• These resources are connected to your project.
• Microsoft-managed encryption keys for Storage Account and Cognitive Account (Foundry) are used by default.

Select your preferred deployment method by using the following tabs:

Verify the deployment

After deployment finishes, verify that all resources are configured correctly:

1. Confirm subnet delegation: In the Azure portal, navigate to your VNet > Subnets and verify the agent subnet shows delegation to Microsoft.App/environments.
2. Check public network access: Open each resource (Foundry, Azure AI Search, Azure Storage, Azure Cosmos DB) and confirm Public network access is set to Disabled.
3. Validate private endpoint DNS resolution: From a machine connected to the VNet, run nslookup against each endpoint listed in the DNS zone configurations summary.
4. Test agent connectivity: Access your Foundry project from within the VNet (see Access your secured agents) and confirm you can create and run an agent.
5. Configure Role assignments: Run the following commands to assign the required roles. The first grants Managed Identity Operator on the user-assigned managed identity, and the second grants Network Contributor on the remote VNet for cross-tenant access.

az role assignment create \
   --assignee <your-principal-id> \
   --role "Managed Identity Operator" \
   --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<id>"

 az role assignment create \
   --assignee <service-principal-object-id-in-remote-tenant> \
   --role "Network Contributor" \
   --scope "/subscriptions/<remote-subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Network/virtualNetworks/<vnet-name>"

Limitations

• VNet and subnet IP address limitations:
  • Your Agent Service delegated subnet must use one of these address spaces:
    • RFC 1918: 10.0.0.0/8, 172.16.0.0/12, or 192.168.0.0/16.
    • RFC 6598 (CGNAT): addresses within 100.64.0.0/10, excluding 100.100.0.0/17, 100.100.192.0/19, and 100.100.224.0/19.
  • Every region where Agent Service is available supports private Class A address space (10.0.0.0/8). For the current list, see Supported regions.
  • You can't use public IP ranges, such as 44.x.x.x, for the Agent Service delegated subnet.
  • Ensure that none of the address spaces in your VNet or any peered VNet overlap with existing networks in your Azure environment or these reserved ranges: 169.254.0.0/16, 172.30.0.0/16, 172.31.0.0/16, 192.0.2.0/24, 0.0.0.0/8, 127.0.0.0/8, 100.100.0.0/17, 100.100.192.0/19, and 100.100.224.0/19.
• Agent subnet exclusivity: The agent subnet can't be shared by multiple Foundry resources. Each Foundry resource must use a dedicated agent subnet.
• Agent subnet size: The recommended size of the delegated Agent subnet is /24 (256 addresses) due to the delegation of the subnet to Microsoft.App/environments. For more on subnet sizing, see Configuring virtual networks for Azure Container Apps.
• Agent subnet name length: For Azure Container Apps-backed deployments, the delegated agent subnet name must not exceed 63 UTF-8 bytes. This limit applies to the subnet name, not the virtual network name or the full subnet resource ID.
• Agent subnet egress firewall allow list: If you integrate an Azure Firewall with your private network secured standard agent, add control-{region}.identity.azure.net, {region}.login.microsoft.com, and login.microsoftonline.com to the firewall allow list. Replace {region} with the Azure region where you deploy the agent. Also add the Fully Qualified Domain Names (FQDNs) listed under Managed Identity in the Integrate with Azure Firewall article, or add the AzureActiveDirectory service tag. If you apply Network Security Groups (NSGs) to the delegated agent subnet or related subnets, configure matching outbound allow rules for required dependencies, including the AzureActiveDirectory service tag for Microsoft Entra ID authentication. If either firewall or NSG rules block required dependencies, agent provisioning and runtime operations can fail.
  • Verify that no TLS inspection happens in the firewall that could add a self-signed certificate. During failures, inspect whether any traffic reaches the firewall and what traffic is blocked.
  • For source-code agent deployments, also allow the deployment endpoints listed in Firewall requirements for private virtual networks.
• The Foundry resource must be deployed in the same region as the virtual network (VNet). Other Azure resources, such as Azure Cosmos DB, Azure AI Search, and Azure Storage, can be deployed in different regions. Consider the cost implications of cross-region deployments.
• Region availability:
  • For supported regions for model deployments, see: Azure OpenAI model region support.
• Azure Blob Storage: Using Azure Blob Storage files with the File Search tool isn't supported.
• Code Interpreter file limitations: In a private network (BYO) configuration, Code Interpreter only works in scenarios that don't involve file uploads or downloads. The tool can't retrieve files from the storage account in this setup. If you need to use files with Code Interpreter, you must use the SDK to create a container explicitly with the required files and then pass the container_id to Code Interpreter. This workaround is only available through the SDK; the Foundry portal UI doesn't support it.
• Grounding with Bing Search: Only the following regions are supported: West Europe, Canada East, Switzerland North, Spain Central, UAE North, Korea Central, Poland Central, Southeast Asia, West US, West US 2, West US 3, East US, East US 2, Central US, South India, Japan East, UK South, France Central, Norway East, Australia East, Canada Central, Sweden Central, South Africa North, Italy North, Brazil South
• Delete network injection: If you want to delete your Foundry resource and Standard Agent with secured network setup, delete your Foundry resource and virtual network last. Before deleting the virtual network, delete and purge your Foundry resource.
• Hosted agent virtual network injection: For Hosted agents, the virtual network configuration (network injection) must be included when you first create the Foundry account. Adding network injection to an existing Foundry account after creation isn't supported for Hosted agents.
• Hosted agent container registry behind a private network: For Hosted agents, support for an Azure Container Registry (ACR) behind a private network (private endpoint with public network access disabled) depends on when the Foundry project was created. Projects created after June 25, 2026 support a private ACR. Projects created before that date require the ACR to be reachable over its public endpoint so the platform can pull the image. Existing projects aren't affected and continue to use public network access.

Architecture diagram

Review the provisioned networking resources

The following resources are automatically provisioned when you use Standard Setup with private networking, unless you bring your own:

Network infrastructure

• A virtual network (192.168.0.0/16)
• Agent Subnet (192.168.0.0/24): Hosts Agent client
• Private endpoint Subnet (192.168.1.0/24): Hosts private endpoints

Virtual network capabilities

Your virtual network controls which endpoints can make API calls to your resources. The Azure service automatically rejects API calls from devices outside your defined network.

Network rules

All accounts and their corresponding projects are protected by default with the Public network access Disabled flag, requiring explicit configuration to allow access through private endpoints. These rules apply to all protocols, including REST and WebSocket.

DNS zone configurations summary

To create a conditional forwarder in the DNS Server to the Azure DNS Virtual Server, use the list of zones mentioned in the above table. The Azure DNS Virtual Server IP address is 168.63.129.16.

Access your secured agents

Once deployment is complete, you can access your Foundry project behind a virtual network using one of the following methods:

• Azure VPN Gateway: Connects on-premises networks to the virtual network over a private connection. Connection is made over the public internet. There are two types of VPN gateways that you might use:
  • Point-to-site: Each client computer uses a VPN client to connect to the virtual network.
  • Site-to-site: A VPN device connects the virtual network to your on-premises network.
• ExpressRoute: Connects on-premises networks into the cloud over a private connection. Connection is made using a connectivity provider.
• Azure Bastion: In this scenario, you create an Azure Virtual Machine (sometimes called a jump box) inside the virtual network. You then connect to the VM using Azure Bastion. Bastion allows you to connect to the VM using either an RDP or SSH session from your local web browser. You then use the jump box as your development environment. Since it's inside the virtual network, it can directly access the workspace.

FAQ

What address range should I use for the overall virtual network?

The virtual network address range can be any private IP range that leaves enough address space for both the delegated agent subnet and the private endpoint subnet.

Can I use peered virtual networks or place resources in different virtual networks?

Peered virtual networks are supported, but data transfer costs can increase.

Can multiple Foundry resources reuse the same virtual network and subnet?

Yes, the same VNET, but not the same subnet. Multiple Foundry resources can reuse the same virtual network. However, each Foundry resource requires its own dedicated agent runtime subnet. The agent subnet can't be shared across multiple Foundry resources.

Does the virtual network need to be in the same resource group as the Foundry resource?

No. The virtual network and Foundry resource don't need to be in the same resource group, but they must be in the same region.

Troubleshooting guide

Refer to this guide to resolve errors during or after a Standard Agent deployment, whether you used the Azure portal, Bicep, or Terraform.

Deployment errors

"CreateCapabilityHostRequestDto is invalid: Agents CapabilityHost supports a single, non empty value for vectorStoreConnections property."

"Agents CapabilityHost supports a single, non empty value for storageConnections property."

"Agents CapabilityHost supports a single, non empty value for threadStorageConnections property."

Solution: Your deployment didn't supply all three bring-your-own (BYO) resources. A secured standard setup requires an Azure Cosmos DB account, an Azure Storage account, and an Azure AI Search service. Set all three on the account or project through capability settings before you create the project. If the project already exists, delete and recreate it with the required settings because capability settings updates aren't supported.

"Provided subnet must be of the proper address space. Please provide a subnet which has address space in the range of 172 or 192."

Solution: You're not using a proper IP range for your delegated agent subnet. Verify that you're using a valid private IP address space. Valid RFC1918 ranges include 10.0.0.0/8, 172.16-31.0.0/12, and 192.168.0.0/16. More details are in limitations above.

"Subscripton is not registered with the required resource providers, please register with the resource providers Microsoft.App and Microsoft.ContainerService."

Solution: You're missing the correct resource registration. Ensure the required resources are registered in your tenant.

"Failed to create Aml RP virtual workspace due to System.Exception: Failed async operation." or "The resource operation completed with terminal provisioning state 'Failed'. Capability host operation failed."

Solution: This error message can indicate many problems. For an ARM REST or Bicep capability settings deployment, confirm the caller has every role listed in Caller permissions for provisioning. For a portal or legacy capability host REST API deployment, confirm the project managed identity has the required provisioning and runtime roles. If the deploying identity has all required roles, create a support ticket to investigate your setup.

"Subnet requires any of the following delegation(s) [Microsoft.App/environments] to reference service association link /subscriptions/11111-aaaaa-2222-bbbb-333333333/resourceGroups/agentRANGEChange/providers/Microsoft.Network/virtualNetworks/my-agent-vnet/subnets/agent-subnet/serviceAssociationLinks/legionservicelink."

Solution: This error appears when you try to delete your secured standard template setup in Azure and didn't correctly delete all resources. One solution is to navigate to your Foundry resource page in the Azure portal and select Manage deleted resources. From there, purge the resource that the agent was associated with for this virtual network. The other option is to run the deleteCaphost.sh script in the secured standard template.

"Timeout of 60000ms exceeded" error when loading the Agent pages in the Foundry project

Solution: The Foundry project has issues communicating with Azure Cosmos DB to create Agents. Verify connectivity to Azure Cosmos DB (Private Endpoint and DNS).

Private endpoint DNS resolution fails

Solution: If resources aren't reachable through private endpoints, verify that each private DNS zone is linked to your virtual network. Confirm conditional forwarders point to the Azure DNS virtual server IP address 168.63.129.16. From a machine connected to the VNet, run nslookup <resource-fqdn> and verify that each name resolves to a private IP address.

Next steps

You've now successfully configured a network-secure account and project. Use the quickstart to create your first agent.

For more on network isolation configuration and options, see Configure network isolation.

Many enterprise environments require that Foundry, the container registry, and dependent services such as Application Insights and Storage be reachable only from a private network. This section explains how to provision and deploy azd hosted agents whose dependencies sit behind private endpoints in a virtual network (VNet).

Configure networking on the azure.ai.project service, review the generated infrastructure, and run azd from a machine with access to the private endpoints.

If you use a coding agent like GitHub Copilot, the Microsoft Foundry Skill can help choose the right private-networking path and apply the required azd, Bicep, or Terraform steps.

Prerequisites

• An initialized hosted agent project. To create one, see Initialize a hosted agent project with the Azure Developer CLI.
• The Azure Developer CLI Foundry extensions installed.
• A virtual network (new or existing) and permission to create private endpoints and private DNS zones.
• Familiarity with the scaffolded Bicep. See Hosted agent infrastructure with the Azure Developer CLI.

What VNet protection means for an azd deployment

A hosted agent project provisions a Foundry account and project, declared models, and an optional container registry. Additional application dependencies need their own infrastructure.

Private networking and session isolation address different requirements. Review the network architecture for ingress and egress behavior.

What the extension does and doesn't do

Decide your topology

Most VNet-protected deployments fall into one of these shapes. Pick one before you edit Bicep:

• Create a project in a new network. Provision the VNet separately, then reference it in the project service's network block.
• Attach a new project to an existing VNet. Reference the VNet and existing subnets, or provide subnet prefixes to create subnets during provisioning.
• Reuse an existing project. Initialize with --project-id and the appropriate registry connection. Manage that project's existing private endpoints and dependent resources through their owning infrastructure.

For a new project, configure networking before provisioning or ejecting infrastructure.

Customize the scaffolded Bicep

Initialization is infrastructure-file-free by default. azd ai agent init --infra ejects editable Bicep. If you already have application infrastructure, ejection preserves it and adds infra/foundry; existing layered configurations retain their declared paths. Configure the project service's network block before ejection so the generated infrastructure reflects the intended private endpoints and egress.

Add VNet and subnet parameters

Declare the private-endpoint subnet and optional customer-managed agent subnet on the project service:

services:
  ai-project:
    host: azure.ai.project
    network:
      peSubnet:
        vnet: ${VNET_RESOURCE_ID}
        name: private-endpoint-subnet
      agentSubnet:
        vnet: ${VNET_RESOURCE_ID}
        name: agent-subnet

The subnets must be different and in the same VNet. Add prefix to a subnet declaration to create it; omit agentSubnet to use Microsoft-managed egress. See the network configuration reference for isolation modes and existing DNS zones.

Set the VNet resource ID, then eject the configured infrastructure:

azd env set VNET_RESOURCE_ID \
  /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.Network/virtualNetworks/<vnet>
azd ai agent init --infra

Lock down each resource

Review the generated modules/ files. The account network block disables public data-plane access and generates the account private endpoint and DNS wiring. It doesn't create private endpoints for every application dependency.

The project extension doesn't support an automatically created container registry when private networking is configured. Use source-code deployment or a prebuilt image.

For a private prebuilt image, configure an existing registry connection and manage its private endpoint and DNS separately. Manage private networking for separately provisioned telemetry, storage, and search resources in their own infrastructure.

Provision the resources

azd provision

After provisioning, verify private DNS resolution and connectivity for the Foundry endpoint and each dependent resource from the deployment machine.

Run azd up from inside the VNet

After you disable public network access, you can't run azd up or azd deploy from a public-internet workstation. The ARM control plane is reachable, but data-plane calls to Foundry and ACR push fail with 403 or connection-refused errors. Use one of the following patterns.

Self-hosted GitHub Actions runner

Provision a runner VM, or an AKS-hosted runner, in a subnet of the same VNet. Point your workflow at that runner with runs-on: [self-hosted, agent-vnet]. Every azd ai step then resolves the private DNS names correctly and pushes through the private endpoint.

jobs:
  deploy:
    runs-on: [self-hosted, agent-vnet]
    steps:
      - uses: actions/checkout@v4
      - uses: Azure/setup-azd@v2
      - run: azd ext install microsoft.foundry
      - run: azd auth login --client-id ${{ secrets.AZURE_CLIENT_ID }} \
          --federated-credential-provider github \
          --tenant-id ${{ secrets.AZURE_TENANT_ID }}
      - run: azd up --no-prompt

Azure DevOps self-hosted agent

Use the same pattern for Azure DevOps. Install the agent in a VNet subnet and target it with the pool: name: agent-vnet directive. The azd CLI and the Foundry extension run unchanged.

Bastion or jump host for one-off runs

For ad hoc runs, such as manual incident response or an out-of-cycle deploy, connect through Azure Bastion to a jump host inside the VNet, install azd and the extensions there, and run azd from that host. Keep the jump host minimal. The long-term answer is CI.

Develop locally against a private Foundry endpoint

azd ai agent invoke --local talks to the locally running agent. Without --local, it invokes the deployed endpoint. Your local agent can still need private-network access to models and tools. When those endpoints are private, provide network reachability from your development machine:

• A point-to-site or always-on VPN that drops you into the VNet DNS scope.
• Azure Bastion to a development VM inside the VNet. Run azd ai agent run on that VM and forward port 8088, and 8087 for the inspector, through the Bastion tunnel.
• A workstation in the corporate network with an ExpressRoute or hub-VNet path to the spoke that hosts the private endpoints.

Project endpoint selection doesn't change. See Set the project context for resolution rules. DNS must resolve the endpoint to a reachable private IP.

Combine with a private ACR

If both the Foundry endpoint and the ACR are on private endpoints in the same VNet, do the following:

1. Configure the existing registry connection and verify its pull identity, as described in the registry guide.
2. Verify private DNS and network access to the registry from the deployment machine and hosted runtime.
3. Run azd up from a machine with the required network access.

For registry-specific details, see Deploy a hosted agent with a private Azure Container Registry.

Diagnose networking issues

• azd ai agent doctor runs local and remote project checks. Private-network access is necessary for remote checks, but doesn't guarantee that authentication and configuration checks pass. Use --local-only to skip remote checks.
• azd ai agent invoke --output raw "ping" dumps the full HTTP response. A connection-refused or no-such-host error here is a DNS or routing problem, not an authentication problem.
• For ACR push failures, the CLI emits a paste-ready az role assignment create command when the cause is a missing role rather than a network issue.

Known limitations

• Declare networking through azure.yaml, not a --vnet initialization flag. Runner placement, dependent-resource private endpoints, DNS, and RBAC still need configuration.
• Region constraints apply. Hosted agents are available in a fixed set of regions. The VNet, ACR, and Foundry account should all live in, or peer to, one of those regions. For the same-region requirement between the Foundry resource and its virtual network, see Regional support for private networking. Run azd ai agent doctor to validate.
• DNS is the most common failure mode. Confirm private DNS resolution end to end, for example with nslookup <endpoint> from the runner or development VM, before you assume the issue is RBAC.

Related content

• Deploy a hosted agent with a private Azure Container Registry
• Isolate hosted agent sessions per user
• Hosted agent infrastructure with the Azure Developer CLI
• Diagnose a project with agent doctor