1---
2name: private-network
3description: "Answer questions about and deploy Microsoft Foundry with network isolation. Covers BYO VNet, Managed VNet, hybrid patterns, private endpoints, and Bicep deployment. WHEN: 'Foundry networking', 'BYO VNet vs managed VNet', 'deploy Foundry in private VNet', 'private endpoints for Foundry'. DO NOT USE FOR: generic Azure networking without Foundry."
4license: MIT
5allowed-tools: Read, Write, Bash, AskUserQuestion, microsoft_docs_search, microsoft_docs_fetch
6---
7 
8# Microsoft Foundry Private Networking
9 
10## Quick Reference
11 
12| Property | Value |
13|----------|-------|
14| **Best for** | Foundry with VNet isolation, private endpoints, subnet delegation, APIM + Foundry, VPN/Bastion access |
15| **Tools** | Azure CLI |
16| **MCP Tools** | `AskUserQuestion` - ask user questions; `microsoft_docs_search` - verify facts before presenting; `microsoft_docs_fetch` - fetch full Learn pages for validation |
17| **Workflow** | Ground in Learn → Gather → Plan → Scaffold → Validate → Deploy → Test |
18 
19### Key Documentation
20 
21| Topic | URL |
22|-------|-----|
23| Network isolation | https://learn.microsoft.com/azure/ai-foundry/how-to/configure-private-link |
24| Agent Service VNet | https://learn.microsoft.com/azure/ai-services/agents/how-to/virtual-networks |
25| Managed VNet | https://learn.microsoft.com/azure/ai-foundry/how-to/configure-managed-network |
26| Feature limitations | https://learn.microsoft.com/azure/foundry/how-to/configure-private-link#foundry-feature-limitations |
27 
28## When to Use
29 
30- User asks about Foundry networking, private endpoints, or VNet isolation
31- User asks about BYO VNet, Managed VNet, or hybrid patterns
32- User wants to deploy Foundry agents in a private network
33- User needs APIM integration with private Foundry agents
34 
35**Do NOT use for:**
36- Public Foundry setup without VNet → use [project/create](../../project/create/create-foundry-project.md)
37- Bare Foundry resource without networking → use [resource/create](../create/create-foundry-resource.md)
38 
39---
40 
41## Step 0 — Ground in Microsoft Learn
42Use `microsoft_docs_fetch` to get docs from Key Documentation sources.
43Use `microsoft_docs_search` to verify any technical fact before presenting it to the user. If Learn contradicts a reference file, **Learn wins**. Cite the URL. If Learn doesn't cover it, say so — do not invent facts, limits, flags, or compatibility claims.
44 
45---
46 
47## End-to-End Deployment Workflow
48 
49> **Important:** All following steps are mandatory. Communicate the plan with the user before acting.
50 
51## Step 1 — Gather Requirements
52 
53Read [references/intake.md](references/intake.md). One pass, three tiers:
54- **Tier 1 (Core):** Subscription, VNet model, agents, region, RG, VNet — determine approach at the end
55- **Tier 2 (Architecture):** DNS, topology, NSG, on-prem, identity, BYO resources
56- **Tier 3 (Enterprise):** Model, client access, auth, policies, monitoring
57 
58Determine the approach (official template / adapt closest / extend user’s IaC) at the end of Tier 1. Continue through Tiers 2–3.
59 
60---
61 
62## Step 2 — Plan Generation
63 
64Use the confirmed requirements from [references/intake.md](references/intake.md).
65 
66**OFFICIAL path:** Load the template's README from its GitHub URL (via [references/template-index.md](references/template-index.md)). Run `microsoft_docs_search` for its prerequisites. Present a deployment plan using the user's actual values.
67 
68**ADAPT path:** Load the closest template's README. Present a deployment plan highlighting what will be modified from the base template.
69 
70**EXTEND path:** Load [references/custom-template-adaptation.md](references/custom-template-adaptation.md). Read the user's existing template. Follow the gap analysis framework to present what's covered, what's missing, and any issues. Get approval before modifying.
71 
72Get confirmation before proceeding.
73 
74---
75 
76## Step 3 — Scaffold & Parameterize
77 
78Read [references/scaffold.md](references/scaffold.md).
79 
80---
81 
82## Step 4 — Pre-Deployment Validation
83 
84Catch blockers **before** deploying. These checks apply to all paths.
85 
86**Sovereign cloud:** Run `az cloud show --query name -o tsv`. If `AzureUSGovernment` or `AzureChinaCloud`, check whether the templates being used (official or user-provided) handle sovereign cloud endpoints. Official templates hardcode `core.windows.net` and Azure Public AAD endpoints.
87 
88**RBAC:** Verify deploying identity has Owner, or Contributor + User Access Administrator.
89 
90**Policy:** Run `az deployment group what-if`. Fix any violations before deploying.
91 
92**Quota:**
93 
94```bash
95az cognitiveservices account list-skus --location <region> --kind AIServices -o table
96```
97 
98**Provider Registrations:** `Microsoft.CognitiveServices`, `Microsoft.DocumentDB`, `Microsoft.Search`, `Microsoft.Network`.
99 
100**Feature Flags:** For Managed VNet — verify `AI.ManagedVnetPreview` is registered.
101 
102> Do NOT deploy until all pre-flight checks pass.
103 
104---
105 
106## Step 5 — Deploy & Track
107 
108**OFFICIAL / ADAPT path:** Read [references/deploy.md](references/deploy.md) for deployment command, monitoring, and error recovery.
109 
110**EXTEND path:** Deploy using the user's existing deployment workflow (their CLI commands, pipeline, or CI/CD). The monitoring and error recovery guidance in [references/deploy.md](references/deploy.md) still applies.
111 
112---
113 
114## Step 6 — Test & Validate
115 
116Read [references/post-deployment-validation.md](references/post-deployment-validation.md). These checks apply to all paths — PE verification, RBAC audit, `publicNetworkAccess` audit, and end-to-end agent test work regardless of how the infrastructure was deployed.
117 
118If any test fails, run `microsoft_docs_search` for the error before attempting remediation.
119 
120---
121 
122## Error Handling
123 
124> ⚠️ **Critical retry rule:** If a deployment fails after the capability host step starts, the agent subnet gets a `legionservicelink` that cannot be removed. On retry, always use a **new VNet name** — never reuse the same agent subnet. See [references/deploy.md](references/deploy.md).
125 
126For all other errors, check `microsoft_docs_search` for current remediation before acting.
127