feat(agents): secure-by-default private networking via azure.yaml

[m5i-work]

Summary

Implements the design spec in #8690 (docs(spec): private networking for host: microsoft.foundry).

Adds declarative, secure-by-default private networking for host: azure.ai.agent 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 via delegated hosted-agent subnet + account networkInjections pointing at that subnet, and managed egress via 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).
• Validate that agentSubnet.name and peSubnet.name differ when they share one VNet (a single VNet cannot hold two subnets with the same name).
• Keep private networking Bicep-only: refuse azd ai agent init --infra=terraform for a service that declares network:. The Terraform IaC module (added in feat(agents): support Terraform as an IaC option for azd ai agent #8756) has no VNet / private-endpoint / DNS resources, so ejecting it would silently provision a public account — the guard preserves the secure-by-default invariant. Full Terraform network parity is a fast-follow.
• Document an advanced power-user workflow: eject the Bicep (--infra), edit it directly (e.g. add a subnet the schema can't express, or set an extra account property), then provision/deploy/invoke the edited tree (azd compiles the on-disk Bicep instead of synthesizing).
• Add docs, schema, unit tests, compiled ARM shape assertions, and synthesizer/template changes. The ad-hoc live e2e harness used during validation is intentionally not committed in this PR.

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 manual validation)	✅	✅
BYO egress · subnet reference · DNS reference	✅ (+ deploy/invoke)	✅	✅
Managed subnet reference	—	✅	✅
Managed AllowInternetOutbound	—	✅	✅
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 was exercised by ARM what-if (template compiles and the CognitiveServices RP accepts the shape, but nothing is created) and by deterministic synthesizer unit tests. Three representative cells were live-provisioned: BYO create/DNS-create, managed AllowOnlyApprovedOutbound, and BYO with referenced subnets + referenced DNS zones. The real deploy/invoke data path was validated against both BYO live cells (DNS-create and DNS-reference). Managed subnet-reference mode and AllowInternetOutbound remain 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/manual): 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).
• DNS reference (live, scoped end-to-end): provisioned the BYO/reference/reference cell against pre-existing privatelink.* zones linked to the VNet. Verified the private endpoint DNS-zone group points at the external DNS RG for all three zones and that azd did not create duplicate private DNS zones in the account RG. Then ran azd deploy and azd ai agent invoke through the jumpbox/SOCKS path. Validated run azd-network-e2e-drdbg104254: account cog-bmgby7ooar752, deploy succeeded in 1m45s, invoke returned [netagent] 🔊 Echo: hello, are you up?.

Live assertions read real resource state (account properties, private endpoint, subnet delegation, DNS zones / DNS-zone group, the account's network injection), not azd's own output variables. Deploy/invoke runs prove the private data-plane path is usable for the live BYO DNS-create and BYO DNS-reference cells.

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).

Eject → edit → re-provision → deploy → invoke (live, full power-user path): applied two manual Bicep edits to the ejected tree — an extra subnet not expressible via the network: schema (infra/modules/network.bicep) and an extra account tag (infra/modules/resources.bicep) — re-provisioned the edited template against the live account, and asserted both landed in real resource state (subnet 192.168.30.0/24 present; account tag editedByPowerUser=true). Then azd deploy + azd ai agent invoke succeeded through the jumpbox/SOCKS path against the edited account, proving the manual edit did not break the private data plane. Validated run azd-net-e2e-live-20260623-152842: account cog-fgdp4sboffk2a, invoke returned [netagent] 🔊 Echo: hello, are you up?.

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 manual validation used a jumpbox VM and local SOCKS5 proxy so azd deploy/invoke ran on the dev host with data-plane HTTPS tunneled into the VNet.

Validated against private BYO accounts (publicNetworkAccess: Disabled): the Foundry project MI was granted Container Registry Repository Reader on an ABAC-enabled ACR for the BYO image pull, azd deploy reached hosted-agent active, and 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

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.
• Terraform IaC does not support private networking yet: azd ai agent init --infra=terraform is refused when a service declares network:. Use Bicep (--infra) — and customize via the eject workflow if needed. Full Terraform parity is a fast-follow.