Use an existing AI Search index with the Azure AI Search tool

2025-08-07

You can use an existing Azure AI Search index with the agent's Azure AI Search tool.

Tip

You can create a new index without leaving the Azure AI Foundry portal. For more information, see the Add the Azure AI Search tool to an agent section.

Azure AI Search indexes must be configured properly and meet the following requirements:

The index must contain at least one searchable & retrievable text field (type Edm.String)
The index must contain at least one searchable vector field (type Collection(Edm.Single))

Search types

You can specify the search type for your index by choosing one of the following

Simple
Semantic
Vector
Hybrid (Vector + Keyword)
Hybrid (Vector + Keyword + Semantic)

You can have indexes without a specified search type. By default, the Azure AI Search tool runs a hybrid search (keyword + vector) on all text fields.

Usage support

Azure AI foundry support	Python SDK	C# SDK	JavaScript SDK	Java SDK	REST API	Basic agent setup	Standard agent setup
✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️

Setup

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 using the import and vectorize data wizard.

Quickstart: Create a vector index with the import and vectorize data wizard in the Azure portal

Create a project connection to the Azure AI Search resource with the index you want to use

Once you complete the 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

Access your Azure AI Search resource.
- In the Azure portal, navigate to the AI Search resource that contains the index you want to use.
Copy the connection endpoint.
- In the Overview tab, copy the URL of your resource. The URL should be in the format https://<your-resource-name>.search.windows.net/.
Verify API Access control is set to Both and copy one of the keys under Manage admin keys.
- From the left-hand navigation bar, scroll down to the Settings section and select Keys.
- Under the API Access Control section, ensure the option Both API key and Role-based access control is selected.
- If you want the connection to use API Keys for authentication, copy one of the keys under Manage admin keys.

Create an Azure AI Search project connection

If you use Microsoft Entra ID for the connection authentication type, you need to manually assign the project managed identity the roles Search Index Data Contributor and Search Service Contributor to the Azure AI Search resource. The connection name must be the AI Search index name.

Create the following connections.yml file

You can use either an API key or keyless YAML configuration file. Replace the name, endpoint, and api_key placeholders with your Azure AI Search resource values. For more information on the YAML configuration file, see the Azure AI Search connection YAML schema.

Here's an API Key example:

name: my_project_acs_connection_keys
type: azure_ai_search
endpoint: https://contoso.search.windows.net/
api_key: XXXXXXXXXXXXXXX

Here's a keyless example:

name: my_project_acs_connection_credentialless
type: azure_ai_search
endpoint: https://contoso.search.windows.net/

Then, run the following command:

Replace my_resource and my_project_name with your resource group and project name created in the agent setup.

az ml connection create --file {connection.yml} --resource-group {my_resource_group} --workspace-name {my_project_name}

To create a project connection to your Azure AI Search resource, replace the my_connection_name, my_endpoint, and my_key (optional) placeholders with your Azure AI Search connection details and run the following code:

from azure.ai.ml.entities import AzureAISearchConnection

# create an Azure AI Search project connection
my_connection_name = "my-connection-name"
my_endpoint = "my-endpoint" # this could also be called target
my_api_keys = None # leave blank for Authentication type = AAD

my_connection = AzureAISearchConnection(name=my_connection_name,
                                    endpoint=my_endpoint, 
                                    api_key= my_api_keys)

# Create the connection
ml_client.connections.create_or_update(my_connection)

Now that you created a project connection to your Azure AI Search resource, you can configure and start using the Azure AI Search tool with the SDK. See the code examples tab to get started.

Add the Azure AI Search tool to an agent

You can add the Azure AI Search tool to an agent programmatically using the code examples listed at the top of this article, or the Azure AI Foundry portal. If you want to use the portal:

In the Agents screen for your agent, scroll down the Setup pane. Then select Knowledge > + Add.
Select Azure AI Search.
Under Connect to an index, you can either select an existing Azure AI Search connection or create a new one. Let's select Indexes that are not part of this project.
Select an existing Azure AI Search connection. You can create a new one in the Azure portal and then return to this wizard.
After you select the connection, you can select or create an index to use with the Azure AI Search tool. Let's select Create a new index.

Tip

You can create a new index without leaving the Azure AI Foundry portal. If you select Create a new index, you're prompted to provide the index name and select the search type.
Enter the index name, connect your data, choose an embedding model, and agree to the terms. Then select Create index.
The index is created and connected to the Azure AI Search service. You can now use the index with the Azure AI Search tool in your agent. You can also use the index outside of the agent, such as the Azure AI Search REST API or SDKs.