Merge branch 'MicrosoftDocs:main' into main

Author: gmndrg

articles/ai-foundry/agents/faq.yml

@@ -8,9 +8,10 @@ metadata:
   ms.service: azure-ai-foundry
   ms.subservice: azure-ai-foundry-agent-service
   ms.topic: faq
-  ms.date: 10/09/2025
+  ms.date: 10/20/2025
   ms.author: aahi
   author: aahill
+  ms.custom: references_regions
 title: Azure AI Foundry Agent Service frequently asked questions
 summary: |
   If you can't find answers to your questions in this document, and still need help check the [Azure AI services support options guide](../../ai-services/cognitive-services-support-options.md). Azure AI Foundry Agent Service is part of Azure AI services.
@@ -39,7 +40,7 @@ sections:
       - question: |
           Is my data used by Microsoft for training models? 
         answer: |
-          No. Data is not used by Microsoft for training models. See the [Responsible AI documentation](/azure/ai-foundry/responsible-ai/openai/data-privacy) for more information.
+          No. Data isn't used by Microsoft for training models. See the [Responsible AI documentation](/azure/ai-foundry/responsible-ai/openai/data-privacy) for more information.
       - question: |
           Where is data stored geographically?
         answer: |
@@ -55,4 +56,56 @@ sections:
       - question: |
           Is there any additional pricing or quota for using Foundry Agent Service? 
         answer: |
