You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
In Azure AI Search, a *knowledge agent* is a top-level resource representing a connection to a conversational language model for use in agentic retrieval workloads. It specifies a model that provides reasoning capabilities, and it identifies the search index used at query time.
18
+
In Azure AI Search, a *knowledge agent* is a top-level resource representing a connection to a chat completion model for use in agentic retrieval workloads. A knowledge agent is used by the [retrieve method](search-agentic-retrieval-how-to-retrieve.md) in an LLM-powered information retrieval pipeline.
19
+
20
+
A knowledge agent specifies:
21
+
22
+
+ A model that provides reasoning capabilities
23
+
+ A target search index used at query time
24
+
+ Parameters on the index for setting default behaviors and response shaping
19
25
20
26
After you can create a knowledge agent, you can update its properties at any time. If the knowledge agent is in use, updates take effect on the next job.
21
27
22
28
## Prerequisites
23
29
24
30
+ Familiarity with [agentic retrieval concepts and use cases](search-agentic-retrieval-concept.md).
25
31
26
-
+ A conversational language model on Azure OpenAI, either gpt-4o or gpt-4o-mini.
32
+
+ A [supported chat completion model](#supported-models) on Azure OpenAI.
27
33
28
-
+ Azure AI Search, in any [region that provides semantic ranker](search-region-support.md), on basic tier and above. Your search service must have a [managed identity](search-howto-managed-identities-data-sources.md) for role-based access to a chat model.
34
+
+ Azure AI Search, in any [region that provides semantic ranker](search-region-support.md), on the basic pricing tier or higher. Your search service must have a [managed identity](search-howto-managed-identities-data-sources.md) for role-based access to the model.
29
35
30
-
+Permission requirements on Azure AI Search. An **Owner/Contributor** or **Search Service Contributor** can create and manage a knowledge agent. **Search Index Data Contributor** uploads and indexes document. **Search Index Data Reader**runs queries. Instructions are provided in this article.
36
+
+Permissions on Azure AI Search. **Search Service Contributor** can create and manage a knowledge agent. **Search Index Data Reader**can run queries. Instructions are provided in this article.
31
37
32
-
+ A search index containing plain text or vectors. The index must [meet requirements for agentic retrieval](search-agentic-retrieval-how-to-index.md), including a [semantic configuration](semantic-how-to-configure.md) with the `defaultConfiguration` specified.
38
+
+ A search index containing plain text or vectors. The index must [meet the requirements for agentic retrieval](search-agentic-retrieval-how-to-index.md), including a [semantic configuration](semantic-how-to-configure.md) with the `defaultConfiguration` specified.
33
39
34
-
+ API requirements. To create or use a knowledge agent, use 2025-05-01-preview data plane REST API or a prerelease package of an Azure SDK that provides knowledge agent APIs.
40
+
+ API requirements. To create or use a knowledge agent, use [2025-05-01-preview](/rest/api/searchservice/operation-groups?view=rest-searchservice-2025-05-01-preview&preserve-view=true) data plane REST API. Or, use a prerelease package of an Azure SDK that provides knowledge agent APIs: [Azure SDK for Python](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/search/azure-search-documents/CHANGELOG.md), [Azure SDK for .NET](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/search/Azure.Search.Documents/CHANGELOG.md#1170-beta3-2025-03-25), [Azure SDK for Java](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/search/azure-search-documents/CHANGELOG.md).
35
41
36
-
To follow the steps in this guide, we recommend [Visual Studio Code](https://code.visualstudio.com/download) with a [REST client](https://marketplace.visualstudio.com/items?itemName=humao.rest-client) for sending REST API calls to Azure AI Search. There's no portal support at this time.
42
+
To follow the steps in this guide, we recommend [Visual Studio Code](https://code.visualstudio.com/download) with a [REST client](https://marketplace.visualstudio.com/items?itemName=humao.rest-client) for sending preview REST API calls to Azure AI Search. There's no portal support at this time.
37
43
38
44
## Deploy a model for agentic retrieval
39
45
@@ -43,7 +49,9 @@ Make sure you have a supported model that Azure AI Search can access. The follow
43
49
44
50
1. Deploy a supported model using [these instructions](/azure/ai-foundry/how-to/deploy-models-openai).
45
51
46
-
1. Verify the search service managed identity has **Cognitive Services User** permissions on the Azure OpenAI resource. If you're testing locally, you also need **Cognitive Services User** permissions.
52
+
1. Verify the search service managed identity has **Cognitive Services User** permissions on the Azure OpenAI resource.
53
+
54
+
If you're testing locally, you also need **Cognitive Services User** permissions.
47
55
48
56
### Supported models
49
57
@@ -97,34 +105,37 @@ You can use API keys if you don't have permission to create role assignments.
97
105
98
106
# List Indexes
99
107
GET https://{{search-url}}/indexes?api-version=2025-05-01-preview
100
-
api-key: {{search-api-key}}
108
+
Content-Type: application/json
109
+
@api-key: {{search-api-ke}}
101
110
```
102
111
103
112
## Check for existing knowledge agents
104
113
105
-
The following request lists knowledge agents by name. Within the knowledge agents collection, all knowledge agents must be uniquely named. It's helpful for knowing about existing knowledge agents for reuse or naming purposes.
114
+
The following request lists knowledge agents by name on your search service. Within the knowledge agents collection, all knowledge agents are uniquely named. It's helpful for knowing about existing knowledge agents for reuse or naming purposes.
106
115
107
116
<!-- ### [**REST APIs**](#tab/rest-get) -->
108
117
109
118
```http
110
119
# List knowledge agents
111
120
GET https://{{search-url}}/agents?api-version=2025-05-01-preview
112
-
api-key: {{search-api-key}}
121
+
Content-Type: application/json
122
+
Authorization: Bearer {{accessToken}}
113
123
```
114
124
115
-
You can also return a single agent by name.
125
+
You can also return a single agent by name to review its JSON definition.
116
126
117
127
```http
118
128
# Get knowledge agent
119
129
GET https://{{search-url}}/agents/{{agent-name}}?api-version=2025-05-01-preview
120
-
api-key: {{search-api-key}}
130
+
Content-Type: application/json
131
+
Authorization: Bearer {{accessToken}}
121
132
```
122
133
123
134
<!-- --- -->
124
135
125
136
## Create a knowledge agent
126
137
127
-
A knowledge agent represents a connection to a model that you've deployed. Parameters on the model establish the connection.
138
+
A knowledge agent represents a connection between a model that you've deployed in Azure OpenAI and a target index on Azure AI Search. Parameters on the model establish the connection. Parameters on the index establish defaults that inform query execution and the response.
128
139
129
140
<!-- ### [**REST APIs**](#tab/rest-create) -->
130
141
@@ -136,12 +147,12 @@ To create an agent, use the 2025-05-01-preview data plane REST API or an Azure S
+`name` must be unique within the knowledge agents collection it must adhere to [naming rules](/rest/api/searchservice/naming-rules) for objects on Azure AI Search.
188
+
+`name` must be unique within the knowledge agents collection and follow the [naming guidelines](/rest/api/searchservice/naming-rules) for objects on Azure AI Search.
178
189
179
190
+`targetIndexes` is required for knowledge agent creation. It lists the search indexes that can use the knowledge agent. Currently in this preview release, the `targetIndexes` array can contain only one index. *It must have a default semantic configuration* (`defaultConfiguration`). For more information, see [Design an index for agentic retrieval](search-agentic-retrieval-how-to-index.md).
180
191
@@ -213,8 +224,8 @@ Replace "What are my vision benefits?" with a query string that's valid for your
213
224
```http
214
225
# Send Grounding Request
215
226
POST https://{{search-url}}/agents/{{agent-name}}/retrieve?api-version=2025-05-01-preview
216
-
api-key: {{search-api-key}}
217
-
Content-Type: application/json
227
+
Content-Type: application/json
228
+
Authorization: Bearer {{accessToken}}
218
229
219
230
{
220
231
"messages" : [
@@ -247,14 +258,18 @@ For more information about the **retrieve** API and the shape of the response, s
247
258
248
259
## Delete an agent
249
260
261
+
If you no longer need the agent, or if you need to rebuild it on the search service, use this request to delete the current object.
0 commit comments