Foundry private networking for Azure AI agents

[m5i-work]

Summary

Adds declarative private networking support for host: microsoft.foundry services in the Azure AI agents extension.

This PR teaches the in-memory Foundry synthesizer to provision a network-bound Foundry account/project from azure.yaml:

services:
  agent:
    host: azure.ai.agent
    network:
      mode: byo
      byo:
        vnet:
          id: ${AZURE_VNET_ID}
        agentSubnet:
          name: agent-subnet
          prefix: 192.168.10.0/24
        peSubnet:
          name: pe-subnet
          prefix: 192.168.11.0/24

It also adds schema/docs/tests and an E2E harness for validating the private-networking scenarios.

Changes

• Add network: schema support for Foundry-hosted services.
• Synthesize Bicep for BYO VNet mode:
  • delegated hosted-agent subnet
  • private endpoint subnet
  • Foundry account network isolation
  • Foundry private endpoint
  • private DNS zones for AI Services/OpenAI/Cognitive Services
• Preserve ${VAR} placeholders during azd ai agent init --infra eject; resolve only at provision time.
• Fix live-deployment-only template issue: avoid unresolved module reference() in networkInjections.subnetArmId by using a deterministic subnet ARM id string.
• Fix ARM output casing restoration for AZURE_FOUNDRY_NETWORK_MODE.
• Add E2E harness under cli/azd/extensions/azure.ai.agents/test/e2e/network/.
• Add optional ABAC ACR image-build path for private-runtime validation.

Documentation

• Added a concise user cheatsheet: cli/azd/extensions/azure.ai.agents/docs/private-networking.md

E2E validation performed

Validated the feature end-to-end against live Azure using a private-networked Foundry account and, for runtime validation, a private-only ABAC ACR.

Scenario 1: Provision private-networked Foundry from azure.yaml

Validated both BYO VNet mode and Microsoft-managed VNet mode.

For BYO VNet mode, validated that a network: block on a Foundry-hosted service provisions:

• Foundry account with public access disabled
• BYO VNet integration
• delegated hosted-agent subnet
• private endpoint subnet
• Foundry private endpoint
• required private DNS zones and VNet links
• AZURE_FOUNDRY_NETWORK_MODE=byo

For managed VNet mode, validated:

• networkInjections.useMicrosoftManagedNetwork=true
• Foundry data plane remains publicly reachable for azd deploy / invoke because managed mode does not create a customer private endpoint
• AZURE_FOUNDRY_NETWORK_MODE=managed
• AZURE_FOUNDRY_MANAGED_ISOLATION_MODE=AllowInternetOutbound

Also validated the matrix of create/reference subnet modes and own/reference DNS modes.

Scenario 2: Eject preserves private-networking configuration

Validated that azd ai agent init --infra ejects equivalent Bicep and preserves ${VAR} placeholders, so values such as ${AZURE_VNET_ID} are resolved at provision time rather than frozen during eject.

The ejected template was verified to be idempotent against the already-provisioned private-networked account.

Scenario 3: Deploy and invoke hosted agents

Validated real hosted-agent deploy and invoke for both network modes.

For BYO VNet mode, validated deploy/invoke with:

• Foundry public access disabled
• Foundry private endpoint only
• ACR public access disabled
• ABAC-enabled ACR
• ACR private endpoint
• private DNS for both Foundry and ACR
• deploy/invoke client running from a peered private-network runner VM

For managed VNet mode, validated deploy/invoke with:

• Microsoft-managed network injection
• Foundry public data-plane access enabled
• ABAC-enabled ACR
• image built with az acr build --source-acr-auth-id [caller]
• Foundry project MI granted Container Registry Repository Reader

In both cases, the hosted agent reached active status and azd ai agent invoke returned the expected echo response.

Validated VNet topology

Workload VNet: azdnetp5one1519-vnet 192.168.0.0/16
├── pe-subnet 192.168.11.0/24
│   ├── Foundry private endpoint
│   └── ACR private endpoint
├── agent-subnet 192.168.10.0/24
│   └── delegated to Microsoft.App/environments
├── ref-pe-subnet 192.168.20.0/24
└── ref-agent-subnet 192.168.21.0/24
    └── delegated to Microsoft.App/environments

Runner VNet: azdnetp5one1519-runner-eastus2 10.240.0.0/16
└── runner-subnet 10.240.1.0/24
    └── runner VM

Peering:
azdnetp5one1519-runner-eastus2 <-> azdnetp5one1519-vnet

Private DNS zones linked to both VNets:

privatelink.services.ai.azure.com
privatelink.openai.azure.com
privatelink.cognitiveservices.azure.com
privatelink.azurecr.io

Notable findings from validation

• BYO VNet deploy/invoke must run from a host with private endpoint reachability; public-internet clients correctly fail when Foundry public access is disabled.
• Managed VNet mode does not create a customer private endpoint, so the Foundry data plane remains public while the hosted-agent runtime uses Microsoft-managed network injection.
• Hosted-agent image pull uses the Foundry project MI, not the parent account MI.
• Private-only ACR runtime pull requires Premium ACR, an ACR private endpoint, privatelink.azurecr.io, and Container Registry Repository Reader on the Foundry project MI.
• Building into an ABAC-enabled ACR requires the caller to have Container Registry Repository Writer; the harness uses az acr build --source-acr-auth-id [caller].

Reviewer checklist

• Review schema shape for network:.
• Review synthesized Bicep and generated ARM JSON.
• Review project MI vs account MI ACR pull grant in the E2E harness.
• Review eject-time ${VAR} preservation behavior.
• Review whether private ACR / VM runner support should remain as E2E harness-only documentation or become fully automated in a follow-up.