1# Azure AI Search Tool
2 
3Ground agent responses with data from an Azure AI Search vector index. Requires a project connection and proper RBAC setup.
4 
5## Prerequisites
6 
7- Azure AI Search index with vector search configured:
8  - One or more `Edm.String` fields (searchable + retrievable)
9  - One or more `Collection(Edm.Single)` vector fields (searchable)
10  - At least one retrievable text field with content for citations
11  - A retrievable field with source URL for citation links
12- A [project connection](../../../project/connections.md) between your Foundry project and search service
13- `azure-ai-projects` package (`pip install azure-ai-projects --pre`)
14 
15## Required RBAC Roles
16 
17For **keyless authentication** (recommended), assign these roles to the **Foundry project's managed identity** on the Azure AI Search resource:
18 
19| Role | Scope | Purpose |
20|------|-------|---------|
21| **Search Index Data Contributor** | AI Search resource | Read/write index data |
22| **Search Service Contributor** | AI Search resource | Manage search service config |
23 
24> **If RBAC assignment fails:** Ask the user to manually assign roles in Azure portal → AI Search resource → Access control (IAM). They need Owner or User Access Administrator on the search resource.
25 
26## Connection Setup
27 
28A project connection between your Foundry project and the Azure AI Search resource is required. See [Project Connections](../../../project/connections.md) for connection management via Foundry MCP tools.
29 
30## Query Types
31 
32| Value | Description |
33|-------|-------------|
34| `SIMPLE` | Keyword search |
35| `VECTOR` | Vector similarity only |
36| `SEMANTIC` | Semantic ranking |
37| `VECTOR_SIMPLE_HYBRID` | Vector + keyword |
38| `VECTOR_SEMANTIC_HYBRID` | Vector + keyword + semantic (default, recommended) |
39 
40## Tool Parameters
41 
42| Parameter | Required | Description |
43|-----------|----------|-------------|
44| `project_connection_id` | Yes | Connection ID (resolve via `project_connection_get`, typically after discovering the connection with `project_connection_list`) |
45| `index_name` | Yes | Search index name |
46| `top_k` | No | Number of results (default: 5) |
47| `query_type` | No | Search type (default: `vector_semantic_hybrid`) |
48| `filter` | No | OData filter applied to all queries |
49 
50## Limitations
51 
52- Only **one index per tool** instance. For multiple indexes, use connected agents each with their own index.
53- Search resource and Foundry agent must be in the **same tenant**.
54- Private AI Search resources require **standard agent deployment** with vNET injection.
55 
56## Troubleshooting
57 
58| Error | Cause | Fix |
59|-------|-------|-----|
60| 401/403 accessing index | Missing RBAC roles | Assign `Search Index Data Contributor` + `Search Service Contributor` to project managed identity |
61| Index not found | Name mismatch | Verify `AI_SEARCH_INDEX_NAME` matches exactly (case-sensitive) |
62| No citations in response | Instructions don't request them | Add citation instructions to agent prompt |
63| Wrong connection endpoint | Connection points to different search resource | Re-create connection with correct endpoint |
64 
65## References
66 
67- [Azure AI Search tool documentation](https://learn.microsoft.com/azure/ai-foundry/agents/how-to/tools/azure-ai-search?view=foundry)
68- [Tool Catalog](https://learn.microsoft.com/azure/ai-foundry/agents/concepts/tool-catalog?view=foundry)
69- [Project Connections](../../../project/connections.md)
70