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
If you're new to using Microsoft Entra ID for authentication see [How to configure Azure OpenAI in Azure AI Foundry Models with Microsoft Entra ID authentication](../how-to/managed-identity.md).
159
159
160
160
```python
161
-
from openai importAzureOpenAI
161
+
from openai importOpenAI
162
162
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
If you're new to using Microsoft Entra ID for authentication see [How to configure Azure OpenAI with Microsoft Entra ID authentication](../how-to/managed-identity.md).
372
371
373
372
```python
374
-
from openai importAzureOpenAI
373
+
from openai importOpenAI
375
374
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
> Full v1 GA support for the OpenAI Python library with Microsoft Entra ID is coming soon. The example below will be replaced once support is added. To learn more, check out the [API lifecycle guide](../api-version-lifecycle.md#api-evolution).
114
-
115
112
```python
116
-
from openai importAzureOpenAI
113
+
from openai importOpenAI
117
114
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
> Full v1 GA support for the OpenAI Python library with Microsoft Entra ID is coming soon. The older preview API example below will be replaced once support is added. To learn more, check out the [API lifecycle guide](../api-version-lifecycle.md#api-evolution).
243
-
244
237
```python
245
-
from openai importAzureOpenAI
238
+
from openai importOpenAI
246
239
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
Copy file name to clipboardExpand all lines: articles/search/search-agentic-retrieval-how-to-retrieve.md
+19-25Lines changed: 19 additions & 25 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -67,7 +67,7 @@ POST https://{{search-url}}/agents/{{agent-name}}/retrieve?api-version=2025-08-0
67
67
"content" : [
68
68
{ "type" : "text", "text" : "You can answer questions about the Earth at night.
69
69
Sources have a JSON format with a ref_id that must be cited in the answer.
70
-
If you do not have the answer, respond with "I don't know"." }
70
+
If you do not have the answer, respond with 'I don't know'." }
71
71
]
72
72
},
73
73
{
@@ -77,39 +77,29 @@ POST https://{{search-url}}/agents/{{agent-name}}/retrieve?api-version=2025-08-0
77
77
]
78
78
}
79
79
],
80
-
"targetIndexParams" : [
81
-
{
82
-
"indexName" : "{{index-name}}",
83
-
"filterAddOn" : "page_number eq '105'",
84
-
"IncludeReferenceSourceData": true,
85
-
"rerankerThreshold" : 2.5,
86
-
"maxDocsForReranker": 50
87
-
}
88
-
]
80
+
"knowledgeSourceParams": [
81
+
{
82
+
"filterAddOn": null,
83
+
"knowledgeSourceName": "earth-at-night-blob-ks",
84
+
"kind": "searchIndex"
85
+
}
86
+
]
89
87
}
90
88
```
91
89
92
90
**Key points**:
93
91
92
+
+ The retrieve action targets a [knowledge agent](search-agentic-retrieval-how-to-create.md). The knowledge agent specifies one or more knowledge sources and a knowledge source configuration. Review your knowledge agent definition for output and semantic ranking configuration.
93
+
94
94
+`messages` articulates the messages sent to the model. The message format is similar to Azure OpenAI APIs.
95
95
96
96
+`role` defines where the message came from, for example either `assistant` or `user`. The model you use determines which roles are valid.
97
97
98
-
+`content` is the message sent to the LLM. It must be text in this preview.
99
-
100
-
+`targetIndexParams` provide instructions on the retrieval. Currently in this preview, you can only target a single index.
101
-
102
-
+`filterAddOn` lets you set an [OData filter expression](search-filters.md) for keyword or hybrid search.
98
+
+`content` is the message or prompt sent to the LLM. It must be text in this preview.
103
99
104
-
+`IncludeReferenceSourceData` tells the retrieval engine to return the source content in the response. This value is initially set in the knowledge agent definition. You can override that setting in the retrieve action to return original source content in the [references section](#review-the-references-array) of the response.
100
+
+[`knowledgeSourceParams`](/rest/api/searchservice/knowledge-retrieval/retrieve?view=rest-searchservice-2025-08-01-preview#searchindexknowledgesourceparams&preserve-view=true) is optional. Specify a knowledge source if the agent has more than one, and you want to focus the retrieve action on just one knowledge source. If the knowledge agent has just one knowledge source with the configuration you want, you can omit this section.
105
101
106
-
+`rerankerThreshold` and `maxDocsForReranker` are also initially set in the knowledge agent definition as defaults. You can override them in the retrieve action to configure [semantic reranker](semantic-how-to-configure.md), setting minimum thresholds and the maximum number of inputs sent to the reranker.
107
-
108
-
`rerankerThreshold` is the minimum semantic reranker score that's acceptable for inclusion in a response. [Reranker scores](semantic-search-overview.md#how-results-are-scored) range from 1 to 4. Plan on revising this value based on testing and what works for your content.
109
-
110
-
`maxDocsForReranker` dictates the maximum number of documents to consider for the final response string. Semantic reranker accepts 50 documents. If the maximum is 200, four more subqueries are added to the query plan to ensure all 200 documents are semantically ranked. for semantic ranking. If the number isn't evenly divisible by 50, the query plan rounds up to nearest whole number.
111
-
112
-
The `content` portion of the response consists of the 200 chunks or less, excluding any results that fail to meet the minimum threshold of a 2.5 reranker score.
102
+
A knowledge source specification on the retrieve action describes the target search index on the search service. So even if the knowledge source "kind" is Azure blob, the valid value here is `searchIndex`. In this first public preview release, `knowledgeSourceParams.kind` is always `searchIndex`.
113
103
114
104
## Review the extracted response
115
105
@@ -133,9 +123,13 @@ The body of the response is also structured in the chat message style format. Cu
133
123
134
124
**Key points**:
135
125
136
-
+`content` is a JSON array. It's a single string composed of the most relevant documents (or chunks) found in the search index, given the query and chat history inputs. This array is your grounding data that a chat completion model uses to formulate a response to the user's question.
126
+
+`content.text` is a JSON array. It's a single string composed of the most relevant documents (or chunks) found in the search index, given the query and chat history inputs. This array is your grounding data that a chat completion model uses to formulate a response to the user's question.
127
+
128
+
This portion of the response consists of the 200 chunks or less, excluding any results that fail to meet the minimum threshold of a 2.5 reranker score.
129
+
130
+
The string starts with the reference ID of the chunk (used for citation purposes), and any fields specified in the semantic configuration of the target index. In this example, you should assume the semantic configuration in the target index has a "title" field, a "terms" field, and a "content" field.
137
131
138
-
+"text" is the only valid value for `type`, and it consists of the reference ID of the chunk (used for citation purposes), and any fields specified in the semantic configuration of the target index. In this example, you should assume the semantic configuration in the target index has a "title" field, a "terms" field, and a "content" field.
132
+
+`content.type` has one valid value in this preview: `text`.
139
133
140
134
> [!NOTE]
141
135
> The `maxOutputSize` property on the [knowledge agent](search-agentic-retrieval-how-to-create.md) determines the length of the string. We recommend 5,000 tokens.
![learn-build-service-prod[bot]](https://avatars.githubusercontent.com/in/237442?v=4&size=40){kind=avatar}
0 commit comments