@@ -582,15 +582,18 @@ To surface document-embedded images (such as diagrams or scans) in answer synthe
 
 ## Known errors
 
-If you get the following similar temporary error when creating a knowledge source with `contentExtractionMode` with `Standard` as a value:
+When you create this knowledge source with `contentExtractionMode` set to `standard`, you might get the following error.
+
+```json
 Failed to create custom analyzer 'azs_tmp': BadRequest - {"error":{"code":"InvalidRequest","message":"Invalid request.","innererror":{"code":"DefaultsNotSet","message":"Defaults have not yet been set. Call 'PATCH /contentunderstanding/defaults' first."}}}
+```
 
-Refer to [this Content Understanding setup](/azure/ai-services/content-understanding/tutorial/create-custom-analyzer?tabs=portal%2Cdocument&pivots=programming-language-rest#prerequisites) so you can define the default values, so you can proceed with the knowledge store creation, right after.
+To resolve the error, define the default values as instructed in the [Content Understanding prerequisites](/azure/ai-services/content-understanding/tutorial/create-custom-analyzer?tabs=portal%2Cdocument&pivots=programming-language-rest#prerequisites). Afterwards, you can proceed with creating the knowledge source.
 
 ## Related content
 
 + [Agentic retrieval in Azure AI Search](agentic-retrieval-overview.md)
 + [What is a knowledge source?](agentic-knowledge-source-overview.md)
 + [Create a knowledge base](agentic-retrieval-how-to-create-knowledge-base.md)
 + [Query a knowledge base](agentic-retrieval-how-to-retrieve.md)
-+ [Blob knowledge source Python sample](https://github.com/Azure/azure-search-vector-samples/blob/main/demo-python/code/knowledge/blob-knowledge-source.ipynb)
++ [Python sample: Azure AI Search blob knowledge source](https://github.com/Azure/azure-search-vector-samples/blob/main/demo-python/code/knowledge/blob-knowledge-source.ipynb)

@@ -308,7 +308,7 @@ The following ingestion parameter properties control how uploaded files are proc
 
 After the knowledge source exists, upload files directly to it. Each upload is a synchronous call: Azure AI Search extracts content from the uploaded file, chunks the content, creates embeddings when needed, and prepares the extracted content for retrieval before the call returns. You don't have to configure or run a separate ingestion pipeline.
 
-The request body contains the file content. The listed `fileName` is taken from the `Content-Disposition: attachment; filename="..."` header on the upload request. If the header isn't set, the service assigns an auto-generated `fileName`. SDKs can set the header through the upload method parameters shown in the following examples.
+The listed `fileName` is taken from the `Content-Disposition: attachment; filename="..."` header on the upload request. REST calls and the .NET SDK set this header directly, while the Python SDK accepts a `filename` parameter and builds the header automatically. If the header isn't set, the service assigns an auto-generated `fileName`.
 
 ::: zone pivot="csharp"
 
@@ -331,6 +331,8 @@ KnowledgeSourceFile uploadedFile = (await indexClient.UploadKnowledgeSourceFileA
 Console.WriteLine($"Uploaded file ID: {uploadedFile.FileId}");
 ```
 
+**Reference:** [SearchIndexClient.UploadKnowledgeSourceFileAsync](/dotnet/api/azure.search.documents.indexes.searchindexclient.uploadknowledgesourcefileasync?view=azure-dotnet-preview&preserve-view=true)
+
 ::: zone-end
 
 ::: zone pivot="python"
@@ -352,6 +354,8 @@ uploaded_file = index_client.upload_knowledge_source_file(
 print(f"Uploaded file ID: {uploaded_file.file_id}")
 ```
 
+**Reference:** [SearchIndexClient.upload_knowledge_source_file](/python/api/azure-search-documents/azure.search.documents.indexes.searchindexclient?view=azure-python-preview&preserve-view=true#azure-search-documents-indexes-searchindexclient-upload-knowledge-source-file)
+
 ::: zone-end
 
 ::: zone pivot="rest"
@@ -365,6 +369,8 @@ Content-Disposition: attachment; filename="installation-guide.pdf"
 <binary file content>
 ```
 
+**Reference:** [Knowledge Sources - Upload File](/rest/api/searchservice/knowledge-sources/upload-file?view=rest-searchservice-2026-05-01-preview&preserve-view=true)
+
 ::: zone-end
 
 > [!NOTE]
@@ -391,6 +397,8 @@ await foreach (KnowledgeSourceFile file in indexClient.GetKnowledgeSourceFilesAs
 }
 ```
 
+**Reference:** [SearchIndexClient.GetKnowledgeSourceFilesAsync](/dotnet/api/azure.search.documents.indexes.searchindexclient.getknowledgesourcefilesasync?view=azure-dotnet-preview&preserve-view=true)
+
 ::: zone-end
 
 ::: zone pivot="python"
@@ -405,6 +413,8 @@ for file in index_client.list_knowledge_source_files("my-file-ks"):
     print(f"{file.file_name} ({file.file_size_bytes} bytes) error={file.error_message}")
 ```
 
+**Reference:** [SearchIndexClient.list_knowledge_source_files](/python/api/azure-search-documents/azure.search.documents.indexes.searchindexclient?view=azure-python-preview&preserve-view=true#azure-search-documents-indexes-searchindexclient-list-knowledge-source-files)
+
 ::: zone-end
 
 ::: zone pivot="rest"
@@ -414,6 +424,8 @@ GET {{search-url}}/knowledgesources/my-file-ks/files?api-version=2026-05-01-prev
 api-key: {{api-key}}
 ```
 
+**Reference:** [Knowledge Sources - List Files](/rest/api/searchservice/knowledge-sources/list-files?view=rest-searchservice-2026-05-01-preview&preserve-view=true)
+
 ::: zone-end
 
 A response includes metadata for each uploaded file. The `errorMessage` value is `null` when the upload is processed without an error.
@@ -450,6 +462,8 @@ var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new AzureKeyCre
 await indexClient.DeleteKnowledgeSourceFileAsync("my-file-ks", "file-abc123");
 ```
 
+**Reference:** [SearchIndexClient.DeleteKnowledgeSourceFileAsync](/dotnet/api/azure.search.documents.indexes.searchindexclient.deleteknowledgesourcefileasync?view=azure-dotnet-preview&preserve-view=true)
+
 ::: zone-end
 
 ::: zone pivot="python"
@@ -463,6 +477,8 @@ index_client = SearchIndexClient(endpoint="search_url", credential=AzureKeyCrede
 index_client.delete_knowledge_source_file("my-file-ks", "file-abc123")
 ```
 
+**Reference:** [SearchIndexClient.delete_knowledge_source_file](/python/api/azure-search-documents/azure.search.documents.indexes.searchindexclient?view=azure-python-preview&preserve-view=true#azure-search-documents-indexes-searchindexclient-delete-knowledge-source-file)
+
 ::: zone-end
 
 ::: zone pivot="rest"
@@ -472,6 +488,8 @@ DELETE {{search-url}}/knowledgesources/my-file-ks/files/file-abc123?api-version=
 api-key: {{api-key}}
 ```
 
+**Reference:** [Knowledge Sources - Delete File](/rest/api/searchservice/knowledge-sources/delete-file?view=rest-searchservice-2026-05-01-preview&preserve-view=true)
+
 ::: zone-end
 
 ## Assign to a knowledge base

@@ -563,10 +563,13 @@ To surface document-embedded images (such as diagrams or scans) in answer synthe
 
 ## Known errors
 
-If you get the following similar temporary error when creating a knowledge source with `contentExtractionMode` with `Standard` as a value:
+When you create this knowledge source with `contentExtractionMode` set to `standard`, you might get the following error.
+
+```json
 Failed to create custom analyzer 'azs_tmp': BadRequest - {"error":{"code":"InvalidRequest","message":"Invalid request.","innererror":{"code":"DefaultsNotSet","message":"Defaults have not yet been set. Call 'PATCH /contentunderstanding/defaults' first."}}}
+```
 
-Refer to [this Content Understanding setup](/azure/ai-services/content-understanding/tutorial/create-custom-analyzer?tabs=portal%2Cdocument&pivots=programming-language-rest#prerequisites) so you can define the default values, so you can proceed with the knowledge store creation, right after.
+To resolve the error, define the default values as instructed in the [Content Understanding prerequisites](/azure/ai-services/content-understanding/tutorial/create-custom-analyzer?tabs=portal%2Cdocument&pivots=programming-language-rest#prerequisites). Afterwards, you can proceed with creating the knowledge source.
 
 ## Related content
 

@@ -360,11 +360,13 @@ To surface document-embedded images (such as diagrams or scans) in answer synthe
 
 ## Known errors
 
-If you get the following similar temporary error when creating a knowledge source with `contentExtractionMode` with `Standard` as a value:
-Failed to create custom analyzer 'azs_tmp': BadRequest - {"error":{"code":"InvalidRequest","message":"Invalid request.","innererror":{"code":"DefaultsNotSet","message":"Defaults have not yet been set. Call 'PATCH /contentunderstanding/defaults' first."}}}
+When you create this knowledge source with `contentExtractionMode` set to `standard`, you might get the following error.
 
-Refer to [this Content Understanding setup](/azure/ai-services/content-understanding/tutorial/create-custom-analyzer?tabs=portal%2Cdocument&pivots=programming-language-rest#prerequisites) so you can define the default values, so you can proceed with the knowledge store creation, right after.
+```json
+Failed to create custom analyzer 'azs_tmp': BadRequest - {"error":{"code":"InvalidRequest","message":"Invalid request.","innererror":{"code":"DefaultsNotSet","message":"Defaults have not yet been set. Call 'PATCH /contentunderstanding/defaults' first."}}}
+```
 
+To resolve the error, define the default values as instructed in the [Content Understanding prerequisites](/azure/ai-services/content-understanding/tutorial/create-custom-analyzer?tabs=portal%2Cdocument&pivots=programming-language-rest#prerequisites). Afterwards, you can proceed with creating the knowledge source.
 
 ## Related content
 

@@ -5,6 +5,7 @@ ms.service: azure-ai-search
 ms.topic: how-to
 ms.date: 06/02/2026
 ai-usage: ai-assisted
+zone_pivot_groups: search-csharp-python-rest
 ---
 
 # Use answer synthesis for citation-backed responses in Azure AI Search (preview)
@@ -32,7 +33,7 @@ You can enable answer synthesis in two ways:
 > [!IMPORTANT]
 > + The `minimal` retrieval reasoning effort disables LLM processing, so it's incompatible with answer synthesis in both knowledge base definitions and retrieval requests. For more information, see [Set the retrieval reasoning effort](agentic-retrieval-how-to-set-retrieval-reasoning-effort.md).
 >
-> + Answer synthesis incurs pay-as-you-go charges from Azure OpenAI, which is based on the number of input and output tokens. Charges appear under the LLM assigned to the knowledge base. For more information, see [Availability and pricing of agentic retrieval](agentic-retrieval-overview.md#availability-and-pricing).
+> + Answer synthesis incurs pay-as-you-go charges from Azure OpenAI, which are based on the number of input and output tokens. Charges appear under the LLM assigned to the knowledge base. For more information, see [Availability and pricing of agentic retrieval](agentic-retrieval-overview.md#availability-and-pricing).
 
 ## Prerequisites
 
@@ -42,43 +43,59 @@ You can enable answer synthesis in two ways:
 
 + For outbound calls to the LLM, the search service must have a [managed identity](search-how-to-managed-identities.md) with **Cognitive Services User** permissions on the Microsoft Foundry resource.
 
-+ The [2026-05-01-preview](/rest/api/searchservice/knowledge-bases/create-or-update?view=rest-searchservice-2026-05-01-preview&preserve-view=true) REST API or an equivalent Azure SDK preview package: [.NET](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/search/Azure.Search.Documents/CHANGELOG.md) | [Java](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/search/azure-search-documents/CHANGELOG.md) | [JavaScript](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/search/search-documents/CHANGELOG.md) | [Python](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/search/azure-search-documents/CHANGELOG.md)
+:::zone pivot="csharp"
 
-## Enable answer synthesis in a knowledge base
++ The latest [`Azure.Search.Documents`](https://www.nuget.org/packages/Azure.Search.Documents) preview package: `dotnet add package Azure.Search.Documents --prerelease`
 
-This section explains how to enable answer synthesis in an existing knowledge base. Although you can use this configuration for new knowledge bases, knowledge base creation is beyond the scope of this article.
+:::zone-end
 
-To enable answer synthesis in a knowledge base:
+:::zone pivot="python"
 
-1. Use the 2026-05-01-preview of [Knowledge Base - Create or Update (REST API)](/rest/api/searchservice/knowledge-bases/create-or-update?view=rest-searchservice-2026-05-01-preview&preserve-view=true) to formulate the request.
++ The latest [`azure-search-documents`](https://pypi.org/project/azure-search-documents/#history) preview package: `pip install --pre azure-search-documents`
 
-1. In the body of the request, set `outputMode` to `answerSynthesis`.
+:::zone-end
 
-1. (Optional) Use `answerInstructions` to customize the answer output. Our example instructs the knowledge base to `Use concise bulleted lists`.
+:::zone pivot="rest"
 
-```http
-@search-url = <YOUR SEARCH SERVICE URL>
-@api-key = <YOUR API KEY>
-@knowledge-base-name = <YOUR KNOWLEDGE BASE NAME>
++ The [2026-05-01-preview](/rest/api/searchservice/operation-groups?view=rest-searchservice-2026-05-01-preview&preserve-view=true) version of the Search Service REST APIs.
 
-### Enable answer synthesis in a knowledge base
-PUT {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version=2026-05-01-preview
-Content-Type: application/json
-api-key: {{api-key}}
+:::zone-end
 
+## Enable answer synthesis in a knowledge base
+
+This section explains how to enable answer synthesis in an existing knowledge base. Although you can use this configuration for new knowledge bases, knowledge base creation is beyond the scope of this article.
+
+:::zone pivot="csharp"
+
+Set `OutputMode` to `"answerSynthesis"` on the `KnowledgeBase` definition. Optionally, set `AnswerInstructions` to customize the answer output. Our example instructs the knowledge base to `Use concise bulleted lists`.
+
+```csharp
+var aoaiParams = new AzureOpenAIVectorizerParameters
 {
-    "name": "{{knowledge-base-name}}",
-    "knowledgeSources": [ ... // OMITTED FOR BREVITY ],
-    "models": [ ... // OMITTED FOR BREVITY ],
-    "outputMode": "answerSynthesis",
-    "answerInstructions": "Use concise bulleted lists"
-}
+    ResourceUri = new Uri(aoaiEndpoint),
+    DeploymentName = aoaiGptDeployment,
+    ModelName = aoaiGptModel,
+};
+
+var knowledgeBase = new KnowledgeBase(
+    name: knowledgeBaseName,
+    knowledgeSources: new[] { new KnowledgeSourceReference(knowledgeSourceName) })
+{
+    Models = { new KnowledgeBaseAzureOpenAIModel(aoaiParams) },
+    OutputMode = "answerSynthesis",
+    AnswerInstructions = "Use concise bulleted lists",
+};
+
+await indexClient.CreateOrUpdateKnowledgeBaseAsync(knowledgeBase);
 ```
 
-> [!NOTE]
-> This example assumes that you're using key-based authentication for local proof-of-concept testing. We recommend role-based access control for production workloads. For more information, see [Connect to Azure AI Search using roles](search-security-rbac.md).
+**Reference:** [SearchIndexClient](/dotnet/api/azure.search.documents.indexes.searchindexclient?view=azure-dotnet-preview&preserve-view=true), [KnowledgeBase](/dotnet/api/azure.search.documents.indexes.models.knowledgebase?view=azure-dotnet-preview&preserve-view=true)
+
+:::zone-end
 
-The equivalent SDK shape sets `output_mode` (Python) or `OutputMode` (C#) to `answerSynthesis` on the `KnowledgeBase` definition and passes the same `KnowledgeBase` instance to `create_or_update_knowledge_base` / `CreateOrUpdateKnowledgeBaseAsync`:
+:::zone pivot="python"
+
+Set `output_mode` to `"answerSynthesis"` on the `KnowledgeBase` definition. Optionally, set `answer_instructions` to customize the answer output. Our example instructs the knowledge base to `Use concise bulleted lists`.
 
 ```python
 from azure.search.documents.indexes import SearchIndexClient
@@ -107,66 +124,66 @@ index_client = SearchIndexClient(endpoint=search_endpoint, credential=credential
 index_client.create_or_update_knowledge_base(knowledge_base)
 ```
 
-```csharp
-var aoaiParams = new AzureOpenAIVectorizerParameters
-{
-    ResourceUri = new Uri(aoaiEndpoint),
-    DeploymentName = aoaiGptDeployment,
-    ModelName = aoaiGptModel,
-};
+**Reference:** [SearchIndexClient](/python/api/azure-search-documents/azure.search.documents.indexes.searchindexclient), [KnowledgeBase](/python/api/azure-search-documents/azure.search.documents.indexes.models.knowledgebase)
 
-var knowledgeBase = new KnowledgeBase(
-    name: knowledgeBaseName,
-    knowledgeSources: new[] { new KnowledgeSourceReference(knowledgeSourceName) })
-{
-    Models = { new KnowledgeBaseAzureOpenAIModel(aoaiParams) },
-    OutputMode = "answerSynthesis",
-    AnswerInstructions = "Use concise bulleted lists",
-};
+:::zone-end
 
-await indexClient.CreateOrUpdateKnowledgeBaseAsync(knowledgeBase);
+:::zone pivot="rest"
+
+Set `outputMode` to `"answerSynthesis"` on the knowledge base definition. Optionally, set `answerInstructions` to customize the answer output. Our example instructs the knowledge base to `Use concise bulleted lists`.
+
+```http
+### Enable answer synthesis in a knowledge base
+PUT {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version=2026-05-01-preview
+Content-Type: application/json
+api-key: {{api-key}}
+
+{
+    "name": "{{knowledge-base-name}}",
+    "knowledgeSources": [ ... // OMITTED FOR BREVITY ],
+    "models": [ ... // OMITTED FOR BREVITY ],
+    "outputMode": "answerSynthesis",
+    "answerInstructions": "Use concise bulleted lists"
+}
 ```
 
+**Reference:** [Knowledge Base - Create or Update](/rest/api/searchservice/knowledge-bases/create-or-update?view=rest-searchservice-2026-05-01-preview&preserve-view=true)
+
+:::zone-end
+
 ## Enable answer synthesis in a retrieve request
 
 For per-query control over the response format, you can enable answer synthesis at query time. This approach overrides the default output mode specified in the knowledge base.
 
-To enable answer synthesis in a retrieve request:
+:::zone pivot="csharp"
 
-1. Use the 2026-05-01-preview of [Knowledge Retrieval - Retrieve (REST API)](/rest/api/searchservice/knowledge-retrieval/retrieve?view=rest-searchservice-2026-05-01-preview&preserve-view=true) to formulate the request.
+Set `OutputMode` to `"answerSynthesis"` on a `KnowledgeBaseRetrievalRequest`.
 
-1. In the body of the request, set `outputMode` to `answerSynthesis`.
-
-```http
-@search-url = <YOUR SEARCH SERVICE URL>
-@api-key = <YOUR API KEY>
-@knowledge-base-name = <YOUR KNOWLEDGE BASE NAME>
-
-### Enable answer synthesis in a retrieve request
-POST {{search-url}}/knowledgebases/{{knowledge-base-name}}/retrieve?api-version=2026-05-01-preview
-Content-Type: application/json
-api-key: {{api-key}}
+```csharp
+var client = new KnowledgeBaseRetrievalClient(
+    endpoint: new Uri(searchEndpoint),
+    knowledgeBaseName: knowledgeBaseName,
+    credential: credential);
 
-{
-    "messages": [
+var request = new KnowledgeBaseRetrievalRequest();
+request.Messages.Add(
+    new KnowledgeBaseMessage(
+        content: new[]
         {
-            "role": "user",
-            "content": [
-                {
-                    "type": "text",
-                    "text": "What is healthcare?"
-                }
-            ]
-        }
-    ],
-    "outputMode": "answerSynthesis"
-}
+            new KnowledgeBaseMessageTextContent("What is healthcare?")
+        }) { Role = "user" });
+request.OutputMode = "answerSynthesis";
+
+var result = await client.RetrieveAsync(request);
 ```
 
-> [!NOTE]
-> This example assumes that you're using key-based authentication for local proof-of-concept testing. We recommend role-based access control for production workloads. For more information, see [Connect to Azure AI Search using roles](search-security-rbac.md).
+**Reference:** [KnowledgeBaseRetrievalClient](/dotnet/api/azure.search.documents.knowledgebases.knowledgebaseretrievalclient?view=azure-dotnet-preview&preserve-view=true), [KnowledgeBaseRetrievalRequest](/dotnet/api/azure.search.documents.knowledgebases.models.knowledgebaseretrievalrequest?view=azure-dotnet-preview&preserve-view=true)
 
-The equivalent SDK shape constructs a `KnowledgeBaseRetrievalRequest` with `output_mode="answerSynthesis"` (Python) or `OutputMode = "answerSynthesis"` (C#):
+:::zone-end
+
+:::zone pivot="python"
+
+Set `output_mode` to `"answerSynthesis"` on a `KnowledgeBaseRetrievalRequest`.
 
 ```python
 from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient
@@ -195,27 +212,43 @@ request = KnowledgeBaseRetrievalRequest(
 result = agent_client.retrieve(retrieval_request=request)
 ```
 
-```csharp
-var client = new KnowledgeBaseRetrievalClient(
-    endpoint: new Uri(searchEndpoint),
-    knowledgeBaseName: knowledgeBaseName,
-    credential: credential);
+**Reference:** [KnowledgeBaseRetrievalClient](/python/api/azure-search-documents/azure.search.documents.knowledgebases.knowledgebaseretrievalclient), [KnowledgeBaseRetrievalRequest](/python/api/azure-search-documents/azure.search.documents.knowledgebases.models.knowledgebaseretrievalrequest)
 
-var request = new KnowledgeBaseRetrievalRequest();
-request.Messages.Add(
-    new KnowledgeBaseMessage(
-        content: new[]
-        {
-            new KnowledgeBaseMessageTextContent("What is healthcare?")
-        }) { Role = "user" });
-request.OutputMode = "answerSynthesis";
+:::zone-end
 
-var result = await client.RetrieveAsync(request);
+:::zone pivot="rest"
+
+Set `outputMode` to `"answerSynthesis"` on a retrieve request.
+
+```http
+### Enable answer synthesis in a retrieve request
+POST {{search-url}}/knowledgebases/{{knowledge-base-name}}/retrieve?api-version=2026-05-01-preview
+Content-Type: application/json
+api-key: {{api-key}}
+
+{
+    "messages": [
+        {
+            "role": "user",
+            "content": [
+                {
+                    "type": "text",
+                    "text": "What is healthcare?"
+                }
+            ]
+        }
+    ],
+    "outputMode": "answerSynthesis"
+}
 ```
 
+**Reference:** [Knowledge Retrieval - Retrieve](/rest/api/searchservice/knowledge-retrieval/retrieve?view=rest-searchservice-2026-05-01-preview&preserve-view=true)
+
+:::zone-end
+
 ## Get a synthesized answer
 
-When answer synthesis is enabled, [Knowledge Retrieval - Retrieve (REST API)](/rest/api/searchservice/knowledge-retrieval/retrieve?view=rest-searchservice-2026-05-01-preview&preserve-view=true) returns a natural-language answer based on the instructions you optionally specified in the knowledge base. Citations to your knowledge sources are formatted as `[ref_id:<number>]`.
+When answer synthesis is enabled, the knowledge base returns a natural-language answer based on the instructions you optionally specified in the knowledge base. Citations to your knowledge sources are formatted as `[ref_id:<number>]`.
 
 For example, if your instructions are `Use concise bulleted lists` and your query is `What is healthcare?`, the response might look like this:
 
@@ -226,7 +259,7 @@ For example, if your instructions are `Use concise bulleted lists` and your quer
       "content": [
         {
           "type": "text",
-          "text": "- Healthcare encompasses various services provided to patients and the general population ... // TRIMMED FOR BREVITY"
+          "text": "- Healthcare encompasses various services provided to patients and the general population ..."
         }
       ]
     }
@@ -244,9 +277,8 @@ Depending on your knowledge base's configuration, the response might include oth
 
 ## Related content
 
-+ [Quickstart: Agentic retrieval in Azure AI Search (uses answer synthesis)](https://github.com/Azure-Samples/azure-search-python-samples/blob/main/Quickstart-Agentic-Retrieval/quickstart-agentic-retrieval.ipynb)
-+ [Azure AI Search Blob knowledge source Python sample (uses answer synthesis)](https://github.com/Azure/azure-search-vector-samples/blob/main/demo-python/code/knowledge/blob-knowledge-source.ipynb)
 + [Agentic retrieval in Azure AI Search](agentic-retrieval-overview.md)
 + [Create a knowledge base](agentic-retrieval-how-to-create-knowledge-base.md)
-+ [Create a search index knowledge source](agentic-knowledge-source-how-to-search-index.md)
-+ [Create a blob knowledge source](agentic-knowledge-source-how-to-blob.md)
++ [Query a knowledge base](agentic-retrieval-how-to-retrieve.md)
++ [Quickstart: Agentic retrieval](search-get-started-agentic-retrieval.md) (uses answer synthesis)
++ [Python sample: Azure AI Search blob knowledge source](https://github.com/Azure/azure-search-vector-samples/blob/main/demo-python/code/knowledge/blob-knowledge-source.ipynb) (uses answer synthesis)
\ No newline at end of file

@@ -151,7 +151,7 @@ If ranking doesn't reflect freshness as expected, inspect the `last_modified` fi
 
 ## Related content
 
-+ [Create a blob knowledge source](agentic-knowledge-source-how-to-blob.md)
-+ [Query a knowledge base using the retrieve action or MCP endpoint](agentic-retrieval-how-to-retrieve.md)
++ [What is a knowledge source?](agentic-knowledge-source-overview.md)
++ [Create a knowledge base](agentic-retrieval-how-to-create-knowledge-base.md)
++ [Query a knowledge base](agentic-retrieval-how-to-retrieve.md)
 + [Add scoring profiles to boost search scores](index-add-scoring-profiles.md)
-+ [Knowledge Sources - Create or Update](/rest/api/searchservice/knowledge-sources/create-or-update?view=rest-searchservice-2026-05-01-preview&preserve-view=true) (REST API)

@@ -3,50 +3,39 @@ title: Create an Index for Agentic Retrieval
 description: Create an index that has fields and configurations that work for agentic retrieval workloads in Azure AI Search.
 ms.service: azure-ai-search
 ms.topic: how-to
-ms.date: 05/05/2026
+ms.date: 06/02/2026
+ai-usage: ai-assisted
 ---
 
 # Create an index for agentic retrieval in Azure AI Search
 
 [!INCLUDE [GA announcement](./includes/previews/agentic-retrieval-ga-announcement.md)]
 
-In Azure AI Search, agentic retrieval uses context and user questions to generate a range of subqueries that can execute against your content in a [knowledge source](agentic-knowledge-source-overview.md). A knowledge source can point to indexed content on Azure AI Search, or remote content that's retrieved using the APIs that are native to the provider. When indexes are used in agentic retrieval, they are either:
+This article explains the required index fields and configurations for agentic retrieval. None of these requirements are new. You can use an existing index that meets the criteria, even if it was created with an earlier API version.
 
-+ An *existing index* containing searchable content. You can make an existing index available to agentic retrieval through a [search index knowledge source](agentic-knowledge-source-how-to-search-index.md) definition.
+Each indexed knowledge source depends on an underlying index. Depending on how you set up your pipeline, the index can be one of the following:
 
-+ A *generated index* created from an indexed [knowledge source](agentic-knowledge-source-overview.md). Indexed knowledge sources create a copy of an external data source inside a search index using a full indexer pipeline (data source, skillset, indexer, and index) for agentic retrieval. Multiple knowledge sources can generate an indexer pipeline that results in a searchable index. These include:
++ **Existing:** A standalone index that's exposed through a [search index knowledge source](agentic-knowledge-source-how-to-search-index.md). The index must meet the criteria in this article.
 
-  + [Azure blobs](agentic-knowledge-source-how-to-blob.md)
-  + [Microsoft OneLake](agentic-knowledge-source-how-to-onelake.md)
-  + [SharePoint (Indexed)](agentic-knowledge-source-how-to-sharepoint-indexed.md)
-
-A generated index is based on a template that meets all of the criteria for knowledge bases and agentic retrieval.
-
-This article explains which index elements affect agentic retrieval query logic. None of the required elements are new or specific to agentic retrieval, which means you can use an existing index if it meets the criteria identified in this article, even if it was created using earlier API versions.
-
-> [!NOTE]
-> The following knowledge sources access external sources directly and don't require a search index: [Web Knowledge Source (Bing)](agentic-knowledge-source-how-to-web.md) and [SharePoint (Remote)](agentic-knowledge-source-how-to-sharepoint-remote.md).
++ **Generated:** An index that's created automatically by an [indexed knowledge source](agentic-knowledge-source-overview.md#supported-knowledge-sources). Generated indexes meet all criteria by default.
 
 ## Criteria for agentic retrieval
 
-An index that's used in agentic retrieval must have these elements:
-
-+ String fields attributed as `searchable` and `retrievable`.
-+ A [semantic configuration](semantic-search-overview.md), with a `defaultSemanticConfiguration` or a semantic configuration override in the knowledge source.
-
-It should also have fields that can be used for citations, such as  document or file name, page or chapter name, or at least a chunk ID.
+The following table organizes the index elements that affect agentic retrieval by requirement level.
 
-It should have [vector fields and a vectorizer](vector-search-how-to-create-index.md) if you want to include text-to-vector query conversion in the pipeline.
-
-Optionally, the following index elements increase your opportunities for optimization:
-
-+ `scoringProfile` with a `defaultScoringProfile`, for boosting relevance
-+ `synonymMaps` for terminology or jargon 
-+ `analyzers` for linguistics rules or patterns (like whitespace preservation, or special characters)
+| Index element | Requirement | Notes |
+|---|---|---|
+| [`searchable` and `retrievable` string fields](search-what-is-an-index.md#field-attributes) | Required | Used for query execution and result retrieval. |
+| [Semantic configuration](#add-a-semantic-configuration) | Required | Use `defaultSemanticConfiguration` or override the semantic configuration in the knowledge source. |
+| Citation fields | Recommended | User-defined fields that attribute responses to source content, such as document name, page number, or chunk ID. |
+| [Vector fields and a vectorizer](#add-a-vectorizer) | Recommended | Enables text-to-vector conversion at query time. |
+| [Scoring profile](#add-a-scoring-profile) | Optional | Boosts relevance for specific fields. Set `defaultScoringProfile` to apply automatically. |
+| [Analyzer](#add-an-analyzer) | Optional | Controls how text is tokenized, such as handling whitespace or special characters. |
+| [Synonym maps](#add-a-synonym-map) | Optional | Expands queries with terminology or jargon. |
 
 ## Example index definition
 
-Here's an example index that works for agentic retrieval. It meets the criteria for required elements. It includes vector fields as a best practice.
+Here's an example index that works for agentic retrieval. It meets the criteria for required elements and includes vector fields as a best practice.
 
 ```json
 {
@@ -142,23 +131,21 @@ Here's an example index that works for agentic retrieval. It meets the criteria
 }
 ```
 
-**Key points**:
-
-A well-designed index that's used for generative AI or retrieval augmented generation (RAG) structure has these components:
+A well-designed index for generative AI or retrieval-augmented generation (RAG) has the following components:
 
 + A description that an LLM or agent can use to determine whether an index should be used or skipped.
 
-+ Chunks of human readable text that can be passed as input tokens to an LLM for answer formulation.
++ Chunks of human-readable text that you can pass as input tokens to an LLM for answer formulation.
 
 + A semantic ranker configuration because agentic retrieval uses level 2 (L2) semantic ranking to identify the most relevant chunks.
 
-+ Optionally, vector-equivalent versions of the human readable chunks of text for complementary vector search.
++ (Optional) Vector-equivalent versions of the human-readable chunks of text for complementary vector search.
 
-Chunked text is important because LLMs consume and emit tokenized strings of human readable plain text content. For this reason, you want `searchable` fields that provide plain text strings, and are `retrievable` in the response. In Azure AI Search, chunked text can be created using [built-in or third-party solutions](vector-search-how-to-chunk-documents.md).
+Chunked text is important because LLMs consume and emit tokenized strings of human-readable plain text content. For this reason, you want `searchable` fields that provide plain text strings and are `retrievable` in the response. In Azure AI Search, you can create chunked text by using [built-in or third-party solutions](vector-search-how-to-chunk-documents.md).
 
-A built-in assumption for chunked content is that the original source documents have large amounts of verbose content. If your source content is structured data, such as a product database, then your index should forego chunking and instead include fields that map to the original data source (for example, a product name, category, description, and so forth). Attribution of `searchable` and `retrievable` applies to structured data as well. Searchable makes the content in-scope for queries, and retrievable adds it to the search results (grounding data).
+A built-in assumption for chunked content is that the original source documents have large amounts of verbose content. If your source content is structured data, such as a product database, your index should forego chunking and instead include fields that map to the original data source, such as a product name, category, or description. Attribution of `searchable` and `retrievable` also applies to structured data. `searchable` makes the content in-scope for queries, and `retrievable` adds it to the search results (grounding data).
 
-Vector content can be useful because it adds *similarity search* to information retrieval. At query time, when vector fields are present in the index, the agentic retrieval engine executes a vector query in parallel to the text query. Because vector queries look for similar content rather than matching words, a vector query can find a highly relevant result that a text query might miss. Adding vectors can enhance and improve the quality of your grounding data, but aren't otherwise strictly required. Azure AI Search has a [built-in approach for vectorization](vector-search-overview.md).
+Vector content can be useful because it adds *similarity search* to information retrieval. At query time, when vector fields are present in the index, the agentic retrieval engine executes a vector query in parallel to the text query. Because vector queries look for similar content rather than matching words, a vector query can find a highly relevant result that a text query might miss. Adding vectors can enhance and improve the quality of your grounding data but aren't strictly required. Azure AI Search has a [built-in approach for vectorization](vector-search-overview.md).
 
 Vector fields are used only for query execution on Azure AI Search. You don't need the vector in results because it isn't human or LLM readable. To minimize space requirements, we recommend setting `retrievable` and `stored` to false. For more information, see [Optimize vector storage and processing](vector-search-how-to-configure-compression-storage.md).
 
@@ -173,16 +160,17 @@ An index `description` field is a user-defined string that you can use to provid
 An index description is a schema update, and you can add it without having to rebuild the entire index.
 
 + String length is 4,000 characters maximum.
+
 + Content must be human-readable, in Unicode. Your use case should determine which language to use (for example, English or another language).
 
 ## Add a semantic configuration
 
-The index must have at least one semantic configuration. The semantic configuration must have:
+The index must have at least one [semantic configuration](semantic-how-to-configure.md#add-a-semantic-configuration). The semantic configuration must have:
 
 + A named configuration.
 + A `prioritizedContentFields` set to at least one string field that is both `searchable` and `retrievable`.
 
-There are two ways to specify a semantic configuration by name. If index has `defaultSemanticConfiguration` set to a named configuration, retrieval uses it. Alternatively, you can specify the semantic configuration inside the [search index knowledge source](agentic-knowledge-source-how-to-search-index.md).
+There are two ways to specify a semantic configuration by name. If the index has `defaultSemanticConfiguration` set to a named configuration, retrieval uses it. Alternatively, you can specify the semantic configuration inside the [search index knowledge source](agentic-knowledge-source-how-to-search-index.md).
 
 Within the configuration, `prioritizedContentFields` is required. Title and keywords are optional. For chunked content, you might not have either. However, if you add [entity recognition](cognitive-search-skill-entity-recognition-v3.md) or [key phrase extraction](cognitive-search-skill-keyphrases.md), you might have some keywords associated with each chunk that can be useful in search scenarios, perhaps in a scoring profile.
 
@@ -228,11 +216,11 @@ Here's an example of a semantic configuration that works for agentic retrieval:
 
 ## Add a vectorizer
 
-If you have vector fields in the index, the query plan includes them if they're `searchable` and have a `vectorizer` assignment.
+If your index contains vector fields, the query plan includes these fields if they're `searchable` and have a `vectorizer` assignment.
 
-A [vectorizer](vector-search-how-to-configure-vectorizer.md) specifies an embedding model that provides text-to-vector conversions at query time. It must point to the same embedding model used to encode the vector content in your index. You can use any embedding model supported by Azure AI Search. Vectorizers are specified on vector fields by way of a *vector profile*.
+A [vectorizer](vector-search-how-to-configure-vectorizer.md) specifies an embedding model that provides text-to-vector conversions at query time. It must point to the same embedding model used to encode the vector content in your index. You can use any embedding model supported by Azure AI Search. You specify vectorizers on vector fields by way of a *vector profile*.
 
-Recall the **vector field definition** in the index example. Attributes on a vector field include dimensions or the number of embeddings generated by the model, and the profile.
+The **vector field definition** in the index example shows the key field attributes: `dimensions`, which is the number of embeddings generated by the model, and `vectorSearchProfile`.
 
 ```json
   {
@@ -247,7 +235,7 @@ Recall the **vector field definition** in the index example. Attributes on a vec
 
 Vector profiles are configurations of vectorizers, algorithms, and compression techniques. Each vector field can only use one profile, but your index can have many in case you want unique profiles for every vector field.
 
-Querying vectors and calling a vectorizer adds latency to the overall request, but if you want similarity search it might be worth the trade-off.
+Querying vectors and calling a vectorizer adds latency to the overall request, but if you want similarity search, it might be worth the trade-off.
 
 Here's an example of a vectorizer that works for agentic retrieval, as it appears in a vectorSearch configuration. There's nothing in the vectorizer definition that needs to be changed to work with agentic retrieval.
 
@@ -296,7 +284,7 @@ A scoring profile is more likely to add value to your solution if your index is
 
 If you create the index using 2025-05-01-preview or later, the scoring profile executes last. If the index is created using an earlier API version, scoring profiles are evaluated before semantic reranking. The actual order of semantically ranked results is determined by the [rankingOrder property](/rest/api/searchservice/indexes/create-or-update#rankingorder) in the index, which is either set to `boostedRerankerScore` (a scoring profile was applied) or `rerankerScore` (no scoring profile).
 
-You can use any scoring profile that makes sense for your index. Here's an example of one that boosts the search score of a match if the match is found in a specific field. Fields are weighted by boosting multipliers. For example if a match was found in the "Category" field, the boosted score is multiplied by 5.
+You can use any scoring profile that makes sense for your index. Here's an example of one that boosts the search score of a match if the match is found in a specific field. Fields are weighted by boosting multipliers. For example, if a match is found in the "Category" field, the boosted score is multiplied by 5.
 
 ```json
 "scoringProfiles": [
@@ -312,7 +300,7 @@ You can use any scoring profile that makes sense for your index. Here's an examp
 ]
 ```
 
-## Add analyzers
+## Add an analyzer
 
 [Analyzers](search-analyzers.md) apply to text fields and can be language analyzers or custom analyzers that control tokenization in the index, such as preserving special characters or whitespace.
 
@@ -332,7 +320,7 @@ Analyzers are defined within a search index and assigned to fields. The [fields
 
 [Synonym maps](search-synonyms.md) expand queries by adding synonyms for named terms. For example, you might have scientific or medical terms for common terms.
 
-Synonym maps are defined as a top-level resource on a search index and assigned to fields. The [fields collection example](#example-index-definition) doesn't include a synonym map, but if you had variant spellings of country names in synonym map, here's what an example might look like if it was assigned to a hypothetical "locations" field.
+Synonym maps are defined as a top-level resource on a search index and assigned to fields. The [fields collection example](#example-index-definition) doesn't include a synonym map, but if you had variant spellings of country names in a synonym map, here's what an example might look like if it was assigned to a hypothetical "locations" field.
 
 ```json
 {
@@ -345,11 +333,10 @@ Synonym maps are defined as a top-level resource on a search index and assigned
 
 ## Add your index to a knowledge source
 
-If you have a standalone index that already exists, and it isn't generated by a knowledge source, create the following objects:
-
-+ A [searchIndex knowledge source](agentic-knowledge-source-how-to-search-index.md) to encapsulate your indexed content.
+If you have a standalone index that already exists and isn't generated by a knowledge source, create the following objects:
 
-+ A [knowledge base](agentic-retrieval-how-to-create-knowledge-base.md) that represents one or more knowledge sources and other instructions for knowledge retrieval.
++ A [search index knowledge source](agentic-knowledge-source-how-to-search-index.md) to encapsulate your indexed content.
++ A [knowledge base](agentic-retrieval-how-to-create-knowledge-base.md) that represents one or more knowledge sources and other instructions for agentic retrieval.
 
 ## Related content
 

@@ -28,7 +28,9 @@ You can create a knowledge base in a [Foundry IQ](/azure/ai-foundry/agents/conce
 A knowledge base specifies:
 
 + One or more knowledge sources that point to searchable content.
+
 + An optional LLM for query planning, answer synthesis, or web content summarization. Supported tasks vary by API version and knowledge source type.
+
 + Custom properties that control routing, source selection, and object encryption.
 
 ### Usage support
@@ -41,9 +43,9 @@ A knowledge base specifies:
 
 + Azure AI Search in any [region that provides agentic retrieval](search-region-support.md). If you're using a [managed identity](search-how-to-managed-identities.md) for role-based access to deployed models, your search service must be on the Basic tier or higher.
 
-+ One or more [knowledge sources](agentic-knowledge-source-overview.md#supported-knowledge-sources). Use the `2026-05-01-preview` API version for preview knowledge source types or to use an LLM with non-web knowledge sources. Use the `2026-04-01` API version for generally available knowledge source types and minimal, extractive retrieval.
++ One or more [knowledge sources](agentic-knowledge-source-overview.md#supported-knowledge-sources). Use the 2026-05-01-preview API version to access preview knowledge sources or to use an LLM with non-web knowledge sources. Use the 2026-04-01 API version for generally available knowledge sources and minimal, extractive retrieval.
 
-+ (Conditional) Azure OpenAI with a [supported LLM](#supported-models) deployment. An LLM is required if your knowledge base includes a web knowledge source. For other knowledge source types, an LLM is optional in the `2026-05-01-preview` API version and unsupported in the `2026-04-01` API version.
++ (Conditional) Azure OpenAI with a [supported LLM](#supported-models) deployment. An LLM is required if your knowledge base includes a web knowledge source. For other knowledge sources, an LLM is optional in the 2026-05-01-preview API version and unsupported in the 2026-04-01 API version.
 
 + Permissions to create knowledge bases. Configure [keyless authentication](search-get-started-rbac.md) with the **Search Service Contributor** role assigned to your user account (recommended) or use an [API key](search-security-api-keys.md).
 
@@ -81,23 +83,23 @@ A knowledge base specifies:
 
 ### Supported models
 
-Use one of the following LLMs from Azure OpenAI in Foundry Models.  Regional availability is determined by Azure OpenAI for the deployment you select. For deployment instructions, see [Deploy Microsoft Foundry Models in the Foundry portal](/azure/ai-foundry/how-to/deploy-models-openai).
+Use one of the following LLMs from Azure OpenAI in Foundry Models. Azure OpenAI determines regional availability for the deployment you select. For deployment instructions, see [Deploy Microsoft Foundry Models in the Foundry portal](/azure/ai-foundry/how-to/deploy-models-openai).
 
 | Model | Supported API versions |
 |--|--|
-| `gpt-4o` | `2025-11-01-preview`, `2026-05-01-preview` |
-| `gpt-4o-mini` | `2025-11-01-preview`, `2026-05-01-preview` |
-| `gpt-4.1` | `2025-11-01-preview`, `2026-05-01-preview` |
-| `gpt-4.1-mini` | `2025-11-01-preview`, `2026-05-01-preview` |
-| `gpt-4.1-nano` | `2025-11-01-preview`, `2026-05-01-preview` |
-| `gpt-5` | `2025-11-01-preview`, `2026-05-01-preview` |
-| `gpt-5-mini` | `2025-11-01-preview`, `2026-05-01-preview` |
-| `gpt-5-nano` | `2025-11-01-preview`, `2026-05-01-preview` |
-| `gpt-5.1` | `2026-05-01-preview` |
-| `gpt-5.2` | `2026-05-01-preview` |
-| `gpt-5.4` | `2026-05-01-preview` |
-| `gpt-5.4-mini` | `2026-05-01-preview` |
-| `gpt-5.4-nano` | `2026-05-01-preview` |
+| `gpt-4o` | 2025-11-01-preview, 2026-05-01-preview |
+| `gpt-4o-mini` | 2025-11-01-preview, 2026-05-01-preview |
+| `gpt-4.1` | 2025-11-01-preview, 2026-05-01-preview |
+| `gpt-4.1-mini` | 2025-11-01-preview, 2026-05-01-preview |
+| `gpt-4.1-nano` | 2025-11-01-preview, 2026-05-01-preview |
+| `gpt-5` | 2025-11-01-preview, 2026-05-01-preview |
+| `gpt-5-mini` | 2025-11-01-preview, 2026-05-01-preview |
+| `gpt-5-nano` | 2025-11-01-preview, 2026-05-01-preview |
+| `gpt-5.1` | 2026-05-01-preview |
+| `gpt-5.2` | 2026-05-01-preview |
+| `gpt-5.4` | 2026-05-01-preview |
+| `gpt-5.4-mini` | 2026-05-01-preview |
+| `gpt-5.4-nano` | 2026-05-01-preview |
 
 ## Configure access
 
@@ -388,7 +390,7 @@ var knowledgeBase = new KnowledgeBase(
 {
     Description = "This knowledge base handles questions directed at two unrelated sample indexes.",
     RetrievalInstructions = "Use the hotels knowledge source for queries about where to stay, otherwise use the earth at night knowledge source.",
-    AnswerInstructions = "Provide a two sentence concise and informative answer based on the retrieved documents.",
+    AnswerInstructions = "Provide a two-sentence, concise, and informative answer based on the retrieved documents.",
     OutputMode = KnowledgeRetrievalOutputMode.AnswerSynthesis,
     Models = { new KnowledgeBaseAzureOpenAIModel(azureOpenAIParameters: aoaiParams) },
     RetrievalReasoningEffort = new KnowledgeRetrievalLowReasoningEffort()
@@ -461,7 +463,7 @@ knowledge_base = KnowledgeBase(
     name = "my-kb",
     description = "This knowledge base handles questions directed at two unrelated sample indexes.",
     retrieval_instructions = "Use the hotels knowledge source for queries about where to stay, otherwise use the earth at night knowledge source.",
-    answer_instructions = "Provide a two sentence concise and informative answer based on the retrieved documents.",
+    answer_instructions = "Provide a two-sentence, concise, and informative answer based on the retrieved documents.",
     output_mode = "answerSynthesis",
     knowledge_sources = [
         KnowledgeSourceReference(name = "hotels-ks"),
@@ -581,17 +583,110 @@ api-key: {{search-api-key}}
 
 ::: zone-end
 
+### Knowledge base properties
+
+Pass the following properties to create a knowledge base.
+
+::: zone pivot="csharp"
+
+# [2026-05-01-preview](#tab/2026-05-01-preview)
+
+| Name | Description | Type | Required |
+|--|--|--|--|
+| `Name` | The name of the knowledge base. It must be unique within the knowledge bases collection and follow the [naming guidelines](/rest/api/searchservice/naming-rules) for objects in Azure AI Search. | String | Yes |
+| `KnowledgeSources` | One or more [supported knowledge sources](agentic-knowledge-source-overview.md#supported-knowledge-sources). | Array | Yes |
+| `Description` | A description of the knowledge base. The LLM uses the description to inform query planning. | String | No |
+| `RetrievalInstructions` | A prompt for the LLM to determine whether a knowledge source should be in scope for a query. Include this prompt when you have multiple knowledge sources. This field influences both knowledge source selection and query formulation. For example, instructions could append information or prioritize a knowledge source. Instructions are passed directly to the LLM, which means it's possible to provide instructions that break query planning, such as instructions that result in bypassing an essential knowledge source. | String | No |
+| `AnswerInstructions` | Custom instructions to shape synthesized answers. The default is null. For more information, see [Use answer synthesis for citation-backed responses](agentic-retrieval-how-to-answer-synthesis.md). | String | No |
+| `OutputMode` | Valid values are `AnswerSynthesis` for an LLM-formulated answer or `ExtractedData` for full search results that you can pass to an LLM as a downstream step. | String | No |
+| `Models` | Required for web knowledge sources. Optional for other knowledge source types. Specifies a [supported LLM](#supported-models) for query planning or answer synthesis. Get connection details from the Microsoft Foundry portal or a command-line request, and then provide them by using the [KnowledgeBaseAzureOpenAIModel class](/dotnet/api/azure.search.documents.indexes.models.knowledgebaseazureopenaimodel?view=azure-dotnet-preview&preserve-view=true). You can use role-based access control instead of API keys for the Azure AI Search connection to the model. | Array | No |
+| `RetrievalReasoningEffort` | Determines the level of LLM-related query processing. Valid values are `minimal`, `low` (default), and `medium`. For more information, see [Set the retrieval reasoning effort](agentic-retrieval-how-to-set-retrieval-reasoning-effort.md). | Object | No |
+| `EncryptionKey` | A [customer-managed key](search-security-manage-encryption-keys.md) to encrypt sensitive information in both the knowledge base and the generated objects. | Object | No |
+
+# [2026-04-01](#tab/2026-04-01)
+
+| Name | Description | Type | Required |
+|--|--|--|--|
+| `Name` | The name of the knowledge base. It must be unique within the knowledge bases collection and follow the [naming guidelines](/rest/api/searchservice/naming-rules) for objects in Azure AI Search. | String | Yes |
+| `KnowledgeSources` | One or more [supported knowledge sources](agentic-knowledge-source-overview.md#supported-knowledge-sources). You must specify generally available knowledge source types. | Array | Yes |
+| `Description` | A description of the knowledge base. | String | No |
+| `Models` | Required for web knowledge sources. Specifies a [supported LLM](#supported-models) used to summarize and preprocess web content before it can be included in retrieval results. Get connection details from the Microsoft Foundry portal or a command-line request, and then provide them by using the [KnowledgeBaseAzureOpenAIModel class](/dotnet/api/azure.search.documents.indexes.models.knowledgebaseazureopenaimodel?view=azure-dotnet&preserve-view=true). You can use role-based access control instead of API keys for the Azure AI Search connection to the model. | Array | No |
+| `EncryptionKey` | A [customer-managed key](search-security-manage-encryption-keys.md) to encrypt sensitive information in both the knowledge base and the generated objects. | Object | No |
+
+---
+
+::: zone-end
+
+::: zone pivot="python"
+
+# [2026-05-01-preview](#tab/2026-05-01-preview)
+
+| Name | Description | Type | Required |
+|--|--|--|--|
+| `name` | The name of the knowledge base. It must be unique within the knowledge bases collection and follow the [naming guidelines](/rest/api/searchservice/naming-rules) for objects in Azure AI Search. | String | Yes |
+| `description` | A description of the knowledge base. The LLM uses the description to inform query planning. | String | No |
+| `retrieval_instructions` | A prompt for the LLM to determine whether a knowledge source should be in scope for a query. Include this prompt when you have multiple knowledge sources. This field influences both knowledge source selection and query formulation. For example, instructions could append information or prioritize a knowledge source. Pass instructions directly to the LLM. It's possible to provide instructions that break query planning, such as instructions that result in bypassing an essential knowledge source. | String | No |
+| `answer_instructions` | Custom instructions to shape synthesized answers. The default is null. For more information, see [Use answer synthesis for citation-backed responses](agentic-retrieval-how-to-answer-synthesis.md). | String | No |
+| `output_mode` | Valid values are `answerSynthesis` for an LLM-formulated answer or `extractedData` for full search results that you can pass to an LLM as a downstream step. | String | No |
+| `knowledge_sources` | One or more [supported knowledge sources](agentic-knowledge-source-overview.md#supported-knowledge-sources). | Array | Yes |
+| `models` | Required for web knowledge sources. Optional for other knowledge source types. Specifies a [supported LLM](#supported-models) for query planning or answer synthesis. Get connection details from the Microsoft Foundry portal or a command-line request. You can use role-based access control instead of API keys for the Azure AI Search connection to the model. | Array | No |
+| `encryption_key` | A [customer-managed key](search-security-manage-encryption-keys.md) to encrypt sensitive information in both the knowledge base and the generated objects. | Object | No |
+| `retrieval_reasoning_effort` | Determines the level of LLM-related query processing. Valid values are `minimal`, `low` (default), and `medium`. For more information, see [Set the retrieval reasoning effort](agentic-retrieval-how-to-set-retrieval-reasoning-effort.md). | Object | No |
+
+# [2026-04-01](#tab/2026-04-01)
+
+| Name | Description | Type | Required |
+|--|--|--|--|
+| `name` | The name of the knowledge base. It must be unique within the knowledge bases collection and follow the [naming guidelines](/rest/api/searchservice/naming-rules) for objects in Azure AI Search. | String | Yes |
+| `description` | A description of the knowledge base. | String | No |
+| `knowledge_sources` | One or more [supported knowledge sources](agentic-knowledge-source-overview.md#supported-knowledge-sources). You must specify generally available knowledge source types. | Array | Yes |
+| `models` | Required for web knowledge sources. Specifies a [supported LLM](#supported-models) used to summarize and preprocess web content before it can be included in retrieval results. Get connection details from the Microsoft Foundry portal or a command-line request. You can use role-based access control instead of API keys for the Azure AI Search connection to the model. | Array | No |
+| `encryption_key` | A [customer-managed key](search-security-manage-encryption-keys.md) to encrypt sensitive information in both the knowledge base and the generated objects. | Object | No |
+
+---
+
+::: zone-end
+
+::: zone pivot="rest"
+
+# [2026-05-01-preview](#tab/2026-05-01-preview)
+
+| Name | Description | Type | Required |
+|--|--|--|--|
+| `name` | The name of the knowledge base. It must be unique within the knowledge bases collection and follow the [naming guidelines](/rest/api/searchservice/naming-rules) for objects in Azure AI Search. | String | Yes |
+| `description` | A description of the knowledge base. The LLM uses the description to inform query planning. | String | No |
+| `retrievalInstructions` | A prompt for the LLM to determine whether a knowledge source should be in scope for a query. Include this prompt when you have multiple knowledge sources. This field influences both knowledge source selection and query formulation. For example, instructions could append information or prioritize a knowledge source. You pass instructions directly to the LLM, which means it's possible to provide instructions that break query planning, such as instructions that result in bypassing an essential knowledge source. | String | No |
+| `answerInstructions` | Custom instructions to shape synthesized answers. The default is null. For more information, see [Use answer synthesis for citation-backed responses](agentic-retrieval-how-to-answer-synthesis.md). | String | No |
+| `outputMode` | Valid values are `answerSynthesis` for an LLM-formulated answer or `extractedData` for full search results that you can pass to an LLM as a downstream step. | String | No |
+| `knowledgeSources` | One or more [supported knowledge sources](agentic-knowledge-source-overview.md#supported-knowledge-sources). | Array | Yes |
+| `models` | Required for web knowledge sources. Optional for other knowledge source types. Specifies a [supported LLM](#supported-models) for query planning or answer synthesis. Get connection details from the Microsoft Foundry portal or a command-line request. You can use role-based access control instead of API keys for the Azure AI Search connection to the model. | Array | No |
+| `encryptionKey` | A [customer-managed key](search-security-manage-encryption-keys.md) to encrypt sensitive information in both the knowledge base and the generated objects. | Object | No |
+| `retrievalReasoningEffort.kind` | Determines the level of LLM-related query processing. Valid values are `minimal`, `low` (default), and `medium`. For more information, see [Set the retrieval reasoning effort](agentic-retrieval-how-to-set-retrieval-reasoning-effort.md). | Object | No |
+
+# [2026-04-01](#tab/2026-04-01)
+
+| Name | Description | Type | Required |
+|--|--|--|--|
+| `name` | The name of the knowledge base. It must be unique within the knowledge bases collection and follow the [naming guidelines](/rest/api/searchservice/naming-rules) for objects in Azure AI Search. | String | Yes |
+| `description` | A description of the knowledge base. | String | No |
+| `knowledgeSources` | One or more [supported knowledge sources](agentic-knowledge-source-overview.md#supported-knowledge-sources). You must specify generally available knowledge source types. | Array | Yes |
+| `models` | Required for web knowledge sources. Specifies a [supported LLM](#supported-models) used to summarize and preprocess web content before it can be included in retrieval results. Get connection details from the Microsoft Foundry portal or a command-line request. You can use role-based access control instead of API keys for the Azure AI Search connection to the model. | Array | No |
+| `encryptionKey` | A [customer-managed key](search-security-manage-encryption-keys.md) to encrypt sensitive information in both the knowledge base and the generated objects. | Object | No |
+
+---
+
+::: zone-end
+
 ### Configure CORS for browser-based retrieve calls (preview)
 
 > [!IMPORTANT]
 > You can use the 2026-05-01-preview to enable cross-origin resource sharing (CORS), which allows browser-based applications to request data directly from the service. Depending on your CORS configuration, external web pages might be able to access or invoke the service and its data using the user's browser context, as well as create other security threats. Enabling CORS is at your own risk.
 
-In the `2026-05-01-preview` API, a knowledge base can define `corsOptions`
-for browser-based applications that call the retrieve action directly from
-JavaScript. The CORS policy identifies which browser origins can send retrieve
-requests to the knowledge base.
+In the 2026-05-01-preview API version, a knowledge base can define `corsOptions` for browser-based applications that call the retrieve action directly from JavaScript. The CORS policy identifies which browser origins can send retrieve requests to the knowledge base.
+
+When you omit `corsOptions`, the knowledge base has no CORS policy, and browsers block cross-origin retrieve requests.
 
-The following examples create a knowledge base that allows retrieve requests from one browser origin.
+The following example creates a knowledge base that allows retrieve requests from one browser origin.
 
 ::: zone pivot="csharp"
 
@@ -677,113 +772,16 @@ api-key: {{search-api-key}}
 
 ::: zone-end
 
-When `corsOptions` is present, `allowedOrigins` lists the origins that can call
-the knowledge base from a browser. `maxAgeInSeconds` is optional and controls
-how long the browser can cache the preflight response.
-
-If `corsOptions` is omitted, the knowledge base has no CORS policy and browsers
-block cross-origin retrieve requests. Set `allowedOrigins` to an explicit list
-of browser origins for production applications. You can use `"*"` to allow all
-origins, but this setting isn't recommended for production. If
-`maxAgeInSeconds` is omitted, the preflight cache duration defaults to 300
-seconds. CORS applies to knowledge base retrieve REST API calls from browsers.
-
-### Knowledge base properties
-
-Pass the following properties to create a knowledge base.
-
-::: zone pivot="csharp"
-
-# [2026-05-01-preview](#tab/2026-05-01-preview)
-
-| Name | Description | Type | Required |
-|--|--|--|--|
-| `Name` | The name of the knowledge base. It must be unique within the knowledge bases collection and follow the [naming guidelines](/rest/api/searchservice/naming-rules) for objects in Azure AI Search. | String | Yes |
-| `KnowledgeSources` | One or more [supported knowledge sources](agentic-knowledge-source-overview.md#supported-knowledge-sources). | Array | Yes |
-| `Description` | A description of the knowledge base. The LLM uses the description to inform query planning. | String | No |
-| `RetrievalInstructions` | A prompt for the LLM to determine whether a knowledge source should be in scope for a query. Include this prompt when you have multiple knowledge sources. This field influences both knowledge source selection and query formulation. For example, instructions could append information or prioritize a knowledge source. Instructions are passed directly to the LLM, which means it's possible to provide instructions that break query planning, such as instructions that result in bypassing an essential knowledge source. | String | No |
-| `AnswerInstructions` | Custom instructions to shape synthesized answers. The default is null. For more information, see [Use answer synthesis for citation-backed responses](agentic-retrieval-how-to-answer-synthesis.md). | String | No |
-| `OutputMode` | Valid values are `AnswerSynthesis` for an LLM-formulated answer or `ExtractedData` for full search results that you can pass to an LLM as a downstream step. | String | No |
-| `Models` | Required for web knowledge sources. Optional for other knowledge source types. Specifies a [supported LLM](#supported-models) for query planning or answer synthesis. Get connection details from the Microsoft Foundry portal or a command-line request, and then provide them by using the [KnowledgeBaseAzureOpenAIModel class](/dotnet/api/azure.search.documents.indexes.models.knowledgebaseazureopenaimodel?view=azure-dotnet-preview&preserve-view=true). You can use role-based access control instead of API keys for the Azure AI Search connection to the model. | Array | No |
-| `RetrievalReasoningEffort` | Determines the level of LLM-related query processing. Valid values are `minimal`, `low` (default), and `medium`. For more information, see [Set the retrieval reasoning effort](agentic-retrieval-how-to-set-retrieval-reasoning-effort.md). | Object | No |
-
-# [2026-04-01](#tab/2026-04-01)
-
-| Name | Description | Type | Required |
-|--|--|--|--|
-| `Name` | The name of the knowledge base. It must be unique within the knowledge bases collection and follow the [naming guidelines](/rest/api/searchservice/naming-rules) for objects in Azure AI Search. | String | Yes |
-| `KnowledgeSources` | One or more [supported knowledge sources](agentic-knowledge-source-overview.md#supported-knowledge-sources). You must specify generally available knowledge source types. | Array | Yes |
-| `Description` | A description of the knowledge base. | String | No |
-| `Models` | Required for web knowledge sources. Specifies a [supported LLM](#supported-models) used to summarize and preprocess web content before it can be included in retrieval results. Get connection details from the Microsoft Foundry portal or a command-line request, and then provide them by using the [KnowledgeBaseAzureOpenAIModel class](/dotnet/api/azure.search.documents.indexes.models.knowledgebaseazureopenaimodel?view=azure-dotnet&preserve-view=true). You can use role-based access control instead of API keys for the Azure AI Search connection to the model. | Array | No |
-| `EncryptionKey` | A [customer-managed key](search-security-manage-encryption-keys.md) to encrypt sensitive information in both the knowledge base and the generated objects. | Object | No |
-
----
-
-::: zone-end
-
-::: zone pivot="python"
-
-# [2026-05-01-preview](#tab/2026-05-01-preview)
-
-| Name | Description | Type | Required |
-|--|--|--|--|
-| `name` | The name of the knowledge base. It must be unique within the knowledge bases collection and follow the [naming guidelines](/rest/api/searchservice/naming-rules) for objects in Azure AI Search. | String | Yes |
-| `description` | A description of the knowledge base. The LLM uses the description to inform query planning. | String | No |
-| `retrieval_instructions` | A prompt for the LLM to determine whether a knowledge source should be in scope for a query. Include this prompt when you have multiple knowledge sources. This field influences both knowledge source selection and query formulation. For example, instructions could append information or prioritize a knowledge source. Pass instructions directly to the LLM. It's possible to provide instructions that break query planning, such as instructions that result in bypassing an essential knowledge source. | String | No |
-| `answer_instructions` | Custom instructions to shape synthesized answers. The default is null. For more information, see [Use answer synthesis for citation-backed responses](agentic-retrieval-how-to-answer-synthesis.md). | String | No |
-| `output_mode` | Valid values are `answerSynthesis` for an LLM-formulated answer or `extractedData` for full search results that you can pass to an LLM as a downstream step. | String | No |
-| `knowledge_sources` | One or more [supported knowledge sources](agentic-knowledge-source-overview.md#supported-knowledge-sources). | Array | Yes |
-| `models` | Required for web knowledge sources. Optional for other knowledge source types. Specifies a [supported LLM](#supported-models) for query planning or answer synthesis. Get connection details from the Microsoft Foundry portal or a command-line request. You can use role-based access control instead of API keys for the Azure AI Search connection to the model. | Array | No |
-| `encryption_key` | A [customer-managed key](search-security-manage-encryption-keys.md) to encrypt sensitive information in both the knowledge base and the generated objects. | Object | No |
-| `retrieval_reasoning_effort` | Determines the level of LLM-related query processing. Valid values are `minimal`, `low` (default), and `medium`. For more information, see [Set the retrieval reasoning effort](agentic-retrieval-how-to-set-retrieval-reasoning-effort.md). | Object | No |
-
-# [2026-04-01](#tab/2026-04-01)
-
-| Name | Description | Type | Required |
-|--|--|--|--|
-| `name` | The name of the knowledge base. It must be unique within the knowledge bases collection and follow the [naming guidelines](/rest/api/searchservice/naming-rules) for objects in Azure AI Search. | String | Yes |
-| `description` | A description of the knowledge base. | String | No |
-| `knowledge_sources` | One or more [supported knowledge sources](agentic-knowledge-source-overview.md#supported-knowledge-sources). You must specify generally available knowledge source types. | Array | Yes |
-| `models` | Required for web knowledge sources. Specifies a [supported LLM](#supported-models) used to summarize and preprocess web content before it can be included in retrieval results. Get connection details from the Microsoft Foundry portal or a command-line request. You can use role-based access control instead of API keys for the Azure AI Search connection to the model. | Array | No |
-| `encryption_key` | A [customer-managed key](search-security-manage-encryption-keys.md) to encrypt sensitive information in both the knowledge base and the generated objects. | Object | No |
-
----
-
-::: zone-end
-
-::: zone pivot="rest"
-
-# [2026-05-01-preview](#tab/2026-05-01-preview)
+`corsOptions` accepts the following properties.
 
 | Name | Description | Type | Required |
 |--|--|--|--|
-| `name` | The name of the knowledge base. It must be unique within the knowledge bases collection and follow the [naming guidelines](/rest/api/searchservice/naming-rules) for objects in Azure AI Search. | String | Yes |
-| `description` | A description of the knowledge base. The LLM uses the description to inform query planning. | String | No |
-| `retrievalInstructions` | A prompt for the LLM to determine whether a knowledge source should be in scope for a query. Include this prompt when you have multiple knowledge sources. This field influences both knowledge source selection and query formulation. For example, instructions could append information or prioritize a knowledge source. You pass instructions directly to the LLM, which means it's possible to provide instructions that break query planning, such as instructions that result in bypassing an essential knowledge source. | String | No |
-| `answerInstructions` | Custom instructions to shape synthesized answers. The default is null. For more information, see [Use answer synthesis for citation-backed responses](agentic-retrieval-how-to-answer-synthesis.md). | String | No |
-| `outputMode` | Valid values are `answerSynthesis` for an LLM-formulated answer or `extractedData` for full search results that you can pass to an LLM as a downstream step. | String | No |
-| `knowledgeSources` | One or more [supported knowledge sources](agentic-knowledge-source-overview.md#supported-knowledge-sources). | Array | Yes |
-| `models` | Required for web knowledge sources. Optional for other knowledge source types. Specifies a [supported LLM](#supported-models) for query planning or answer synthesis. Get connection details from the Microsoft Foundry portal or a command-line request. You can use role-based access control instead of API keys for the Azure AI Search connection to the model. | Array | No |
-| `encryptionKey` | A [customer-managed key](search-security-manage-encryption-keys.md) to encrypt sensitive information in both the knowledge base and the generated objects. | Object | No |
-| `retrievalReasoningEffort.kind` | Determines the level of LLM-related query processing. Valid values are `minimal`, `low` (default), and `medium`. For more information, see [Set the retrieval reasoning effort](agentic-retrieval-how-to-set-retrieval-reasoning-effort.md). | Object | No |
-
-# [2026-04-01](#tab/2026-04-01)
-
-| Name | Description | Type | Required |
-|--|--|--|--|
-| `name` | The name of the knowledge base. It must be unique within the knowledge bases collection and follow the [naming guidelines](/rest/api/searchservice/naming-rules) for objects in Azure AI Search. | String | Yes |
-| `description` | A description of the knowledge base. | String | No |
-| `knowledgeSources` | One or more [supported knowledge sources](agentic-knowledge-source-overview.md#supported-knowledge-sources). You must specify generally available knowledge source types. | Array | Yes |
-| `models` | Required for web knowledge sources. Specifies a [supported LLM](#supported-models) used to summarize and preprocess web content before it can be included in retrieval results. Get connection details from the Microsoft Foundry portal or a command-line request. You can use role-based access control instead of API keys for the Azure AI Search connection to the model. | Array | No |
-| `encryptionKey` | A [customer-managed key](search-security-manage-encryption-keys.md) to encrypt sensitive information in both the knowledge base and the generated objects. | Object | No |
-
----
-
-::: zone-end
+| `allowedOrigins` | Lists the origins that can call the knowledge base from a browser. For production applications, use an explicit list of origins. You can use `"*"` to allow all origins, but this setting isn't recommended for production. | Array | Yes |
+| `maxAgeInSeconds` | Controls how long browsers can cache the preflight response. When omitted, the preflight cache duration defaults to 300 seconds. | Integer | No |
 
 ## Query a knowledge base
 
-After you create a knowledge base, use the [retrieve action](agentic-retrieval-how-to-retrieve.md) to query it and verify the LLM connection.
+After you create a knowledge base, call the [retrieve action or MCP endpoint](agentic-retrieval-how-to-retrieve.md) to query it.
 
 ## Delete a knowledge base
 
@@ -835,5 +833,5 @@ api-key: {{search-api-key}}
 ## Related content
 
 + [Agentic retrieval in Azure AI Search](agentic-retrieval-overview.md)
-+ [Agentic RAG: Build a reasoning retrieval engine with Azure AI Search (YouTube video)](https://www.youtube.com/watch?v=PeTmOidqHM8)
-+ [Azure OpenAI demo featuring agentic retrieval](https://github.com/Azure-Samples/azure-search-openai-demo)
++ [Query a knowledge base](agentic-retrieval-how-to-retrieve.md)
++ [Migrate agentic retrieval code](agentic-retrieval-how-to-migrate.md)

@@ -61,7 +61,7 @@ In this tutorial, you:
 + The [Azure CLI](/cli/azure/install-azure-cli) for keyless authentication with Microsoft Entra ID.
 
 > [!IMPORTANT]
-> If you've disabled public network access for your search service and use it as an agent tool with a network-isolated Microsoft Foundry resource, you must use the Microsoft Foundry (new) portal, SDK, or CLI to build agents. The Microsoft Foundry (classic) portal doesn't support this scenario. For more information, see [Agent tools with network isolation](/azure/ai-foundry/how-to/configure-private-link#agent-tools-with-network-isolation).
+> If you disable public network access for your search service and use it as an agent tool with a network-isolated Microsoft Foundry resource, you must use the Microsoft Foundry (new) portal, SDK, or CLI to build agents. The Microsoft Foundry (classic) portal doesn't support this scenario. For more information, see [Agent tools with network isolation](/azure/ai-foundry/how-to/configure-private-link#agent-tools-with-network-isolation).
 
 ## Understand the solution
 
@@ -107,9 +107,9 @@ To configure access for this solution:
 
 1. Open the folder in Visual Studio Code.
 
-1. Select **View > Command Palette**, and then select **Python: Create Environment**. Follow the prompts to create a virtual environment.
+1. Select **View** > **Command Palette**, and then select **Python: Create Environment**. Follow the prompts to create a virtual environment.
 
-1. Select **Terminal > New Terminal**.
+1. Select **Terminal** > **New Terminal**.
 
 1. Install the required packages.
 
@@ -350,7 +350,7 @@ mcp_endpoint = f"{endpoint.rstrip('/')}/knowledgebases/{base_name}/mcp?api-versi
 
 ### Set up a project client
 
-Use [AIProjectClient](/python/api/azure-ai-projects/azure.ai.projects.aiprojectclient?view=azure-python-preview&preserve-view=true) to create a client connection to your Microsoft Foundry project. Your project might not contain any agents yet, but if you've already completed this tutorial, the agent is listed here.
+Use [AIProjectClient](/python/api/azure-ai-projects/azure.ai.projects.aiprojectclient?view=azure-python-preview&preserve-view=true) to create a client connection to your Microsoft Foundry project. Your project might not contain any agents yet, but if you already completed this tutorial, the agent is listed here.
 
 ```python
 from azure.ai.projects import AIProjectClient
@@ -576,9 +576,9 @@ print(f"Index '{index_name}' deleted successfully")
 
 ## Improve data quality
 
-By default, search results from knowledge bases are consolidated into a large, unified string that can be passed to agents for grounding. Azure AI Search provides the following indexing and relevance-tuning features to help you generate high-quality results. You can implement these features in the search index, and the improvements in search relevance are evident in the quality of retrieval responses.
+By default, search results from knowledge bases are consolidated into a large, unified string that you can pass to agents for grounding. Azure AI Search provides the following indexing and relevance-tuning features to help you generate high-quality results. You can implement these features in the search index, and the improvements in search relevance are evident in the quality of retrieval responses.
 
-+ [Scoring profiles](index-add-scoring-profiles.md) provide built-in boosting criteria. Your index must specify a default scoring profile, which is used by the retrieval engine when queries include fields associated with that profile.
++ [Scoring profiles](index-add-scoring-profiles.md) provide built-in boosting criteria. Your index must specify a default scoring profile, which the retrieval engine uses when queries include fields associated with that profile.
 
 + [Semantic configuration](semantic-how-to-configure.md) is required, but you determine which fields are prioritized and used for ranking.
 

@@ -183,19 +183,19 @@ The combination of `assetStore`, `disableImageVerbalization`, and `chatCompletio
 
 Wait for ingestion to complete before continuing:
 
-+ Check indexer status in the [Azure portal](https://portal.azure.com) or with [Get Indexer Status](/rest/api/searchservice/indexers/get-status) (REST API).
++ Check indexer status in the [Azure portal](https://portal.azure.com) or use [Get Indexer Status](/rest/api/searchservice/indexers/get-status) (REST API).
 
 + Verify that indexed chunks have a populated `image_path` field. Empty `image_path` values usually mean the source documents don't contain extractable images, the asset store isn't configured, or the indexer hasn't finished.
 
 + Inspect the asset store container. You should see image blobs that the indexer wrote during ingestion.
 
 ## Enable image serving on a knowledge base
 
-Set `enableImageServing` to `true` on the knowledge source reference inside the knowledge base definition. This becomes the default for every retrieve request that targets the knowledge source.
+Set `enableImageServing` to `true` on the knowledge source reference inside the knowledge base definition. This setting becomes the default for every retrieve request that targets the knowledge source.
 
-The knowledge base definition also specifies the LLM used for **answer synthesis at query time**. This is independent of any `chatCompletionModel` that you set on the knowledge source's `ingestionParameters`, which drives image verbalization during indexing.
+The knowledge base definition also specifies the LLM used for **answer synthesis at query time**. This setting is independent of any `chatCompletionModel` that you set on the knowledge source's `ingestionParameters`, which drives image verbalization during indexing.
 
-If your knowledge base references multiple knowledge sources, set `enableImageServing` only on supported file-based indexed kinds that have `assetStore` configured. Unsupported kinds (for example, search index, remote SharePoint, or web) still contribute text grounding but don't return images.
+If your knowledge base references multiple knowledge sources, set `enableImageServing` only on supported file-based indexed kinds that have `assetStore` configured. Unsupported kinds (such as search index, remote SharePoint, or web) still contribute text grounding but don't return images.
 
 ```http
 PUT https://{service-name}.search.windows.net/knowledgebases/my-kb?api-version=2026-05-01-preview
@@ -299,7 +299,7 @@ The following table summarizes the nine combinations.
 
 ## Inspect image serving statistics
 
-When image serving runs, the retrieve response includes an `imageServing` section per knowledge source inside the `activity` array. Use this section to verify whether images were sent to the model and to diagnose dropped images.
+When image serving runs, the retrieve response includes an `imageServing` section for each knowledge source inside the `activity` array. Use this section to verify whether images were sent to the model and to diagnose dropped images.
 
 ```json
 "activity": [
@@ -334,7 +334,7 @@ Portal support for enabling and managing image serving is planned for a future u
 
 ## Test image serving end to end
 
-To exercise the full setup against multiple agentic retrieval configurations (image serving enabled and disabled, different output modes, runtime overrides), see the [image serving testing samples](https://aka.ms/agentic-retrieval-image-serving-testing). The samples include an end-to-end walkthrough that creates the knowledge source, knowledge base, and retrieve requests so you can compare answers with and without image serving.
+To test the full setup against multiple agentic retrieval configurations (image serving enabled and disabled, different output modes, runtime overrides), see the [image serving testing samples](https://aka.ms/agentic-retrieval-image-serving-testing). The samples include an end-to-end walkthrough that creates the knowledge source, knowledge base, and retrieve requests so you can compare answers with and without image serving.
 
 A typical A/B comparison checklist:
 
@@ -361,7 +361,7 @@ Use the `imageServing` activity block from [Inspect image serving statistics](#i
 
 ## Related content
 
-+ [Query a knowledge base via APIs or MCP](agentic-retrieval-how-to-retrieve.md)
++ [Query a knowledge base](agentic-retrieval-how-to-retrieve.md)
 + [Use answer synthesis for citation-backed responses](agentic-retrieval-how-to-answer-synthesis.md)
-+ [Knowledge sources for agentic retrieval](agentic-knowledge-source-overview.md)
++ [What is a knowledge source?](agentic-knowledge-source-overview.md)
 + [Knowledge store concepts](knowledge-store-concept-intro.md)

@@ -45,7 +45,7 @@ If your code targets a preview version, we recommend migrating to the latest sta
 
 ### [**2026-04-01**](#tab/2026-04-01)
 
-If you're migrating from [2025-11-01-preview](#2025-11-01-preview-1), you can migrate directly to 2026-04-01. Your index and content remain unchanged; only the knowledge base schema and the retrieve request shape require updates.
+If you're migrating from [2025-11-01-preview](#2025-11-01-preview-1), you can migrate directly to 2026-04-01. Your index and content remain unchanged. You only need to update the knowledge base schema and the retrieve request shape.
 
 1. [Migrate knowledge sources](#migrate-knowledge-sources)
 1. [Migrate the knowledge base](#migrate-the-knowledge-base)
@@ -55,7 +55,7 @@ If you're migrating from [2025-11-01-preview](#2025-11-01-preview-1), you can mi
 
 #### Migrate knowledge sources
 
-`searchIndex`, `azureBlob`, `indexedOneLake`, and `web` knowledge source types are generally available in 2026-04-01. Other knowledge source types remain in preview.
+In 2026-04-01, the `searchIndex`, `azureBlob`, `indexedOneLake`, and `web` knowledge source types are generally available. Other knowledge source types remain in preview.
 
 1. Use [Knowledge Sources - Get](/rest/api/searchservice/knowledge-sources/get?view=rest-searchservice-2025-11-01-preview&preserve-view=true) (REST API) to get the current definition.
 
@@ -328,7 +328,7 @@ This procedure creates a new 2025-11-01-preview `searchIndex` knowledge source a
     }
     ```
 
-You now have a migrated `searchIndex` knowledge source is backwards compatible with the previous version, using the correct property specifications for the 2025-11-01-preview. 
+You now have a migrated `searchIndex` knowledge source that's backward compatible with the previous version, using the correct property specifications for the 2025-11-01-preview. 
 
 The response includes the full definition of the new object. For more information about new properties available to this knowledge source type, which you can now do through updates, see [How to create a search index knowledge source](agentic-knowledge-source-how-to-search-index.md).
 
@@ -487,7 +487,7 @@ This procedure creates a new 2025-11-01-preview `azureBlob` knowledge source at
     }
     ```
 
-You now have a migrated `azureBlob` knowledge source that is backwards compatible with the previous version, using the correct property specifications for the 2025-11-01-preview. 
+You now have a migrated `azureBlob` knowledge source that's backward compatible with the previous version, using the correct property specifications for the 2025-11-01-preview. 
 
 The response includes the full definition of the new object. For more information about new properties available to this knowledge source type, which you can now do through updates, see [Create a blob knowledge source](agentic-knowledge-source-how-to-blob.md).
 
@@ -591,11 +591,11 @@ The response includes the full definition of the new object. For more informatio
 
    + Change the API version to `2025-11-01-preview`.
 
-   + Delete `requestLimits`. The `maxRuntimeInSeconds` and `maxOutputSize` properties are now specified on the retrieval request object directly
+   + Delete `requestLimits`. The `maxRuntimeInSeconds` and `maxOutputSize` properties are now specified on the retrieval request object directly.
 
    + Update `knowledgeSources`:
 
-     + Delete `maxSubQueries` and replace with a retrievalReasoningEffort` (see [Set the retrieval reasoning effort](agentic-retrieval-how-to-set-retrieval-reasoning-effort.md)).
+     + Delete `maxSubQueries` and replace it with `retrievalReasoningEffort` (see [Set the retrieval reasoning effort](agentic-retrieval-how-to-set-retrieval-reasoning-effort.md)).
 
      + Move `alwaysQuerySource`, `includeReferenceSourceData`, `includeReferences`, and `rerankerThreshold` to the `knowledgeSourcesParams` section of a [retrieve action](agentic-retrieval-how-to-retrieve.md).
 
@@ -646,7 +646,7 @@ The response includes the full definition of the new object. For more informatio
     }
    ```
 
-You now have a knowledge base instead of a knowledge agent, and the object is backwards compatible with the previous version 
+You now have a knowledge base instead of a knowledge agent, and the object is backwards compatible with the previous version. 
 
 The response includes the full definition of the new object. For more information about new properties available to a knowledge base, which you can now do through updates, see [How to create a knowledge base](agentic-retrieval-how-to-create-knowledge-base.md).
 
@@ -658,7 +658,7 @@ The retrieval request is modified for the 2025-11-01-preview to support more sha
 
 1. Change the API version to `2025-11-01-preview`.
 
-1. No changes to `messages` are required if you are using a `low` or `medium` retrievalReasoningEffort. Replace messages with `intent` if you use `minimal `reasoning (see [Set the retrieval reasoning effort](agentic-retrieval-how-to-set-retrieval-reasoning-effort.md)).
+1. No changes to `messages` are required if you're using a `low` or `medium` retrievalReasoningEffort. Replace messages with `intent` if you use `minimal` reasoning (see [Set the retrieval reasoning effort](agentic-retrieval-how-to-set-retrieval-reasoning-effort.md)).
 
 1. Modify `knowledgeSourceParams` to include any properties that were removed from the agent: `rerankerThreshold`, `alwaysQuerySource`, `includeReferenceSourceData`, `includeReferences`.
 
@@ -845,7 +845,7 @@ This section covers breaking and nonbreaking changes for the following REST API
 
 ### 2026-05-01-preview
 
-2026-05-01-preview adds knowledge base, knowledge source, and retrieve features on top of [2025-11-01-preview](#2025-11-01-preview-1) without removing previously persisted properties. Existing knowledge bases and knowledge sources created on earlier preview versions continue to work; this version mostly exposes new functionality and reverts a few preview-only limits.
+2026-05-01-preview adds knowledge base, knowledge source, and retrieve features on top of [2025-11-01-preview](#2025-11-01-preview-1) without removing previously persisted properties. Existing knowledge bases and knowledge sources that you created in earlier preview versions continue to work. This version mostly exposes new functionality and reverts a few preview-only limits.
 
 To review the [REST API reference documentation](/rest/api/searchservice/operation-groups?view=rest-searchservice-2026-05-01-preview&preserve-view=true) for this version, select the 2026-05-01-preview API version filter at the top of the page.
 
@@ -1023,5 +1023,5 @@ To review the [REST API reference documentation](/rest/api/searchservice/operati
 ## Related content
 
 + [Agentic retrieval in Azure AI Search](agentic-retrieval-overview.md)
-+ [Create a knowledge agent](agentic-retrieval-how-to-create-knowledge-base.md)
-+ [Create a knowledge source](agentic-knowledge-source-overview.md)
++ [Create a knowledge base](agentic-retrieval-how-to-create-knowledge-base.md)
++ [Query a knowledge base](agentic-retrieval-how-to-retrieve.md)

@@ -1,6 +1,6 @@
 ---
 title: Query Knowledge Base via APIs or MCP
-description: Learn how to Query a knowledge base using the retrieve action or MCP endpoint in Azure AI Search using REST APIs, Azure SDKs, or any MCP-compatible client.
+description: Learn how to query a knowledge base using the retrieve action or MCP endpoint in Azure AI Search using REST APIs, Azure SDKs, or any MCP-compatible client.
 ms.service: azure-ai-search
 ms.topic: how-to
 ms.date: 06/02/2026
@@ -335,21 +335,21 @@ Pass the following parameters to call the retrieve action.
 |--|--|--|--|--|
 | `messages` | Contains the chat conversation history sent to the agentic retrieval pipeline. The LLM determines the query from the conversation history. The message format is similar to Azure OpenAI APIs. Supported only if the [retrieval reasoning effort](agentic-retrieval-how-to-set-retrieval-reasoning-effort.md) is low or medium. | Object | Yes | No |
 | `messages.role` | Defines where the message came from, such as `assistant` or `user`. The model you use determines which roles are valid. | String | Yes | No |
-| `messages.content` | The message or prompt sent to the LLM. Must be text. | String | Yes | No |
-| `includeActivity` | When `true`, the response includes an `activity` array that describes the steps the pipeline ran, such as query planning, search index calls, and answer synthesis. Defaults to `false`. | Boolean | Yes | No |
-| `maxOutputDocuments` | Caps the number of grounding documents returned by the retrieve call. Applies after per-source candidate selection. For more information, see [Limit final grounding documents](#limit-final-grounding-documents). | Integer | Yes | No |
-| `maxOutputSize` | Limits the size, in tokens, of the grounded response payload. Documents that don't fit under the limit are omitted from the response. | Integer | Yes | No |
+| `messages.content` | The message or prompt sent to the LLM. Must be text. | Array | Yes | No |
+| `includeActivity` | When `true`, the response includes an `activity` array that describes the steps the pipeline ran, such as query planning, search index calls, and answer synthesis. Defaults to `false`. For a usage example, see [Inspect model names in activity logs](#inspect-model-names-in-activity-logs). | Boolean | Yes | No |
+| `maxOutputDocuments` | Caps the number of grounding documents returned by the retrieve call. Applies after per-source candidate selection. If `maxOutputSize` is also set, both constraints apply, and whichever limit is reached first wins. The service can return fewer documents than this parameter's value if fewer results survive ranking, thresholding, or deduplication. For a usage example and a table of setting combinations, see [Limit final grounding documents](#limit-final-grounding-documents). | Integer | Yes | No |
+| `maxOutputSize` | Limits the size, in tokens, of the grounded response payload. Documents that don't fit under the limit are omitted from the response. If `maxOutputDocuments` is also set, both constraints apply, and whichever limit is reached first wins. For a usage example and a table of setting combinations, see [Limit final grounding documents](#limit-final-grounding-documents). | Integer | Yes | No |
 | `retrievalReasoningEffort` | Sets the retrieval reasoning effort for the request and overrides the knowledge base default. For valid values and tradeoffs, see [Set the retrieval reasoning effort](agentic-retrieval-how-to-set-retrieval-reasoning-effort.md). | Object | Yes | No |
 | `knowledgeSourceParams` | Overrides default retrieval settings per knowledge source. Useful for customizing the query or response at query time. | Object | Yes | No |
 | `knowledgeSourceParams.knowledgeSourceName` | Name of the knowledge source the entry applies to. The knowledge source must already be attached to the knowledge base. | String | Yes | Yes |
 | `knowledgeSourceParams.kind` | Discriminator for the knowledge source type, such as `searchIndex`, `web`, `azureBlob`, or `sharepoint`. Must match the underlying knowledge source kind. | String | Yes | Yes |
-| `knowledgeSourceParams.alwaysQuerySource` | When `true`, the pipeline always queries this knowledge source instead of relying on the planner to decide. Useful when a source must always participate in the response. | Boolean | Yes | No |
-| `knowledgeSourceParams.failOnError` | When `true`, the retrieve request fails with `502 Bad Gateway` if this knowledge source can't be queried, instead of returning a partial response from the remaining sources. Defaults to `false`. For more information, see [Require a knowledge source to succeed](#require-a-knowledge-source-to-succeed). | Boolean | Yes | No |
-| `knowledgeSourceParams.maxOutputDocuments` | Caps the number of candidate documents this knowledge source contributes before the final result selection. Use `50` for cross-region compatibility because some preview regions cap this per-source setting at 50. Doesn't control the final number of grounding documents returned to the caller. For more information, see [Tune candidate documents per knowledge source](#tune-candidate-documents-per-knowledge-source). | Integer | Yes | No |
-| `knowledgeSourceParams.includeReferences` | When `true`, the response includes a `references` array that identifies the documents that contributed to the answer for this source. | Boolean | Yes | No |
-| `knowledgeSourceParams.includeReferenceSourceData` | When `true`, references include the source data fields configured on the knowledge source. | Boolean | Yes | No |
+| `knowledgeSourceParams.alwaysQuerySource` | When `true`, the pipeline always queries this knowledge source instead of relying on the planner to decide. Useful when a source must always participate in the response. This parameter is independent of `failOnError`. To require a source to always run and fail the request if it errors, set both to `true`. | Boolean | Yes | No |
+| `knowledgeSourceParams.failOnError` | When `true`, the retrieve request fails with `502 Bad Gateway` and an error message that identifies the knowledge source that couldn't be queried, instead of returning a partial response from the remaining sources. Defaults to `false`, which means the pipeline favors availability and returns results from other sources when one fails. Independent of `alwaysQuerySource`, which controls whether the source is attempted at all; `failOnError` controls what happens when that attempt fails. For a usage example, see [Require a knowledge source to succeed](#require-a-knowledge-source-to-succeed). | Boolean | Yes | No |
+| `knowledgeSourceParams.maxOutputDocuments` | Caps the number of candidate documents this knowledge source contributes before the final result selection. Use `50` for cross-region compatibility because some preview regions cap this per-source parameter at 50. Doesn't control the final number of grounding documents returned to the caller. The service can return fewer documents when fewer matches are available or when internal limits apply. For a usage example, see [Tune candidate documents per knowledge source](#tune-candidate-documents-per-knowledge-source). | Integer | Yes | No |
+| `knowledgeSourceParams.includeReferences` | When `true`, the response includes a `references` array that identifies the documents that contributed to the answer for this source. For a usage example, see [Set references for each knowledge source](#set-references-for-each-knowledge-source). | Boolean | Yes | No |
+| `knowledgeSourceParams.includeReferenceSourceData` | When `true`, references include the source data fields configured on the knowledge source. For a usage example, see [Set references for each knowledge source](#set-references-for-each-knowledge-source). | Boolean | Yes | No |
 | `knowledgeSourceParams.rerankerThreshold` | Minimum reranker score that a candidate document must have to be included in the result set for this source. | Number | Yes | No |
-| `knowledgeSourceParams.filterAddOn` | OData filter appended to the persisted `baseFilter` (if any) for search index knowledge sources, narrowing the source query at request time. | String | Yes | No |
+| `knowledgeSourceParams.filterAddOn` | OData filter appended to the persisted `baseFilter` (if any) for search index knowledge sources, narrowing the source query at request time. For filter syntax and examples, see [Filter search index knowledge sources at query time](#filter-search-index-knowledge-sources-at-query-time). | String | Yes | No |
 
 # [2026-04-01](#tab/2026-04-01)
 
@@ -368,7 +368,7 @@ For [blob](agentic-knowledge-source-how-to-blob.md), [indexed OneLake](agentic-k
 
 Image serving runs only when `outputMode` is `answerSynthesis` and requires the 2026-05-01-preview REST API or an equivalent Azure SDK preview package. For setup steps, the precedence table, and how to inspect image serving statistics, see [Surface document-embedded images in agentic retrieval (preview)](agentic-retrieval-how-to-image-serving.md).
 
-### Retrieval from a search index
+### Search index behavior
 
 For knowledge sources that target a search index, all `searchable` fields are in scope for query execution. The implied query type is `semantic`, and there's no search mode.
 
@@ -387,7 +387,8 @@ In Azure AI Search, each knowledge base is a standalone MCP server that exposes
 
 ### MCP endpoint format
 
-Each knowledge base has an MCP endpoint at the following URL:
+Each knowledge base has an MCP endpoint at the following URL.
+
 ```
 https://<your-service-name>.search.windows.net/knowledgebases/<your-knowledge-base-name>/mcp?api-version=<api-version>
 ```
@@ -409,7 +410,7 @@ The MCP endpoint requires authentication via custom headers. You have two option
 >
 > + In [GitHub Copilot](https://docs.github.com/en/copilot/how-tos/provide-context/use-mcp/extend-copilot-chat-with-mcp) and similar clients, you configure headers in the MCP server JSON, such as `mcp.json`.
 
-## Filter at query time (search index)
+## Filter search index knowledge sources at query time
 
 When retrieving from a search index knowledge source, you can apply an [OData filter](search-query-odata-filter.md) at query time to narrow the results to specific documents or fields. The filter expression uses OData syntax and is passed via the `filterAddOn` parameter.
 
@@ -423,13 +424,6 @@ The `filterAddOn` parameter accepts OData filter expressions. Example patterns i
 - **Text matching**: `substringof('climate', description)`, `indexof(title, 'urgent') ge 0`
 - **Logical operators**: `(category eq 'News' or category eq 'Analysis') and status eq 'published'`
 
-Example filter expressions:
-
-- `status eq 'published'`
-- `created ge 2025-01-01`
-- `city eq 'Redmond' and department eq 'Engineering'`
-- `(priority eq 'High' or priority eq 'Critical') and resolved eq false`
-
 :::zone pivot="csharp"
 
 ```csharp
@@ -577,7 +571,7 @@ Authorization: Bearer <YOUR ACCESS TOKEN>
 
 ### Multi-filter example
 
-You can combine multiple filters to refine results further:
+You can combine multiple filters to further refine results.
 
 :::zone pivot="csharp"
 
@@ -647,7 +641,6 @@ In the .NET SDK, pass the token as the `xMsQuerySourceAuthorization` parameter o
 
 ```csharp
 using Azure;
-using Azure;
 using Azure.Search.Documents.KnowledgeBases;
 using Azure.Search.Documents.KnowledgeBases.Models;
 
@@ -694,7 +687,8 @@ Console.WriteLine(text);
 In the Python SDK, pass the token as the `x_ms_query_source_authorization` parameter on `retrieve`:
 
 ```python
-from azure.core.credentials import AzureKeyCredential, get_bearer_token_provider
+from azure.identity import DefaultAzureCredential
+from azure.core.credentials import get_bearer_token_provider
 from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient
 from azure.search.documents.knowledgebases.models import (
     KnowledgeBaseMessage, KnowledgeBaseMessageTextContent,
@@ -771,7 +765,7 @@ x-ms-query-source-authorization: {{userAccessToken}}
 
 ## Review the response
 
-Successful retrieval returns a `200 OK` status code. If the knowledge base fails to retrieve from one or more knowledge sources, the service returns a `206 Partial Content` status code. The response only includes results from sources that succeeded. Details about the partial response appear as errors in the activity array.
+Successful retrieval returns a `200 OK` status code. If the knowledge base fails to retrieve from one or more knowledge sources, the service returns a `206 Partial Content` status code. The response only includes results from sources that succeeded. The activity array contains details about the partial response as errors.
 
 The retrieve action returns three main components:
 
@@ -828,30 +822,28 @@ Key points:
 
 The activity array outputs the query plan, which provides operational transparency for tracking operations, billing implications, and resource invocations. It also includes subqueries sent to the retrieval pipeline and errors for any retrieval failures, such as inaccessible knowledge sources.
 
-The output includes the following components:
+The output includes the following components.
 
 # [2026-05-01-preview](#tab/2026-05-01-preview)
 
 | Section | Description |
 |---------|-------------|
-| modelQueryPlanning | For knowledge bases that use an LLM for query planning, this section reports on the token counts used for input, and the token count for the subqueries. |
-| source-specific activity | For each knowledge source included in the query, this section reports on elapsed time and which arguments were used in the query, including semantic ranker. Knowledge source types include `searchIndex`, `azureBlob`, and other [supported knowledge sources](agentic-knowledge-source-overview.md#supported-knowledge-sources). |
-| agenticReasoning | This section reports on token consumption for agentic reasoning during retrieval, which depends on the specified [retrieval reasoning effort](agentic-retrieval-how-to-set-retrieval-reasoning-effort.md). |
-| modelAnswerSynthesis | For knowledge bases that use [answer synthesis](agentic-retrieval-how-to-answer-synthesis.md), this section reports on the token count for formulating the answer, and the token count of the answer output. |
-| imageServing | For knowledge sources that have [image serving](agentic-retrieval-how-to-image-serving.md) enabled, this section reports `imagesRetrieved`, `imagesSentToModel`, `totalImageSizeBytes`, and whether indexing-time `verbalizationUsed` was on. To find the number of dropped images, subtract `imagesSentToModel` from `imagesRetrieved`. |
+| `modelQueryPlanning` | For knowledge bases that use an LLM for query planning, this section reports on the token counts used for input, and the token count for the subqueries. Includes a `modelName` field with the public model name (not the deployment name) of the model that ran the activity. |
+| Source-specific activity | For each knowledge source included in the query, this section reports on elapsed time and which arguments were used in the query, including semantic ranker. Knowledge source types include `searchIndex`, `azureBlob`, and other [supported knowledge sources](agentic-knowledge-source-overview.md#supported-knowledge-sources). |
+| `agenticReasoning` | This section reports on token consumption for agentic reasoning during retrieval, which depends on the specified [retrieval reasoning effort](agentic-retrieval-how-to-set-retrieval-reasoning-effort.md). |
+| `modelAnswerSynthesis` | For knowledge bases that use [answer synthesis](agentic-retrieval-how-to-answer-synthesis.md), this section reports on the token count for formulating the answer, and the token count of the answer output. Includes a `modelName` field with the public model name (not the deployment name) of the model that ran the activity. |
+| `modelWebSummarization` | For knowledge bases that use web summarization, this section reports on token consumption for summarizing web results. Includes a `modelName` field with the public model name (not the deployment name) of the model that ran the activity. |
+| `imageServing` | For knowledge sources that have [image serving](agentic-retrieval-how-to-image-serving.md) enabled, this section reports `imagesRetrieved`, `imagesSentToModel`, `totalImageSizeBytes`, and whether indexing-time `verbalizationUsed` was on. To find the number of dropped images, subtract `imagesSentToModel` from `imagesRetrieved`. |
 
 # [2026-04-01](#tab/2026-04-01)
 
 | Section | Description |
 |---------|-------------|
-| source-specific activity | For each knowledge source included in the query, this section reports on elapsed time and which arguments were used in the query, including semantic ranker. Knowledge source types include `searchIndex`, `azureBlob`, and other [supported knowledge sources](agentic-knowledge-source-overview.md#supported-knowledge-sources). |
-| agenticReasoning | This section reports on token consumption for agentic reasoning during retrieval. |
+| Source-specific activity | For each knowledge source included in the query, this section reports on elapsed time and which arguments were used in the query, including semantic ranker. Knowledge source types include `searchIndex`, `azureBlob`, and other [supported knowledge sources](agentic-knowledge-source-overview.md#supported-knowledge-sources). |
+| `agenticReasoning` | This section reports on token consumption for agentic reasoning during retrieval. |
 
 ---
 
-> [!NOTE]
-> The `modelQueryPlanning` and `modelAnswerSynthesis` sections don't appear in the 2026-04-01 activity array because query planning and answer synthesis are preview-only features. For full activity output, use the 2026-05-01-preview.
-
 Here's an example of the activity array:
 
 # [2026-05-01-preview](#tab/2026-05-01-preview)
@@ -996,7 +988,7 @@ When you query a knowledge base that ingests [Microsoft Purview sensitivity labe
 | Per reference | `sensitivityLabelInfo` | The sensitivity label applied to each document returned in the `references` array. |
 | Response | `metadata.responseSensitivityLabelInfo` | An aggregate label that represents the highest-priority sensitivity label across all referenced documents in the response. Useful for client-side display banners and policy enforcement. |
 
-The response-level label is computed by Microsoft Graph from the per-reference labels using the [Microsoft Purview label inheritance rules](/purview/sensitivity-labels). Typically, the most restrictive label wins.
+Microsoft Graph computes the response-level label from the per-reference labels using the [Microsoft Purview label inheritance rules](/purview/sensitivity-labels). Typically, the most restrictive label wins.
 
 The following example shows a retrieve response with two referenced documents (one `Confidential`, one `Internal`) and the resulting response-level label.
 
@@ -1080,7 +1072,7 @@ The field name and availability of label metadata depend on the knowledge source
 
 The MCP endpoint exposed by each knowledge base surfaces the same sensitivity label fields as the REST API. When an MCP-compatible client invokes the `knowledge_base_retrieve` tool, the tool result contains the same per-reference `sensitivityLabelInfo` and response-level `metadata.responseSensitivityLabelInfo` documented earlier in this section. MCP clients enforce label-aware display and policy controls based on these fields.
 
-## Examples
+## Retrieve action examples (preview)
 
 The following examples illustrate different ways to call the retrieve action using the 2026-05-01-preview API version, which supports the full feature set, including answer synthesis and a configurable reasoning effort. For 2026-04-01 usage, see the previous sections.
 
@@ -1094,14 +1086,7 @@ The following examples illustrate different ways to call the retrieve action usi
 
 ### Inspect model names in activity logs
 
-In the `2026-05-01-preview` API, model-backed activity records can include
-`modelName` when `includeActivity` is enabled. Use this field to confirm which
-configured model handled query planning, answer synthesis, or web
-summarization during a retrieve request.
-
-The field is additive and appears only on activity entries that represent
-model-backed work. Nonmodel activity records, such as search index retrieval
-steps, don't include `modelName`.
+Model-backed activity records include a `modelName` field when `includeActivity` is enabled. Use this field to confirm which configured model handled query planning, answer synthesis, or web summarization during a retrieve request.
 
 :::zone pivot="csharp"
 
@@ -1173,7 +1158,7 @@ Content-Type: application/json
 
 :::zone-end
 
-The following response excerpt shows activity records with `modelName`:
+The following response excerpt shows activity records with `modelName`.
 
 ```json
 {
@@ -1205,22 +1190,9 @@ The following response excerpt shows activity records with `modelName`:
 }
 ```
 
-For this preview, `modelName` appears on model activity records, including
-`modelQueryPlanning`, `modelAnswerSynthesis`, and `modelWebSummarization`. The
-value is the public model name used for the activity, such as `gpt-5-mini`, not
-the deployment name. If an activity step isn't backed by a single
-customer-visible model, the field is omitted.
-
 ### Require a knowledge source to succeed
 
-In the `2026-05-01-preview` API, `knowledgeSourceParams` can include
-`failOnError` to mark a specific knowledge source as required for the retrieve
-request. Use this setting when a partial answer would be misleading or
-noncompliant if that source is unavailable.
-
-By default, retrieve favors availability and can return results from other
-sources when an optional source fails. `failOnError` changes that behavior for
-the source where it's set.
+Set `failOnError` in `knowledgeSourceParams` to mark a knowledge source as required. Use this parameter when a partial answer would be misleading or noncompliant if that source is unavailable.
 
 :::zone pivot="csharp"
 
@@ -1315,26 +1287,9 @@ Content-Type: application/json
 
 :::zone-end
 
-`failOnError` defaults to `false`. When a queried source has
-`failOnError: true` and the source query fails, the retrieve request fails
-instead of returning `206 Partial Content`. The expected error is `502 Bad
-Gateway`, with an error message that identifies the knowledge source that
-couldn't be queried. The setting is independent of `alwaysQuerySource`:
-`alwaysQuerySource` controls whether the source is attempted, while
-`failOnError` controls what happens if that attempt fails. If a source must
-always participate and must fail the request on error, set both properties to
-`true`.
-
 ### Tune candidate documents per knowledge source
 
-In the `2026-05-01-preview` API, `knowledgeSourceParams` can include
-`maxOutputDocuments` to cap output documents per knowledge source before
-final result selection. Use this setting when you want one source to
-contribute a bounded number of documents to the retrieve pipeline.
-
-This setting is per source. Use `50` for cross-region compatibility because
-some preview regions cap per-source output documents at 50. It doesn't control
-the final number of grounding documents returned to the caller.
+Set `maxOutputDocuments` in `knowledgeSourceParams` to cap how many candidate documents a specific knowledge source contributes before final result selection. Use this parameter when you want to bound one source's input to the pipeline without affecting others.
 
 :::zone pivot="csharp"
 
@@ -1416,18 +1371,10 @@ Content-Type: application/json
 
 :::zone-end
 
-The service can return fewer documents when fewer matches are available or when
-internal limits reduce the applied window.
 
 ### Limit final grounding documents
 
-In the `2026-05-01-preview` API, top-level `maxOutputDocuments` caps how
-many grounding documents are returned in the final retrieve response. Use this
-setting when your application needs a predictable citation or reference count.
-
-This count-based control complements `maxOutputSize`, which limits payload
-size. If both settings are present, both constraints apply to the final
-response.
+The top-level `maxOutputDocuments` parameter caps how many grounding documents are returned in the final retrieve response. Use this parameter when your application needs a predictable citation or reference count.
 
 :::zone pivot="csharp"
 
@@ -1499,22 +1446,19 @@ Content-Type: application/json
 
 :::zone-end
 
+The following table shows how `maxOutputDocuments` and `maxOutputSize` interact across all four combinations.
+
 | `maxOutputDocuments` | `maxOutputSize` | Behavior |
 | --- | --- | --- |
 | Unspecified | Unspecified | Uses the default `maxOutputSize` response limit behavior. |
 | Unspecified | Specified | Discards documents once the payload-size limit is reached. |
 | Specified | Unspecified | Returns up to the specified number of grounding documents and doesn't apply a `maxOutputSize` limit. |
 | Specified | Specified | Returns up to `maxOutputDocuments` documents or however many documents fit under `maxOutputSize`, whichever limit applies first. |
 
-The service can return fewer documents than `maxOutputDocuments` if fewer
-results survive ranking, thresholding, or deduplication. Unlike per-source
-`knowledgeSourceParams.maxOutputDocuments`, the top-level final-result cap
-applies after the knowledge sources have contributed documents to the retrieve
-pipeline.
 
 ### Override default reasoning effort and set request limits
 
-This example specifies [answer synthesis](agentic-retrieval-how-to-answer-synthesis.md), so the retrieval reasoning effort must be low or medium.
+This example specifies [answer synthesis](agentic-retrieval-how-to-answer-synthesis.md), so the retrieval reasoning effort must be `low` or `medium`. It also sets `maxRuntimeInSeconds` to cap total request latency and `maxOutputSize` to bound the response payload.
 
 :::zone pivot="csharp"
 
@@ -1597,7 +1541,7 @@ Content-Type: application/json
 
 ### Set references for each knowledge source
 
-This example uses the default reasoning effort specified in the knowledge base. The focus of this example is specification of how much information to include in the response.
+Use `includeReferences` and `includeReferenceSourceData` in `knowledgeSourceParams` to control which sources appear in the references array and how much source data each entry includes. This example uses the knowledge base's default reasoning effort.
 
 :::zone pivot="csharp"
 

@@ -21,14 +21,14 @@ ms.custom: references_regions
 >
 > You're responsible for carefully reviewing and testing applications you build in the context of your specific use cases and making all appropriate decisions and customizations. This includes implementing your own responsible AI mitigations, such as metaprompts, content filters, or other safety systems, and ensuring your applications meet appropriate quality, reliability, security, and trustworthiness standards. For more information, see the [Azure AI Search Transparency Note](/azure/foundry/responsible-ai/search/transparency-note).
 
-In agentic retrieval, you can specify the level of large language model (LLM) processing for query planning and answer formulation. Use the *retrieval reasoning effort* (preview) to set LLM processing levels that affect costs and latency. Extra LLM processing improves relevancy, but it also takes longer and uses billable LLM resources. You can set this property in a knowledge base or on a retrieve request.
+In agentic retrieval, you can specify the level of large language model (LLM) processing for query planning and answer formulation. Use the *retrieval reasoning effort* (preview) to set LLM processing levels that affect costs and latency. Extra LLM processing improves relevance, but it also takes longer and uses billable LLM resources. You can set this property in a knowledge base or on a retrieve request.
 
 Levels of reasoning effort include:
 
 | Level | Effort |
 |-------|--------|
 | `minimal` | No LLM processing. You provide the query.|
-| `low` | Runs a single pass of LLM-based query planning and knowledge source selection. This is the default. The LLM analyzes the query and breaks it into component parts as needed.|
+| `low` | Runs a single pass of LLM-based query planning and knowledge source selection. This level is the default. The LLM analyzes the query and breaks it into component parts as needed.|
 | `medium` | Adds deeper search and an enhanced retrieval stack to agentic retrieval to maximize completeness. |
 
 ## Prerequisites
@@ -54,14 +54,14 @@ This section describes:
 | Level | Description | Recommendation | Limits | 
 |-|-|-|-|
 | `minimal` | Disables LLM-based query planning to deliver the lowest cost and latency for agentic retrieval. It issues direct text and vector searches across the knowledge sources listed in the knowledge base, and returns the best-matching passages. Because all knowledge sources in the knowledge base are always searched and no query expansion is performed, behavior is predictable and easy to control. It also means the `alwaysQueryKnowledgeSource` property on a retrieve request is ignored.  | Use "minimal" for migrations from the [Search API](/rest/api/searchservice/documents/search-post) or when you want to manage query planning yourself. | <ul><li>`outputMode` must be set to `extractiveData`.</li><li>[Answer synthesis](agentic-retrieval-how-to-answer-synthesis.md) and [web knowledge](agentic-knowledge-source-how-to-web.md) aren't supported.</li><li>Maximum of [10 knowledge sources per knowledge base](search-limits-quotas-capacity.md#agentic-retrieval-limits).</li></ul> |
-| `low` | The default mode of agentic retrieval, running a single pass of LLM-based query planning and knowledge source selection. The agentic retrieval engine generates subqueries and fans them out to the selected knowledge sources, then merges the results. You can enable answer synthesis to produce a grounded natural-language response with inline citations. | Use "low" when you want a balance between minimal latency and deeper processing. | <ul><li>5,000 answer tokens.</li><li>In `2026-05-01-preview`, maximum of [10 knowledge sources per knowledge base on most paid tiers](search-limits-quotas-capacity.md#agentic-retrieval-limits).</li><li>In earlier preview API versions, maximum of three subqueries from three knowledge sources per knowledge base.</li><li>Maximum of 50 documents for semantic ranking, and 10 documents if the semantic ranker uses L3 classification.</li></ul> |
-| `medium` | Adds deeper search and an enhanced retrieval stack to agentic retrieval to maximize completeness. After the first search is performed, a [high-precision semantic classifier](search-relevance-overview.md) evaluates the retrieved documents to determine whether further processing and L3 ranking is required. If the initial results from the first pass are insufficiently relevant to the query, a follow-up iteration is performed using a revised query plan. This revised query plan takes the previous results into account and iterates by fine-tuning queries, broadening terms, or adding other knowledge sources such as the web. It also increases resource limits compared to low and minimal effort. This reasoning level optimizes for relevance rather than exhaustive recall. | Use "medium" to maximize the utility of LLM-assisted knowledge retrieval. | <ul><li>10,000 answer tokens.</li><li>In `2026-05-01-preview`, maximum of [10 knowledge sources per knowledge base on most paid tiers](search-limits-quotas-capacity.md#agentic-retrieval-limits).</li><li>In earlier preview API versions, maximum of five subqueries from five knowledge sources per knowledge base.</li><li>Maximum of 50 documents for semantic ranking, and 20 documents if the semantic ranker uses L3 classification.</li><li>Available in [select regions](#region-support-for-medium-retrieval).</li></ul> |
+| `low` | The default mode of agentic retrieval, running a single pass of LLM-based query planning and knowledge source selection. The agentic retrieval engine generates subqueries and fans them out to the selected knowledge sources, then merges the results. You can enable answer synthesis to produce a grounded natural-language response with inline citations. | Use "low" when you want a balance between minimal latency and deeper processing. | <ul><li>5,000 answer tokens.</li><li>In the 2026-05-01-preview, maximum of [10 knowledge sources per knowledge base on most paid tiers](search-limits-quotas-capacity.md#agentic-retrieval-limits).</li><li>In earlier preview API versions, maximum of three subqueries from three knowledge sources per knowledge base.</li><li>Maximum of 50 documents for semantic ranking, and 10 documents if the semantic ranker uses L3 classification.</li></ul> |
+| `medium` | Adds deeper search and an enhanced retrieval stack to agentic retrieval to maximize completeness. After the first search is performed, a [high-precision semantic classifier](search-relevance-overview.md) evaluates the retrieved documents to determine whether further processing and L3 ranking is required. If the initial results from the first pass are insufficiently relevant to the query, a follow-up iteration is performed using a revised query plan. This revised query plan takes the previous results into account and iterates by fine-tuning queries, broadening terms, or adding other knowledge sources such as the web. It also increases resource limits compared to low and minimal effort. This reasoning level optimizes for relevance rather than exhaustive recall. | Use "medium" to maximize the utility of LLM-assisted knowledge retrieval. | <ul><li>10,000 answer tokens.</li><li>In the 2026-05-01-preview, maximum of [10 knowledge sources per knowledge base on most paid tiers](search-limits-quotas-capacity.md#agentic-retrieval-limits).</li><li>In earlier preview API versions, maximum of five subqueries from five knowledge sources per knowledge base.</li><li>Maximum of 50 documents for semantic ranking, and 20 documents if the semantic ranker uses L3 classification.</li><li>Available in [select regions](#region-support-for-medium-retrieval).</li></ul> |
 
 ### Iterative search for medium retrieval
 
 A medium retrieval reasoning effort provides iterative search if initial results aren't sufficiently relevant. An extra *semantic classifier model* is called to determine if a second iteration is necessary.
 
-The semantic classifier performs the following:
+The semantic classifier:
 
 + Recognizes when there's enough context to answer the question.
 
@@ -128,5 +128,5 @@ To override the default on a query-by-query basis, set the property in the retri
 ## Related content
 
 + [Agentic retrieval in Azure AI Search](agentic-retrieval-overview.md)
-+ [Agentic RAG: Build a reasoning retrieval engine with Azure AI Search (YouTube video)](https://www.youtube.com/watch?v=PeTmOidqHM8)
-+ [Azure OpenAI demo featuring agentic retrieval](https://github.com/Azure-Samples/azure-search-openai-demo)
++ [Create a knowledge base](agentic-retrieval-how-to-create-knowledge-base.md)
++ [Query a knowledge base](agentic-retrieval-how-to-retrieve.md)

@@ -3,9 +3,10 @@ title: Supported Regions
 description: Learn about the regions that offer Azure AI Search and the features available in each region.
 author: mattwojo
 ms.author: mattwoj
-ms.date: 03/25/2026
+ms.date: 06/05/2026
 ms.service: azure-ai-search
 ms.topic: concept-article
+ai-usage: ai-assisted
 ms.custom:
   - references_regions
   - build-2025
@@ -43,7 +44,7 @@ You can create an Azure AI Search service in any of the following Azure public r
 | Canada Central​​ <sup>1</sup> | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Canada East​​ ​<sup>1</sup> |  |  | ✅ |  | ✅ |  |
 | ​Central US​​ | ✅ | ✅ | ✅ |  | ✅ | ✅ |
-| East US​ <sup>1, 2</sup> | ✅ | ✅ | ✅ |  | ✅ |  |
+| East US​ <sup>1, 2</sup> | ✅ | ✅ | ✅ |  | ✅ | ✅ |
 | East US 2 <sup>1, 2</sup> | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Mexico Central |  | ✅ |  |  |  |  |
 | North Central US​ <sup>1</sup> ​| ✅ |  | ✅ |  | ✅ | ✅ |
@@ -64,11 +65,11 @@ You can create an Azure AI Search service in any of the following Azure public r
 | Region | AI enrichment | Availability zones | Agentic retrieval | Confidential computing | Semantic ranker | Query rewrite |
 |--|--|--|--|--|--|--|
 | France Central​​ <sup>1</sup> | ✅ | ✅ | ✅ |  | ✅ | ✅ |
-| Germany West Central​ <sup>1</sup> ​| ✅ | ✅ | ✅ |  | ✅ |  |
-| Italy North​​ |  | ✅ | ✅ | ✅ | ✅ |  |
+| Germany West Central​ <sup>1</sup> ​| ✅ | ✅ | ✅ |  | ✅ | ✅ |
+| Italy North​​ |  | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Norway East​​ | ✅ | ✅ |  | ✅ |  |  |
 | North Europe​ <sup>2</sup> | ✅ | ✅ | ✅ |  | ✅ | ✅ |
-| Poland Central​​ <sup>1</sup> |  |  | ✅ |  | ✅ |  |
+| Poland Central​​ <sup>1</sup> |  |  | ✅ |  | ✅ | ✅ |
 | Spain Central <sup>3</sup> |  | ✅ |  | ✅ | ✅ | ✅ |
 | Sweden Central​​ <sup>1</sup> | ✅ | ✅ | ✅ |  | ✅ | ✅ |
 | Switzerland North​ <sup>1</sup> | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
@@ -88,8 +89,8 @@ You can create an Azure AI Search service in any of the following Azure public r
 | Region | AI enrichment | Availability zones | Agentic retrieval | Confidential computing | Semantic ranker | Query rewrite |
 |--|--|--|--|--|--|--|
 | Israel Central​ <sup>1</sup> |  | ✅ |  |  |  |  |
-| Qatar Central​ <sup>1</sup> |  | ✅ | ✅ |  | ✅ |  |
-| UAE North​​ <sup>2</sup> | ✅ | ✅ | ✅ | ✅ | ✅ |  |
+| Qatar Central​ <sup>1</sup> |  | ✅ | ✅ |  | ✅ | ✅ |
+| UAE North​​ <sup>2</sup> | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 
 <sup>1</sup> [Higher storage limits](search-limits-quotas-capacity.md#service-limits) aren't available in this region. If you want higher limits, choose a different region.
 
@@ -99,7 +100,7 @@ You can create an Azure AI Search service in any of the following Azure public r
 
 | Region | AI enrichment | Availability zones | Agentic retrieval | Confidential computing | Semantic ranker | Query rewrite |
 |--|--|--|--|--|--|--|
-| South Africa North​ <sup>1</sup> | ✅ | ✅ | ✅ | ✅ | ✅ |  |
+| South Africa North​ <sup>1</sup> | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 
 <sup>1</sup> This region supports [agentic retrieval](agentic-retrieval-overview.md) and [semantic ranker](semantic-search-overview.md) on the free tier.
 
@@ -115,7 +116,7 @@ You can create an Azure AI Search service in any of the following Azure public r
 | Jio India West​​ | ✅ |  | ✅ |  | ✅ | ✅ |
 | Jio India Central​​ |  |  |  |  |  |  |
 | Japan East <sup>1</sup> | ✅ | ✅ | ✅ |  | ✅ | ✅ |
-| Japan West​ | ✅ |  | ✅ |  | ✅ |  |
+| Japan West​ | ✅ |  | ✅ |  | ✅ | ✅ |
 | Korea Central <sup>1</sup> | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Korea South​​ |  |  | ✅ |  | ✅ |  |
 | Malaysia West |  | ✅ |  |  |  |  |