Foundry private networking for Azure AI agents

[m5i-work]

Summary

Adds declarative, secure-by-default private networking for host: microsoft.foundry
services in the Azure AI agents extension. Declaring a network: block on a
Foundry-hosted service provisions a network-bound Foundry account/project from
azure.yaml with the data plane private in every mode (account
publicNetworkAccess: Disabled + customer private endpoint).

The config surface is flat and mirrors the natural Azure resource shape — two
orthogonal axes, no mode enum:

• Ingress (required): peSubnet — the account private endpoint. Its presence
  is what makes the data plane private; omitting it while declaring network: is
  an error (never a silent public fallback).
• Egress (optional): agentSubnet — present ⇒ the agent is injected into your
  subnet (BYO egress); absent ⇒ the Microsoft-managed network is used (managed
  egress), where isolationMode becomes valid.

# BYO egress (agent injected into your subnet)
services:
  agent:
    host: azure.ai.agent
    network:
      agentSubnet:
        vnet: ${AZURE_VNET_ID}
        name: agent-subnet
        prefix: 192.168.10.0/24   # omit prefix to reference an existing subnet
      peSubnet:
        vnet: ${AZURE_VNET_ID}
        name: pe-subnet
        prefix: 192.168.11.0/24
      dns:                         # optional; omit to let azd create + link zones
        resourceGroup: rg-private-dns

# Managed egress (no agentSubnet; isolationMode now valid)
services:
  agent:
    host: azure.ai.agent
    network:
      isolationMode: AllowOnlyApprovedOutbound
      peSubnet:
        vnet: ${AZURE_VNET_ID}
        name: pe-subnet
        prefix: 192.168.11.0/24

Changes

• Add the flat network: schema for Foundry-hosted services (agentSubnet,
  peSubnet, dns, isolationMode); the VNet rides on each subnet.
• Synthesize Bicep that is private in every network-bound mode:
  • account publicNetworkAccess: Disabled (disablePublicDataPlaneAccess = enableNetworkIsolation)
  • Foundry private endpoint in peSubnet (+ private DNS zones / VNet links, or
    referenced existing zones via dns:)
  • BYO egress: delegated hosted-agent subnet + account networkInjections
    pointing at that subnet
  • managed egress: useManagedEgress injection + a managedNetworks/default
    child resource carrying isolationMode
• Derive egress from agentSubnet presence (useManagedEgress = agentSubnet == nil);
  replace the networkMode template param with a useManagedEgress bool.
• Validate at synthesis time: peSubnet required when network: is declared;
  isolationMode valid only for managed egress; all subnets share one VNet.
• Preserve ${VAR} placeholders during azd ai agent init --infra eject; resolve
  only at provision time.
• Use a deterministic subnet ARM id string for networkInjections.subnetArmId
  (an inter-module reference() is unresolved at the CognitiveServices RP
  preflight and what-if does not catch it).
• Add docs, schema, unit tests, and a live E2E harness under
  cli/azd/extensions/azure.ai.agents/test/e2e/network/.

Note on the prior approach: an earlier revision re-enabled
publicNetworkAccess in managed mode. That was a security regression — the
service supports a private data plane in managed mode too (a customer private
endpoint with Microsoft-managed egress). Managed mode is now private by
default, consistent with BYO mode.

Test coverage

Three tiers; only the live tier creates resources.

Combination	Live-provisioned	ARM what-if (no creation)	Synthesizer unit test
BYO egress · subnet create · DNS create	✅ (+ deploy/invoke)	✅	✅
Managed egress · create · AllowOnlyApprovedOutbound	✅ (gated RUN_MANAGED_ISO)	✅	✅
Subnet reference (existing subnet)	—	✅ (BYO + managed)	✅
Managed AllowInternetOutbound	—	✅	✅
DNS reference (existing zones)	—	✅	✅
peSubnet omitted while network: declared	—	—	✅ (expected error)
endpoint: brownfield + network:	—	—	✅ (network ignored)

The full 8-cell BYO/managed × create/reference × own/reference × isolation-mode
matrix is exercised by ARM what-if (template compiles and the CognitiveServices
RP accepts the shape, but nothing is created) and by deterministic synthesizer
unit tests. Two representative cells are live-provisioned end to end, and the
real deploy/invoke data path is validated against the BYO cell. Reference-subnet
mode, AllowInternetOutbound, and referenced-DNS are what-if + unit-test only.

E2E validation performed

Scenario 1 — Provision a private-networked Foundry from azure.yaml

• BYO egress (live): account publicNetworkAccess: Disabled,
  networkAcls.defaultAction: Deny; Foundry private endpoint (account group)
  in peSubnet; agent subnet delegated to Microsoft.App/environments; the
  account networkInjections references the customer agent subnet; the three
  privatelink.* DNS zones created and linked.
• Managed egress (live, gated): provisioned AllowOnlyApprovedOutbound into a
  dedicated VNet; verified the managedNetworks/default child resource was
  accepted with isolationMode = AllowOnlyApprovedOutbound (the one thing
  what-if cannot confirm, since the V2 managed network is created, not planned).

Live assertions read real resource state (account properties, private
endpoint, subnet delegation, DNS zones, the account's network injection), not
azd's own output variables.

Scenario 2 — Eject preserves private-networking config

azd ai agent init --infra ejects equivalent Bicep and preserves ${VAR}
placeholders (e.g. ${AZURE_VNET_ID} resolves at provision time, not eject time).
The ejected template what-ifs as no changes against the already-provisioned
account (idempotent).

Scenario 3 — Deploy and invoke a hosted agent over the private data plane

Because the data plane is private in every mode, deploy/invoke must run with
line-of-sight to the private endpoint. The harness captures this automatically
(lib-jumpbox.sh): it stands up a jumpbox VM (inside the foundry VNet, or a
peered VNet in another region when the account region has no VM capacity) and
exposes it as a local SOCKS5 proxy, so azd deploy/invoke run on the dev
host with data-plane HTTPS tunneled into the VNet.

Validated against the live BYO account (publicNetworkAccess: Disabled):

• the Foundry project MI granted Container Registry Repository Reader on an
  ABAC-enabled ACR for the BYO image pull
• azd deploy → hosted agent reached active
• azd ai agent invoke → returned the expected echo response

A direct deploy/invoke from the public internet fails as expected with
403 Public access is disabled.

Documentation

• User cheatsheet:
  cli/azd/extensions/azure.ai.agents/docs/private-networking.md
• E2E harness README:
  cli/azd/extensions/azure.ai.agents/test/e2e/network/README.md

Known limitations

• v1 BYO supports a single VNet shared by agentSubnet and peSubnet; cross-VNet
  topologies are deferred (require customer-managed peering + DNS-zone links).
• One default-DNS account per VNet: a dns-create account links the VNet to the
  three AI privatelink.* zones, and a VNet allows only one link per namespace —
  a second account (or brownfield hub) must use dns: reference mode.