Merge pull request #5123 from MicrosoftDocs/main

5/21/2025 PM Publish

Author: Taojunshen

articles/ai-foundry/concepts/concept-model-distillation.md

@@ -5,7 +5,7 @@ description: Learn how to do distillation in Azure AI Foundry portal.
 manager: scottpolly
 ms.service: azure-ai-foundry
 ms.topic: how-to
-ms.date: 03/09/2025
+ms.date: 05/20/2025
 ms.reviewer: vkann
 reviewer: anshirga
 ms.author: ssalgado

articles/ai-foundry/concepts/concept-synthetic-data.md

@@ -5,7 +5,7 @@ description: Learn how to generate a synthetic dataset in Azure AI Foundry porta
 manager: scottpolly
 ms.service: azure-ai-foundry
 ms.topic: how-to
-ms.date: 03/11/2025
+ms.date: 05/20/2025
 ms.reviewer: vkann
 reviewer: anshirga
 ms.author: ssalgado

articles/ai-foundry/how-to/configure-managed-network.md

@@ -855,8 +855,33 @@ When you create a private endpoint for hub dependency resources, such as Azure S
 
 A private endpoint is automatically created for a connection if the target resource is an Azure resource listed previously. A valid target ID is expected for the private endpoint. A valid target ID for the connection can be the Azure Resource Manager ID of a parent resource. The target ID is also expected in the target of the connection or in `metadata.resourceid`. For more on connections, see [How to add a new connection in Azure AI Foundry portal](connections-add.md).
 
-> [!IMPORTANT]
-> As of April 30th 2025, the Azure AI Enterprise Network Connection Approver role must be assigned to the Azure AI Foundry hub's managed identity to approve private endpoints to securely access your Azure resources from the managed virtual network. This doesn't impact existing resources with approved private endpoints as the role is correctly assigned by the service. For new resources, ensure the role is assigned to the hub's managed identity. For Azure Data Factory, Azure Databricks, and Azure Function Apps, the Contributor role should instead be assigned to your hub's managed identity. This role assignment is applicable to both User-assigned identity and System-assigned identity workspaces. 
+### Approval of Private Endpoints
+
+To establish Private Endpoint connections in managed virtual networks using Azure AI Foundry, the workspace managed identity, whether system-assigned or user-assigned, must have permissions to approve the Private Endpoint connections on the target resources. Previously, this was done through automatic role assignments by the Azure AI Foundry service. However, there are security concerns about the automatic role assignment. To improve security, starting April 30th, 2025, we will discontinue this automatic permission grant logic. We recommend assigning the [Azure AI Enterprise Network Connection Approver role](/azure/role-based-access-control/built-in-roles/ai-machine-learning) or a custom role with the necessary Private Endpoint connection permissions on the target resource types and grant this role to the Azure Machine Learning workspace's managed identity to allow Azure AI Foundry services to approve Private Endpoint connections to the target Azure resources.
+
+Here's the list of private endpoint target resource types covered by covered by the Azure AI Enterprise Network Connection Approver role:
+
+* Azure Application Gateway
+* Azure Monitor
+* Azure AI Search
+* Event Hubs
+* Azure SQL Database
+* Azure Storage
+* Azure Machine Learning workspace
+* Azure Machine Learning registry
+* Azure AI Foundry
+* Azure Key Vault
+* Azure CosmosDB
+* Azure Database for MySQL
+* Azure Database for PostgreSQL
+* Azure AI Services
+* Azure Cache for Redis
+* Container Registry
+* API Management
+
+For creating Private Endpoint outbound rules to target resource types not covered by the Azure AI Enterprise Network Connection Approver role, such as Azure Data Factory, Azure Databricks, and Azure Function Apps, a custom scoped-down role is recommended, defined only by the actions necessary to approve private endpoint connections on the target resource types.
+
+For creating Private Endpoint outbound rules to default workspace resources, the required permissions are automatically covered by the role assignments granted during workspace creation, so no additional action is needed.
 
 ## Select an Azure Firewall version for allowed only approved outbound
 

articles/ai-foundry/how-to/create-projects.md

@@ -9,7 +9,7 @@ ms.custom:
   - build-2024
   - ignite-2024
 ms.topic: how-to
-ms.date: 04/11/2025
+ms.date: 05/20/2025
 ms.reviewer: deeikele
 ms.author: sgilley
 author: sdgilley
@@ -19,7 +19,7 @@ zone_pivot_groups: project-type
 
 # Create a project for Azure AI Foundry
 