-          No. All [quotas](quotas-limits.md) apply to using models with Foundry Agent Service.
+          No. All [quotas](quotas-limits.md) apply to using models with Foundry Agent Service.
+  - name: Virtual networking
+    questions:
+      - question: |
+          What does 'bring your own virtual network' mean? 
+        answer: |
+          Virtual networks secure the inbound and outbound access of your Azure resources, preventing bad actors from accessing your resources. Network isolation is achieved through virtual network integrations in Azure. This is a fundamental requirement for security in enterprises. To learn more about virtual network isolation, see [Virtual network integration of Azure services for network isolation](/azure/virtual-network/vnet-integration-for-azure-services) and [What is Azure Virtual Network?](/azure/virtual-network/virtual-networks-overview)
+      - question: |
+          Why is subnet delegation needed? 
+        answer: |
+          Both the Agent client and compute run on Azure Container Apps (ACA). When you run the Agent client and the associated compute on Azure Container Apps (ACA) inside an existing virtual network, you must supply a dedicated subnet delegated to `Microsoft.App/environments`.
+          1. Delegation pins them to the right subnet. It tells Azure exactly where to “inject” the Agent client so ACA can create network interfaces there.   
+          2. ACA then applies the needed plumbing - IP addresses, routing, NSGs, and service-managed identity wiring, is configured automatically.   
+          3. Without the delegation, ACA refuses to deploy, so neither the Agent client nor the compute layer could join your Virtual Network, breaking isolation, and compliance requirements.   
+          In short, delegating the subnet is the prerequisite that lets ACA, and therefore your Agent runtime, live inside your private network with the correct security and routing policies in place and in your control. 
+      - question: |
+          What regions are supported for class A? 
+        answer: | 
+          Supported regions: West US, East US, East US 2, Japan East, France Central, UAE North, South Central US, Italy North, Germany West Central, Brazil South, South Africa North, Australia East, Sweden Central, Canada East, West Europe, Spain Central, UK South 
+      - question: |
+          What class range is supported for public or private Class A, B, C subnets? 
+        answer: |
+          Only private class A, B, and C ranges are supported. No public class ranges are supported.  
+      - question: |
+          What is the minimum size for the agent subnet and how many IPs should be used?
+        answer: |
+          The recommended subnet size is /24 (256 address) and is what we default to in our templates. The minimum subnet size is /27 (32 addresses). The reason why /24 is recommended is because of the runtime impact in the event of a container update, listed in the ACA documentation. For more information, see [Configuring virtual networks Azure Container Apps environments](/azure/container-apps/custom-virtual-networks?tabs=workload-profiles-env#subnet). 
+
+          We set an IP range per Azure AI Foundry account. Each project gets an IP from the range. There isn't IP address set per Agent, but per project. This means there's no limit to the number of agents to create within your project. The user isn't limited by the minimum address space of the subnet to create any number of agents. 
+      - question: |
+          What is the minimum and recommended virtual network address range for the Agent service? 
+        answer: |
+          As long as there's address space for Agent subnet and private endpoints, then virtual network address range can be anything. 
+      - question: |
+          Can I use peered Virtual Networks? Can I have resources in different virtual networks?  
+        answer: |
+          Yes this is feasibly possible since the virtual network is in your subscription, and you  should be able to peer with any virtual network. But data transfer is quite costly so it isn't recommended to do this. The requirement is all resources must be in the same region as the Foundry resource.  
+      - question: |
+          Do I need to allowlist any FQDNs if I'm using an Azure firewall? 
+        answer: |
+          Yes, allowlist the Fully Qualified Domain Names (FQDNs) listed **Managed Identity in the [Use Azure Firewall with Azure Container Apps](/azure/container-apps/use-azure-firewall) article or add the service tag `AzureActiveDirectory`. Verify no TLS inspection happens in the firewall that could be adding a self-signed certificate. During failures, inspect if there's any traffic landing on the firewall and what traffic is being blocked by the firewall.  
+      - question: 
+          Can the virtual network be reused by multiple Azure AI Foundry resources? 
+        answer: |
+          Yes, a virtual network can be reused by multiple Foundry resources, but the Agent runtime subnet is per Foundry account.
+      - question: |
+          Does the virtual network need to be in the same resource group as Foundry?
+        answer: |
+          No, the same resource group isn't needed, but the same region is required.
+      - question: |
+          What additional configuration is needed if I want to add tools to my agents? 
+        answer: |
+          The template provides support for the built-in tools: Code Interpreter, File Search, Azure AI Search, Cosmos DB (all tools that use the Bring-Your-Own (BYO) resource connections). To configure tools that require the creation of a new connection, you must create a private endpoint from your `peSubnet`` and create a private link from the Azure Resource. 

articles/ai-foundry/agents/how-to/virtual-networks.md

@@ -7,7 +7,7 @@ manager: nitinme
 ms.service: azure-ai-foundry
 ms.subservice: azure-ai-foundry-agent-service
 ms.topic: how-to
-ms.date: 08/01/2025
+ms.date: 10/21/2025
 author: aahill
 ms.author: aahi
 ms.reviewer: fosteramanda
@@ -18,6 +18,9 @@ ms.custom: azure-ai-agents
 
 Azure AI Foundry Agent Service offers **Standard Setup with private networking** environment setup, allowing you to bring your own (BYO) private virtual network. This setup creates an isolated network environment that lets you securely access data and perform actions while maintaining full control over your network infrastructure. This guide provides a step-by-step walkthrough of the setup process and outlines all necessary requirements.
 
+> [!TIP]
+> See the [FAQ article](../faq.yml#virtual-networking) for common questions when working with Virtual Networks.
+
 ## Security features
 
 By default, the Standard Setup with Private Network Isolation ensures:
@@ -34,7 +37,7 @@ For customers without an existing virtual network, the Standard Setup with Priva
 :::image type="content" source="../media\private-network-isolation.png" alt-text="A diagram showing virtual network architecture.":::
 ### Known limitations
 
-- **Subnet IP address limitation**: both subnets must have IP ranges under `172.16.0.0/12` or `192.168.0.0/16`, i.e. class B or C private address ranges reserved for private networking. Public Class A, B or C address ranges are not supported. Private Class A address ranges have limited region support. For more information, see [our Private Network Secured Agent deployment template on GitHub](https://github.com/azure-ai-foundry/foundry-samples/blob/main/samples/microsoft/infrastructure-setup/15-private-network-standard-agent-setup/README.md).
+- **Subnet IP address limitation**: both subnets must have IP ranges under `172.16.0.0/12` or `192.168.0.0/16`, which are class B or C private address ranges reserved for private networking. Public Class A, B or C address ranges are not supported. Private Class A address ranges have limited region support. For more information, see [our Private Network Secured Agent deployment template on GitHub](https://github.com/azure-ai-foundry/foundry-samples/blob/main/samples/microsoft/infrastructure-setup/15-private-network-standard-agent-setup/README.md).
 - **Agent subnet exclusivity**: The agent subnet cannot be shared by multiple Azure AI Foundry resources. Each AI Foundry must use a dedicated agent subnet.
 - **Agent subnet size**: The recommended size of the delegated Agent subnet is /24 (256 addresses) due to the delegation of the subnet to `Microsoft.App/environment`. For more on the subnet sizing, see [Configuring virtual networks for Azure Container Apps](/azure/container-apps/custom-virtual-networks?tabs=workload-profiles-env#subnet).
 - **Agent subnet egress firewall allowlisting**: If you are integrating an Azure Firewall with your private network secured standard agent, please allowlist the Fully Qualified Domain Names (FQDNs) listed under __Managed Identity__ in the [Integrate with Azure Firewall](/azure/container-apps/use-azure-firewall#application-rules) article or add the Service Tag __AzureActiveDirectory__.
@@ -83,15 +86,15 @@ For customers without an existing virtual network, the Standard Setup with Priva
 ## Configure a new network-secured environment 
 
 > [!NOTE]
-> - Programmatic deployment is required to setup a network-secured environment for Azure AI Foundry Agent Service. Deployment through the Azure portal is currently not supported.
+> - Programmatic deployment is required to set up a network-secured environment for Azure AI Foundry Agent Service. Deployment through the Azure portal is currently not supported.
 > - If you want to delete your Foundry resource and Standard Agent with secured network set-up, delete your AI Foundry resource and virtual network last. Before deleting the virtual network, ensure to delete and [purge](../../../ai-services/recover-purge-resources.md#purge-a-deleted-resource) your AI Foundry resource.
 > - In the Standard Setup, agents use customer-owned, single-tenant resources. You have full control and visibility over these resources, but you incur costs based on your usage.
 
 You can deploy and customize the Standard Setup with Private Networking using either Bicep or Terraform. The provided samples allow you to bring your own virtual network and customize the deployment to meet your specific requirements:
 
 * Foundry account and Foundry project are created.
 * A gpt-4o model is deployed.
-* Azure resources for storing customer data — Azure Storage, Azure Cosmos DB, and Azure AI Search — are automatically created if existing resources are not provided. 
+* Azure resources for storing customer data: Azure Storage, Azure Cosmos DB, and Azure AI Search are automatically created if existing resources are not provided. 
 * These resources are connected to your project to store files, threads, and vector data.
 * Microsoft-managed encryption keys for Storage Account and Cognitive Account (AI Foundry) are used by default.
  
@@ -123,7 +126,7 @@ The following DNS zones are configured:
 Virtual networks enable you to specify which endpoints can make API calls to your resources. The Azure service automatically rejects API calls from devices outside your defined network. You can establish allowed networks using either formula-based definitions or by creating an exhaustive list of permitted endpoints. This security layer can be combined with other security measures for enhanced protection.
 
 > [!NOTE]
-> If you bring your existing virtual network and subnet with the *Microsoft.App/environments* delegation, the minimize size of your subnet should be /27 (32 addresses). We recommend a subnet size of /24 (256 addresses), which is the default subnet size set in the network secured template. 
+> If you bring your existing virtual network and subnet with the *Microsoft.App/environments* delegation, the minimized size of your subnet should be /27 (32 addresses). We recommend a subnet size of /24 (256 addresses), which is the default subnet size set in the network secured template. 
 
 ### Network rules
 
@@ -173,8 +176,52 @@ Once your template deployment is complete, you can access your Foundry project b
 
 This setup enables AI agents to operate entirely within a dedicated, isolated virtual network. By leveraging private network isolation (BYO VNet), organizations can enforce custom security policies, ensuring that AI agents operate within their trusted infrastructure.    
 
-Our goal is to accelerate the development and deployment of AI agents without compromising critical security requirements. With our bicep and ARM templates, you can quickly setup your agent environment while still maintaining full control over their networking and data.   
+Our goal is to accelerate the development and deployment of AI agents without compromising critical security requirements. With our bicep and ARM templates, you can quickly set up your agent environment while still maintaining full control over their networking and data.   
+
+## Troubleshooting guide 
+
+Refer to this guide to resolve errors regarding the standard secured agent template deployment errors or errors post template deployment in the Azure AI Foundry portal.  
+
+### Template deployment errors 
+
+`"CreateCapabilityHostRequestDto is invalid: Agents CapabilityHost supports a single, non empty value for vectorStoreConnections property."` 
+
+`"Agents CapabilityHost supports a single, non empty value for storageConnections property."`
+
+`"Agents CapabilityHost supports a single, non empty value for threadStorageConnections property."`
+
+**Solution**: Providing all connections to all Bring-your-Own (BYO) resources, requires connections to all BYO resources. You cannot create a secured standard agent in Foundry without all three resources provided. 
+
+`"Provided subnet must be of the proper address space. Please provide a subnet which has address space in the range of 172 or 192."` 
+
+**Solution**: You are not using a proper IP range for your delegated agent subnet. Please verify you are using a valid Private IP address spaces.  
+
+`"Subscripton is not registered with the required resource providers, please register with the resource providers Microsoft.App and Microsoft.ContainerService."` 
+
+**Solution**: You are missing the correct resource registration. Ensure the required resources are registered in your tenant. 
+
+```azurecli
+az provider register --namespace 'Microsoft.KeyVault' 
+az provider register --namespace 'Microsoft.CognitiveServices' 
+az provider register --namespace 'Microsoft.Storage' 
+az provider register --namespace 'Microsoft.MachineLearningServices' 
+az provider register --namespace 'Microsoft.Search' 
+az provider register --namespace 'Microsoft.Network' 
+az provider register --namespace 'Microsoft.App' 
+az provider register --namespace 'Microsoft.ContainerService' 
+```
+ 
+
+`"Failed to create Aml RP virtual workspace due to System.Exception: Failed async operation."` or `"The resource operation completed with terminal provisioning state 'Failed'. Capability host operation failed."` 
+
+**Solution**: This is a catch all error we provide. Create a support ticket request to investigate your set-up. Check the capability host for the error. 
+
+ 
+
+`"Subnet requires any of the following delegation(s) [Microsoft.App/environments] to reference service association link /subscriptions/11111-aaaaa-2222-bbbb-333333333/resourceGroups/agentRANGEChange/providers/Microsoft.Network/virtualNetworks/my-agent-vnet/subnets/agent-subnet/serviceAssociationLinks/legionservicelink."` 
+
+**Solution**: This error appears when you try to delete your secured standard template set-up in Azure and did not correctly delete all resources. One solution is to navigate to your AI Foundry resource page in the Azure portal and select **Manage deleted resources**. From there, purge the resource that the agent was associated with for this virtual network. The other option is to run the `deleteCaphost.sh` script in the secured standard template. 
 
+## Next steps
 
-## What's next?
-You’ve now successfully configured a Network Secure Account and project, use the [quickstart](../quickstart.md) to create your first agent. 
+You've now successfully configured a network-secure account and project, use the [quickstart](../quickstart.md) to create your first agent. 

articles/ai-foundry/openai/azure-government.md

@@ -66,7 +66,7 @@ In some cases, models are retired in Azure Governmen ahead of dates in the comme
 
 <br>
 
-### Deafault Model Versions 
+### Default Model Versions 
 In some cases, new model versions are designated as default in Azure Governmen ahead of dates in the commercial cloud. General information on model upgrades can be found at [Working with Azure OpenAI models](/azure/ai-foundry/openai/how-to/working-with-models?tabs=powershell&branch=main#model-deployment-upgrade-configuration)
 
 The following shows default model differences in Azure Government. 

articles/ai-foundry/openai/concepts/prompt-engineering.md

@@ -28,7 +28,7 @@ Text prompts are how users interact with GPT models. As with all generative lang
 | Prompt                             |Completion |
 |------------------------------------|-----------|
 | Four score and seven years ago our | fathers brought forth on this continent, a new nation, conceived in Liberty, and dedicated to the proposition that all men are created equal. […]|
-| "Call me Ishmael."                 | "Some years ago—never mind how long precisely—having little o no money in my purse, and nothing particular to interest me on shore, I thought I would sail about a little and see the watery part of the world." […]|
+| "Call me Ishmael."                 | "Some years ago—never mind how long precisely—having little or no money in my purse, and nothing particular to interest me on shore, I thought I would sail about a little and see the watery part of the world." […]|
 
 As you develop more complex prompts, it's helpful to keep this fundamental behavior in mind. Regardless of the prompt that is provided, the model is simply responding with what it determines is most likely (given its training data and training targets). If you ask a question in your prompt, the model isn't following a separate “Q&A” code path, but rather it appears to answer the question because an answer is the most likely sort of response for the given question as input.