Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
You can connect an AI agents group for serverless sandboxes in Azure Container Instances (ACI) to a subnet in your Azure virtual network. Each sandbox in the group gets a private IP address from the subnet, so sandboxes can reach private resources in the virtual network, such as internal services, databases, and private endpoints.
In this tutorial, you deploy a web app with only a private IP address. You then create an AI agents group in the same virtual network, and reach the web app from a sandbox.
In this tutorial, you learn how to:
- Create a virtual network with a delegated subnet for sandboxes
- Deploy a private web app in the virtual network
- Create an AI agents group that's connected to the subnet
- Reach the private web app from a sandbox
Prerequisites
An Azure subscription. If you don't have an Azure subscription, create a free account before you begin.
The Azure CLI, version 2.60 or later, signed in with
az login, or another tool to send authenticated REST requests to Azure Resource Manager.The
Microsoft.ContainerInstanceresource provider registered in your subscription.az provider register --namespace Microsoft.ContainerInstance --waitThe Contributor, Azure Deployment Stack Owner, and Storage Blob Data Contributor roles assigned to the Compute Sandbox Groups service principal on your subscription, so that the service can provision the managed resource group and snapshot storage account in your subscription. To assign the roles, you need permission to create role assignments on the subscription, such as the Owner or User Access Administrator role:
subscriptionId=$(az account show --query id --output tsv) spObjectId=$(az ad sp show --id 1eeacc2b-ec4a-4b1e-977a-2b5fef2131c6 --query id --output tsv 2>/dev/null || \ az ad sp create --id 1eeacc2b-ec4a-4b1e-977a-2b5fef2131c6 --query id --output tsv) for role in "Contributor" "Azure Deployment Stack Owner" "Storage Blob Data Contributor"; do az role assignment create --assignee-object-id $spObjectId --assignee-principal-type ServicePrincipal \ --role "$role" --scope /subscriptions/$subscriptionId doneRole assignments can take up to 15 minutes to take effect.
Quota provisioned for serverless sandboxes in Azure Container Instances on your subscription:
Open New support request in the Azure portal (with Issue type set to Service and subscription limits (quotas) and Quota type set to Container Instances), select your subscription, and go to the Additional details tab.
Select Enter details to open the Quota details pane, choose your Location, select AIAgentsGroups - StandardCores (Preview) for Quota type, and fill in Networking type, Container Type, Total AIAgentsGroups Group Limit, and Total AIAgentsGroups Core Limit:
Submit the support request. After your quota request is approved, re-register the
Microsoft.ContainerInstanceresource provider (az provider register --namespace Microsoft.ContainerInstance --wait) so that your subscription picks up the newly enabled capabilities.
To connect to a running sandbox after you create an AI agents group and a sandbox (see Quickstart: Create your first serverless sandbox), a gRPC client generated from the sandbox gateway protobuf file,
sandboxgateway.proto. A gRPC client is required because the sandbox gateway exposes a gRPC service (aci.sandboxgateway.SandboxGatewayService) for in-sandbox operations such as waiting for readiness, running commands, transferring files, and reading logs. To use the cross-platform sample C# CLI in this documentation (supported on Linux, macOS, and Windows), install the .NET 8 SDK and build the CLI.Note
A gRPC client isn't required if you schedule and manage serverless sandboxes through Azure Kubernetes Service (AKS).
Create a virtual network
Create a virtual network with two subnets:
| Subnet | Delegation | Used by |
|---|---|---|
sandbox-subnet |
Microsoft.ContainerInstance/AIAgentsGroups |
The sandboxes. Each sandbox uses one IP address. |
app-subnet |
Microsoft.ContainerInstance/containerGroups |
The private web app in this tutorial. |
az group create --name myResourceGroup --location centralus
az network vnet create --resource-group myResourceGroup --name myVnet --location centralus --address-prefix 10.10.0.0/16
az network vnet subnet create --resource-group myResourceGroup --vnet-name myVnet --name sandbox-subnet \
--address-prefixes 10.10.0.0/21 --delegations Microsoft.ContainerInstance/AIAgentsGroups
az network vnet subnet create --resource-group myResourceGroup --vnet-name myVnet --name app-subnet \
--address-prefixes 10.10.8.0/24 --delegations Microsoft.ContainerInstance/containerGroups
Size the sandbox subnet for the number of sandboxes that you plan to run at the same time. Each sandbox uses one IP address from the subnet. The /21 subnet in this example has room for about 2,000 sandboxes.
Important
For outbound internet access (egress), associate a NAT gateway with the sandbox subnet in your virtual network and set the subnet's default outbound access setting (defaultOutboundAccess) to true. For NAT gateway configuration guidance, see Configure container group egress with a NAT gateway.
Deploy a private web app
Deploy a container group in app-subnet. The container group has only a private IP address, so it isn't reachable from the internet:
az container create --resource-group myResourceGroup --name private-web \
--image mcr.microsoft.com/azuredocs/aci-helloworld --vnet myVnet --subnet app-subnet --os-type Linux --cpu 1 --memory 1.5
az container show --resource-group myResourceGroup --name private-web --query ipAddress.ip -o tsv
The output is a private IP address from app-subnet, such as 10.10.8.4.
Create an AI agents group in the virtual network
Create the AI agents group with the resource ID of
sandbox-subnetinproperties.networkProfile.subnets:PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/myResourceGroup/providers/Microsoft.ContainerInstance/AIAgentsGroups/myVnetAgentsGroup?api-version=2026-08-01-preview { "location": "centralus", "properties": { "networkProfile": { "subnets": [ { "id": "/subscriptions/{subscriptionId}/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/myVnet/subnets/sandbox-subnet" } ] } } }Check the AI agents group until
properties.provisioningStateisSucceeded, and then callconnectto get its{endpoint}and{accessToken}:GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/myResourceGroup/providers/Microsoft.ContainerInstance/AIAgentsGroups/myVnetAgentsGroup?api-version=2026-08-01-previewPOST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/myResourceGroup/providers/Microsoft.ContainerInstance/AIAgentsGroups/myVnetAgentsGroup/connect?api-version=2026-08-01-preview
All the sandboxes in the group use the subnet. You can't change the network profile of an AI agents group after you create it.
Reach the private web app from a sandbox
Create a sandbox in the group. The
azure-cliimage includescurl:PUT {endpoint}/sandboxes/vnet1?api-version=2026-08-01-preview Authorization: Bearer {accessToken} Content-Type: application/json { "location": "centralus", "properties": { "image": "mcr.microsoft.com/azure-cli" } }Wait until
properties.provisioningStateisSucceeded. Then copyproperties.connectionStringfrom the response, and wait until the guest is ready (WaitForReady). By using the sample C# CLI:dotnet run -- -cs "<vnet1-connection-string>" waitIn
vnet1, request the private web app (ExecSandbox). Replace<private-web-ip>with the private IP address ofprivate-web:dotnet run -- -cs "<vnet1-connection-string>" exec curl -s http://<private-web-ip>The response contains the HTML of the web app, which includes this text:
Welcome to Azure Container Instances!
The sandbox reached the web app through the virtual network. A sandbox in an AI agents group that isn't connected to the virtual network can't reach this private IP address.
Note
For ACI serverless sandboxes connected to a virtual network, network isolation depends on the delegated subnet. To block or restrict traffic in any direction (inbound or outbound), configure a network security group (NSG) on the sandbox subnet.
Clean up resources
Delete the AI agents group. Deleting an AI agents group is a long-running operation. It also deletes the sandboxes in the group:
DELETE https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/myResourceGroup/providers/Microsoft.ContainerInstance/AIAgentsGroups/myVnetAgentsGroup?api-version=2026-08-01-previewDelete the web app and the virtual network. Delete the virtual network after the AI agents group deletion finishes. You can't delete a subnet while an AI agents group uses it.
az container delete --resource-group myResourceGroup --name private-web --yes az network vnet delete --resource-group myResourceGroup --name myVnet