-This article describes how to create an [Azure AI Foundry](https://ai.azure.com) project. Projects are folders that let you organize your work for exploring new ideas, and as you're prototyping on a particular use cases.
+This article describes how to create an [Azure AI Foundry](https://ai.azure.com) project. Projects let you organize your work for exploring new ideas and as you prototype on a particular use cases.
 
 Azure AI Foundry supports two types of projects: a **[!INCLUDE [fdp](../includes/fdp-project-name.md)]** and a **[!INCLUDE [hub](../includes/hub-project-name.md)]**. For more information about the differences between these two project types, see [Types of projects](../what-is-azure-ai-foundry.md#project-types).
 
@@ -70,7 +70,7 @@ Use the following tabs to select the method you plan to use to create a [!INCLUD
 
 ---
 
-## Create a project
+## Create a [!INCLUDE [hub-project-name](../includes/hub-project-name.md)]
 
 # [Azure AI Foundry portal](#tab/ai-foundry)
 
@@ -129,7 +129,7 @@ On the project **Overview** page, you can find information about the project.
 
 :::image type="content" source="../media/how-to/projects/project-settings.png" alt-text="Screenshot of an Azure AI Foundry project settings page." lightbox = "../media/how-to/projects/project-settings.png":::
 
-- Name: The name of the project appears in the top left corner. You can rename the project using the edit tool.
+- Name: The name of the project appears in the top left corner.
 - Subscription: The subscription that hosts the hub that hosts the project.
 - Resource group: The resource group that hosts the hub that hosts the project.
 

articles/ai-foundry/includes/create-project-fdp.md

@@ -18,7 +18,7 @@ ms.custom: include
 * This project type gives you the best support for:
 
     * Agents
-    * AI Model Inference including Azure Open AI	
+    * AI Model Inference including Azure OpenAI	
     * AI Foundry API that works with agents and across models	
     * Project files (directly upload files and start experimenting)
     * Evaluations
@@ -51,21 +51,29 @@ Use the following tabs to select the method you plan to use to create a [!INCLUD
 
 ---
 
-## Create a project
+## Create a [!INCLUDE [fdp-project-name](fdp-project-name.md)]
 
 # [Azure AI Foundry portal](#tab/ai-foundry)
 
 To create a [!INCLUDE [fdp-project-name](fdp-project-name.md)] in [Azure AI Foundry](https://ai.azure.com), follow these steps:
 
-1. Go to [Azure AI Foundry](https://ai.azure.com). If you are in a project, select **Azure AI Foundry** at the top left of the page to go to the **Home** page.
-1. In the middle of the page, select **Start building**. This creates a project and also include steps to start working with a basic agent.
-1. Or select **+ Create project** in the top right corner of the page if you have existing projects. This creates the project alone, without extra steps to start working with an agent.
-1. Enter a name for the project.
-1. Select **Create**. Or, if you want to customize your settings, follow the steps in the next section.
+1. Go to [Azure AI Foundry](https://ai.azure.com).
+
+2. What you do next depends on where you are:
+
+    * **If you don't have any existing projects**: Follow the steps in [Quickstart: Get started with Azure AI Foundry](../quickstarts/get-started-code.md) to create your first project.
+
+    * **If you're in a project**: Select the project breadcrumb, then select **Create new resource**.
+    
+        :::image type="content" source="../media/how-to/projects/create-new-resource.png" alt-text="Screenshot shows creating a new project from a breadcrumb.":::
+    
+    * **If you're not in a project**: Select **Create new** in the top right to create a new [!INCLUDE [fdp-project-name-plural](fdp-project-name.md)]
+    
+        :::image type="content" source="../media/how-to/projects/create-new.png" alt-text="Screenshot shows how to create a new project in Azure AI Foundry.":::
 
 ### Advanced options
 
-A [!INCLUDE [fdp-project-name](fdp-project-name.md)] is created on an `AIServices` resource. This resource is created for you automatically when you create the project. 
+A [!INCLUDE [fdp-project-name](fdp-project-name.md)] is created on an `AI Foundry` resource. This resource is created for you automatically when you create the project. 
 
 To customize the settings for your project, follow these steps:
 
@@ -166,9 +174,9 @@ To create a [!INCLUDE [fdp](../includes/fdp-project-name.md)]:
     [!INCLUDE [cli-create-project](cli-create-project.md)]
  -->
 
----
+CLI commands not currently available for creating a [!INCLUDE [fdp-project-name](fdp-project-name.md)].
 
-CLI comannds not currently available for creating a [!INCLUDE [fdp-project-name](fdp-project-name.md)].
+---
 
 ## Create multiple projects on the same resource
 
@@ -180,7 +188,7 @@ CLI comannds not currently available for creating a [!INCLUDE [fdp-project-name]
 
 On the project **Home** page, you can find information about the project.
 
-- Name: The name of the project appears in the top left corner. You can rename the project using the edit tool.
+- Name: The name of the project appears in the top left corner. 
 - Subscription: The subscription that hosts the hub that hosts the project.
 - Resource group: The resource group that hosts the hub that hosts the project.
 

articles/ai-foundry/includes/create-second-fdp-project.md

@@ -11,7 +11,7 @@ ms.custom: include, build-2024, ignite-2024
 ---
 
 
-Create multiple [!INCLUDE [fdp-project-name-plural](fdp-project-name-plural.md)] on an existing `AI Services` resource, so you can share your environment with your team for collaboration. 
+Create multiple [!INCLUDE [fdp-project-name-plural](fdp-project-name-plural.md)] on an existing `AI Foundry` resource, so you can share your environment with your team for collaboration. 
 
 [!INCLUDE [fdp-project-name-plural](fdp-project-name-plural.md)] as Azure child resources may get assigned their own access controls, but share common settings such as network security, deployments, and Azure tool integration from their parent resource.
 
@@ -72,7 +72,7 @@ Your first project (default project) plays a special role and has access to more
      az cognitiveservices account project create --resource-group {my_resource_group} --name {my_project_name} --account-name {foundry_resource_name} 
     ```
      -->
-    CLI comannds not currently available for creating a [!INCLUDE [fdp-project-name](fdp-project-name.md)].
+    CLI commands not currently available for creating a [!INCLUDE [fdp-project-name](fdp-project-name.md)].
 
     ---
 

articles/ai-foundry/includes/get-started-fdp.md

@@ -30,24 +30,20 @@ The Azure AI Foundry SDK is available in multiple languages, including Python, J
 
 [!INCLUDE [feature-preview](feature-preview.md)]
 
-## Create a [!INCLUDE [fdp-project-name](fdp-project-name.md)] 
+## Start with a project and model
 
 1. Sign in to the [Azure AI Foundry portal](https://ai.azure.com).
-1. On the home page, select **Create an agent**. This creates a project and also include steps to start working with a basic Agent.
+1. On the home page, select **Create an agent**. 
 
-    <!-- :::image type="content" source="../media/quickstarts/start-building.png" alt-text="Screenshot shows how to start building an Agent in Azure AI Foundry portal."::: -->
+    :::image type="content" source="../media/quickstarts/start-building.png" alt-text="Screenshot shows how to start building an Agent in Azure AI Foundry portal.":::
 
-1. Fill in a name for your project and select **Create**. 
-
-## Deploy a model
-
-[!INCLUDE [tip-left-pane](../includes/tip-left-pane.md)]
-
-1. If you just used the Azure AI Foundry portal to create the project with the **Create an agent** link, you'll already have a default **gpt-4o** model deployed.
-1. Or else, sign in to the [Azure AI Foundry portal](https://ai.azure.com), select your project, and select **Model catalog**.
-1. Search for the model you want to deploy. For this quickstart, select **gpt-4o**.
-1. Select **Confirm**.
-1. Don't change the default settings. Select **Deploy**.
+1. Fill in a name to use for your project and select **Create**. 
+1. Once your resources are created, you are in the agent playground. 
+1. If you're asked to select a model, search for and select **gpt-4o**. 
+    1. Select **Confirm**.
+    1. Don't change the default settings. Select **Deploy**.
+    
+You now have both a project and a model available for your agent.
 
 ### Set up your environment  
 
@@ -130,59 +126,17 @@ No installation is necessary to use the Azure AI Foundry portal.
 
 ---
 
-## Run a chat completion
-
-Chat completions are the basic building block of AI applications. Using chat completions you can send a list of messages and get a response.
-
-# [Azure AI Foundry portal](#tab/azure-ai-foundry)
-
-1. If you used **Create an agent** to create the project, you'll now find yourself in the Agents playground, ready to try it out. You'll come back here in a moment, but first let's play with the model.
-1. In the left pane, select **Playgrounds**. 
-1. Select **Try the chat playground**.
-1. Fill in the prompt and select the **Send** button.
-1. The model returns a response in the **Response** pane.
-
-# [Python](#tab/python)
-
-Substitute your value for the endpoint in this code:
-
-:::code language="python" source="~/foundry-samples-main/samples/microsoft/python/mslearn-resources/quickstart/quickstart.py" id="chat_completion":::
-
 
-# [Java (preview)](#tab/java)
-
-:::code language="java" source="~/foundry-samples-main/samples/microsoft/java/mslearn-resources/quickstart/src/main/java/com/azure/ai/foundry/samples/ChatCompletionSample.java" :::
-
-# [JavaScript (preview)](#tab/javascript)
-
-:::code language="javascript" source="~/foundry-samples-main/samples/microsoft/javascript/mslearn-resources/quickstart/src/quickstart.js" id="chat_completion":::
-
-
-# [C#](#tab/csharp)
-
-:::code language="csharp" source="~/foundry-samples-main/samples/microsoft/csharp/mslearn-resources/quickstart/Samples/SimpleInference.cs" id="chat_completion":::
-
-# [REST API](#tab/rest)
-
-Replace `YOUR-FOUNDRY-RESOURCE-NAME` with your values:
-
-:::code language="console" source="~/foundry-samples-main/samples/microsoft/REST/mslearn-resources/quickstart/quickstart.sh" id="chat_completion":::
-
----
+## Chat with an agent
 
-## Create and run an agent
-
-Agents allow more powerful capabilities through the use of tools. First, let's write the same chat completion code using agents.
+Agents have powerful capabilities through the use of tools. Start by chatting with an agent.
  
 # [Azure AI Foundry portal](#tab/azure-ai-foundry)
 
-1. In your project, on the left pane, select **Agents**.
-1. Select the agent created with the project. 
-1. If you didn't create one with your project, select **New agent** to create an agent now.
-1. On the right **Setup** pane, change the name if you'd like.
+After the preceding steps, you're now in the agents playground. 
+
 1. Add instructions, such as, "You are a helpful writing assistant."
-1. At the top of the **Setup** pane, select **Try in playground**.
-1. Start chatting with your agent, for example, "Write me a poem about flowers"
+1. Start chatting with your agent, for example, "Write me a poem about flowers."
 
 # [Python](#tab/python)
 
@@ -252,6 +206,44 @@ Replace `YOUR-FOUNDRY-RESOURCE-NAME` and `YOUR-PROJECT-NAME` with your values:
 
 ---
 
+## Run a chat completion
+
+Chat completions are the basic building block of AI applications. Using chat completions you can send a list of messages and get a response from the model instead of the agent.
+
+# [Azure AI Foundry portal](#tab/azure-ai-foundry)
+
+1. In the left pane, select **Playgrounds**. 
+1. Select **Try the chat playground**.
+1. Fill in the prompt and select the **Send** button.
+1. The model returns a response in the **Response** pane.
+
+# [Python](#tab/python)
+
+Substitute your value for the endpoint in this code:
+
+:::code language="python" source="~/foundry-samples-main/samples/microsoft/python/mslearn-resources/quickstart/quickstart.py" id="chat_completion":::
+
+
+# [Java (preview)](#tab/java)
+
+:::code language="java" source="~/foundry-samples-main/samples/microsoft/java/mslearn-resources/quickstart/src/main/java/com/azure/ai/foundry/samples/ChatCompletionSample.java" :::
+
+# [JavaScript (preview)](#tab/javascript)
+
+:::code language="javascript" source="~/foundry-samples-main/samples/microsoft/javascript/mslearn-resources/quickstart/src/quickstart.js" id="chat_completion":::
+
+
+# [C#](#tab/csharp)
+
+:::code language="csharp" source="~/foundry-samples-main/samples/microsoft/csharp/mslearn-resources/quickstart/Samples/SimpleInference.cs" id="chat_completion":::
+
+# [REST API](#tab/rest)
+
+Replace `YOUR-FOUNDRY-RESOURCE-NAME` with your values:
+
+:::code language="console" source="~/foundry-samples-main/samples/microsoft/REST/mslearn-resources/quickstart/quickstart.sh" id="chat_completion":::
+
+---
 
 ## Clean up resources
 

articles/ai-foundry/index.yml

@@ -168,6 +168,8 @@ additionalContent:
               url: https://aka.ms/azureaifoundry/vscode
         - title: Explore more Azure AI
           links:
+            - text: What are Azure AI services?
+              url: ../ai-services/what-are-ai-services.md
             - text: Semantic Kernel
               url: /semantic-kernel/
             - text: Document Intelligence