Merge pull request #5604 from MicrosoftDocs/main

6/18/2025 PM Publish

Author: Taojunshen

articles/ai-foundry/agents/environment-setup.md

@@ -8,7 +8,7 @@ ms.author: aahi
 ms.reviewer: fosteramanda 
 ms.service: azure-ai-agent-service
 ms.topic: how-to
-ms.date: 05/09/2025
+ms.date: 06/18/2025
 ms.custom: azure-ai-agents
 ---
 
@@ -25,19 +25,22 @@ Use this article to learn more about setting up your agent environment.
 | Action                                                                 | Required Role                   |
 |------------------------------------------------------------------------|----------------------------------|
 | Create an account and project                                          | Azure AI Account Owner           |
-| **Standard Setup Only:** Assign RBAC for required resources (Cosmos DB, Search, Storage, etc.) | Role Based Access Control Administrator  |
+| [standard setup](#choose-your-setup) Only: Assign RBAC for required resources (Cosmos DB, Search, Storage, etc.) | Role Based Access Control Administrator  |
 | Create and edit agents                                                 | Azure AI User                    |
 
 ## Set up your agent environment
-To get started, you need an account and a project.  
-Agents are scoped at the project level, which ensures data isolation—agents within the same project share access to the same resources. 
+To get started, you need an Azure AI Foundry resource and a Foundry project.  
+Agents are created within a specific project, and each project acts as an isolated workspace. This means:
+* All agents in the same project share access to the same file storage, thread storage (conversation history), and search indexes.
+* Data is isolated between projects. Agents in one project cannot access resources from another.
+Projects are currently the unit of sharing and isolation in Foundry. See the [what is AI foundry](../../ai-foundry/what-is-azure-ai-foundry.md) article for more information on Foundry projects.
 
 ### Prerequisites 
 
 * An Azure subscription - [Create one for free](https://azure.microsoft.com/free/cognitive-services).
 * Ensure that the individual creating the account and project has the **Azure AI Account Owner** role at the subscription scope
-* If configuring **Standard Setup**, the same individual must also have permissions to assign roles to required resources (Cosmos DB, Search, Storage).
-    * The built-in role needed is **Role Based Access Control Administrator**.
+* If configuring a [standard setup](#choose-your-setup), the same individual must also have permissions to assign roles to required resources (Cosmos DB, Azure AI Search, Azure Blob Storage). For more information on RBAC roles, specific to Azure AI Foundry Agent Service, see [Azure AI Foundry Agent Service RBAC roles](../concepts/rbac-azure-ai-foundry.md).
+    * The built-in role needed is **Role Based Access Administrator**.
     * Alternatively, having the **Owner** role at the subscription level also satisfies this requirement.
     * The key permission needed is: `Microsoft.Authorization/roleAssignments/write`
 
@@ -76,6 +79,12 @@ If you want support for Private Network Isolation see [network-secured setup](ho
 | Deploy a standard agent setup that uses **Managed Identity** for authentication. <br>An account and project are created. <br> A GPT-4o model is deployed. <br> Azure resources for storing customer data - **Azure Storage**, **Azure Cosmos DB**, and **Azure AI Search** - are automatically created if existing resources are't  provided. <br> These resources are connected to your project to store files, threads, and vector data. <br> A Microsoft-managed Key Vault is used by default.</li></ul> <br> [![Deploy To Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fazure-ai-foundry%2Ffoundry-samples%2Frefs%2Fheads%2Fmain%2Fsamples%2Fmicrosoft%2Finfrastructure-setup%2F41-standard-agent-setup%2Fazuredeploy.json) | :::image type="content" source="./media\quickstart\standard-agent-setup.png" alt-text="An architecture diagram for standard agent setup." lightbox="./media\quickstart\standard-agent-setup.png"::: |
 
 ### [Optional] Model selection in autodeploy template
+
+> [!IMPORTANT]
+> **Don't change the modelFormat parameter.** 
+>
+> The templates only support deployment of Azure OpenAI models. See which Azure OpenAI models are supported in the [model support](./concepts/model-region-support.md) article.
+
 You can customize the model used by your agent by editing the model parameters in the autodeploy template. To deploy a different model, you need to update at least the `modelName` and `modelVersion` parameters. 
 
 By default, the deployment template is configured with the following values:
@@ -88,12 +97,6 @@ By default, the deployment template is configured with the following values:
 | modelSkuName     | GlobalStandard |
 | modelLocation    | eastus         |
 
-> [!IMPORTANT]
-> **Don't change the modelFormat parameter.** 
->
-> The templates only support deployment of Azure OpenAI models. See which Azure OpenAI models are supported in the [Azure AI Foundry Agent Service model support](concepts\model-region-support.md) documentation.
-
-
 ### What's next?
 * [Create your first agent](quickstart.md)
 * Explore more:

articles/ai-foundry/agents/how-to/tools/openapi-spec-samples.md

@@ -5,7 +5,7 @@ description: Find code samples to use OpenAPI tools with agents.
 author: aahill
 ms.author: aahi
 manager: nitinme
-ms.date: 04/09/2025
+ms.date: 06/18/2025
 ms.service: azure-ai-agent-service
 ms.topic: how-to
 ms.custom:
@@ -33,8 +33,8 @@ Use this article to find step-by-step instructions and code samples for using Op
 
    :::image type="content" source="../../media\tools\open-api-details.png" alt-text="A screenshot showing the openAPI tool details in the Azure AI Foundry portal." lightbox="../../media\tools\open-api-details.png":::
 
-1. Select **Next** and select your authentication method. Choose `connection` for `API key`.
-   1. If you choose `connection`, you need to select the custom keys connection you have created before.
+1. Select **Next** and select your authentication method.
+   1. If you choose `connection`, you need to select the custom connection you have created before.
    1. If you choose `managed identity`, you need to input the audience to get your token. An example of an audience would be `https://cognitiveservices.azure.com/` to connect to Azure AI Services. Make sure you have already set up authentication and role assignment (as described in the [section](./openapi-spec.md#authenticating-with-managed-identity-microsoft-entra-id) above).
 
 1. Copy and paste your OpenAPI specification in the text box.
@@ -70,18 +70,14 @@ with AIProjectClient(
 ) as project_client:
 ```
 
-## Countries Tool Setup
-Similarly, the OpenAPI specification for the countries service is loaded from `countries.json`. An anonymous authentication object (`OpenApiAnonymousAuthDetails`) is created, as this specific API doesn't require authentication in this example.
+## Tool setup
+Similarly, the OpenAPI specification is loaded from `weather.json`. An anonymous authentication object (`OpenApiAnonymousAuthDetails`) is created, as this specific API doesn't require authentication in this example. You can find an example OpenAPI spec on [GitHub](https://github.com/azure-ai-foundry/foundry-samples/blob/main/samples/microsoft/python/getting-started-agents/openapi/weather_openapi.json).
 
 ```python
-    # Load the OpenAPI specification for the countries service from a local JSON file
+    # Load the OpenAPI specification for the weather service from a local JSON file
     with open(os.path.join(os.path.dirname(__file__), "weather.json"), "r") as f:
          openapi_weather = jsonref.loads(f.read())
 
-    # Load the OpenAPI specification for the countries service from a local JSON file
-    with open(os.path.join(os.path.dirname(__file__), "countries.json"), "r") as f:
-         openapi_countries = jsonref.loads(f.read())
-
     # Create Auth object for the OpenApiTool (note: using anonymous auth here; connection or managed identity requires additional setup)
     auth = OpenApiAnonymousAuthDetails()
     # for connection setup
@@ -93,10 +89,6 @@ Similarly, the OpenAPI specification for the countries service is loaded from `c
     openapi_tool = OpenApiTool(
         name="get_weather", spec=openapi_weather, description="Retrieve weather information for a location", auth=auth
     )
-    # Add the countries API definition to the same tool object
-    openapi_tool.add_definition(
-        name="get_countries", spec=openapi_countries, description="Retrieve a list of countries", auth=auth
-    )
 ```
 
 ## Agent Creation
@@ -125,7 +117,7 @@ Create the thread and add the initial user message.
     message = project_client.agents.messages.create(
         thread_id=thread.id,
         role="user",
-        content="What's the weather in Seattle and What is the name and population of the country that uses currency with abbreviation THB?",
+        content="What's the weather in Seattle?",
     )
     print(f"Created message, ID: {message.id}")
 ```
@@ -201,6 +193,8 @@ const client = new AgentsClient(projectEndpoint, new DefaultAzureCredential());
 
 ## Read in the OpenAPI spec
 
+You can find an example OpenAPI spec on [GitHub](https://github.com/azure-ai-foundry/foundry-samples/blob/main/samples/microsoft/python/getting-started-agents/openapi/weather_openapi.json).
+
 ```javascript
 // Read in OpenApi spec
 const filePath = "./data/weatherOpenApi.json";
@@ -283,7 +277,7 @@ console.log(`Deleted agent, agent ID: ${agent.id}`);
 :::zone pivot="csharp"
 
 ## Configure client and OpenAPI tool
-First, retrieve configuration details and create a `PersistentAgentsClient`, then define the `OpenApiToolDefinition` using the OpenAPI specification.
+First, retrieve configuration details and create a `PersistentAgentsClient`, then define the `OpenApiToolDefinition` using the OpenAPI specification. You can find an example OpenAPI spec on [GitHub](https://github.com/azure-ai-foundry/foundry-samples/blob/main/samples/microsoft/python/getting-started-agents/openapi/weather_openapi.json).
 
 ```csharp
 using Azure;
@@ -392,7 +386,7 @@ Follow the [REST API Quickstart](../../quickstart.md?pivots=rest-api#api-call-in
 
 ## Create the OpenAPI Spec tool definition, agent, and thread
 
-You might want to store the OpenAPI specification in another file and import the content to initialize the tool. This example is using `anonymous` as the authentication type.
+You might want to store the OpenAPI specification in another file and import the content to initialize the tool. This example is using `anonymous` as the authentication type. You can find an example OpenAPI spec on [GitHub](https://github.com/azure-ai-foundry/foundry-samples/blob/main/samples/microsoft/python/getting-started-agents/openapi/weather_openapi.json).
 
 ```bash
 curl --request POST \