Merge branch 'release-build-agents' of https://github.com/MicrosoftDocs/azure-ai-docs-pr into amandabuild-4

Author: aahill

.openpublishing.redirection.json

@@ -92,7 +92,7 @@
     },
     {
       "source_path_from_root": "/articles/ai-services/agents/how-to/tools/licensed-data.md",
-      "redirect_url": "/azure/ai-services/agents/how-to/tools/catalog",
+      "redirect_url": "/azure/ai-services/agents/how-to/tools/overview",
       "redirect_document_id": false
     },
     {

articles/ai-services/agents/concepts/standard-agent-setup.md

@@ -0,0 +1,88 @@
+---
+title: Built-in enterprise readiness with standard agent setup
+titleSuffix: Azure AI Foundry
+description: Learn about the enterprise features of the standard setup
+manager: nitinme
+author: fosteramanda
+ms.author: fosteramanda
+ms.service: azure-ai-agent-service
+ms.topic: conceptual
+ms.date: 05/05/2025
+ms.custom: azure-ai-agents
+---
+
+# Built-in enterprise readiness with standard agent setup 
+
+Standard Agent Setup offers enterprise-grade security, compliance, and control. This configuration uses customer-managed, single-tenant resources to store agent state and ensures all data remains within your control.  
+
+In this setup: 
+* Agent states (files, threads, vector stores) are stored in your own Azure resources. 
+* Available with both public networking and private networking (Bring Your Own virtual network) options. 
+
+## Leveraging your own resources for storing customer data
+Both standard setup configurations are designed to give you complete control over sensitive data by requiring the use of your own Azure resources. The required Bring Your Own (BYO) resources include:   
+* BYO File Storage: All files uploaded by developers (during agent configuration) or end-users (during interactions) are stored directly in the customer’s Azure Storage account.   
+* BYO Search: All vector stores created by the agent leverage the customer’s Azure AI Search resource.   
+* BYO Thread Storage: All customer messages and conversation history will be stored in the customer’s own Azure Cosmos DB account.  
+
+By bundling these BYO features (file storage, search, and thread storage), the standard setup guarantees that your deployment is secure by default. All data processed by Azure AI Agent Service is automatically stored at rest in your own Azure resources, helping you meet internal policies, compliance requirements, and enterprise security standards. 
+
+## Project-Level Data Isolation
+
+Azure AI Foundry enforces project-level data isolation by default. When you configure your own resources in the project capability host: 
+* **Azure Storage**: Two Blob containers are automatically provisioned: 
+    * One for uploaded files 
+    * One for intermediate system data (for example, chunks, embeddings) 
+* **Azure Cosmos DB**: Three containers are provisioned under a dedicated enterprise_memory database: 
+    * thread-message-store: End-user conversations 
+    * system-thread-message-store: Internal system messages 
+    * agent-entity-store: Model inputs and outputs 
+
+This default behavior was chosen to reduce configuration complexity while still enforcing strict data boundaries—ensuring each project has a clean, isolated storage footprint without requiring manual setup. 
+
+## Capability hosts
+**Capability hosts** are sub-resources on both the Account and Project, enabling interaction with the Azure AI Agent Service. 
+- **Account Capability Host**: The account capability host has an empty request body except for the parameter capabilityHostKind="Agents". 
+- **Project Capability Host**: Specifies resources for storing agent state, either managed multitenant (basic setup) or customer-owned (standard setup), single-tenant resource. Think of project capability host as the project settings.
+
+### Limitations
+- **Update Not Supported**: Cannot update the capability host for a project or account.
+
+
+## Step by Step Provisioning Process
+1. Create project dependent resources for standard setup
+    * Create new (or pass in resource ID of existing) Cosmos DB resource 
+    * Create new (or pass in resource ID of existing) Azure Storage resource 
+    * Create new (or pass in resource ID of existing) Azure AI Search resource 
+    * Create a new Key Vault resource 
+    * [Optional]: Create new application insights resource 
+    * [Optional]: pass in resource ID of existing AI Foundry resource 
+2. Create Azure AI Foundry Resource (cognitive service/accounts kind=AIServices) 
+3. Create Account-level connections 
+    * Create account connection to Application Insights resource 
+4. Deploy gpt-4o or other agent compatible model 
+5. Create Project (cognitive service/accounts/project) 
+6. Create project connections 
+    * [if provided] Project connection to AI Foundry resource 
+    * Create project connection to Azure Storage account 
+    * Create project connection to Azure AI Search account 
+    * Create project connection to Cosmos DB account 
+7. Assign the project-managed identity (including for SMI) the following roles: 
+    * Cosmos DB Operator at the scope of the account level for the Cosmos DB account resource 
+    * Storage Account Contributor at the scope of the account level for the Storage Account resource 
+8. Set Account capability host with empty properties section. 
+9. Set Project capability host with properties Cosmos DB, Azure Storage, AI Search connections 
+10. Assign the Project Managed Identity (both for SMI and UMI) the following roles on the specified resource scopes: 
+    * Azure AI Search (can be assigned either before or after capHost creation) 
+        * Assign roles: Search Index Data Contributor, Search Service Contributor 
+    * Azure Blob Storage Container: `<workspaceId>-azureml-blobstore`
+        * Assign role: Storage Blob Data Contributor 
+    * Azure Blob Storage Container: `<workspaceId>- agents-blobstore` 
+        * Assign role: Storage Blob Data Owner  
+    * Cosmos DB for NoSQL container: `<'${projectWorkspaceId}>-thread-message-store'`
+        * Assign role: Cosmos DB Built-in Data Contributor 
+    * Cosmos DB for NoSQL container: `<'${projectWorkspaceId}>-thread-message-store'` 
+        * Assign role: Cosmos DB Built-in Data Contributor 
+    * Cosmos DB for NoSQL container: `<'${projectWorkspaceId}>-agent-entity-store'` 
+        * Assign role: Cosmos DB Built-in Data Contributor 
+11. Once all resources are provisioned, all developers who want to create/edit agents in the project should be assigned the role: Azure AI User on the project scope. 

articles/ai-services/agents/how-to/tools/azure-ai-search-samples.md

@@ -136,112 +136,132 @@ print("Deleted agent")
 
 :::zone pivot="csharp"
 
-## Step 1: Create an Azure AI Client
-First, create an Azure AI Client using the connection string of your project.
+## Step 1: Create a project client
+Create a client object, which will contain the project endpoint for connecting to your AI project and other resources.
 
 ```csharp
+using Azure;
+using Azure.AI.Agents.Persistent;
+using Azure.Identity;
+using Microsoft.Extensions.Configuration;
 using System;
-using System.Threading.Tasks;
-using Azure.Core;
-using Azure.Core.TestFramework;
-using NUnit.Framework;
-using System.Collections.Generic;
-
-// Create an Azure AI Client from a connection string, copied from your Azure AI Foundry project.
-// At the moment, it should be in the format "<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>"
-// Customer needs to login to Azure subscription via Azure CLI and set the environment variables
-var connectionString = TestEnvironment.AzureAICONNECTIONSTRING;
-var clientOptions = new AIProjectClientOptions();
-
-// Adding the custom headers policy
-clientOptions.AddPolicy(new CustomHeadersPolicy(), HttpPipelinePosition.PerCall);
-var projectClient = new AIProjectClient(connectionString, new DefaultAzureCredential(), clientOptions);
-```
+using System.Threading;
 
-## Step 2: Get the connection ID for the Azure AI Search resource
-Get the connection ID of the Azure AI Search connection in the project.
+// Get Connection information from app configuration
+IConfigurationRoot configuration = new ConfigurationBuilder()
+    .SetBasePath(AppContext.BaseDirectory)
+    .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
+    .Build();
 
-```csharp
-ListConnectionsResponse connections = await projectClient.GetConnectionsClient().GetConnectionsAsync(ConnectionType.AzureAISearch).ConfigureAwait(false);
+var projectEndpoint = configuration["ProjectEndpoint"];
+var modelDeploymentName = configuration["ModelDeploymentName"];
+var azureAiSearchConnectionId = configuration["AzureAiSearchConnectionId"];
 
-if (connections?.Value == null || connections.Value.Count == 0)
-{
-    throw new InvalidOperationException("No connections found for the Azure AI Search.");
-}
+// Create the Agent Client
+PersistentAgentsClient agentClient = new(projectEndpoint, new DefaultAzureCredential());
 ```
 
-## Step 3: Configure the Azure AI Search tool
-Using the connection ID you got in the previous step, you can now configure the Azure AI Search tool to use your Azure AI Search index.
+## Step 2: Configure the Azure AI Search tool
+Using the AI Search Connection ID, configure the Azure AI Search tool to use your Azure AI Search index.
 
 ```csharp
-// TO DO: replace this value with the connection ID of the search index
-ConnectionResponse connection = connections.Value[0];
+AzureAISearchResource searchResource = new(
+    indexConnectionId: azureAiSearchConnectionId,
+    indexName: "sample_index",
+    topK: 5,
+    filter: "category eq 'sleeping bag'",
+    queryType: AzureAISearchQueryType.Simple
+);
+
+ToolResources toolResource = new() { AzureAISearch = searchResource };
 
-// Initialize agent Azure AI search tool and add the search index connection ID and index name
-// TO DO: replace <your-index-name> with the name of the index you want to use
-ToolResources searchResource = new ToolResources
-{
-    AzureAISearch = new AzureAISearchResource
-    {
-        IndexList = { new IndexResource(connection.Id, "<your-index-name>", "<select-search-type>") }
-    }
-};
 ```
 
-## Step 4: Create an agent with the Azure AI Search tool enabled
+## Step 3: Create an agent with the Azure AI Search tool enabled
 Change the model to the one deployed in your project. You can find the model name in the Azure AI Foundry under the **Models** tab. You can also change the name and instructions of the agent to suit your needs.
 
 ```csharp
-AgentsClient agentClient = projectClient.GetAgentsClient();
-
-Response<Agent> agentResponse = await agentClient.CreateAgentAsync(
-    model: "gpt-4o-mini",
-    name: "my-assistant",
-    instructions: "You are a helpful assistant.",
-    tools: new List<ToolDefinition> { new AzureAISearchToolDefinition() },
-    toolResources: searchResource);
-Agent agent = agentResponse.Value;
+// Create an agent with Tools and Tool Resources
+PersistentAgent agent = agentClient.Administration.CreateAgent(
+    model: modelDeploymentName,
+    name: "my-agent",
+    instructions: "You are a helpful agent.",
+    tools: [new AzureAISearchToolDefinition()],
+    toolResources: toolResource);
+
 ```
 
-## Step 5: Ask the agent questions about data in the index
+## Step 4: Ask the agent questions about data in the index
 Now that the agent is created, ask it questions about the data in your Azure AI Search index.
 
 ```csharp
 // Create thread for communication
-Response<AgentThread> threadResponse = await agentClient.CreateThreadAsync();
-AgentThread thread = threadResponse.Value;
+PersistentAgentThread thread = agentClient.Threads.CreateThread();
 
-// Create message to thread
-Response<ThreadMessage> messageResponse = await agentClient.CreateMessageAsync(
+// Create message and run the agent
+ThreadMessage message = agentClient.Messages.CreateMessage(
     thread.Id,
     MessageRole.User,
-    "what are my health insurance plan coverage types?");
-ThreadMessage message = messageResponse.Value;
+    "What is the temperature rating of the cozynights sleeping bag?");
+ThreadRun run = agentClient.Runs.CreateRun(thread, agent);
+
+```
+
+## Step 4: Wait for the agent to complete and print the output
 
-// Run the agent
-Response<ThreadRun> runResponse = await agentClient.CreateRunAsync(thread, agent);
+Wait for the agent to complete the run and print output to console.
 
+```csharp
+// Wait for the agent to finish running
 do
 {
-    await Task.Delay(TimeSpan.FromMilliseconds(500));
-    runResponse = await agentClient.GetRunAsync(thread.Id, runResponse.Value.Id);
+    Thread.Sleep(TimeSpan.FromMilliseconds(500));
+    run = agentClient.Runs.GetRun(thread.Id, run.Id);
 }
-while (runResponse.Value.Status == RunStatus.Queued
-    || runResponse.Value.Status == RunStatus.InProgress);
+while (run.Status == RunStatus.Queued
+    || run.Status == RunStatus.InProgress);
 
-Response<PageableList<ThreadMessage>> afterRunMessagesResponse
-    = await agentClient.GetMessagesAsync(thread.Id);
-IReadOnlyList<ThreadMessage> messages = afterRunMessagesResponse.Value.Data;
+// Confirm that the run completed successfully
+if (run.Status != RunStatus.Completed)
+{
+    throw new Exception("Run did not complete successfully, error: " + run.LastError?.Message);
+}
+
+// Retrieve the messages from the agent client
+Pageable<ThreadMessage> messages = agentClient.Messages.GetMessages(
+    threadId: thread.Id,
+    order: ListSortOrder.Ascending
+);
 
-// Note: messages iterate from newest to oldest, with the messages[0] being the most recent
+// Process messages in order
 foreach (ThreadMessage threadMessage in messages)
 {
     Console.Write($"{threadMessage.CreatedAt:yyyy-MM-dd HH:mm:ss} - {threadMessage.Role,10}: ");
     foreach (MessageContent contentItem in threadMessage.ContentItems)
     {
         if (contentItem is MessageTextContent textItem)
         {
-            Console.Write(textItem.Text);
+            // We need to annotate only Agent messages.
+            if (threadMessage.Role == MessageRole.Agent && textItem.Annotations.Count > 0)
+            {
+                string annotatedText = textItem.Text;
+
+                // If we have Text URL citation annotations, reformat the response to show title & URL for citations
+                foreach (MessageTextAnnotation annotation in textItem.Annotations)
+                {
+                    if (annotation is MessageTextUrlCitationAnnotation urlAnnotation)
+                    {
+                        annotatedText = annotatedText.Replace(
+                            urlAnnotation.Text,
+                            $" [see {urlAnnotation.UrlCitation.Title}] ({urlAnnotation.UrlCitation.Url})");
+                    }
+                }
+                Console.Write(annotatedText);
+            }
+            else
+            {
+                Console.Write(textItem.Text);
+            }
         }
         else if (contentItem is MessageImageFileContent imageFileItem)
         {
@@ -250,6 +270,17 @@ foreach (ThreadMessage threadMessage in messages)
         Console.WriteLine();
     }
 }
+```
+## Step 5: Clean up resources
+
+Clean up the resources from this sample.
+
+```csharp
+
+// Delete thread and agent
+agentClient.Threads.DeleteThread(thread.Id);
+agentClient.Administration.DeleteAgent(agent.Id);
+
 ```
 
 :::zone-end