Azure AI Search tool

2025-10-24

The Azure AI Search tool in Azure AI Foundry Agent Service connects an agent to a new or existing search index. You can use this tool to retrieve and summarize your indexed documents, grounding the agent's responses in your proprietary content.

This article describes how to set up the Azure AI Search tool, including creating a project connection and adding the tool to your agent.

Prerequisites

An Azure AI Foundry agent.
An Azure AI Search index configured for vector search. The index must include:
- One or more Edm.String (text) fields attributed as searchable and retrievable.
- One or more Collection(Edm.Single) (vector) fields attributed as searchable.

Tip

Instead of using an existing index, you can create an index without leaving the Azure AI Foundry portal. For more information, see the Add the tool to an agent section.

Usage support

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

Limitations

To use the Azure AI Search tool in the Azure AI Foundry portal behind a virtual network, you must create an agent using the SDK or REST API. After you create the agent programmatically, you can then use it in the portal.
The Azure AI Search tool can only target one index. To use multiple indexes, consider using connected agents, each with a configured index.
An Azure AI Foundry resource with basic agent deployments do not support private Azure AI Search resources, nor Azure AI Search with public network access disabled and a private endpoint. To use a private Azure AI Search tool with your agents, deploy the standard agent with virtual network injection.

Setup

In this section, you create a connection between the Azure AI Foundry project that contains your agent and the Azure AI Search service that contains your index.

If you already connected your project to your search service, skip this section.

Get search service connection details

The project connection requires the endpoint of your search service and either key-based authentication or keyless authentication with Microsoft Entra ID.

For keyless authentication, you must enable role-based access control (RBAC) and assign roles to your project's managed identity. Although this method involves extra steps, it enhances security by eliminating the need for hard-coded API keys.

Select the tab for your desired authentication method.

Key-based authentication
Keyless authentication

Sign in to the Azure portal and select your search service.
To get the endpoint:
1. From the left pane, select Overview.
2. Make a note of the URL, which should look like https://my-service.search.windows.net.
To get the API key:
1. From the left pane, select Settings > Keys.
2. Select Both to enable both key-based and keyless authentication, which is recommended for most scenarios.
3. Make a note of one of the keys under Manage admin keys.

Sign in to the Azure portal and select your search service.
To get the endpoint:
1. From the left pane, select Overview.
2. Make a note of the URL, which should look like https://my-service.search.windows.net.
To enable RBAC:
1. From the left pane, select Settings > Keys.
2. Select Both to enable both key-based and keyless authentication, which is recommended for most scenarios.
To assign the necessary roles:
1. From the left pane, select Access control (IAM).
2. Select Add > Add role assignment.
3. Assign the Search Index Data Contributor role to the managed identity of your project.
4. Repeat the role assignment for Search Service Contributor.

Create the project connection

The next step is to create the project connection using the search service details you gathered. The connection name must be the name of your search index. For more information about this step, see Add a new connection to your project.

Select the tab for your desired usage method.

Create the following connections.yml file:

You can use a YAML configuration file for both key-based and keyless authentication. Replace the name, endpoint, and api_key (optional) placeholders with your search service details. For more information, see the Azure AI Search connection YAML schema.

Here's a key-based 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_keyless
type: azure_ai_search
endpoint: https://contoso.search.windows.net/

Then, run the following command:

Replace my_resource with the resource group that contains your project and my_project_name with the name of your project.

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

Replace the my_connection_name, my_endpoint, and my_key (optional) placeholders with your search service details, and then 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)

Add the tool to an agent

You can add the Azure AI Search tool to an agent programmatically or through the Azure AI Foundry portal. For programmatic examples, see Use an existing index with the Azure AI Search tool.

To add the tool through the portal:

From the left pane, select Agents.
Select your agent from the list, and then select Knowledge > Add.
Select Azure AI Search.
Under Connect to an index, select Indexes that are not part of this project.
Under Azure AI Search resource connection, select the project connection you created in the previous section.
Under Azure AI Search index, select your vector index.

Tip

If you don't have an index, select Create a new index. You're then prompted to name the index, connect to a data source, select an existing embedding model deployment, and agree to the terms.

After you create the index, you can use it both inside and outside your agent. For example, you can use the index with the Azure AI Search REST APIs or SDKs.
Under Display name, enter the name of your index.
Depending on your index configuration, choose one of the following search types:
- Simple
- Semantic
- Vector
- Hybrid (vector + keyword)
- Hybrid + semantic
By default, the Azure AI Search tool runs a hybrid search (vector + keyword) on all text fields.
Select Connect to add the Azure AI Search tool to your agent.