Merge pull request #1962 from fosteramanda/release-azure-agents

Adding code for Azure Blob Storage + more fixes

Author: v-dirichards

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

@@ -14,8 +14,7 @@ zone_pivot_groups: selection-azure-ai-search
 ---
 
 # Use an existing AI Search index with the Azure AI Search tool
-::: zone pivot="overview"
-
+::: zone pivot="overview-azure-ai-search"
 Use an existing Azure AI Search index with the agent's Azure AI Search tool.
 
 > [!NOTE] 

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

@@ -1,9 +1,17 @@
+---
+manager: nitinme
+author: fosteramanda
+ms.author: fosteramanda
+ms.service: azure
+ms.topic: include
+ms.date: 12/10/2024
+---
 ## Quickstart – Use an existing Azure AI Search index with the Azure AI Search tool
 
 This quickstart shows how to use an existing Azure AI Search index with the Azure AI Search tool.
 
 ### Prerequisites
-Complete the [Azure AI Search tool setup](?pivot=setup).
+Complete the [Azure AI Search tool setup](../../how-to/tools/azure-ai-search.md?pivot=overview-azure-ai-search).
 
 ### Step 1: Create an Azure AI Client
 First, create an Azure AI Client using the connection string of your project.
@@ -119,7 +127,6 @@ agent = project_client.agents.create_agent(
     instructions="You are a helpful assistant",
     tools=ai_search.definitions,
     tool_resources = ai_search.resources,
-    headers={"x-ms-enable-preview": "true"},
 )
 print(f"Created agent, ID: {agent.id}")
 ```

articles/ai-services/agents/includes/azure-search/code-examples.md

@@ -10,9 +10,8 @@ ms.date: 12/10/2024
 ## Setup: Create an agent that can use an existing Azure AI Search index
 
 #### Prerequisite: Have an existing Azure AI Search index
-A prerequisite of using the Azure AI Search tool is to have an existing Azure AI Search index. If you don't have an existing index, you can create one in the Azure portal or via REST API.
--  [Quickstart: Create a vector index using the Azure portal](../../../../search/search-get-started-portal-import-vectors.md)
-- [Quickstart: Create a vector index using REST API](../../../../search/search-get-started-vector.md)
+A prerequisite of using the Azure AI Search tool is to have an existing Azure AI Search index. If you don't have an existing index, you can create one in the Azure portal using the import and vectorize data wizard.
+-  [Quickstart: Create a vector index with the import and vectorize data wizard in the Azure portal](../../../../search/search-get-started-portal-import-vectors.md)
 
 
 #### Complete the agent setup
@@ -22,7 +21,9 @@ A prerequisite of using the Azure AI Search tool is to have an existing Azure AI
 
 
 #### Create a project connection to the Azure AI Search resource with the index you want to use
-If you already connected the AI Search resource that contains the index you want to use to your project, skip this step.
+Once you have completed the standard agent setup, you must create a project connection to the Azure AI Search resource that contains the index you want to use. 
+
+If you already connected the AI Search resource that contains the index you want to use to your project, skip this step. 
 
 ##### Get your Azure AI Search resource connection key and endpoint
 1. Access your Azure AI Search resource.
@@ -43,11 +44,11 @@ If you already connected the AI Search resource that contains the index you want
 **Create the following connections.yml file**
 
 
-You can use either an API key or credential-less YAML configuration file. For more information on the YAML configuration file, see the [Azure AI Search connection YAML schema](../../../../machine-learning/reference-yaml-connection-ai-search.md):
+You can use either an API key or credential-less YAML configuration file. Replace the placeholders for ```name```, ```endpoint``` and ```api_key``` with your Azure AI Search resource values. For more information on the YAML configuration file, see the [Azure AI Search connection YAML schema](../../../../machine-learning/reference-yaml-connection-ai-search.md). 
 - API Key example:
 
     ```yml
-    name: myazaics_apk
+    name: my_project_acs_connection_keys
     type: azure_ai_search
     endpoint: https://contoso.search.windows.net/
     api_key: XXXXXXXXXXXXXXX
