Foundry IQ (Azure AI Search) tool (classic)

Note

This document refers to the Microsoft Foundry (classic) agents.

🔍 View the new Foundry IQ (Azure AI Search) tool documentation. Agents (classic) are now deprecated and will be retired on March 31, 2027. Use the new agents in the generally available Microsoft Foundry Agents Service. Follow the migration guide to update your workloads.

The Foundry IQ tool in 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 Foundry IQ tool, including creating a project connection and adding the tool to your agent.

Prerequisites

Tip

Instead of using an existing index, you can create an index without leaving the 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 Foundry IQ tool in the 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 Foundry IQ tool can only target one index. To use multiple indexes, consider using connected agents, each with a configured index.

  • A Foundry resource with basic agent deployments does not support private Foundry IQ resources, nor Foundry IQ with public network access disabled and a private endpoint. To use a private Foundry IQ tool with your agents, deploy the standard agent with virtual network injection.

  • If you disabled public network access on your Foundry IQ resource, configure the connection to use managed identity (keyless authentication) instead of an API key. API key-based connections can't reach a Foundry IQ service that has public network access disabled.

  • Your Foundry IQ resource and Foundry Agent need to be in the same tenant.

Setup

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

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

Get Foundry IQ service connection details

The project connection requires the endpoint of your Foundry IQ 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.

  1. Sign in to the Azure portal and select your Foundry IQ service.

  2. 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.

      A screenshot of an AI Search resource Overview tab in the Azure portal.

  3. 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.

      A screenshot of an AI Search resource Keys tab in the Azure portal.

    3. Make a note of one of the keys under Manage admin keys.

Create the project connection

The next step is to create the project connection using the Foundry IQ 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 Foundry IQ service details. For more information, see the Foundry IQ 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}

Add the tool to an agent

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

To add the tool through the portal:

  1. From the left pane, select Agents.

  2. Select your agent from the list, and then select Knowledge > Add.

    A screenshot showing the available tool categories in the Foundry portal.

  3. Select Foundry IQ.

    A screenshot showing the available knowledge tools in the Foundry portal.

  4. Under Connect to an index, select Indexes that are not part of this project.

  5. Under Foundry IQ resource connection, select the project connection you created in the previous section.

  6. Under Foundry IQ 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 Foundry IQ REST APIs or SDKs.

  7. Under Display name, enter the name of your index.

  8. Depending on your index configuration, choose one of the following search types:

    • Simple
    • Semantic
    • Vector
    • Hybrid (vector + keyword)
    • Hybrid + semantic

    By default, the Foundry IQ tool runs a hybrid search (vector + keyword) on all text fields.

  9. Select Connect to add the Foundry IQ tool to your agent.

    A screenshot of the Connect button in the Foundry portal.

Next step

Try some programmatic examples of configuring and using the Foundry IQ tool: