|
| 1 | +## Quickstart – Use an existing Azure AI Search index with the Azure AI Search tool |
| 2 | + |
| 3 | +This quickstart shows how to use an existing Azure AI Search index with the Azure AI Search tool. |
| 4 | + |
| 5 | +### Prerequisites |
| 6 | +Complete the [Azure AI Search tool setup](?pivot=setup). |
| 7 | + |
| 8 | +### Step 1: Create an Azure AI Client |
| 9 | +First, create an Azure AI Client using the connection string of your project. |
| 10 | +# [Python](#tab/python) |
| 11 | +```python |
| 12 | +import os |
| 13 | +from azure.ai.projects import AIProjectClient |
| 14 | +from azure.identity import DefaultAzureCredential |
| 15 | +from azure.ai.projects.models import AzureAISearchTool |
| 16 | + |
| 17 | +# Create an Azure AI Client from a connection string, copied from your AI Studio project. |
| 18 | +# At the moment, it should be in the format "<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>" |
| 19 | +# HostName can be found by navigating to your discovery_url and removing the leading "https://" and trailing "/discovery" |
| 20 | +# To find your discovery_url, run the CLI command: az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url |
| 21 | +# Project Connection example: eastus.api.azureml.ms;my-subscription-id;my-resource-group;my-hub-name |
| 22 | + |
| 23 | +connection_string = os.environ["PROJECT_CONNECTION_STRING"] |
| 24 | + |
| 25 | +project_client = AIProjectClient.from_connection_string( |
| 26 | + credential=DefaultAzureCredential(), |
| 27 | + conn_str=connection_string, |
| 28 | +) |
| 29 | +``` |
| 30 | + |
| 31 | +# [C#](#tab/csharp) |
| 32 | +```csharp |
| 33 | +using System; |
| 34 | +using System.Threading.Tasks; |
| 35 | +using Azure.Core; |
| 36 | +using Azure.Core.TestFramework; |
| 37 | +using NUnit.Framework; |
| 38 | +using System.Collections.Generic; |
| 39 | + |
| 40 | +// Create an Azure AI Client from a connection string, copied from your AI Studio project. |
| 41 | +// At the moment, it should be in the format "<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>" |
| 42 | +// Customer needs to login to Azure subscription via Azure CLI and set the environment variables |
| 43 | +var connectionString = TestEnvironment.AzureAICONNECTIONSTRING; |
| 44 | +var clientOptions = new AIProjectClientOptions(); |
| 45 | + |
| 46 | +// Adding the custom headers policy |
| 47 | +clientOptions.AddPolicy(new CustomHeadersPolicy(), HttpPipelinePosition.PerCall); |
| 48 | +var projectClient = new AIProjectClient(connectionString, new DefaultAzureCredential(), clientOptions); |
| 49 | +``` |
| 50 | +--- |
| 51 | +### Step 2: Get the connection ID for the Azure AI Search resource |
| 52 | + |
| 53 | +Get the connection ID of the Azure AI Search connection in the project. You can use the code snippet to print the connection ID of all the Azure AI Search connections in the project. |
| 54 | + |
| 55 | +# [Python](#tab/python) |
| 56 | + |
| 57 | +```python |
| 58 | +# AI Search resource connection ID |
| 59 | +# This code prints out the connection ID of all the Azure AI Search connections in the project |
| 60 | +# If you have more than one AI search connection, make sure to select the correct one that contains the index you want to use. |
| 61 | +conn_list = project_client.connections.list() |
| 62 | +conn_id = "" |
| 63 | +for conn in conn_list: |
| 64 | + if conn.connection_type == "CognitiveSearch": |
| 65 | + print(f"Connection ID: {conn.id}") |
| 66 | +``` |
| 67 | +# [C#](#tab/csharp) |
| 68 | +```csharp |
| 69 | +ListConnectionsResponse connections = await projectClient.GetConnectionsClient().GetConnectionsAsync(ConnectionType.AzureAISearch).ConfigureAwait(false); |
| 70 | + |
| 71 | + if (connections?.Value == null || connections.Value.Count == 0) |
| 72 | + { |
| 73 | + throw new InvalidOperationException("No connections found for the Azure AI Search."); |
| 74 | + } |
| 75 | + |
| 76 | +``` |
| 77 | +--- |
| 78 | +The second way to get the connection ID is to navigate to the project in the Azure AI Foundry and click on the **Connected resources** tab and then select your Azure AI Search resource. |
| 79 | +:::image type="content" source="../../media/tools/ai-search/success-connection.png" alt-text="A screenshot of an AI Search resource connection page in Azure AI Foundry." lightbox="../../media/tools/ai-search/success-connection.png"::: |
| 80 | +In the URL, you see the wsid=/subscription/your-subscription-id..., this is the connection ID you need to use. Copy everything that comes after wsid=. |
| 81 | +:::image type="content" source="../../media/tools/ai-search/connection-id.png" alt-text="A screenshot of an AI Search resource connection and how to copy the connection ID." lightbox="../../media/tools/ai-search/connection-id.png"::: |
| 82 | + |
| 83 | +### Step 3: Configure the Azure AI Search tool |
| 84 | +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. |
| 85 | +# [Python](#tab/python) |
| 86 | +```python |
| 87 | +# TO DO: replace this value with the connection ID of the search index |
| 88 | +conn_id = "/subscriptions/<your-subscription-id>/resourceGroups/<your-resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<your-project-name>/connections/<your-azure-ai-search-connection-name>" |
| 89 | + |
| 90 | +# Initialize agent AI search tool and add the search index connection ID and index name |
| 91 | +# TO DO: replace <your-index-name> with the name of the index you want to use |
| 92 | +ai_search = AzureAISearchTool() |
| 93 | +ai_search.add_index(conn_id, "<your-index-name>") |
| 94 | +``` |
| 95 | +# [C#](#tab/csharp) |
| 96 | +```csharp |
| 97 | +// TO DO: replace this value with the connection ID of the search index |
| 98 | +ConnectionResponse connection = connections.Value[0]; |
| 99 | + |
| 100 | +// Initialize agent Azure AI search tool and add the search index connection ID and index name |
| 101 | +// TO DO: replace <your-index-name> with the name of the index you want to use |
| 102 | +ToolResources searchResource = new ToolResources |
| 103 | +{ |
| 104 | + AzureAISearch = new AzureAISearchResource |
| 105 | + { |
| 106 | + IndexList = { new IndexResource(connection.Id, "<your-index-name>") } |
| 107 | + } |
| 108 | +}; |
| 109 | +``` |
| 110 | +--- |
| 111 | + |
| 112 | +### Step 4: Create an agent with the Azure AI Search tool enabled |
| 113 | +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. |
| 114 | +# [Python](#tab/python) |
| 115 | +```python |
| 116 | +agent = project_client.agents.create_agent( |
| 117 | + model="gpt-4o-mini", |
| 118 | + name="my-assistant", |
| 119 | + instructions="You are a helpful assistant", |
| 120 | + tools=ai_search.definitions, |
| 121 | + tool_resources = ai_search.resources, |
| 122 | + headers={"x-ms-enable-preview": "true"}, |
| 123 | +) |
| 124 | +print(f"Created agent, ID: {agent.id}") |
| 125 | +``` |
| 126 | +# [C#](#tab/csharp) |
| 127 | +```csharp |
| 128 | +AgentsClient agentClient = projectClient.GetAgentsClient(); |
| 129 | + |
| 130 | +Response<Agent> agentResponse = await agentClient.CreateAgentAsync( |
| 131 | + model: "gpt-4o-mini", |
| 132 | + name: "my-assistant", |
| 133 | + instructions: "You are a helpful assistant.", |
| 134 | + tools: new List<ToolDefinition> { new AzureAISearchToolDefinition() }, |
| 135 | + toolResources: searchResource); |
| 136 | +Agent agent = agentResponse.Value; |
| 137 | +``` |
| 138 | +--- |
| 139 | + |
| 140 | +### Step 5: Ask the agent questions about data in the index |
| 141 | +Now that the agent is created, ask it questions about the data in your Azure AI Search index. The example assumes your Azure AI Search index contains information about health care plans. |
| 142 | +# [Python](#tab/python) |
| 143 | +```python |
| 144 | +# Create a thread |
| 145 | +thread = project_client.agents.create_thread() |
| 146 | +print(f"Created thread, thread ID: {thread.id}") |
| 147 | + |
| 148 | +# Create a message |
| 149 | +message = project_client.agents.create_message( |
| 150 | + thread_id=thread.id, |
| 151 | + role="user", |
| 152 | + content="what are my health insurance plan coverage types?", |
| 153 | +) |
| 154 | +print(f"Created message, message ID: {message.id}") |
| 155 | + |
| 156 | +# Run the agent |
| 157 | +run = project_client.agents.create_and_process_run(thread_id=thread.id, assistant_id=agent.id) |
| 158 | +print(f"Run finished with status: {run.status}") |
| 159 | + |
| 160 | +if run.status == "failed": |
| 161 | + # Check if you got "Rate limit is exceeded.", then you want to get more quota |
| 162 | + print(f"Run failed: {run.last_error}") |
| 163 | + |
| 164 | +# Get messages from the thread |
| 165 | +messages = project_client.agents.list_messages(thread_id=thread.id) |
| 166 | +print(f"Messages: {messages}") |
| 167 | + |
| 168 | +assistant_message = "" |
| 169 | +for message in messages.data: |
| 170 | + if message["role"] == "assistant": |
| 171 | + assistant_message = message["content"][0]["text"]["value"] |
| 172 | + |
| 173 | +# Get the last message from the sender |
| 174 | +print(f"Assistant response: {assistant_message}") |
| 175 | +``` |
| 176 | +# [C#](#tab/csharp) |
| 177 | +```csharp |
| 178 | + |
| 179 | +// Create thread for communication |
| 180 | +Response<AgentThread> threadResponse = await agentClient.CreateThreadAsync(); |
| 181 | +AgentThread thread = threadResponse.Value; |
| 182 | + |
| 183 | +// Create message to thread |
| 184 | +Response<ThreadMessage> messageResponse = await agentClient.CreateMessageAsync( |
| 185 | + thread.Id, |
| 186 | + MessageRole.User, |
| 187 | + "Hello, send an email with the datetime and weather information in New York?"); |
| 188 | +ThreadMessage message = messageResponse.Value; |
| 189 | + |
| 190 | +// Run the agent |
| 191 | +Response<ThreadRun> runResponse = await agentClient.CreateRunAsync(thread, agent); |
| 192 | + |
| 193 | +do |
| 194 | +{ |
| 195 | + await Task.Delay(TimeSpan.FromMilliseconds(500)); |
| 196 | + runResponse = await agentClient.GetRunAsync(thread.Id, runResponse.Value.Id); |
| 197 | +} |
| 198 | +while (runResponse.Value.Status == RunStatus.Queued |
| 199 | + || runResponse.Value.Status == RunStatus.InProgress); |
| 200 | + |
| 201 | +Response<PageableList<ThreadMessage>> afterRunMessagesResponse |
| 202 | + = await agentClient.GetMessagesAsync(thread.Id); |
| 203 | +IReadOnlyList<ThreadMessage> messages = afterRunMessagesResponse.Value.Data; |
| 204 | + |
| 205 | +// Note: messages iterate from newest to oldest, with the messages[0] being the most recent |
| 206 | +foreach (ThreadMessage threadMessage in messages) |
| 207 | +{ |
| 208 | + Console.Write($"{threadMessage.CreatedAt:yyyy-MM-dd HH:mm:ss} - {threadMessage.Role,10}: "); |
| 209 | + foreach (MessageContent contentItem in threadMessage.ContentItems) |
| 210 | + { |
| 211 | + if (contentItem is MessageTextContent textItem) |
| 212 | + { |
| 213 | + Console.Write(textItem.Text); |
| 214 | + } |
| 215 | + else if (contentItem is MessageImageFileContent imageFileItem) |
| 216 | + { |
| 217 | + Console.Write($"<image from ID: {imageFileItem.FileId}"); |
| 218 | + } |
| 219 | + Console.WriteLine(); |
| 220 | + } |
| 221 | +} |
| 222 | +``` |
| 223 | +--- |
0 commit comments