@@ -56,7 +57,7 @@ You can use either an API key or credential-less YAML configuration file. For mo
 - Credential-less
 
     ```yml    
-    name: myazaics_ei
+    name: my_project_acs_connection_credentialless
     type: azure_ai_search
     endpoint: https://contoso.search.windows.net/
     ```

articles/ai-services/agents/includes/azure-search/setup.md

@@ -15,7 +15,7 @@ The following section shows you how to set up the required resources for getting
 
 1. Creating an Azure AI project under your Hub creates an endpoint for your app to call, and sets up app services to access to resources in your tenant.
 
-1. Connecting an Azure OpenAI resource or an Azure AI resource
+1. Connecting an Azure OpenAI resource or an Azure AI Services resource
 
 
 ## Choose Basic or Standard Agent Setup
@@ -24,15 +24,86 @@ The following section shows you how to set up the required resources for getting
 
 **Standard Setup**: Agents use customer-owned, single-tenant search and storage resources. With this setup, you have full control and visibility over these resources, but you incur costs based on your usage.
 
-| Description   | Autodeploy |
-| -----------------------------------------------| -----------------------|
-| Deploy a basic agent setup that uses Managed Identity for authentication. | [![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FAzure%2Fazure-quickstart-templates%2Fmaster%2Fquickstarts%2Fmicrosoft.azure-ai-agent-service%2Fbasic-agent-identity%2Fazuredeploy.json)
-| Deploy a standard agent setup that uses Managed Identity for authentication. | [![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FAzure%2Fazure-quickstart-templates%2Frefs%2Fheads%2Fmaster%2Fquickstarts%2Fmicrosoft.azure-ai-agent-service%2Fstandard-agent%2Fazuredeploy.json)
+| Description   | Resources  | Autodeploy |
+| -----------------------------------------------| -----------------------|----------------------|
+| Deploy a basic agent setup that uses Managed Identity authentication on the AI Services and storage account connections. | AI hub, AI project, AI Services | [![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FAzure%2Fazure-quickstart-templates%2Fmaster%2Fquickstarts%2Fmicrosoft.azure-ai-agent-service%2Fbasic-agent-identity%2Fazuredeploy.json) |
+| Deploy a standard agent setup that uses Managed Identity authentication on the AI Services, storage account, and Azure AI Search connections. |AI hub, AI project, storage account, key vault, Azure AI Search, AI Services | [![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FAzure%2Fazure-quickstart-templates%2Frefs%2Fheads%2Fmaster%2Fquickstarts%2Fmicrosoft.azure-ai-agent-service%2Fstandard-agent%2Fazuredeploy.json)|
+
+### [Optional] Model selection in autodeploy template
+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:
+
+| Model Parameter  | Default Value  |
+|------------------|----------------|
+| modelName        | gpt-4o-mini    |
+| modelFormat      | OpenAI         |
+| modelVersion     | 2024-07-18     |
+| modelSkuName     | GlobalStandard |
+| modelLocation    | eastus         |
+
+> [!IMPORTANT]
+> **Don't change the modelFormat parameter.** 
+>
+> The templates only support deployment of OpenAI models. See which OpenAI models are supported in the [Azure AI Agent Service model support](../concepts/model-region-support.md) documentation.
+
+
+### [Optional] Use your own resources in agent setup
+
+> [!NOTE]
+> If you use an existing AI Services/AOAI resource, no model will be deployed. You can deploy a model to the resource after the agent setup is complete. 
+
+#### Basic agent setup: use an existing AI Services resource 
+
+Replace the parameter value for `aiServiceAccountResourceId` with the full arm resource ID of the AI Services account you want to use.
+
+1. To get the AI Services account resource ID, sign in to the Azure CLI and select the subscription with your AI Services account:
+       
+    ```az login``` 
+2. Replace `<your-resource-group>` with the resource group containing your resource and `your-ai-service-resource-name` with the name of your AI Service resource, and run:
+    
+    ```az cognitiveservices account show --resource-group <your-resource-group> --name <your-ai-service-resource-name> --query "id" --output tsv```
+
+    The value returned is the `aiServiceAccountResourceId` you need to use in the template.
+
+2. In the basic agent template file, set the parameter:
+    - aiServiceAccountResourceId:/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{serviceName}
+
+#### Standard agent setup: use an existing AI Services, storage, and/or Azure AI Search resource 
+
+Use an existing AI Search, storage account, and/or Azure AI Search resource by providing the full arm resource ID in the standard agent template file.
+
+Use an existing AI Services resource:
+1. Follow the steps in basic agent setup to get the AI Services account resource ID.
+2. In the standard agent template file, set the parameter:
+    - aiServiceAccountResourceId:/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{serviceName}
+
+Use an existing storage account:
+1. To get your storage account resource ID, sign in to the Azure CLI and select the subscription with your storage account: 
+    
+    ```az login``` 
+2. Then run the command:
+
+    ```az search service show --resource-group  <your-resource-group> --name <your-storage-account>  --query "id" --output tsv```
+    
+     The output is the `aiStorageAccountResourceID` you need to use in the template.
+3. In the standard agent template file, set the parameter:
+    - aiStorageAccountResourceId:/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{storageAccountName}
+
+Use an existing Azure AI Search resource:
+1. To get your Azure AI Search resource ID, sign into Azure CLI and select the subscription with your search resource: 
+    
+    ```az login```
+2. Then run the command:
+    
+    ```az search service show --resource-group  <your-resource-group> --name <your-search-service>  --query "id" --output tsv```
+3. In the standard agent template file, set the parameter:
+    - aiSearchServiceResourceId:/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}
 
 ## Basic agent setup resource architecture
 :::image type="content" source="../media/quickstart/basic-agent-setup-resources.png" alt-text="An architecture diagram for basic agent setup." lightbox="../media/quickstart/basic-agent-setup-resources.png":::
 
-Resources for the AI hub, AI project, storage account, and AI Services are created for you. The AI Services account is connected to your project/hub and a gpt-4o-mini model is deployed in the eastus region. A Microsoft-managed key vault is used by default.
+Resources for the AI hub, AI project, and AI Services are created for you. A storage account is created because it's a required resource for hubs, but this storage account is not used by agents. The AI Services account is connected to your project/hub and a gpt-4o-mini model is deployed in the eastus region. A Microsoft-managed key vault, storage account, and search resource is used by default.
 
 ## Standard agent setup resource architecture
 :::image type="content" source="../media/quickstart/standard-agent-setup-resources.png" alt-text="An architecture diagram for standard agent setup." lightbox="../media/quickstart/standard-agent-setup-resources.png":::

articles/ai-services/agents/includes/bicep-setup.md

@@ -0,0 +1,117 @@
+---
+manager: nitinme
+author: fosteramanda
+ms.author: fosteramanda
+ms.service: azure
+ms.topic: include
+ms.date: 12/10/2024
+---
+
+## Quickstart – Use existing files in Azure Blob Storage with file search
+In this example, we use Azure AI Agent Service to create an agent that can help answer questions on information from files in Azure Blob Storage.
+
+###  Prerequisites 
+1. Complete the [standard agent setup](../../quickstart.md).
+
+2. Ensure that you have the role  **Storage Blob Data Contributor** on your project's storage account.
+
+3. Ensure that you have the role **Azure AI Developer** on your project.
+
+> [!IMPORTANT]
+> File search using Blob storage is only supported by the standard agent setup.
+
+### Step 1: Create a project client
+```python
+import os
+from azure.ai.projects import AIProjectClient
+from azure.ai.projects.models import FileSearchTool, VectorStoreDataSource, VectorStoreDataSourceAssetType
+from azure.identity import DefaultAzureCredential
+
+
+# Create an Azure AI Client from a connection string, copied from your AI Studio 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
+
+credential = DefaultAzureCredential()
+project_client = AIProjectClient.from_connection_string(
+    credential=credential, conn_str=os.environ["PROJECT_CONNECTION_STRING"]
+)
+```
+
+### Step 2: Upload local files to your project Azure Blob Storage container
+Upload your local file to the project’s Azure Blob Storage container. This is the same storage account you connected to your agent during setup. When creating additional agents within the same project, you can reuse the asset URIs of any previously uploaded files that those agents need. This means you don't have to upload the same file repeatedly, as the asset URIs allow you to reference the files directly.
+
+Then, create a vector store using the ```asset_uri```, which is the location of your file in your project's datastore.
+```python
+# We'll upload the local file to your project Azure Blob Storage container and will use it for vector store creation.
+_, asset_uri = project_client.upload_file("sample_file_for_upload.md")
+print(f"Uploaded file, asset URI: {asset_uri}")
+
+# create a vector store with a file in blob storage and wait for it to be processed
+ds = VectorStoreDataSource(asset_identifier=asset_uri, asset_type=VectorStoreDataSourceAssetType.URI_ASSET)
+vector_store = project_client.agents.create_vector_store_and_poll(data_sources=[ds], name="sample_vector_store")
+print(f"Created vector store, vector store ID: {vector_store.id}")
+```
+
+### Step 3: Create an agent with access to the file search tool
+
+```python
+# create a file search tool
+file_search_tool = FileSearchTool(vector_store_ids=[vector_store.id])
+
+# notices that FileSearchTool as tool and tool_resources must be added or the assistant unable to search the file
+agent_1 = project_client.agents.create_agent(
+    model="gpt-4o-mini",
+    name="my-assistant",
+    instructions="You are helpful assistant",
+    tools=file_search_tool.definitions,
+    tool_resources=file_search_tool.resources,
+)
+# [END upload_file_and_create_agent_with_file_search]
+print(f"Created agent_1, agent_1 ID: {agent_1.id}")
+
+thread = project_client.agents.create_thread()
+print(f"Created thread, thread ID: {thread.id}")
+
+message = project_client.agents.create_message(
+    thread_id=thread.id, role="user", content="What feature does Smart Eyewear offer?"
+)
+print(f"Created message, message ID: {message.id}")
+
+run = project_client.agents.create_and_process_run(thread_id=thread.id, assistant_id=agent_1.id)
+
+project_client.agents.delete_vector_store(vector_store.id)
+print("Deleted vector store")
+
+project_client.agents.delete_agent(agent.id)
+print("Deleted agent")
+
+messages = project_client.agents.list_messages(thread_id=thread.id)
+print(f"Messages: {messages}")
+```
+
+### Step 4: Create second vector store using the previously uploaded file
+Now, create a second vector store using the previously uploaded file. Using the ```asset_uri``` of a file already in Azure Blob Storage is useful if you have multiple agents that need access to the same files, as it eliminates the need to upload the same file multiple times.
+```python
+
+# create a vector store with a previously uploaded file and wait for it to be processed
+ds_2 = VectorStoreDataSource(asset_identifier=asset_uri, asset_type=VectorStoreDataSourceAssetType.URI_ASSET)
+vector_store_2 = project_client.agents.create_vector_store_and_poll(data_sources=[ds_2], name="sample_vector_store_2")
+print(f"Created vector store, vector store ID: {vector_store.id}")
+
+```
+
+### Step 5: Create a second agent with access to the file search tool
+```python
+file_search_tool_2 = FileSearchTool(vector_store_ids=[vector_store_2.id])
+# notices that FileSearchTool as tool and tool_resources must be added or the assistant unable to search the file
+agent_2 = project_client.agents.create_agent(
+    model="gpt-4o-mini",
+    name="my-assistant-2",
+    instructions="You are helpful assistant",
+    tools=file_search_tool_2.definitions,
+    tool_resources=file_search_tool_2.resources,
+)
+# [END upload_file_and_create_agent_with_file_search]
+print(f"Created agent, agent ID: {agent_2.id}")
+```