@@ -8,14 +8,14 @@ ms.service: azure-ai-search
 ms.custom:
   - build-2025
 ms.topic: reference
-ms.date: 07/28/2025
+ms.date: 08/27/2025
 ---
 
 # GenAI Prompt skill
 
 [!INCLUDE [Feature preview](./includes/previews/preview-generic.md)]
 
-The **GenAI (Generative AI) Prompt** skill executes a *chat completion* request against a Large Language Model (LLM) deployed in Azure AI Foundry or Azure OpenAI in Azure AI Foundry Models. Use this capability to create new information that can be indexed and stored as searchable content.
+The **GenAI (Generative AI) Prompt** skill executes a *chat completion* request against a large language model (LLM) deployed in Azure AI Foundry or Azure OpenAI in Azure AI Foundry Models. Use this capability to create new information that can be indexed and stored as searchable content.
 
 Here are some examples of how the GenAI prompt skill can help you create content:
 
@@ -24,7 +24,7 @@ Here are some examples of how the GenAI prompt skill can help you create content
 - Simplify complex content
 - Perform any other task that you can articulate in a prompt
 
-The GenAI Prompt skill is available in the [2025-05-01-preview REST API](/rest/api/searchservice/skillsets/create?view=rest-searchservice-2025-05-01-preview&preserve-view=true) only. The skill supports text, image, and multimodal content such as a PDF that contains text and images. 
+The GenAI Prompt skill is available in the [latest preview REST API](/rest/api/searchservice/skillsets/create?view=rest-searchservice-2025-08-01-preview&preserve-view=true). This skill supports text, image, and multimodal content, such as a PDF that contains text and images.
 
 > [!TIP]
 > It's common to use this skill combined with a data chunking skill. The following tutorials demonstrate image verbalization with two different data chunking techniques:
@@ -37,6 +37,8 @@ The GenAI Prompt skill is available in the [2025-05-01-preview REST API](/rest/a
 
 You can use any [chat completion inference model](/azure/ai-foundry/model-inference/concepts/models) deployed in AI Foundry, such as GPT models, Deepseek R#, Llama-4-Mavericj, Cohere-command-r, and so forth.
 
+For image verbalization, the model you use to analyze the image determines what image formats are supported.
+
 Billing is based on the pricing of the model you use.
 
 > [!NOTE]

@@ -6,7 +6,7 @@ author: HeidiSteen
 ms.author: heidist
 ms.service: azure-ai-search
 ms.topic: how-to
-ms.date: 07/28/2025
+ms.date: 08/27/2025
 ms.update-cycle: 180-days
 ms.custom:
   - ignite-2023
@@ -55,10 +55,10 @@ You can use the Azure portal, preview APIs, or preview Azure SDK packages to ena
 
 On new indexers, add the `cache` property in the indexer definition payload when calling Create or Update Indexer. 
 
-We recommend the latest preview for [Create or Update Indexer (2025-05-01-preview)](/rest/api/searchservice/indexers/create-or-update?view=rest-searchservice-2025-05-01-preview&preserve-view=true).
+We recommend the latest preview REST API for [Create or Update Indexer](/rest/api/searchservice/indexers/create-or-update?view=rest-searchservice-2025-08-01-preview&preserve-view=true).
 
 ```https
-POST https://[service name].search.windows.net/indexers?api-version=2025-05-01-preview
+POST https://[service name].search.windows.net/indexers?api-version=2025-08-01-preview
     {
         "name": "<YOUR-INDEXER-NAME>",
         "targetIndexName": "<YOUR-INDEX-NAME>",
@@ -82,10 +82,10 @@ For existing indexers that already have a skillset, use the following steps to a
 
 ### Step 1: Get the indexer definition
 
-Start with a valid, work indexer that has these components: data source, skillset, index. Using an API client, send a [GET Indexer](/rest/api/searchservice/indexers/get?view=rest-searchservice-2025-05-01-preview&preserve-view=true) request to retrieve the indexer. When you use the preview API version to the GET the indexer, a `cache` property set to null is added to the definition automatically.
+Start with a valid, work indexer that has these components: data source, skillset, index. Using an API client, send a [GET Indexer](/rest/api/searchservice/indexers/get?view=rest-searchservice-2025-08-01-preview&preserve-view=true) request to retrieve the indexer. When you use the preview API version to the GET the indexer, a `cache` property set to null is added to the definition automatically.
 
 ```http
-GET https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]?api-version=2025-05-01-preview
+GET https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]?api-version=2025-08-01-preview
     Content-Type: application/json
     api-key: [YOUR-ADMIN-KEY]
 ```
@@ -98,7 +98,7 @@ In the index definition, modify `cache` to include the following required and op
 + (Optional) `enableReprocessing` boolean property (`true` by default), indicates that incremental enrichment is enabled. Set to `false` if you want to suspend incremental processing while other resource-intensive operations, such as indexing new documents, are underway and then switch back to `true` later.
 
 ```http
-POST https://[service name].search.windows.net/indexers?api-version=2025-05-01-preview
+POST https://[service name].search.windows.net/indexers?api-version=2025-08-01-preview
     {
         "name": "<YOUR-INDEXER-NAME>",
         "targetIndexName": "<YOUR-INDEX-NAME>",
@@ -119,17 +119,17 @@ POST https://[service name].search.windows.net/indexers?api-version=2025-05-01-p
 [Reset Indexer](/rest/api/searchservice/indexers/reset) is required when setting up incremental enrichment for existing indexers to ensure all documents are in a consistent state. You can use the Azure portal or an API client for this task.
 
 ```https
-POST https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]/reset?api-version=2025-05-01-preview
+POST https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]/reset?api-version=2025-08-01-preview
     Content-Type: application/json
     api-key: [YOUR-ADMIN-KEY]
 ```
 
 ### Step 4: Save the indexer
 
-[Update Indexer](/rest/api/searchservice/indexers/create-or-update?view=rest-searchservice-2025-05-01-preview&preserve-view=true) with a PUT request, where the body of the request includes `cache`.
+[Update Indexer](/rest/api/searchservice/indexers/create-or-update?view=rest-searchservice-2025-08-01-preview&preserve-view=true) with a PUT request, where the body of the request includes `cache`.
 
 ```http
-PUT https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]?api-version=2025-05-01-preview
+PUT https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]?api-version=2025-08-01-preview
     Content-Type: application/json
     api-key: [YOUR-ADMIN-KEY]
     {
@@ -159,7 +159,7 @@ To run indexer, you can use the Azure portal or the API. In the Azure portal, fr
 Alternatively, you can use REST to [run the indexer](/rest/api/searchservice/indexers/run):
 
 ```http
-POST https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]/run?api-version=2025-05-01-preview
+POST https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]/run?api-version=2025-08-01-preview
 Content-Type: application/json
 api-key: [YOUR-ADMIN-KEY]
 ```

@@ -6,7 +6,7 @@ author: HeidiSteen
 ms.author: heidist
 ms.service: azure-ai-search
 ms.topic: how-to
-ms.date: 07/28/2025
+ms.date: 08/27/2025
 ms.update-cycle: 180-days
 ms.custom:
   - ignite-2023
@@ -43,10 +43,10 @@ The cache is created when you specify the "cache" property and run the indexer.
 
 The following example illustrates an indexer with caching enabled. See [Configure enrichment caching](enrichment-cache-how-to-configure.md) for full instructions. 
 
-To set the cache property, use a preview REST API [Create or Update Indexer](/rest/api/searchservice/indexers/create-or-update?view=rest-searchservice-2025-05-01-preview&preserve-view=true) or a preview Azure SDK package that provides the feature. You can also enable enrichment caching in the Import data wizard in the Azure portal.
+To set the cache property, use latest preview REST API for [Create or Update Indexer](/rest/api/searchservice/indexers/create-or-update?view=rest-searchservice-2025-08-01-preview&preserve-view=true) or a preview Azure SDK package that provides the feature. You can also enable enrichment caching in the Import data wizard in the Azure portal.
 
 ```json
-POST https://[YOUR-SEARCH-SERVICE-NAME].search.windows.net/indexers?api-version=2025-05-01-preview
+POST https://[YOUR-SEARCH-SERVICE-NAME].search.windows.net/indexers?api-version=2025-08-01-preview
     {
         "name": "myIndexerName",
         "targetIndexName": "myIndex",
@@ -96,7 +96,7 @@ If you know that a change to the skill is indeed superficial, you should overrid
 Setting this parameter ensures that only updates to the skillset definition are committed and the change isn't evaluated for effects on the existing cache. Use a preview API version, 2020-06-30-Preview or later. We recommend the latest preview API.
 
 ```http
-PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=2025-05-01-preview&disableCacheReprocessingChangeDetection
+PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=2025-08-01-preview&disableCacheReprocessingChangeDetection
   
 ```
 
@@ -107,7 +107,7 @@ PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-versi
 Most changes to a data source definition will invalidate the cache. However, for scenarios where you know that a change shouldn't invalidate the cache - such as changing a connection string or rotating the key on the storage account - append the `ignoreResetRequirement` parameter on the [data source update](/rest/api/searchservice/data-sources/create-or-update). Setting this parameter to true allows the commit to go through, without triggering a reset condition that would result in all objects being rebuilt and populated from scratch.
 
 ```http
-PUT https://[search service].search.windows.net/datasources/[data source name]?api-version=2025-05-01-preview&ignoreResetRequirement
+PUT https://[search service].search.windows.net/datasources/[data source name]?api-version=2025-08-01-preview&ignoreResetRequirement
  
 ```
 
@@ -117,13 +117,13 @@ PUT https://[search service].search.windows.net/datasources/[data source name]?a
 
 The purpose of the cache is to avoid unnecessary processing, but suppose you make a change to a skill that the indexer doesn't detect (for example, changing something in external code, such as a custom skill).
 
-In this case, you can use the [Reset Skills](/rest/api/searchservice/skillsets/reset-skills?view=rest-searchservice-2025-05-01-preview&preserve-view=true) to force reprocessing of a particular skill, including any downstream skills that have a dependency on that skill's output. This API accepts a POST request with a list of skills that should be invalidated and marked for reprocessing. After Reset Skills, follow with a [Run Indexer](/rest/api/searchservice/indexers/run) request to invoke the pipeline processing.
+In this case, you can use the [Reset Skills](/rest/api/searchservice/skillsets/reset-skills?view=rest-searchservice-2025-08-01-preview&preserve-view=true) to force reprocessing of a particular skill, including any downstream skills that have a dependency on that skill's output. This API accepts a POST request with a list of skills that should be invalidated and marked for reprocessing. After Reset Skills, follow with a [Run Indexer](/rest/api/searchservice/indexers/run) request to invoke the pipeline processing.
 
 ## Re-cache specific documents
 
 [Resetting an indexer](/rest/api/searchservice/indexers/reset) will result in all documents in the search corpus being reprocessed. 
 
-In scenarios where only a few documents need to be reprocessed, use [Reset Documents (preview)](/rest/api/searchservice/indexers/reset-docs?view=rest-searchservice-2025-05-01-preview&preserve-view=true) to force reprocessing of specific documents. When a document is reset, the indexer invalidates the cache for that document, which is then reprocessed by reading it from the data source. For more information, see [Run or reset indexers, skills, and documents](search-howto-run-reset-indexers.md).
+In scenarios where only a few documents need to be reprocessed, use [Reset Documents (preview)](/rest/api/searchservice/indexers/reset-docs?view=rest-searchservice-2025-08-01-preview&preserve-view=true) to force reprocessing of specific documents. When a document is reset, the indexer invalidates the cache for that document, which is then reprocessed by reading it from the data source. For more information, see [Run or reset indexers, skills, and documents](search-howto-run-reset-indexers.md).
 
 To reset specific documents, the request provides a list of document keys as read from the search index. If the key is mapped to a field in the external data source, the value that you provide should be the one used in the search index.
 
@@ -138,7 +138,7 @@ Depending on how you call the API, the request will either append, overwrite, or
 The following example illustrates a reset document request:
 
 ```http
-POST https://[search service name].search.windows.net/indexers/[indexer name]/resetdocs?api-version=2025-05-01-preview
+POST https://[search service name].search.windows.net/indexers/[indexer name]/resetdocs?api-version=2025-08-01-preview
     {
         "documentKeys" : [
             "key1",
@@ -189,10 +189,10 @@ Preview APIs provide extra properties on indexers. We recommend the latest previ
 
 Skillsets and data sources can use the generally available version. In addition to the reference documentation, see  [Configure caching for incremental enrichment](enrichment-cache-how-to-configure.md) for details about order of operations.
 
-+ [Create or Update Indexer (api-version=2025-05-01-preview)](/rest/api/searchservice/indexers/create-or-update?view=rest-searchservice-2025-05-01-preview&preserve-view=true) 
++ [Create or Update Indexer (api-version=2025-08-01-preview)](/rest/api/searchservice/indexers/create-or-update?view=rest-searchservice-2025-08-01-preview&preserve-view=true) 
 
-+ [Reset Skills (api-version=2025-05-01-preview)](/rest/api/searchservice/skillsets/reset-skills?view=rest-searchservice-2025-05-01-preview&preserve-view=true)
++ [Reset Skills (api-version=2025-08-01-preview)](/rest/api/searchservice/skillsets/reset-skills?view=rest-searchservice-2025-08-01-preview&preserve-view=true)
 
-+ [Create or Update Skillset (api-version=2025-05-01-preview)](/rest/api/searchservice/skillsets/create-or-update?view=rest-searchservice-2025-05-01-preview&preserve-view=true) (New URI parameter on the request)
++ [Create or Update Skillset (api-version=2025-08-01-preview)](/rest/api/searchservice/skillsets/create-or-update?view=rest-searchservice-2025-08-01-preview&preserve-view=true) (New URI parameter on the request)
 
-+ [Create or Update Data Source (api-version=2025-05-01-preview)](/rest/api/searchservice/data-sources/create-or-update?view=rest-searchservice-2025-05-01-preview&preserve-view=true), when called with a preview API version, provides a new parameter named "ignoreResetRequirement", which should be set to true when your update action shouldn't invalidate the cache. Use "ignoreResetRequirement" sparingly as it could lead to unintended inconsistency in your data that won't be detected easily.
++ [Create or Update Data Source (api-version=2025-08-01-preview)](/rest/api/searchservice/data-sources/create-or-update?view=rest-searchservice-2025-08-01-preview&preserve-view=true), when called with a preview API version, provides a new parameter named "ignoreResetRequirement", which should be set to true when your update action shouldn't invalidate the cache. Use "ignoreResetRequirement" sparingly as it could lead to unintended inconsistency in your data that won't be detected easily.

@@ -8,7 +8,7 @@ ms.service: azure-ai-search
 ms.custom:
   - ignite-2023
 ms.topic: how-to
-ms.date: 07/21/2025
+ms.date: 08/28/2025
 ---
 
 # Create a hybrid query in Azure AI Search
@@ -163,12 +163,12 @@ A hybrid query can be tuned to control how much of each subquery contributes to
 
 If you use `maxTextRecallSize`, you might also want to set `CountAndFacetMode`. This parameter determines whether the `count` and `facets` should include all documents that matched the search query, or only those documents retrieved within the `maxTextRecallSize` window. The default value is "countAllResults".
 
-We recommend the latest preview REST API version [2025-05-01-preview](/rest/api/searchservice/documents/search-post?view=rest-searchservice-2025-05-01-preview&preserve-view=true) for setting these options.
+We recommend the [latest preview REST API](/rest/api/searchservice/documents/search-post?view=rest-searchservice-2025-08-01-preview&preserve-view=true) for setting these options.
 
 > [!TIP]
 > Another approach for hybrid query tuning is [vector weighting](vector-search-how-to-query.md#vector-weighting), used to increase the importance of vector queries in the request.
 
-1. Use [Search - POST (preview)](/rest/api/searchservice/documents/search-post?view=rest-searchservice-2025-05-01-preview&preserve-view=true) or [Search - GET (preview)](/rest/api/searchservice/documents/search-get?view=rest-searchservice-2025-05-01-preview&preserve-view=true) to specify preview parameters.
+1. Use [Search - POST (preview)](/rest/api/searchservice/documents/search-post?view=rest-searchservice-2025-08-01-preview&preserve-view=true) or [Search - GET (preview)](/rest/api/searchservice/documents/search-get?view=rest-searchservice-2025-08-01-preview&preserve-view=true) to specify preview parameters.
 
 1. Add a `hybridSearch` query parameter object to set the maximum number of documents recalled through the BM25-ranked results of a hybrid query. It has two properties:
 
@@ -259,7 +259,7 @@ api-key: {{admin-api-key}}
         }
     ],
     "search": "historic hotel walk to restaurants and shopping",
-    "vectorFilterMode": "postFilter",
+    "vectorFilterMode": "preFilter",
     "filter": "ParkingIncluded",
     "top": "10"
 }
@@ -269,28 +269,28 @@ api-key: {{admin-api-key}}
 
 + Filters are applied to the content of filterable fields. In this example, the ParkingIncluded field is a boolean and it's marked as `filterable` in the index schema.
 
-+ In hybrid queries, filters can be applied before query execution to reduce the query surface, or after query execution to trim results. `"preFilter"` is the default. To use `postFilter`, set the [filter processing mode](vector-search-filters.md) as shown in this example.
++ In hybrid queries, filters can be applied before query execution to reduce the query surface or after query execution to trim results. `"preFilter"` is the default. To use `postFilter` or `strictPostFilter` (preview), set the [filter processing mode](vector-search-filters.md) as shown in this example.
 
 + When you postfilter query results, the number of results might be less than top-n.
 
 ### Example: Hybrid search with filters targeting vector subqueries (preview)
 
-Using a [preview API](/rest/api/searchservice/documents/search-post?view=rest-searchservice-2025-05-01-preview&preserve-view=true), you can override a global filter on the search request by applying a secondary filter that targets just the vector subqueries in a hybrid request.
+Using the [latest preview REST API](/rest/api/searchservice/documents/search-post?view=rest-searchservice-2025-08-01-preview&preserve-view=true), you can override a global filter on the search request by applying a secondary filter that targets just the vector subqueries in a hybrid request.
 
 This feature provides fine-grained control by ensuring that filters only influence the vector search results, leaving keyword-based search results unaffected. 
 
 The targeted filter fully overrides the global filter, including any filters used for [security trimming](search-security-trimming-for-azure-search.md) or geospatial search.  In cases where global filters are required, such as security trimming, you must explicitly include these filters in both the top-level filter and in each vector-level filter to ensure security and other constraints are consistently enforced.
 
 To apply targeted vector filters:
 
-+ Use the [latest preview Search Documents REST API](/rest/api/searchservice/documents/search-post?view=rest-searchservice-2025-05-01-preview&preserve-view=true#request-body) or an Azure SDK beta package that provides the feature.
++ Use the [latest preview Search Documents REST API](/rest/api/searchservice/documents/search-post?view=rest-searchservice-2025-08-01-preview&preserve-view=true#request-body) or an Azure SDK beta package that provides the feature.
 
 + Modify a query request, adding a new `vectorQueries.filterOverride` parameter set to an [OData filter expression](search-query-odata-filter.md).
 
 Here's an example of hybrid query that adds a filter override. The global filter "Rating gt 3" is replaced at run time by the `filterOverride`.
 
 ```http
-POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2025-05-01=preview
+POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2025-08-01-preview
 
 {
     "vectorQueries": [
@@ -390,7 +390,7 @@ api-key: {{admin-api-key}}
     "captions": "extractive",
     "answers": "extractive",
     "filter": "ParkingIsIncluded'",
-    "vectorFilterMode": "postFilter",
+    "vectorFilterMode": "preFilter",
     "top": "50"
 }
 ```
@@ -399,9 +399,11 @@ api-key: {{admin-api-key}}
 
 + The filter mode can affect the number of results available to the semantic reranker. As a best practice, it's smart to give the semantic ranker the maximum number of documents (50). If prefilters or postfilters are too selective, you might be underserving the semantic ranker by giving it fewer than 50 documents to work with.
 
-+ Prefiltering is applied before query execution. If prefilter reduces the search area to 100 documents, the vector query executes over the "DescriptionVector" field for those 100 documents, returning the k=50 best matches. Those 50 matching documents then pass to RRF for merged results, and then to semantic ranker.
++ `preFilter` is applied before query execution. If prefilter reduces the search area to 100 documents, the vector query executes over the `DescriptionVector` field for those 100 documents, returning the k=50 best matches. Those 50 matching documents then pass to RRF for merged results, and then to semantic ranker.
 
-+ Postfilter is applied after query execution. If k=50 returns 50 matches on the vector query side, followed by a post-filter applied to the 50 matches, your results are reduced by the number of documents that meet filter criteria. This leaves you with fewer than 50 documents to pass to semantic ranker. Keep this in mind if you're using semantic ranking. The semantic ranker works best if it has 50 documents as input.
++ `postFilter` is applied after query execution. If k=50 returns 50 matches on the vector query side, followed by a post-filter applied to the 50 matches, your results are reduced by the number of documents that meet filter criteria. This leaves you with fewer than 50 documents to pass to semantic ranker. Keep this in mind if you're using semantic ranking. The semantic ranker works best if it has 50 documents as input.
+
++ `strictPostFilter` (preview) is applied on the unfiltered top-`k` results after query execution. It always returns less than or equal to `k` documents. If the unfiltered k=50 returns 50 unfiltered results, and the filter matches 30 documents, only 30 documents are returned in the result set, even if the index has more than 30 documents that match the filter. Since this mode has the greatest reduction in recall, we don't recommend that you use it with semantic ranker.
 
 ## Configure a query response
 

@@ -8,7 +8,7 @@ ms.service: azure-ai-search
 ms.custom:
   - ignite-2023
 ms.topic: conceptual
-ms.date: 07/21/2025
+ms.date: 08/27/2025
 ---
 
 # Relevance scoring in hybrid search using Reciprocal Rank Fusion (RRF)
@@ -18,7 +18,7 @@ Reciprocal Rank Fusion (RRF) is an algorithm that evaluates the search scores fr
 RRF is based on the concept of *reciprocal rank*, which is the inverse of the rank of the first relevant document in a list of search results. The goal of the technique is to take into account the position of the items in the original rankings, and give higher importance to items that are ranked higher in multiple lists. This can help improve the overall quality and reliability of the final ranking, making it more useful for the task of fusing multiple ordered search results.
 
 > [!NOTE]
-> [Preview APIs](/rest/api/searchservice/documents/search-post?view=rest-searchservice-2025-05-01-preview&preserve-view=true) can deconstruct an RRF-ranked search score into its component subscores. This gives you transparency into all-up score composition. For more information, see [unpack search scores (preview)](#unpack-a-search-score-into-subscores-preview) in this article.
+> The [latest preview REST API](/rest/api/searchservice/documents/search-post?view=rest-searchservice-2025-08-01-preview&preserve-view=true) can deconstruct an RRF-ranked search score into its component subscores. This gives you transparency into all-up score composition. For more information, see [Unpack search scores (preview)](#unpack-a-search-score-into-subscores-preview) in this article.
 
 ## How RRF ranking works
 
@@ -61,20 +61,20 @@ Semantic ranking occurs after RRF merging of results. Its score (`@search.rerank
 
 ## Unpack a search score into subscores (preview)
 
-Using the [latest preview API version](/rest/api/searchservice/documents/search-post?view=rest-searchservice-2025-05-01-preview&preserve-view=true), you can deconstruct a search score to view its subscores.
+Using the [latest preview REST API](/rest/api/searchservice/documents/search-post?view=rest-searchservice-2025-08-01-preview&preserve-view=true), you can deconstruct a search score to view its subscores.
 
 For vector queries, this information can help you determine an appropriate value for [vector weighting](vector-search-how-to-query.md#vector-weighting) or [setting minimum thresholds](vector-search-how-to-query.md#set-thresholds-to-exclude-low-scoring-results-preview).
 
 To get subscores:
 
-+ Use the [latest preview Search Documents REST API](/rest/api/searchservice/documents/search-post?view=rest-searchservice-2025-05-01-preview&preserve-view=true#request-body) or an Azure SDK beta package that provides the feature.
++ Use the [latest preview Search Documents REST API](/rest/api/searchservice/documents/search-post?view=rest-searchservice-2025-08-01-preview&preserve-view=true#request-body) or an Azure SDK beta package that provides the feature.
 
 + Modify a query request, adding a new `debug` parameter set to either `vector`, `semantic` if using semantic ranker, or `all`.
 
 Here's an example of hybrid query that returns subscores in debug mode:
 
 ```http
-POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2025-05-01=preview
+POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2025-08-01-preview
 
 {
     "vectorQueries": [

@@ -4,7 +4,7 @@ author: haileytap
 ms.author: haileytapia
 ms.service: azure-ai-search
 ms.topic: include
-ms.date: 6/24/2025
+ms.date: 08/28/2025
 ---
 
 [!INCLUDE [Feature preview](../previews/preview-generic.md)]
@@ -13,8 +13,10 @@ In this quickstart, you use [agentic retrieval](../../search-agentic-retrieval-c
 
 Although you can provide your own data, this quickstart uses [sample JSON documents](https://github.com/Azure-Samples/azure-search-sample-data/tree/main/nasa-e-book/earth-at-night-json) from NASA's Earth at Night e-book. The documents describe general science topics and images of Earth at night as observed from space.
 
+To get started with a Jupyter notebook instead, see the [Azure-Samples/azure-search-dotnet-samples](https://github.com/Azure-Samples/azure-search-dotnet-samples/tree/main/quickstart-agentic-retrieval) repository on GitHub.
+
 > [!TIP]
-> To get started with a Jupyter notebook instead, see the [Azure-Samples/azure-search-dotnet-samples](https://github.com/Azure-Samples/azure-search-dotnet-samples/tree/main/quickstart-agentic-retrieval) repository on GitHub.
+> The C# version of this quickstart uses the 2025-05-01-preview REST API version, which doesn't support knowledge sources and other agentic retrieval features introduced in the 2025-08-01-preview. To use these features, see the REST version of this quickstart.
 
 ## Prerequisites
 

@@ -4,14 +4,18 @@ author: haileytap
 ms.author: haileytapia
 ms.service: azure-ai-search
 ms.topic: include
-ms.date: 7/21/2025
+ms.date: 08/28/2025
 ---
+
 [!INCLUDE [Feature preview](../previews/preview-generic.md)]
 
 In this quickstart, you use [agentic retrieval](../../search-agentic-retrieval-concept.md) to create a conversational search experience powered by large language models (LLMs) and your proprietary data. Agentic retrieval breaks down complex user queries into subqueries, runs the subqueries in parallel, and extracts grounding data from documents indexed in Azure AI Search. The output is intended for integration with agentic and custom chat solutions.
 
 Although you can provide your own data, this quickstart uses [sample JSON documents](https://github.com/Azure-Samples/azure-search-sample-data/tree/main/nasa-e-book/earth-at-night-json) from NASA's Earth at Night e-book. The documents describe general science topics and images of Earth at night as observed from space.
 
+> [!TIP]
+> The Java version of this quickstart uses the 2025-05-01-preview REST API version, which doesn't support knowledge sources and other agentic retrieval features introduced in the 2025-08-01-preview. To use these features, see the REST version of this quickstart.
+
 ## Prerequisites
 
 + An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).

@@ -4,14 +4,18 @@ author: haileytap
 ms.author: haileytapia
 ms.service: azure-ai-search
 ms.topic: include
-ms.date: 7/21/2025
+ms.date: 08/28/2025
 ---
+
 [!INCLUDE [Feature preview](../previews/preview-generic.md)]
 
 In this quickstart, you use [agentic retrieval](../../search-agentic-retrieval-concept.md) to create a conversational search experience powered by large language models (LLMs) and your proprietary data. Agentic retrieval breaks down complex user queries into subqueries, runs the subqueries in parallel, and extracts grounding data from documents indexed in Azure AI Search. The output is intended for integration with agentic and custom chat solutions.
 
 Although you can provide your own data, this quickstart uses [sample JSON documents](https://github.com/Azure-Samples/azure-search-sample-data/tree/main/nasa-e-book/earth-at-night-json) from NASA's Earth at Night e-book. The documents describe general science topics and images of Earth at night as observed from space.
 
+> [!TIP]
+> The JavaScript version of this quickstart uses the 2025-05-01-preview REST API version, which doesn't support knowledge sources and other agentic retrieval features introduced in the 2025-08-01-preview. To use these features, see the REST version of this quickstart.
+
 ## Prerequisites
 
 + An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).

@@ -4,7 +4,7 @@ author: haileytap
 ms.author: haileytapia
 ms.service: azure-ai-search
 ms.topic: include
-ms.date: 6/24/2025
+ms.date: 08/28/2025
 ---
 
 [!INCLUDE [Feature preview](../previews/preview-generic.md)]
@@ -15,6 +15,9 @@ Although you can provide your own data, this quickstart uses [sample JSON docume
 
 This quickstart is based on the [Quickstart-Agentic-Retrieval](https://github.com/Azure-Samples/azure-search-python-samples/tree/main/Quickstart-Agentic-Retrieval) Jupyter notebook on GitHub.
 
+> [!TIP]
+> The Python version of this quickstart uses the 2025-05-01-preview REST API version, which doesn't support knowledge sources and other agentic retrieval features introduced in the 2025-08-01-preview. To use these features, see the REST version of this quickstart.
+
 ## Prerequisites
 
 + An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).

@@ -4,178 +4,182 @@ author: haileytap
 ms.author: haileytapia
 ms.service: azure-ai-search
 ms.topic: include
-ms.date: 6/15/2025
+ms.date: 08/26/2025
 ---
 
 [!INCLUDE [Feature preview](../previews/preview-generic.md)]
 
-In this quickstart, you use [agentic retrieval](../../search-agentic-retrieval-concept.md) to create a conversational search experience powered by large language models (LLMs) and your proprietary data. Agentic retrieval breaks down complex user queries into subqueries, runs the subqueries in parallel, and extracts grounding data from documents indexed in Azure AI Search. The output is intended for integration with custom chat solutions.
+In this quickstart, you use [agentic retrieval](../../search-agentic-retrieval-concept.md) to create a conversational search experience powered by documents indexed in Azure AI Search and large language models (LLMs) from Azure AI Foundry Models.
+
+A *knowledge agent* orchestrates agentic retrieval by decomposing complex queries into subqueries, running the subqueries against one or more *knowledge sources*, and returning results with metadata. By default, the agent outputs raw content from your sources, but this quickstart passes the output to an LLM for natural-language answer generation.
 
 Although you can provide your own data, this quickstart uses [sample JSON documents](https://github.com/Azure-Samples/azure-search-sample-data/tree/main/nasa-e-book/earth-at-night-json) from NASA's Earth at Night e-book. The documents describe general science topics and images of Earth at night as observed from space.
 
 > [!TIP]
-> The REST version of this quickstart introduces agentic retrieval in Azure AI Search, which *extracts* rather than *generates* answers. For an end-to-end workflow, including steps for adding conversational turns and passing your retrieved content to an LLM for answer generation, see the C# or Python version.
+> Want to get started right away? See the [azure-search-rest-samples](https://github.com/Azure-Samples/azure-search-rest-samples/tree/main/Quickstart-agentic-retrieval) repository on GitHub.
 
 ## Prerequisites
 
 + An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
 
 + An [Azure AI Search service](../../search-create-service-portal.md) on the Basic tier or higher with [semantic ranker enabled](../../semantic-how-to-enable-disable.md).
 
-+ An [Azure AI Foundry project](/azure/ai-foundry/how-to/create-projects). You get an Azure AI Foundry resource (that's needed for model deployments) when you create an Azure AI Foundry project.
-
-+ [Visual Studio Code](https://code.visualstudio.com/download) with a [REST client](https://marketplace.visualstudio.com/items?itemName=humao.rest-client).
++ An [Azure AI Foundry project](/azure/ai-foundry/how-to/create-projects) and Azure AI Foundry resource. When you create a project, the resource is automatically created.
 
 + The [Azure CLI](/cli/azure/install-azure-cli) for keyless authentication with Microsoft Entra ID.
 
++ [Visual Studio Code](https://code.visualstudio.com/download) with the [REST Client extension](https://marketplace.visualstudio.com/items?itemName=humao.rest-client).
+
 [!INCLUDE [Setup](./agentic-retrieval-setup.md)]
 
 ## Connect from your local system
 
-You configured role-based access to interact with Azure AI Search and Azure OpenAI. From the command line, use the Azure CLI to sign in to the same subscription and tenant for both services. For more information, see [Quickstart: Connect without keys](../../search-get-started-rbac.md).
+You configured role-based access to interact with Azure AI Search and Azure AI Foundry. From the command line, use the Azure CLI to sign in to the same subscription and tenant for both resources. For more information, see [Quickstart: Connect without keys](../../search-get-started-rbac.md).
 
 To connect from your local system:
 
-1. Open a new terminal in Visual Studio Code and change to the directory where you want to save your files.
+1. Open a command-line tool, such as PowerShell.
 
-1. Run the following command and sign in with your Azure account. If you have multiple subscriptions, select the one that contains your Azure AI Search service and Azure AI Foundry project.
+1. Sign in to your Azure account. If you have multiple subscriptions, select the one that contains your Azure AI Search service and Azure AI Foundry project.
 
     ```azurecli
     az login
     ```
 
-1. To obtain your Microsoft Entra token, run the following command. You specify this value in the next section.
+1. Generate a Microsoft Entra ID token.
 
    ```azurecli
    az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv
    ```
 
+1. Make a note of the token for use in the next section.
+
 ## Load connections
 
-Before you send any requests, define credentials, endpoints, and deployment details for connections to Azure AI Search and Azure OpenAI. These values are used in subsequent operations.
+Before you send any requests, define endpoints, credentials, and deployment details for connections to Azure AI Search and Azure AI Foundry. These values are used in the following sections.
 
 To load the connections:
 
-1. In Visual Studio Code create a `.rest` or `.http` file. For example, you can name the file `agentic-retrieval.rest`.
-1. Paste these placeholders into the new file:
+1. In Visual Studio Code, create a file named `agentic-retrieval.rest`.
+
+1. Paste the following variables and HTTP request into the file.
 
     ```HTTP
-    @baseUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE
+    @search-url = PUT-YOUR-SEARCH-SERVICE-URL-HERE
     @token = PUT-YOUR-MICROSOFT-ENTRA-TOKEN-HERE
-    @aoaiBaseUrl = PUT-YOUR-AI-FOUNDRY-URL-HERE
-    @aoaiGptModel = gpt-4.1-mini
-    @aoaiGptDeployment = gpt-4.1-mini
-    @aoaiEmbeddingModel = text-embedding-3-large
-    @aoaiEmbeddingDeployment = text-embedding-3-large
-    @index-name = earth_at_night
-    @agent-name = earth-search-agent
-    @api-version = 2025-05-01-Preview
-    ```
+    @aoai-url = PUT-YOUR-AOAI-FOUNDRY-URL-HERE
+    @aoai-embedding-model = text-embedding-3-large
+    @aoai-embedding-deployment = text-embedding-3-large
+    @aoai-gpt-model = gpt-4.1-mini
+    @aoai-gpt-deployment = gpt-4.1-mini
+    @index-name = earth-at-night
+    @knowledge-source-name = earth-knowledge-source
+    @knowledge-agent-name = earth-knowledge-agent
+    @api-version = 2025-08-01-Preview
 
-1. Set `@baseUrl` to your Azure AI Search endpoint, which looks like `https://<your-search-service-name>.search.windows.net.` Set `@aoaiBaseUrl` to your Azure AI Foundry endpoint, which looks like `https://<your-foundry-resource-name>.openai.azure.com.` You obtained both values in the [Get endpoints](#get-endpoints) section. 
-
-1. Replace `@token` with the Microsoft Entra token you obtained in [Connect from your local system](#connect-from-your-local-system).
-
-1. In the same file, enter and send the following HTTP request to verify that you can connect to Azure AI Search. The request lists existing indexes in your search service.
-
-    ```HTTP
     ### List existing indexes by name
-    GET {{baseUrl}}/indexes?api-version={{api-version}}  HTTP/1.1
+    GET {{search-url}}/indexes?api-version={{api-version}}  HTTP/1.1
         Content-Type: application/json
         Authorization: Bearer {{token}}
     ```
 
+1. Set `@search-url` and `aoai-url` to the values you obtained in [Get endpoints](#get-endpoints).
+
+1. Set `@token` to the value you obtained in [Connect from your local system](#connect-from-your-local-system).
+
+1. Under `### List existing indexes by name`, select **Send Request** to verify the connection to your search service.
+
     A response should appear in an adjacent pane. If you have existing indexes, they're listed. Otherwise, the list is empty. If the HTTP code is `200 OK`, you're ready to proceed.
 
 ## Create a search index
 
-In Azure AI Search, an index is a structured collection of data. Use [Create Index](/rest/api/searchservice/indexes/create) to define an index named `earth_at_night`, which you specified using the `@index-name` variable in the previous section.
+In Azure AI Search, an index is a structured collection of data. Use [Indexes - Create (REST API)](/rest/api/searchservice/indexes/create) to define an index named `earth-at-night`, which you previously specified using the `@index-name` variable.
+
+The index schema contains fields for document identification and page content, embeddings, and numbers. The schema also includes configurations for semantic ranking and vector search, which uses your `text-embedding-3-large` deployment to vectorize text and match documents based on semantic or conceptual similarity.
 
 ```HTTP
 ### Create an index
-PUT {{baseUrl}}/indexes/{{index-name}}?api-version={{api-version}}  HTTP/1.1
+PUT {{search-url}}/indexes/{{index-name}}?api-version={{api-version}}  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
 
     {
-    "name": "{{index-name}}",
-    "fields": [
-        {
-        "name": "id",
-        "type": "Edm.String",
-        "key": true
-        },
-        {
-        "name": "page_chunk",
-        "type": "Edm.String",
-        "searchable": true
-        },
-        {
-        "name": "page_embedding_text_3_large",
-        "type": "Collection(Edm.Single)",
-        "stored": false,
-        "dimensions": 3072,
-        "vectorSearchProfile": "hnsw_text_3_large"
+        "name": "{{index-name}}",
+        "fields": [
+            {
+                "name": "id",
+                "type": "Edm.String",
+                "key": true
+            },
+            {
+                "name": "page_chunk",
+                "type": "Edm.String",
+                "searchable": true
+            },
+            {
+                "name": "page_embedding_text_3_large",
+                "type": "Collection(Edm.Single)",
+                "stored": false,
+                "dimensions": 3072,
+                "vectorSearchProfile": "hnsw_text_3_large"
+            },
+            {
+                "name": "page_number",
+                "type": "Edm.Int32",
+                "filterable": true
+            }
+        ],
+        "semantic": {
+            "defaultConfiguration": "semantic_config",
+            "configurations": [
+                {
+                    "name": "semantic_config",
+                    "prioritizedFields": {
+                    "prioritizedContentFields": [
+                        {
+                            "fieldName": "page_chunk"
+                        }
+                    ]
+                    }
+                }
+            ]
         },
-        {
-        "name": "page_number",
-        "type": "Edm.Int32",
-        "filterable": true
-        }
-    ],
-    "semantic": {
-        "defaultConfiguration": "semantic_config",
-        "configurations": [
-        {
-            "name": "semantic_config",
-            "prioritizedFields": {
-            "prioritizedContentFields": [
+        "vectorSearch": {
+            "profiles": [
+                {
+                    "name": "hnsw_text_3_large",
+                    "algorithm": "alg",
+                    "vectorizer": "azure_openai_text_3_large"
+                }
+            ],
+            "algorithms": [
+                {
+                    "name": "alg",
+                    "kind": "hnsw"
+                }
+            ],
+            "vectorizers": [
                 {
-                "fieldName": "page_chunk"
+                    "name": "azure_openai_text_3_large",
+                    "kind": "azureOpenAI",
+                    "azureOpenAIParameters": {
+                    "resourceUri": "{{aoai-url}}",
+                    "deploymentId": "{{aoai-embedding-deployment}}",
+                    "modelName": "{{aoai-embedding-model}}"
+                    }
                 }
             ]
-            }
         }
-        ]
-    },
-    "vectorSearch": {
-        "profiles": [
-        {
-            "name": "hnsw_text_3_large",
-            "algorithm": "alg",
-            "vectorizer": "azure_openai_text_3_large"
-        }
-        ],
-        "algorithms": [
-        {
-            "name": "alg",
-            "kind": "hnsw"
-        }
-        ],
-        "vectorizers": [
-        {
-            "name": "azure_openai_text_3_large",
-            "kind": "azureOpenAI",
-            "azureOpenAIParameters": {
-            "resourceUri": "{{aoaiBaseUrl}}",
-            "deploymentId": "{{aoaiEmbeddingDeployment}}",
-            "modelName": "{{aoaiEmbeddingModel}}"
-            }
-        }
-        ]
-    }
     }
 ```
 
-The index schema contains fields for document identification and page content, embeddings, and numbers. It also includes configurations for semantic ranking and vector queries, which use the `text-embedding-3-large` model you previously deployed.
-
 ## Upload documents to the index
 
-Currently, the `earth_at_night` index is empty. Use [Index Documents](/rest/api/searchservice/documents/index) to populate the index with JSON documents from NASA's Earth at Night e-book. As required by Azure AI Search, each document conforms to the fields and data types defined in the index schema.
+Currently, the `earth-at-night` index is empty. Use [Documents - Index (REST API)](/rest/api/searchservice/documents/index) to populate the index with JSON documents from NASA's Earth at Night e-book. As required by Azure AI Search, each document conforms to the fields and data types defined in the index schema.
 
 ```HTTP
-### Load documents
-POST {{baseUrl}}/indexes/{{index-name}}/docs/index?api-version={{api-version}}  HTTP/1.1
+### Upload documents
+POST {{search-url}}/indexes/{{index-name}}/docs/index?api-version={{api-version}}  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
 
@@ -203,46 +207,72 @@ POST {{baseUrl}}/indexes/{{index-name}}/docs/index?api-version={{api-version}}
     }
 ```
 
+## Create a knowledge source
+
+A knowledge source is a reusable reference to your source data. Use [Knowledge Sources - Create (REST API)](/rest/api/searchservice/knowledge-sources/create?view=rest-searchservice-2025-08-01-preview&preserve-view=true) to define a knowledge source named `earth-knowledge-source` that targets the `earth-at-night` index.
+
+`searchIndexParameters.sourceDataSelect` specifies which index fields are accessible for retrieval and citations. Our example includes only human-readable fields to avoid lengthy, uninterpretable embeddings in responses.
+
+```HTTP
+### Create a knowledge source
+POST {{search-url}}/knowledgesources?api-version={{api-version}}  HTTP/1.1
+    Content-Type: application/json
+    Authorization: Bearer {{token}}
+
+    {
+        "name": "{{knowledge-source-name}}",
+        "description": "This knowledge source pulls from a search index that contains pages from the Earth at Night e-book.",
+        "kind": "searchIndex",
+        "searchIndexParameters": {
+            "searchIndexName": "{{index-name}}",
+            "sourceDataSelect": "id, page_chunk, page_number"
+        }
+    }
+```
+
 ## Create a knowledge agent
 
-To connect Azure AI Search to your `gpt-4.1-mini` deployment and target the `earth_at_night` index at query time, you need a knowledge agent. Use [Create Knowledge Agents](/rest/api/searchservice/knowledge-agents/create?view=rest-searchservice-2025-05-01-preview&preserve-view=true) to define an agent named `earth-search-agent`, which you specified using the `@agent-name` variable in a previous section.
+To target your `earth-knowledge-source` and `gpt-4.1-mini` deployment at query time, you need a knowledge agent. Use [Knowledge Agents - Create (REST API)](/rest/api/searchservice/knowledge-agents/create?view=rest-searchservice-2025-08-01-preview&preserve-view=true) to define an agent named `earth-knowledge-agent`, which you previously specified using the `@knowledge-agent-name` variable.
 
-To ensure relevant and semantically meaningful responses, `defaultRerankerThreshold` is set to exclude responses with a reranker score of `2.5` or lower.
+`knowledgeSources.rerankerThreshold` ensures semantic relevance by excluding responses with a reranker score of `2.5` or lower. Meanwhile, `outputConfiguration.modality` is set to `answerSynthesis`, enabling natural-language answers that cite the retrieved documents.
 
 ```HTTP
-### Create an agent
-PUT {{baseUrl}}/agents/{{agent-name}}?api-version={{api-version}}  HTTP/1.1
+### Create a knowledge agent
+PUT {{search-url}}/agents/{{knowledge-agent-name}}?api-version={{api-version}}  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
 
     {
-        "name": "{{agent-name}}",
-        "targetIndexes": [
+        "name": "{{knowledge-agent-name}}",
+        "knowledgeSources": [
             {
-                "indexName": "{{index-name}}",
-                "defaultRerankerThreshold": 2.5
+            "name": "{{knowledge-source-name}}",
+            "rerankerThreshold": 2.5
             }
         ],
         "models": [
             {
                 "kind": "azureOpenAI",
                 "azureOpenAIParameters": {
-                    "resourceUri": "{{aoaiBaseUrl}}",
-                    "deploymentId": "{{aoaiGptDeployment}}",
-                    "modelName": "{{aoaiGptModel}}"
+                    "resourceUri": "{{aoai-url}}",
+                    "deploymentId": "{{aoai-gpt-deployment}}",
+                    "modelName": "{{aoai-gpt-model}}"
                 }
             }
-        ]
+        ],
+        "outputConfiguration": {
+            "modality": "answerSynthesis"
+        }
     }
 ```
 
 ## Run the retrieval pipeline
 
-You're ready to initiate the agentic retrieval pipeline. Use [Knowledge Retrieval - Retrieve](/rest/api/searchservice/knowledge-retrieval/retrieve?view=rest-searchservice-2025-05-01-preview&preserve-view=true) to send a two-part user query to `earth-search-agent`, which deconstructs the query into subqueries, runs the subqueries against both text fields and vector embeddings in the `earth_at_night` index, and ranks and merges the results.
+You're ready to run agentic retrieval. Use [Knowledge Retrieval - Retrieve (REST API)](/rest/api/searchservice/knowledge-retrieval/retrieve?view=rest-searchservice-2025-08-01-preview&preserve-view=true) to send a two-part user query to `earth-knowledge-agent`, which deconstructs the query into subqueries, runs the subqueries against text and vector fields in the `earth-at-night` index, and ranks and merges the results.
 
 ```HTTP
 ### Run agentic retrieval
-POST {{baseUrl}}/agents/{{agent-name}}/retrieve?api-version={{api-version}}  HTTP/1.1
+POST {{search-url}}/agents('{{knowledge-agent-name}}')/retrieve?api-version={{api-version}}  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
 
@@ -258,110 +288,137 @@ POST {{baseUrl}}/agents/{{agent-name}}/retrieve?api-version={{api-version}}  HTT
                 ]
             }
         ],
-        "targetIndexParams": [
+        "knowledgeSourceParams": [
             {
-                "indexName": "{{index-name}}",
-                "rerankerThreshold": 2.5
+                "knowledgeSourceName": "{{knowledge-source-name}}",
+                "kind": "searchIndex"
             }
         ]
     }
 ```
 
 The output should be similar to the following JSON, where:
 
-+ `response` provides a text string of the most relevant documents (or chunks) in the search index based on the user query. You can pass this string to an LLM for use as grounding data in answer generation.
++ `response` provides a synthesized, LLM-generated answer to the query based on the retrieved documents. When answer synthesis isn't enabled, this section contains content extracted directly from the documents.
 
-+ `activity` tracks the steps that were taken during the retrieval process, including the subqueries generated by your `gpt-4.1-mini` deployment and the tokens used for query planning and execution.
++ `activity` tracks the steps that were taken during the retrieval process, including the subqueries generated by your `gpt-4.1-mini` deployment and the tokens used for semantic ranking, query planning, and answer synthesis.
 
 + `references` lists the documents that contributed to the response, each one identified by their `docKey`.
 
 ```JSON
 {
   "response": [
     {
-      "role": "assistant",
       "content": [
         {
           "type": "text",
-          "text": "[{\"ref_id\":1,\"content\":\"# Urban Structure\\n\\n## March 16, 2013\\n\\n### Phoenix Metropolitan Area at Night\\n\\nThis figure presents a nighttime satellite view of the Phoenix metropolitan area, highlighting urban structure and transport corridors. City lights illuminate the layout of several cities and major thoroughfares.\\n\\n**Labeled Urban Features:**\\n\\n- **Phoenix:** Central and brightest area in the right-center of the image.\\n- **Glendale:** Located to the west of Phoenix, this city is also brightly lit.\\n- **Peoria:** Further northwest, this area is labeled and its illuminated grid is seen.\\n- **Grand Avenue:** Clearly visible as a diagonal, brightly lit thoroughfare running from Phoenix through Glendale and Peoria.\\n- **Salt River Channel:** Identified in the southeast portion, running through illuminated sections.\\n- **Phoenix Mountains:** Dark, undeveloped region to the northeast of Phoenix.\\n- **Agricultural Fields:** Southwestern corner of the image, grid patterns are visible but with much less illumination, indicating agricultural land use.\\n\\n**Additional Notes:**\\n\\n- The overall pattern shows a grid-like urban development typical of western U.S. cities, with scattered bright nodes at major intersections or city centers.\\n- There is a clear transition from dense urban development to sparsely populated or agricultural land, particularly evident towards the bottom and left of the image.\\n- The illuminated areas follow the existing road and street grids, showcasing the extensive spread of the metropolitan area.\\n\\n**Figure Description:**  \\nA satellite nighttime image captured on March 16, 2013, showing Phoenix and surrounding areas (including Glendale and Peoria). Major landscape and infrastructural features, such as the Phoenix Mountains, Grand Avenue, the Salt River Channel, and agricultural fields, are labeled. The image reveals the extent of urbanization and the characteristic street grid illuminated by city lights.\\n\\n---\\n\\nPage 89\"},{\"ref_id\":0,\"content\":\"<!-- PageHeader=\\\"Urban Structure\\\" -->\\n\\n### Location of Phoenix, Arizona\\n\\nThe image depicts a globe highlighting the location of Phoenix, Arizona, in the southwestern United States, marked with a blue pinpoint on the map of North America. Phoenix is situated in the central part of Arizona, which is in the southwestern region of the United States.\\n\\n---\\n\\n### Grid of City Blocks-Phoenix, Arizona\\n\\nLike many large urban areas of the central and western United States, the Phoenix metropolitan area is laid out along a regular grid of city blocks and streets. While visible during the day, this grid is most evident at night, when the pattern of street lighting is clearly visible from the low-Earth-orbit vantage point of the ISS.\\n\\nThis astronaut photograph, taken on March 16, 2013, includes parts of several cities in the metropolitan area, including Phoenix (image right), Glendale (center), and Peoria (left). While the major street grid is oriented north-south, the northwest-southeast oriented Grand Avenue cuts across the three cities at image center. Grand Avenue is a major transportation corridor through the western metropolitan area; the lighting patterns of large industrial and commercial properties are visible along its length. Other brightly lit properties include large shopping centers, strip malls, and gas stations, which tend to be located at the intersections of north-south and east-west trending streets.\\n\\nThe urban grid encourages growth outwards along a city's borders by providing optimal access to new real estate. Fueled by the adoption of widespread personal automobile use during the twentieth century, the Phoenix metropolitan area today includes 25 other municipalities (many of them largely suburban and residential) linked by a network of surface streets and freeways.\\n\\nWhile much of the land area highlighted in this image is urbanized, there are several noticeably dark areas. The Phoenix Mountains are largely public parks and recreational land. To the west, agricultural fields provide a sharp contrast to the lit streets of residential developments. The Salt River channel appears as a dark ribbon within the urban grid.\\n\\n\\n<!-- PageFooter=\\\"Earth at Night\\\" -->\\n<!-- PageNumber=\\\"88\\\" -->\"}]",
-          "image": null
+          "text": "Suburban belts display larger December brightening than urban cores despite higher absolute light levels downtown because the urban grid encourages outward growth along city borders, fueled by widespread personal automobile use, leading to extensive suburban and residential municipalities linked by surface streets and freeways. This expansion results in increased lighting in suburban areas during December. The Phoenix nighttime street grid is sharply visible from space due to its regular grid layout of city blocks and streets, with major transportation corridors like Grand Avenue and brightly lit commercial properties at intersections, which create distinct lighting patterns. In contrast, large stretches of interstate highways between Midwestern cities remain comparatively dim because they lack the dense, grid-like urban development and associated lighting found in metropolitan areas like Phoenix [ref_id:0][ref_id:1]."
         }
       ]
     }
   ],
   "activity": [
     {
-      "type": "ModelQueryPlanning",
+      "type": "modelQueryPlanning",
       "id": 0,
-      "inputTokens": 1355,
-      "outputTokens": 423
+      "inputTokens": 2079,
+      "outputTokens": 121,
+      "elapsedMs": 2887
     },
     {
-      "type": "AzureSearchQuery",
+      "type": "searchIndex",
       "id": 1,
-      "targetIndex": "earth_at_night",
-      "query": {
-        "search": "suburban belts December brightening urban cores comparison",
+      "knowledgeSourceName": "earth-knowledge-source",
+      "queryTime": "2025-08-25T16:23:17.832Z",
+      "count": 0,
+      "elapsedMs": 1065,
+      "searchIndexArguments": {
+        "search": "Reasons for larger December brightening in suburban belts compared to urban cores despite higher downtown light levels",
         "filter": null
-      },
-      "queryTime": "2025-05-06T15:57:14.666Z",
-      "elapsedMs": 270
+      }
     },
     {
-      "type": "AzureSearchQuery",
+      "type": "searchIndex",
       "id": 2,
-      "targetIndex": "earth_at_night",
-      "query": {
-        "search": "Phoenix nighttime street grid visibility from space",
-        "filter": null
-      },
-      "queryTime": "2025-05-06T15:57:14.858Z",
+      "knowledgeSourceName": "earth-knowledge-source",
+      "queryTime": "2025-08-25T16:23:18.139Z",
       "count": 2,
-      "elapsedMs": 192
+      "elapsedMs": 298,
+      "searchIndexArguments": {
+        "search": "Factors making Phoenix nighttime street grid sharply visible from space",
+        "filter": null
+      }
     },
     {
-      "type": "AzureSearchQuery",
+      "type": "searchIndex",
       "id": 3,
-      "targetIndex": "earth_at_night",
-      "query": {
-        "search": "interstate visibility from space midwestern cities",
+      "knowledgeSourceName": "earth-knowledge-source",
+      "queryTime": "2025-08-25T16:23:18.332Z",
+      "count": 0,
+      "elapsedMs": 189,
+      "searchIndexArguments": {
+        "search": "Reasons why large stretches of interstate between Midwestern cities are comparatively dim at night from space",
         "filter": null
-      },
-      "queryTime": "2025-05-06T15:57:15.026Z",
-      "count": 1,
-      "elapsedMs": 167
+      }
+    },
+    {
+      "type": "semanticReranker",
+      "id": 4,
+      "inputTokens": 2349
+    },
+    {
+      "type": "modelAnswerSynthesis",
+      "id": 5,
+      "inputTokens": 3216,
+      "outputTokens": 155,
+      "elapsedMs": 2274
     }
   ],
   "references": [
     {
-      "type": "AzureSearchDoc",
+      "type": "searchIndex",
       "id": "0",
       "activitySource": 2,
-      "docKey": "earth_at_night_508_page_104_verbalized",
-      "sourceData": null
+      "sourceData": null,
+      "rerankerScore": 2.6642752,
+      "docKey": "earth_at_night_508_page_104_verbalized"
     },
     {
-      "type": "AzureSearchDoc",
+      "type": "searchIndex",
       "id": "1",
       "activitySource": 2,
-      "docKey": "earth_at_night_508_page_105_verbalized",
-      "sourceData": null
+      "sourceData": null,
+      "rerankerScore": 2.5905457,
+      "docKey": "earth_at_night_508_page_105_verbalized"
     }
   ]
 }
 ```
 
 ## Clean up resources
 
-When working in your own subscription, it's a good idea to finish a project by determining whether you still need the resources you created. Resources that are left running can cost you money. You can delete resources individually, or you can delete the resource group to delete the entire set of resources.
+When you work in your own subscription, it's a good idea to finish a project by determining whether you still need the resources you created. Resources that are left running can cost you money.
+
+Run the following code to delete the objects you created in this quickstart.
+
+<!-- You can delete resources individually or delete the entire resource group.
 
-In the Azure portal, you can find and manage resources by selecting **All resources** or **Resource groups** from the left pane. You can also run the following code to delete the objects you created in this quickstart.
+In the Azure portal, you can find and manage resources by selecting **All resources** or **Resource groups** from the left pane. -->
+
+### Delete the knowledge agent
 
+```HTTP
 ### Delete the knowledge agent
+DELETE {{search-url}}/agents/{{knowledge-agent-name}}?api-version={{api-version}}  HTTP/1.1
+    Content-Type: application/json
+    Authorization: Bearer {{token}}
+```
+
+### Delete the knowledge source
 
 ```HTTP
-### Delete the agent
-DELETE {{baseUrl}}/agents/{{agent-name}}?api-version={{api-version}}
+### Delete the knowledge source
+DELETE {{search-url}}/knowledgesources('{{knowledge-source-name}}')?api-version={{api-version}}  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
 ```
@@ -370,7 +427,7 @@ DELETE {{baseUrl}}/agents/{{agent-name}}?api-version={{api-version}}
 
 ```HTTP
 ### Delete the index
-DELETE {{baseUrl}}/indexes/{{index-name}}?api-version={{api-version}}
+DELETE {{search-url}}//indexes/{{index-name}}?api-version={{api-version}}  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
 ```

@@ -4,87 +4,101 @@ author: haileytap
 ms.author: haileytapia
 ms.service: azure-ai-search
 ms.topic: include
-ms.date: 06/23/2025
+ms.date: 08/26/2025
 ---
 
-## Configure role-based access
+## Configure access
 
-You can use search service API keys or Microsoft Entra ID with role assignments. Keys are easier to start with, but roles are more secure.
+Before you begin, make sure you have permissions to access content and operations. We recommend Microsoft Entra ID for authentication and role-based access for authorization. You must be an **Owner** or **User Access Administrator** to assign roles. If roles aren't feasible, use [key-based authentication](../../search-security-api-keys.md) instead.
 
-To configure the recommended role-based access:
+To configure access for this quickstart, select both of the following tabs.
 
-1. Sign in to the [Azure portal](https://portal.azure.com/).
+### [Azure AI Search](#tab/search-perms)
 
-1. [Enable role-based access](../../search-security-enable-roles.md) on your Azure AI Search service.
+Azure AI Search provides the agentic retrieval pipeline. Configure access for yourself and your search service to read and write data, interact with Azure AI Foundry, and run the pipeline.
 
-1. On your Azure AI Search service, [assign the following roles](../../search-security-rbac.md#how-to-assign-roles-in-the-azure-portal) to yourself.
+To configure access for Azure AI Search:
+
+1. Sign in to the [Azure portal](https://portal.azure.com/) and select your search service.
+
+1. [Enable role-based access](../../search-security-enable-roles.md).
+
+1. [Create a system-assigned managed identity](../../search-how-to-managed-identities.md#create-a-system-managed-identity).
+
+1. [Assign the following roles](../../search-security-rbac.md#how-to-assign-roles-in-the-azure-portal) to yourself.
 
     + **Search Service Contributor**
 
     + **Search Index Data Contributor**
 
     + **Search Index Data Reader**
 
-For agentic retrieval, Azure AI Search also needs access to your Azure OpenAI Foundry resource.
+### [Azure AI Foundry](#tab/foundry-perms)
 
-1. [Create a system-assigned managed identity](../../search-how-to-managed-identities.md#create-a-system-managed-identity) on your Azure AI Search service. Here's how to do it using the Azure CLI:
+Azure AI Foundry provides the Azure OpenAI models used for embeddings, query planning, and answer generation. Grant your search service permission to use these models.
 
-   ```azurecli
-   az search service update --name YOUR-SEARCH-SERVICE-NAME --resource-group YOUR-RESOURCE-GROUP-NAME --identity-type SystemAssigned
-   ```
+To configure access for Azure AI Foundry:
 
-    If you already have a managed identity, you can skip this step.
+1. Sign in to the [Azure portal](https://portal.azure.com/) and select your Azure AI Foundry resource.
 
-1. On your Azure AI Foundry resource, assign **Cognitive Services User** to the managed identity that you created for your search service.
+1. Assign **Cognitive Services User** to the managed identity of your search service.
 
-## Deploy models
+---
 
-To use agentic retrieval, you must deploy [one of the supported Azure OpenAI models](../../search-agentic-retrieval-how-to-create.md#supported-models) to your Azure AI Foundry resource:
+> [!IMPORTANT]
+> Agentic retrieval has two token-based billing models:
+>
+> + Billing from Azure AI Search for semantic ranking.
+> + Billing from Azure OpenAI for query planning and answer synthesis.
+>
+> Semantic ranking is free in the initial public preview. After the preview, standard token billing applies. For more information, see [Availability and pricing of agentic retrieval](../../search-agentic-retrieval-concept.md#availability-and-pricing).
 
-+ A chat model for query planning and answer generation. We use `gpt-4.1-mini` in this quickstart. Optionally, you can use a different model for query planning and another for answer generation, but this quickstart uses the same model for simplicity.
+## Get endpoints
 
-+ An embedding model for vector queries. We use `text-embedding-3-large` in this quickstart, but you can use any embedding model that supports the `text-embedding` task.
+Each Azure AI Search service and Azure AI Foundry resource has an *endpoint*, which is a unique URL that identifies and provides network access to the resource. In a later section, you specify these endpoints to connect to your resources programmatically.
 
-To deploy the Azure OpenAI models:
+To get the endpoints for this quickstart, select both of the following tabs.
 
-1. Sign in to the [Azure AI Foundry portal](https://ai.azure.com/?cid=learnDocs) and select your Azure AI Foundry resource.
+### [Azure AI Search](#tab/search-endpoint)
 
-1. From the left pane, select **Model catalog**.
+1. Sign in to the [Azure portal](https://portal.azure.com/) and select your search service.
 
-1. Select **gpt-4.1-mini**, and then select **Use this model**.
+1. From the left pane, select **Overview**.
 
-1. Specify a deployment name. To simplify your code, we recommend **gpt-4.1-mini**.
+1. Make a note of the endpoint, which should look like `https://my-service.search.windows.net`.
 
-1. Leave the default settings.
+### [Azure AI Foundry](#tab/foundry-endpoint)
 
-1. Select **Deploy**.
+1. Sign in to the [Azure portal](https://portal.azure.com/) and select your Azure AI Foundry resource.
 
-1. Repeat the previous steps, but this time deploy the **text-embedding-3-large** embedding model.
+1. From the left pane, select **Resource Management** > **Keys and Endpoint**.
 
-## Get endpoints
+1. Select the **OpenAI** tab.
 
-In your code, you specify the following endpoints to establish connections with your Azure AI Search service and Azure AI Foundry resource. These steps assume that you [configured role-based access as described previously](#configure-role-based-access).
+1. Make a note of the endpoint, which should look like `https://my-resource.openai.azure.com`.
 
-To obtain your service endpoints:
+---
 
-1. Sign in to the [Azure portal](https://portal.azure.com/).
+## Deploy models
 
-1. On your Azure AI Search service:
+To use agentic retrieval, you must deploy two Azure OpenAI models to your Azure AI Foundry resource:
 
-    1. From the left pane, select **Overview**.
++ An embedding model for text-to-vector conversion. This quickstart uses `text-embedding-3-large`, but you can use any embedding model that supports the `text-embedding` task.
 
-    1. Copy the URL, which should be similar to `https://my-service.search.windows.net`.
++ A [supported chat completion model](../../search-agentic-retrieval-how-to-create.md#supported-models) for query planning and answer generation. This quickstart uses `gpt-4.1-mini`. Optionally, you can use one model for query planning and another model for answer generation, but this quickstart uses the same model for simplicity.
 
-1. On your Azure AI Foundry resource:
+To deploy the Azure OpenAI models:
 
-    1. From the left pane, select **Resource Management** > **Keys and Endpoint**.
+1. Sign in to the [Azure AI Foundry portal](https://ai.azure.com/?cid=learnDocs) and select your Azure AI Foundry resource.
 
-    1. Select the **OpenAI** tab and copy the URL that looks similar to `https://my-resource.openai.azure.com`.
+1. From the left pane, select **Model catalog**.
 
-> [!IMPORTANT]
-> Agentic retrieval has two token-based billing models:
->
-> + Billing from Azure OpenAI for query planning.
-> + Billing from Azure AI Search for query execution (semantic ranking).
->
-> Semantic ranking is free in the initial public preview. After the preview, standard token billing applies. For more information, see [Availability and pricing of agentic retrieval](../../search-agentic-retrieval-concept.md#availability-and-pricing).
+1. Select **text-embedding-3-large**, and then select **Use this model**.
+
+1. Enter a deployment name. To simplify your code, we recommend **text-embedding-3-large**.
+
+1. Leave the default settings.
+
+1. Select **Deploy**.
+
+1. Repeat the previous steps, but this time, deploy **gpt-4.1-mini** from the model catalog.

@@ -4,14 +4,18 @@ author: haileytap
 ms.author: haileytapia
 ms.service: azure-ai-search
 ms.topic: include
-ms.date: 7/21/2025
+ms.date: 08/28/2025
 ---
+
 [!INCLUDE [Feature preview](../previews/preview-generic.md)]
 
 In this quickstart, you use [agentic retrieval](../../search-agentic-retrieval-concept.md) to create a conversational search experience powered by large language models (LLMs) and your proprietary data. Agentic retrieval breaks down complex user queries into subqueries, runs the subqueries in parallel, and extracts grounding data from documents indexed in Azure AI Search. The output is intended for integration with agentic and custom chat solutions.
 
 Although you can provide your own data, this quickstart uses [sample JSON documents](https://github.com/Azure-Samples/azure-search-sample-data/tree/main/nasa-e-book/earth-at-night-json) from NASA's Earth at Night e-book. The documents describe general science topics and images of Earth at night as observed from space.
 
+> [!TIP]
+> The TypeScript version of this quickstart uses the 2025-05-01-preview REST API version, which doesn't support knowledge sources and other agentic retrieval features introduced in the 2025-08-01-preview. To use these features, see the REST version of this quickstart.
+
 ## Prerequisites
 
 + An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).

@@ -4,7 +4,7 @@ author: heidisteen
 ms.author: haileytapia
 ms.service: azure-ai-search
 ms.topic: include
-ms.date: 07/08/2025
+ms.date: 08/27/2025
 ---
 
 ## Prerequisites
@@ -104,7 +104,7 @@ We recommend [Visual Studio Code](https://code.visualstudio.com/download) with a
 
    ```http
    ### List existing indexes by name (verify the connection)
-    GET  {{searchUrl}}/indexes?api-version=2025-05-01-preview&$select=name  HTTP/1.1
+    GET  {{searchUrl}}/indexes?api-version=2025-08-01-preview&$select=name  HTTP/1.1
     Authorization: Bearer {{personalAccessToken}}
    ```
 

@@ -4,7 +4,7 @@ author: heidisteen
 ms.author: haileytapia
 ms.service: azure-ai-search
 ms.topic: include
-ms.date: 07/03/2025
+ms.date: 08/27/2025
 ---
 
 [!INCLUDE [Semantic ranker introduction](semantic-ranker-intro.md)]
@@ -30,7 +30,7 @@ We recommend [Visual Studio Code](https://code.visualstudio.com/download) with a
 
    ```http
    ### List existing indexes by name (verify the connection)
-    GET  {{searchUrl}}/indexes?api-version=2025-05-01-preview&$select=name  HTTP/1.1
+    GET  {{searchUrl}}/indexes?api-version=2025-08-01-preview&$select=name  HTTP/1.1
     Authorization: Bearer {{personalAccessToken}}
    ```
 
@@ -64,7 +64,7 @@ To update an index using the REST API, you must provide the entire schema, plus
 1. Formulate a POST request specifying the index name, operation, and full JSON schema. All required elements of the schema must be present. This request includes the full schema for hotels-sample-index plus the semantic configuration.
 
     ```http
-    POST  {{searchUrl}}/indexes?api-version=2025-05-01-preview  HTTP/1.1
+    POST  {{searchUrl}}/indexes?api-version=2025-08-01-preview  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{personalAccessToken}}
     
@@ -160,14 +160,14 @@ Required semantic parameters include `query_type` and `semantic_configuration_na
 1. Test the connection with a GET request that returns the hotels-sample-index.
 
     ```http
-    GET  {{searchUrl}}/indexes/hotels-sample-index?api-version=2025-05-01-preview  HTTP/1.1
+    GET  {{searchUrl}}/indexes/hotels-sample-index?api-version=2025-08-01-preview  HTTP/1.1
     Authorization: Bearer {{personalAccessToken}}
     ```
 
 1. Send a query that includes the semantic query type and configuration name.
 
    ```http
-    POST {{searchUrl}}/indexes/hotels-sample-index/docs/search?api-version=2025-05-01-preview  HTTP/1.1
+    POST {{searchUrl}}/indexes/hotels-sample-index/docs/search?api-version=2025-08-01-preview  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{personalAccessToken}}
     
@@ -247,7 +247,7 @@ Optionally, you can add captions to extract portions of the text and apply hit h
 1. Add the `captions` parameter and send the request.
 
     ```http
-    POST {{searchUrl}}/indexes/hotels-sample-index/docs/search?api-version=2025-05-01-preview  HTTP/1.1
+    POST {{searchUrl}}/indexes/hotels-sample-index/docs/search?api-version=2025-08-01-preview  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{personalAccessToken}}
     
@@ -290,7 +290,7 @@ To produce a semantic answer, the question and answer must be closely aligned, a
 1. Formulate the request using a search string that asks a question.
 
     ```http
-    POST {{searchUrl}}/indexes/hotels-sample-index/docs/search?api-version=2025-05-01-preview  HTTP/1.1
+    POST {{searchUrl}}/indexes/hotels-sample-index/docs/search?api-version=2025-08-01-preview  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{personalAccessToken}}
     

@@ -8,7 +8,7 @@ ms.service: azure-ai-search
 ms.custom:
   - ignite-2023
 ms.topic: conceptual
-ms.date: 08/13/2025
+ms.date: 08/27/2025
 ms.update-cycle: 365-days
 ---
 
@@ -137,7 +137,7 @@ In Azure AI Search, for keyword search and the text portion of a hybrid query, y
 > [!NOTE]
 > The `featuresMode` parameter isn't documented in the REST APIs, but you can use it on a preview REST API call to Search Documents for text (Keyword) search that's BM25-ranked.
 
-[Search Documents (preview)](/rest/api/searchservice/documents/search-post?view=rest-searchservice-2025-05-01-preview&preserve-view=true) requests support a `featuresMode` parameter that provides more detail about a BM25 relevance score at the field level. Whereas the `@searchScore` is calculated for the document all-up (how relevant is this document in the context of this query), featuresMode reveals information about individual fields, as expressed in a `@search.features` structure. The structure contains all fields used in the query (either specific fields through **searchFields** in a query, or all fields attributed as **searchable** in an index).
+[Search Documents (preview)](/rest/api/searchservice/documents/search-post?view=rest-searchservice-2025-08-01-preview&preserve-view=true) requests support a `featuresMode` parameter that provides more detail about a BM25 relevance score at the field level. Whereas the `@searchScore` is calculated for the document all-up (how relevant is this document in the context of this query), featuresMode reveals information about individual fields, as expressed in a `@search.features` structure. The structure contains all fields used in the query (either specific fields through **searchFields** in a query, or all fields attributed as **searchable** in an index).
 
 Valid values for featuresMode:
 
@@ -155,7 +155,7 @@ This parameter is especially useful when you're trying to understand why certain
 For a query that targets a "description" field, a request might look like this:
 
 ```http
-POST {{baseUrl}}/indexes/hotels-sample-index/docs/search?api-version=2025-05-01-preview  HTTP/1.1
+POST {{baseUrl}}/indexes/hotels-sample-index/docs/search?api-version=2025-08-01-preview  HTTP/1.1
   Content-Type: application/json
   Authorization: Bearer {{accessToken}}
 

@@ -7,7 +7,7 @@ manager: nitinme
 ms.author: heidist
 ms.service: azure-ai-search
 ms.topic: conceptual
-ms.date: 05/27/2025
+ms.date: 08/21/2025
 ms.update-cycle: 180-days
 ms.custom:
   - ignite-2023
@@ -16,6 +16,9 @@ ms.custom:
 
 # Knowledge store in Azure AI Search
 
+> [!NOTE]
+> Knowledge stores exist in Azure Storage and contain the outputs of Azure AI Search skillsets. They're separate from knowledge sources and knowledge agents, which are used in [agentic retrieval](search-agentic-retrieval-concept.md) workflows.
+
 Knowledge store is secondary storage for [AI-enriched content created by a skillset](cognitive-search-concept-intro.md) in Azure AI Search. In Azure AI Search, an indexing job always sends output to a search index, but if you attach a skillset to an indexer, you can optionally also send AI-enriched output to a container or table in Azure Storage. A knowledge store can be used for independent analysis or downstream processing in non-search scenarios like knowledge mining. 
 
 The two outputs of indexing, a search index and knowledge store, are mutually exclusive products of the same pipeline. They're derived from the same inputs and contain the same data, but their content is structured, stored, and used in different applications.

@@ -7,7 +7,7 @@ ms.author: heidist
 manager: nitinme
 ms.service: azure-ai-search
 ms.topic: conceptual
-ms.date: 05/27/2025
+ms.date: 08/21/2025
 ms.update-cycle: 365-days
 ms.custom:
   - ignite-2023
@@ -16,6 +16,9 @@ ms.custom:
 
 # Connect a knowledge store with Power BI
 
+> [!NOTE]
+> Knowledge stores exist in Azure Storage and contain the outputs of Azure AI Search skillsets. They're separate from knowledge sources and knowledge agents, which are used in [agentic retrieval](search-agentic-retrieval-concept.md) workflows.
+
 In this article, learn how to connect to and query a knowledge store using Power Query in the Power BI Desktop app. You can get started faster with templates, or build a custom dashboard from scratch.
 
 A knowledge store that's composed of tables in Azure Storage work best in Power BI. If the tables contain projections from the same skillset and projection group, you can easily "join" them to build table visualizations that include fields from related tables.

@@ -7,7 +7,7 @@ ms.author: haileytapia
 manager: nitinme
 ms.service: azure-ai-search
 ms.topic: quickstart
-ms.date: 03/04/2025
+ms.date: 08/21/2025
 ms.update-cycle: 365-days
 ms.custom:
   - mode-ui
@@ -17,6 +17,9 @@ ms.custom:
 
 # Quickstart: Create a knowledge store in the Azure portal
 
+> [!NOTE]
+> Knowledge stores exist in Azure Storage and contain the outputs of Azure AI Search skillsets. They're separate from knowledge sources and knowledge agents, which are used in [agentic retrieval](search-agentic-retrieval-concept.md) workflows.
+
 In this quickstart, you create a [knowledge store](knowledge-store-concept-intro.md) that serves as a repository for output generated from an [AI enrichment pipeline](cognitive-search-concept-intro.md) in Azure AI Search. A knowledge store makes generated content available in Azure Storage for workloads other than search.
 
 First, you set up sample data in Azure Storage. Next, you run the **Import data** wizard to create an enrichment pipeline that also generates a knowledge store. The knowledge store contains original source content pulled from the data source (customer reviews of a hotel), plus AI-generated content that includes a sentiment label, key phrase extraction, and text translation of non-English customer comments.

@@ -7,7 +7,7 @@ manager: nitinme
 ms.author: heidist
 ms.service: azure-ai-search
 ms.topic: how-to
-ms.date: 06/17/2025
+ms.date: 08/21/2025
 ms.custom:
   - ignite-2023
   - sfi-image-nochange
@@ -16,6 +16,9 @@ ms.custom:
 
 # Create a knowledge store using REST
 
+> [!NOTE]
+> Knowledge stores exist in Azure Storage and contain the outputs of Azure AI Search skillsets. They're separate from knowledge sources and knowledge agents, which are used in [agentic retrieval](search-agentic-retrieval-concept.md) workflows.
+
 In Azure AI Search, a [knowledge store](knowledge-store-concept-intro.md) is a repository of [AI-generated content](cognitive-search-concept-intro.md) that's used for non-search scenarios. You create the knowledge store using an indexer and skillset, and specify Azure Storage to store the output. After the knowledge store is populated, use tools like [Storage Explorer](/azure/vs-azure-tools-storage-manage-with-storage-explorer) or [Power BI](knowledge-store-connect-power-bi.md) to explore the content.
 
 In this article, you use the REST API to ingest, enrich, and explore a set of customer reviews of hotel stays in a knowledge store. The knowledge store contains original text content pulled from the source, plus AI-generated content that includes a sentiment score, key phrase extraction, language detection, and text translation of non-English customer comments.

@@ -7,7 +7,7 @@ author: HeidiSteen
 ms.author: heidist
 ms.service: azure-ai-search
 ms.topic: concept-article
-ms.date: 07/28/2025
+ms.date: 08/21/2025
 ms.update-cycle: 365-days
 ms.custom:
   - ignite-2023
@@ -16,6 +16,9 @@ ms.custom:
 
 # Example of shapes and projections in a knowledge store
 
+> [!NOTE]
+> Knowledge stores exist in Azure Storage and contain the outputs of Azure AI Search skillsets. They're separate from knowledge sources and knowledge agents, which are used in [agentic retrieval](search-agentic-retrieval-concept.md) workflows.
+
 This article provides a detailed example that supplements [high-level concepts](knowledge-store-projection-overview.md) and [syntax-based articles](knowledge-store-projections-examples.md) by walking you through the shaping and projection steps required for fully expressing the output of a rich skillset in a [knowledge store](knowledge-store-concept-intro.md) in Azure Storage.
 
 If your application requirements call for multiple skills and projections, this example can give you a better idea of how shapes and projections interact.

@@ -7,7 +7,7 @@ author: HeidiSteen
 ms.author: heidist
 ms.service: azure-ai-search
 ms.topic: conceptual
-ms.date: 06/17/2025
+ms.date: 08/21/2025
 ms.update-cycle: 365-days
 ms.custom:
   - ignite-2023
@@ -16,6 +16,9 @@ ms.custom:
 
 # Knowledge store "projections" in Azure AI Search
 
+> [!NOTE]
+> Knowledge stores exist in Azure Storage and contain the outputs of Azure AI Search skillsets. They're separate from knowledge sources and knowledge agents, which are used in [agentic retrieval](search-agentic-retrieval-concept.md) workflows.
+
 Projections define the physical tables, objects, and files in a [**knowledge store**](knowledge-store-concept-intro.md) that accept content from an Azure AI Search enrichment pipeline. If you're creating a knowledge store, defining and shaping projections is most of the work.
 
 This article introduces projection concepts and workflow so that you have some background before you start coding.

@@ -6,7 +6,7 @@ author: HeidiSteen
 ms.author: heidist
 ms.service: azure-ai-search
 ms.topic: conceptual
-ms.date: 06/17/2025
+ms.date: 08/21/2025
 ms.update-cycle: 365-days
 ms.custom:
   - ignite-2023
@@ -15,6 +15,9 @@ ms.custom:
 
 # Shaping data for projection into a knowledge store
 
+> [!NOTE]
+> Knowledge stores exist in Azure Storage and contain the outputs of Azure AI Search skillsets. They're separate from knowledge sources and knowledge agents, which are used in [agentic retrieval](search-agentic-retrieval-concept.md) workflows.
+
 In Azure AI Search, "shaping data" describes a step in the [knowledge store workflow](knowledge-store-concept-intro.md) that creates a data representation of the content that you want to project into tables, objects, and files in Azure Storage.
 
 As skills execute, the outputs are written to an enrichment tree in a hierarchy of nodes, and while you might want to view and consume the enrichment tree in its entirety, it's more likely that you'll want a finer grain, creating subsets of nodes for different scenarios, such as placing the nodes related to translated text or extracted entities in specific tables.

@@ -7,7 +7,7 @@ author: HeidiSteen
 ms.author: heidist
 ms.service: azure-ai-search
 ms.topic: conceptual
-ms.date: 06/17/2025
+ms.date: 08/21/2025
 ms.update-cycle: 365-days
 ms.custom:
   - ignite-2023
@@ -16,6 +16,9 @@ ms.custom:
 
 # Define projections in a knowledge store
 
+> [!NOTE]
+> Knowledge stores exist in Azure Storage and contain the outputs of Azure AI Search skillsets. They're separate from knowledge sources and knowledge agents, which are used in [agentic retrieval](search-agentic-retrieval-concept.md) workflows.
+
 [Projections](knowledge-store-projection-overview.md) are the component of a [knowledge store definition](knowledge-store-concept-intro.md) that determines how AI enriched content is stored in Azure Storage. Projections determine the type, quantity, and composition of the data structures containing your content.
 
 In this article, learn the syntax for each type of projection:

@@ -5,7 +5,7 @@ description: Learn about agentic retrieval concepts, architecture, and use cases
 author: HeidiSteen
 ms.author: heidist
 manager: nitinme
-ms.date: 08/18/2025
+ms.date: 09/02/2025
 ms.service: azure-ai-search
 ms.topic: concept-article
 ms.custom:
@@ -21,13 +21,13 @@ In Azure AI Search, *agentic retrieval* is a new multi-query pipeline designed f
 
 + Uses a large language model (LLM) to break down a complex query into smaller, focused subqueries for better coverage over your indexed content. Subqueries can include chat history for extra context.
 
-+ Runs the multiple subqueries in parallel. Each subquery is semantically reranked to find the most relevant matches.
++ Runs subqueries in parallel. Each subquery is semantically reranked to promote the most relevant matches.
 
-+ Combines the best results into a unified response that your LLM can use to generate answers with your proprietary content.
++ Combines the best results into a unified response that an LLM can use to generate answers with your proprietary content.
 
 This high-performance pipeline helps you generate high quality grounding data for your chat application, with the ability to answer complex questions quickly.
 
-Programmatically, agentic retrieval is supported through a new [Knowledge Agents object](/rest/api/searchservice/knowledge-agents?view=rest-searchservice-2025-05-01-preview&preserve-view=true) in the 2025-05-01-preview data plane REST API and in Azure SDK preview packages that provide the feature. A knowledge agent's retrieval response is designed for downstream consumption by other agents and chat apps.
+Programmatically, agentic retrieval is supported through a new [Knowledge Agents object](/rest/api/searchservice/knowledge-agents?view=rest-searchservice-2025-08-01-preview&preserve-view=true) in the 2025-08-01-preview and 2025-05-01-preview data plane REST APIs and in Azure SDK preview packages that provide the feature. A knowledge agent's retrieval response is designed for downstream consumption by other agents and chat apps.
 
 ## Why use agentic retrieval
 
@@ -67,7 +67,7 @@ The agentic retrieval process follows three main phases:
 
 1. **Query planning**: A knowledge agent sends your query and conversation history to an LLM (gpt-4o or gpt-4.1 series), which analyzes the context and breaks down complex questions into focused subqueries. This step is automated and not customizable. The number of subqueries depends on what the LLM decides and whether the `maxDocsForReranker` parameter is higher than 50. A new subquery is defined for each 50-document batch sent to semantic ranker.
 
-2. **Query execution**: All subqueries run simultaneously against your search index, using keyword, vector, and hybrid search. Each subquery undergoes semantic reranking to find the most relevant matches. References are extracted and retained for citation purposes.
+2. **Query execution**: All subqueries run simultaneously against your knowledge sources, using keyword, vector, and hybrid search. Each subquery undergoes semantic reranking to find the most relevant matches. References are extracted and retained for citation purposes.
 
 3. **Result synthesis**: The system merges and ranks all results, then returns a unified response containing grounding data, source references, and execution metadata.
 
@@ -81,6 +81,7 @@ Your search index determines query execution and any optimizations that occur du
 | **Knowledge agent** | Azure AI Search | Orchestrates the pipeline, connecting to your LLM and managing query parameters |
 | **Search index** | Azure AI Search | Stores your searchable content (text and vectors) with semantic configuration |
 | **Semantic ranker** | Azure AI Search | Required component that reranks results for relevance (L2 reranking) |
+| **Knowledge source** | Azure AI Search | Wraps the search index with properties pertaining to knowledge agent usage |
 
 ### Integration requirements
 
@@ -106,11 +107,16 @@ Choose any of these options for your next step.
 
 + How-to guides for a focused look at development tasks:
 
+  + [Create a search index knowledge source](search-knowledge-source-how-to-index.md) or a [blob knowledge source](search-knowledge-source-how-to-blob.md)
   + [Create a knowledge agent](search-agentic-retrieval-how-to-create.md)
   + [Use a knowledge agent to retrieve data](search-agentic-retrieval-how-to-retrieve.md)
-  + [Build an agent-to-agent retrieval solution](search-agentic-retrieval-how-to-pipeline.md).
+  + [Build an agent-to-agent retrieval solution](search-agentic-retrieval-how-to-pipeline.md)
 
-+ REST API reference, [Knowledge Agents](/rest/api/searchservice/knowledge-agents?view=rest-searchservice-2025-05-01-preview&preserve-view=true) and [Knowledge Retrieval](/rest/api/searchservice/knowledge-retrieval/retrieve?view=rest-searchservice-2025-05-01-preview&preserve-view=true).
++ REST API reference:
+
+  + [Knowledge Sources](/rest/api/searchservice/knowledge-sources?view=rest-searchservice-2025-08-01-preview&preserve-view=true)
+  + [Knowledge Agents](/rest/api/searchservice/knowledge-agents?view=rest-searchservice-2025-08-01-preview&preserve-view=true)
+  + [Knowledge Retrieval](/rest/api/searchservice/knowledge-retrieval/retrieve?view=rest-searchservice-2025-08-01-preview&preserve-view=true)
 
 + [Azure OpenAI Demo](https://github.com/Azure-Samples/azure-search-openai-demo), updated to use agentic retrieval.
 
@@ -120,7 +126,7 @@ Agentic retrieval is available in [all regions that provide semantic ranker](sea
 
 Billing for agentic retrieval has two parts:
 
-+ Billing for query planning is pay-as-you-go in Azure OpenAI. It's token based for both input and output tokens. The model you assign to the knowledge agent is the one charged for token usage. For example, if you use gpt-4o, the token charge appears in the bill for gpt-4o.
++ Billing for query planning and [answer synthesis](search-agentic-retrieval-how-to-synthesize.md) (optional) is pay-as-you-go in Azure OpenAI. It's token based for both input and output tokens. The model you assign to the knowledge agent is the one charged for token usage. For example, if you use gpt-4o, the token charge appears in the bill for gpt-4o.
 
 + Billing for semantic ranking during query execution. Billing is suspended during the initial roll-out phase but then transitions to pay-as-you-go on the Azure AI Search side through the semantic ranker. Semantic ranker, which is a premium billable feature, is an integral part of agentic retrieval. You're charged on the Azure AI Search side for token inputs to the semantic ranking models.
 
@@ -138,9 +144,9 @@ Semantic ranking is performed for every subquery in the plan. Semantic ranking c
 
 ### Example: Estimate costs
 
-Agentic retrieval has two billing models: billing from Azure OpenAI (query planning) and billing from Azure AI Search for semantic ranking (query execution).
+Agentic retrieval has two billing models: billing from Azure OpenAI (query planning and, if enabled, answer synthesis) and billing from Azure AI Search for semantic ranking (query execution).
 
-The prices shown in this article are hypothetical. They're used to illustrate the estimation process. Your costs could be lower. For the actual price of transactions, see [Azure OpenAI pricing](https://azure.microsoft.com/pricing/details/cognitive-services/openai-service/#pricing). For query execution, there's no charge for semantic ranking for agentic retrieval in the initial public preview.
+This example omits answer synthesis and uses hypothetical prices to illustrate the estimation process. Your costs could be lower. For the actual price of transactions, see [Azure OpenAI pricing](https://azure.microsoft.com/pricing/details/cognitive-services/openai-service/#pricing). For query execution, there's no charge for semantic ranking for agentic retrieval in the initial public preview.
 
 #### Estimated billing costs for query planning
 

@@ -7,7 +7,7 @@ author: HeidiSteen
 ms.author: heidist
 ms.service: azure-ai-search
 ms.topic: how-to
-ms.date: 05/30/2025
+ms.date: 08/29/2025
 ---
 
 # Create a knowledge agent in Azure AI Search
@@ -18,12 +18,15 @@ In Azure AI Search, a *knowledge agent* is a top-level resource representing a c
 
 A knowledge agent specifies:
 
-+ A model that provides reasoning capabilities
-+ A target search index used at query time
-+ Parameters on the index for setting default behaviors and response shaping
++ A knowledge source (one or more) that points to a searchable content
++ A chat completion model that provides reasoning capabilities for query planning and answer formulation
++ Properties for performance optimization (constrain query processing time)
 
 After you create a knowledge agent, you can update its properties at any time. If the knowledge agent is in use, updates take effect on the next job.
 
+> [!IMPORTANT]
+> 2025-08-01-preview introduces breaking changes for existing knowledge agents. This preview version requires one or more `knowledgeSource` definitions. We recommend [migrating existing code](search-agentic-retrieval-how-to-migrate.md) to the new APIs as soon as possible.
+
 ## Prerequisites
 
 + Familiarity with [agentic retrieval concepts and use cases](search-agentic-retrieval-concept.md).
@@ -32,17 +35,17 @@ After you create a knowledge agent, you can update its properties at any time. I
 
 + Azure AI Search, in any [region that provides semantic ranker](search-region-support.md), on the basic pricing tier or higher. Your search service must have a [managed identity](search-how-to-managed-identities.md) for role-based access to the model.
 
-+ Permissions on Azure AI Search. **Search Service Contributor** can create and manage a knowledge agent. **Search Index Data Reader** can run queries. Instructions are provided in this article.
++ Permissions on Azure AI Search. **Search Service Contributor** can create and manage a knowledge agent. **Search Index Data Reader** can run queries. Instructions are provided in this article. [Quickstart: Connect to a search service](/azure/search/search-get-started-rbac?pivots=rest) explains how to configure roles and get a personal access token for REST calls.
 
-+ A search index containing plain text or vectors. The index must [meet the requirements for agentic retrieval](search-agentic-retrieval-how-to-index.md), including a [semantic configuration](semantic-how-to-configure.md) with the `defaultConfiguration` specified.
++ A [knowledge source](search-knowledge-source-overview.md) that identifies searchable content used by the agent. It can be either a [search index knowledge source](search-knowledge-source-how-to-index.md) or a [blob knowledge source](search-knowledge-source-how-to-blob.md)
 
-+ API requirements. To create or use a knowledge agent, use the [2025-05-01-preview](/rest/api/searchservice/operation-groups?view=rest-searchservice-2025-05-01-preview&preserve-view=true) data plane REST API. Or, use a prerelease package of an Azure SDK that provides knowledge agent APIs: [Azure SDK for Python](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/search/azure-search-documents/CHANGELOG.md), [Azure SDK for .NET](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/search/Azure.Search.Documents/CHANGELOG.md#1170-beta3-2025-03-25), [Azure SDK for Java](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/search/azure-search-documents/CHANGELOG.md).
++ API requirements. To create or use a knowledge agent, use the [2025-08-01-preview](/rest/api/searchservice/operation-groups?view=rest-searchservice-2025-08-01-preview&preserve-view=true) data plane REST API. Or, use a preview package of an Azure SDK that provides knowledge agent APIs: [Azure SDK for Python](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/search/azure-search-documents/CHANGELOG.md), [Azure SDK for .NET](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/search/Azure.Search.Documents/CHANGELOG.md#1170-beta3-2025-03-25), [Azure SDK for Java](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/search/azure-search-documents/CHANGELOG.md). **There's no Azure portal support knowledge agents at this time**.
 
-To follow the steps in this guide, we recommend [Visual Studio Code](https://code.visualstudio.com/download) with a [REST client](https://marketplace.visualstudio.com/items?itemName=humao.rest-client) for sending preview REST API calls to Azure AI Search. There's no portal support at this time.
+To follow the steps in this guide, we recommend [Visual Studio Code](https://code.visualstudio.com/download) with a [REST client](https://marketplace.visualstudio.com/items?itemName=humao.rest-client) for sending preview REST API calls to Azure AI Search. T
 
 ## Deploy a model for agentic retrieval
 
-Make sure you have a supported model that Azure AI Search can access. The following instruction assumes Azure AI Foundry Model as the provider.
+Make sure you have a supported model that Azure AI Search can access. The following instructions assume Azure AI Foundry Model as the provider.
 
 1. Sign in to [Azure AI Foundry portal](https://ai.azure.com/?cid=learnDocs).
 
@@ -83,7 +86,7 @@ In Azure, you must have **Owner** or **User Access Administrator** permissions o
     @accessToken=<YOUR PERSONAL ID>
     
     # List Indexes
-    GET https://{{search-url}}/indexes?api-version=2025-05-01-preview
+    GET https://{{search-url}}/indexes?api-version=2025-08-01-preview
     Authorization: Bearer {{accessToken}}
     ```
 
@@ -103,7 +106,7 @@ You can use API keys if you don't have permission to create role assignments.
     @search-api-key=<YOUR SEARCH SERVICE ADMIN API KEY>
 
    # List Indexes
-   GET https://{{search-url}}/indexes?api-version=2025-05-01-preview
+   GET {{search-url}}/indexes?api-version=2025-08-01-preview
       Content-Type: application/json
       @api-key: {{search-api-key}}
    ```
@@ -112,11 +115,9 @@ You can use API keys if you don't have permission to create role assignments.
 
 The following request lists knowledge agents by name. Within the knowledge agents collection, all knowledge agents must be uniquely named. It's helpful to know about existing knowledge agents for reuse or for naming new agents.
 
-<!-- ### [**REST APIs**](#tab/rest-get) -->
-
 ```http
 # List knowledge agents
-GET https://{{search-url}}/agents?api-version=2025-05-01-preview
+GET {{search-url}}/agents?api-version=2025-08-01-preview
    Content-Type: application/json
    Authorization: Bearer {{accessToken}}
 ```
@@ -125,41 +126,52 @@ You can also return a single agent by name to review its JSON definition.
 
 ```http
 # Get knowledge agent
-GET https://{{search-url}}/agents/{{agent-name}}?api-version=2025-05-01-preview
+GET {{search-url}}/agents/{{agent-name}}?api-version=2025-08-01-preview
    Content-Type: application/json
    Authorization: Bearer {{accessToken}}
 ```
 
-<!-- --- -->
-
 ## Create a knowledge agent
 
-A knowledge agent represents a connection between a model that you've deployed in Azure OpenAI and a target index on Azure AI Search. Parameters on the model establish the connection. Parameters on the index establish defaults that inform query execution and the response.
+A knowledge agent drives the agentic retrieval pipeline. In application code, it's called by other agents or chat bots. 
 
-<!-- ### [**REST APIs**](#tab/rest-create) -->
+Its composition consists of connections between *knowledge sources* (searchable content) and chat completion models that you've deployed in Azure OpenAI. Properties on the model establish the connection. Properties on the knowledge source establish defaults that inform query execution and the response.
 
-To create an agent, use the 2025-05-01-preview data plane REST API or an Azure SDK prerelease package that provides equivalent functionality.
+To create an agent, use the 2025-08-01-preview data plane REST API or an Azure SDK preview package that provides equivalent functionality.
 
 ```http
 @search-url=<YOUR SEARCH SERVICE URL>
 @agent-name=<YOUR AGENT NAME>
 @index-name=<YOUR INDEX NAME>
 @model-provider-url=<YOUR AZURE OPENAI RESOURCE URI>
+@model-api-key=<YOUR AZURE OPENAI API KEY>
 @accessToken = <a long GUID>
 
 # Create knowledge agent
-PUT https://{{search-url}}/agents/{{agent-name}}?api-version=2025-05-01-preview
+PUT {{search-url}}/agents/{{agent-name}}?api-version=2025-08-01-preview
    Content-Type: application/json
    Authorization: Bearer {{accessToken}}
 
 {
     "name" : "{{agent-name}}",
-    "targetIndexes" : [
+    "description": "This knowledge agent handles questions directed at two unrelated sample indexes."
+    "retrievalInstructions": "Use the hotels knowledge source only for queries about hotels or where to stay, otherwise use the earth at night knowledge source.",
+    "knowledgeSources": [
         {
-            "indexName" : "{{index-name}}",
-            "defaultRerankerThreshold": 2.5,
-            "defaultIncludeReferenceSourceData": true,
-            "defaultMaxDocsForReranker": 200
+            "name": "earth-at-night-blob-ks",
+            "alwaysQuerySource": false,
+            "includeReferences": true,
+            "includeReferenceSourceData": true,
+            "maxSubQueries": 30,
+            "rerankerThreshold": null
+        },
+        {
+            "name": "hotels-index-ks",
+            "alwaysQuerySource": false,
+            "includeReferences": true,
+            "includeReferenceSourceData": true,
+            "maxSubQueries": 5,
+            "rerankerThreshold": null
         }
     ],
     "models" : [ 
@@ -173,37 +185,53 @@ PUT https://{{search-url}}/agents/{{agent-name}}?api-version=2025-05-01-preview
             }
         }
     ],
+    "outputConfiguration": {
+        "modality": "extractiveData",
+        "answerInstructions": "Provide a concise answer to the question.",
+        "attemptFastPath": false,
+        "includeActivity": true
+    },
     "requestLimits": {
         "maxOutputSize": 5000,
         "maxRuntimeInSeconds": 60
-    },
-    "encryptionKey": { }
+    }
 }
 ```
 
 **Key points**:
 
 + `name` must be unique within the knowledge agents collection and follow the [naming guidelines](/rest/api/searchservice/naming-rules) for objects on Azure AI Search.
 
-+ `targetIndexes` is required for knowledge agent creation. It lists the search indexes that can use the knowledge agent. Currently in this preview release, the `targetIndexes` array can contain only one index. *It must have a default semantic configuration* (`defaultConfiguration`). For more information, see [Design an index for agentic retrieval](search-agentic-retrieval-how-to-index.md).
++ `description` is recommended for query planning. The LLM uses the description to inform query planning. 
 
-    ```json
-    "semantic": {
-        "defaultConfiguration": "my-default-semantic-config",
-        "configurations": [ ]
-    }
-    ```
++ `retrievalInstructions` is recommended for query planning when you have multiple knowledge sources. The instructions are passed as a prompt to the LLM to determine whether a knowledge source should be in scope for a query. 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 (for example, if instructions resulted in bypassing an essential knowledge source). If you set `retrievalInstructions`, make sure `alwaysQuerySource` is set to false.
 
-+ `defaultRerankerThreshold` is the minimum semantic reranker score that's acceptable for inclusion in a response. [Reranker scores](semantic-search-overview.md#how-results-are-scored) range from 1 to 4. Plan on revising this value based on testing and what works for your content.
++ `knowledgeSources` is required for knowledge agent creation. It specifies the search indexes or Azure blobs used by the knowledge agent. New in this preview release, the `knowledgeSources` is an array, and it replaces the previous `targetIndexes` array. 
 
-+ `defaultIncludeReferenceSourceData` is a boolean that determines whether the reference portion of the response includes source data. We recommend starting with this value set to true if you want to shape your own response using output from the search engine. Otherwise, if you want to use the output in the response `content` string, you can set it to false.
+    + `name` is a reference to either a [search index knowledge source](search-knowledge-source-how-to-index.md) or a [blob knowledge source](search-knowledge-source-how-to-blob.md).
+    
+    + `alwaysQuerySource` is a boolean that specifies whether a knowledge source must always be used (true), or only used if the query planning step determines it's useful. The default is false, which means source selection can skip this source if the model doesn’t think the query needs it. Source descriptions and retrieval instructions are used in this assessment. If you're using `attemptFastPath` on a specific knowledge source, `alwaysQuerySource` must be set to true.
+    
+    + `includeReferences` is a boolean that determines whether the reference portion of the response includes source data. We recommend starting with this value set to true if you want to shape your own response using output from the search engine. Otherwise, if you want to use the output in the response `content` string, you can set it to false.
+    
+    + `maxSubQueries` is the maximum number of queries the query planning step will generate. Each query can return up to 50 documents, which are reranked by semantic ranker. The `maxSubQueries` property must be between 2 and 40.
 
-+ `defaultMaxDocsForReranker` is the maximum number of documents that can be sent to the semantic ranker. Each subquery can pass a maximum of 50 documents to the semantic reranker, so setting this value above 50 generates more subqueries until the maximum is reached. For example, if you set this value to 200, then four subqueries are generated to support this number. This 
+    + `rerankerThreshold` is the minimum semantic reranker score that's acceptable for inclusion in a response. [Reranker scores](semantic-search-overview.md#how-results-are-scored) range from 1 to 4. Plan on revising this value based on testing and what works for your content.
 
 + `models` specifies one or more connections to an existing gpt-4o or gpt-4o-mini model. Currently in this preview release, models can contain just one model, and the model provider must be Azure OpenAI. Obtain model information from the Azure AI Foundry portal or from a command line request. You can use role-based access control instead of API keys for the Azure AI Search connection to the model. For more information, see [How to deploy Azure OpenAI models with Azure AI Foundry](/azure/ai-foundry/how-to/deploy-models-openai).
 
++ `outputConfiguration` gives you control over query execution logic and output.
+
+  + `modality` determines the shape of the results. Valid values are `extractiveData` (default) or `answerSynthesis` (see [Use answer synthesis for citation-backed responses](search-agentic-retrieval-how-to-synthesize.md)).
+
+  + `answerInstructions` is used for shaping answers (see [Use answer synthesis for citation-backed responses](search-agentic-retrieval-how-to-synthesize.md)). The default is null.
+
+  + `attemptFastPath` is a boolean that can be used to enable a fast path to query execution. If `true`, the search engine skips query planning if the query is less than 512 characters and the semantic ranker score on the small query is above 1.9, indicating sufficient relevance. If the query is larger or the score is lower, query planning is invoked. You must have at least one knowledge source that has `alwaysQuerySource` enabled. If there are multiple knowledge sources, they must all have `alwaysQuerySource` enabled to be considered for fast path. The small query runs on all of them. The default is `false`.
+
+  + `includeActivity` indicates whether retrieval results should include the query plan. The default is `true`.
+
 <!--  Check minimum 10k  -->
-+ `requestLimits` gives you control over the output generated during retrieval so that you can better manage inputs to the LLM. 
++ `requestLimits` sets numeric limits over query processing.
 
   + `maxOutputSize` is the maximum number of tokens in the response `content` string, with 5,000 tokens as the minimum and recommended value, and no explicit maximum. The most relevant matches are preserved but the overall response is truncated at the last complete document to fit your token budget. 
 
@@ -213,15 +241,70 @@ PUT https://{{search-url}}/agents/{{agent-name}}?api-version=2025-05-01-preview
 
 <!-- --- -->
 
-## Confirm knowledge agent operations
+## Query the knowledge agent
+
+Call the **retrieve** action on the knowledge agent object to confirm the model connection and return a response. Use the [2025-08-01-preview](/rest/api/searchservice/operation-groups?view=rest-searchservice-2025-08-01-preview&preserve-view=true) data plane REST API or an Azure SDK preview package that provides equivalent functionality for this task.
+
+Replace "where does the ocean look green?" with a query string that's valid for your search index.
+
+```http
+# Send grounding request
+POST {{search-url}}/agents/{{agent-name}}/retrieve?api-version=2025-08-01-preview
+   Content-Type: application/json
+   Authorization: Bearer {{accessToken}}
 
-Call the **retrieve** action on the knowledge agent object to confirm the model connection and return a response. Use the [2025-05-01-preview](/rest/api/searchservice/operation-groups?view=rest-searchservice-2025-05-01-preview&preserve-view=true) data plane REST API or an Azure SDK prerelease package that provides equivalent functionality for this task.
+{
+  "messages" : [
+        { "role" : "assistant",
+                "content" : [
+                  { "type" : "text", "text" : "Use the earth at night index to answer the question. If you can't find relevant content, say you don't know." }
+                ]
+        },
+        {
+            "role" : "user",
+            "content" : [
+                {
+                    "text" : "where does the ocean look green?",
+                    "type" : "text"
+                }
+            ]
+        }
+    ],
+  "knowledgeSourceParams": [
+    {
+      "filterAddOn": null,
+      "knowledgeSourceName": "earth-at-night-blob-ks",
+      "kind": "searchIndex"
+    }
+  ]
+}
+```
+
+[messages](/rest/api/searchservice/knowledge-retrieval/retrieve?view=rest-searchservice-2025-08-01-preview#knowledgeagentmessage&preserve-view=true) is required, but you can run this example using just "user" role that provides the query.
+
+[`knowledgeSourceParams`](/rest/api/searchservice/knowledge-retrieval/retrieve?view=rest-searchservice-2025-08-01-preview#searchindexknowledgesourceparams&preserve-view=true) is optional. Specify a knowledge source if the agent is configured for multiple sources and you want to focus the retrieve action on just one of them.
 
-Replace "What are my vision benefits?" with a query string that's valid for your search index.
+A knowledge source specification on the retrieve action describes the target search index on the search service. So even if the knowledge source "kind" is Azure blob, the valid value here is `searchIndex`. In this first public preview release, `knowledgeSourceParams.kind` is always `searchIndex`.
+
+The response to the previous query might look like this:
 
 ```http
+  "response": [
+    {
+      "content": [
+        {
+          "type": "text",
+          "text": "The ocean appears green off the coast of Antarctica due to phytoplankton flourishing in the water, particularly in Granite Harbor near Antarctica’s Ross Sea, where they can grow in large quantities during spring, summer, and even autumn under the right conditions [ref_id:0]. Additionally, off the coast of Namibia, the ocean can also look green due to blooms of phytoplankton and yellow-green patches of sulfur precipitating from bacteria in oxygen-depleted waters [ref_id:1]. In the Strait of Georgia, Canada, the waters turned bright green due to a massive bloom of coccolithophores, a type of phytoplankton [ref_id:5]. Furthermore, a milky green and blue bloom was observed off the coast of Patagonia, Argentina, where nutrient-rich waters from different currents converge [ref_id:6]. Lastly, a large bloom of cyanobacteria was captured in the Baltic Sea, which can also give the water a green appearance [ref_id:9]."
+        }
+      ]
+    }
+  ],
+```
+
+
+<!-- ```http
 # Send grounding request
-POST https://{{search-url}}/agents/{{agent-name}}/retrieve?api-version=2025-05-01-preview
+POST {{search-url}}/agents/{{agent-name}}/retrieve?api-version=2025-08-01-preview
    Content-Type: application/json
    Authorization: Bearer {{accessToken}}
 
@@ -250,7 +333,7 @@ POST https://{{search-url}}/agents/{{agent-name}}/retrieve?api-version=2025-05-0
         } 
     ]
 }
-```
+``` -->
 
 For more information about the **retrieve** API and the shape of the response, see [Retrieve data using a knowledge agent in Azure AI Search](search-agentic-retrieval-how-to-retrieve.md).
 
@@ -260,7 +343,7 @@ If you no longer need the agent, or if you need to rebuild it on the search serv
 
 ```http
 # Delete agent
-DELETE https://{{search-url}}/agents/{{agent-name}}?api-version=2025-05-01-preview
+DELETE {{search-url}}/agents/{{agent-name}}?api-version=2025-08-01-preview
    Authorization: Bearer {{accessToken}}
 ```
 

@@ -7,7 +7,7 @@ author: HeidiSteen
 ms.author: heidist
 ms.service: azure-ai-search
 ms.topic: how-to
-ms.date: 05/05/2025
+ms.date: 08/29/2025
 ---
 
 # Design an index for agentic retrieval in Azure AI Search
@@ -16,18 +16,28 @@ ms.date: 05/05/2025
 
 In Azure AI Search, *agentic retrieval* is a new parallel query architecture that uses a chat completion model for query planning, generating subqueries that broaden the scope of what's searchable and relevant.
 
-Queries are created internally. Certain aspects of those generated queries are determined by your search index. This article explains which index elements affect agentic retrieval. 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.
+Subqueries are created internally. Certain aspects of the subqueries are determined by your search index. This article explains which index elements have an effect on agentic retrieval. 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.
 
-Summarized, the search index specified in the `targetIndexes` of an [agent definition](search-agentic-retrieval-how-to-create.md) must have these elements:
+A search index that's used in agentic retrieval is specified as *knowledge source* and is either:
+
++ An existing indexing containing searchable content. This index is made available to agentic retrieval through a [search index knowledge source](search-knowledge-source-how-to-index.md) definition.
+
++ A generated index created from a generated blob indexer pipeline. This index is generated and populated using information from a [blob knowledge source](search-knowledge-source-how-to-blob.md). It's based on a template that meets all of the criteria for knowledge agents and agentic retrieval. 
+
+## 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, with a `defaultSemanticConfiguration`
-+ A vectorizer if you want to include vector queries in the pipeline
++ Vector fields and a vectorizer if you want to include vector queries in the pipeline
+
+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.
 
 Optionally, the following index elements increase your opportunities for optimization:
 
 + `scoringProfile` with a `defaultScoringProfile`, for boosting relevance
-+ `synonymMaps` for terminology or jargon
++ `synonymMaps` for terminology or jargon 
 + `analyzers` for linguistics rules or patterns (like whitespace preservation, or special characters)
 
 ## Example index definition
@@ -139,9 +149,11 @@ Here's an example index that works for agentic retrieval. It meets the criteria
 
 **Key points**:
 
-In agentic retrieval, a large language model (LLM) is used twice. First, it's used to create a query plan. After the query plan is executed and search results are generated, those results are passed to the LLM again, this time as grounding data. LLMs consume and emit tokenized strings of human readable plain text content. For this reason, you must have `searchable` fields that provide plain text strings, and are `retrievable` in the response.
+In agentic retrieval, a large language model (LLM) is used twice. First, it's used to create a query plan. After the query plan is executed and search results are generated, those results are passed to the LLM again, this time as grounding data that's used to formulate an answer. 
+
+LLMs consume and emit tokenized strings of human readable plain text content. For this reason, you must have `searchable` fields that provide plain text strings, and are `retrievable` in the response. Vector fields and vector search are also important because they add similarity search to information retrieval. Vectors enhance and improve the quality of search, but aren't otherwise strictly required. Azure AI Search has built-in capabilities that [simplify and automate vectorization](vector-search-overview.md).
 
-This index includes a vector field that's used at query time. You don't need the vector in results because it isn't human or LLM readable, but it does need to be `searchable`. Since you don't need vectors in the response, both `retrievable` and `stored` are false. 
+The previous example index includes a vector field that's used at query time. You don't need the vector in results because it isn't human or LLM readable, but notice that its `searchable` for vector search. Since you don't need vectors in the response, both `retrievable` and `stored` are false. 
 
 The vectorizer defined in the vector search configuration is critical. It determines whether your vector field is used during query execution. The vectorizer encodes subqueries into vectors at query time for similarity search over the vectors. The vectorizer must be the same embedding model used to create the vectors in the index.
 
@@ -269,7 +281,7 @@ Here's an example of a vectorizer that works for agentic retrieval, as it appear
 
 [Scoring profiles](index-add-scoring-profiles.md) are criteria for relevance boosting. They're applied to non-vector fields (text and numbers) and are evaluated during query execution, although the precise behavior depends on the API version used to create the index.
 
-If you create the index using 2025-05-01-preview, the scoring profile executes last. If the index is created using an earlier API version, scoring profiles are evaluated before semantic reranking.
+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.
 
 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.
 

@@ -0,0 +1,192 @@
+---
+title: Migrate Agentic Retrieval Code
+titleSuffix: Azure AI Search
+description: Learn how to migrate your agentic retrieval code to the latest REST API version. Starting with the 2025-08-01-preview, you must update knowledge agents to use knowledgeSources instead of targetIndexes due to breaking changes.
+manager: nitinme
+author: haileytap
+ms.author: haileytapia
+ms.service: azure-ai-search
+ms.topic: how-to
+ms.date: 08/28/2025
+---
+
+# Migrate agentic retrieval code to the latest version
+
+[!INCLUDE [Feature preview](./includes/previews/preview-generic.md)]
+
+If you wrote [agentic retrieval](search-agentic-retrieval-concept.md) code using an early preview REST API, this article explains when and how to migrate to the latest version. It also describes breaking and nonbreaking changes for all REST API versions that support agentic retrieval.
+
+## When to migrate
+
+Migrate your agentic retrieval code when any of the following apply:
+
++ The REST API version you use is announced for retirement or enters a deprecation window.
+
++ A newer REST API version introduces breaking changes that affect features you use. For example, you must address breaking changes if your code targets the [2025-05-01-preview](#2025-05-01-preview), which uses `targetIndexes` in agent definitions.
+
++ You want features that are only available in a newer REST API version.
+
++ Your code fails when unrecognized properties are returned in a REST API response. As a best practice, your application should ignore properties it doesn't understand.
+
+## How to migrate
+
+If you created a knowledge agent using the [2025-05-01-preview](#2025-05-01-preview), your agent's definition includes an inline `targetIndexes` array and an optional `defaultMaxDocsForReranker` property.
+
+Starting with the [2025-08-01-preview](#2025-08-01-preview), reusable knowledge sources replace `targetIndexes`, and `defaultMaxDocsForReranker` is no longer supported. These breaking changes require you to:
+
+1. [Get the current `targetIndexes` configuration](#get-the-current-configuration).
+2. [Create an equivalent knowledge source](#create-a-knowledge-source).
+3. [Update the agent to use `knowledgeSources` instead of `targetIndexes`](#update-the-agent).
+4. [Send a query to test the retrieval](#test-the-retrieval).
+5. [Remove code that uses `targetIndexes` and update clients](#update-code-and-clients).
+
+### Get the current configuration
+
+To retrieve your agent's definition, use the 2025-05-01-preview of [Knowledge Agents - Get (REST API)](/rest/api/searchservice/knowledge-agents/get?view=rest-searchservice-2025-05-01-preview&preserve-view=true).
+
+```http
+@search-url = <YourSearchServiceUrl>
+@agent-name = <YourAgentName>
+@api-key = <YourApiKey>
+
+### Get agent definition
+GET https://{{search-url}}/agents/{{agent-name}}?api-version=2025-05-01-preview  HTTP/1.1
+    api-key: {{api-key}}
+```
+
+The response should be similar to the following example. Copy the `indexName`, `defaultRerankerThreshold`, and `defaultIncludeReferenceSourceData` values for use in the upcoming steps. `defaultMaxDocsForReranker` is deprecated, so you can ignore its value.
+
+```json
+{
+  "@odata.etag": "0x1234568AE7E58A1",
+  "name": "my-knowledge-agent",
+  "description": "My description of the agent",
+  "targetIndexes": [
+    {
+      "indexName": "my-index", // Copy this value
+      "defaultRerankerThreshold": 2.5, // Copy this value
+      "defaultIncludeReferenceSourceData": true, // Copy this value
+      "defaultMaxDocsForReranker": 100
+    }
+  ],
+  ... // Redacted for brevity
+}
+```
+
+### Create a knowledge source
+
+To create a `searchIndex` knowledge source, use the 2025-08-01-preview of [Knowledge Sources - Create (REST API)](/rest/api/searchservice/knowledge-sources/create?view=rest-searchservice-2025-08-01-preview&preserve-view=true). Set `searchIndexName` to the value you previously copied.
+
+```http
+@source-name = <YourSourceName>
+
+### Create a knowledge source
+PUT https://{{search-url}}/knowledgeSources/{{source-name}}?api-version=2025-08-01-preview  HTTP/1.1
+    Content-Type: application/json
+    api-key: {{api-key}}
+    
+    {
+        "name": "{{source-name}}",
+        "description": "My description of the knowledge source",
+        "kind": "searchIndex",
+        "searchIndexParameters": {
+            "searchIndexName": "my-index" // Use the previous value
+        }
+    }
+```
+
+This example creates a knowledge source that represents one index, but you can target multiple indexes or an Azure blob. For more information, see [Create a knowledge source](search-knowledge-source-overview.md).
+
+### Update the agent
+
+To replace `targetIndexes` with `knowledgeSources` in your agent's definition, use the 2025-08-01-preview of [Knowledge Agents - Create or Update (REST API)](/rest/api/searchservice/knowledge-agents/create-or-update?view=rest-searchservice-2025-08-01-preview&preserve-view=true). Set `rerankerThreshold` and `includeReferenceSourceData` to the values you previously copied.
+
+```http
+### Replace targetIndexes with knowledgeSources
+POST https://{{search-url}}/agents/{{agent-name}}?api-version=2025-08-01-preview  HTTP/1.1
+    Content-Type: application/json
+    api-key: {{api-key}}
+
+    { 
+        "name": "{{agent-name}}", 
+        "knowledgeSources": [  
+            {  
+                "name": "{{source-name}}",
+                "rerankerThreshold": 2.5, // Use the previous value
+                "includeReferenceSourceData": true // Use the previous value
+            }
+        ]
+    } 
+```
+
+This example updates the definition to reference one knowledge source, but you can target multiple knowledge sources. You can also use other properties to control the retrieval behavior, such as `alwaysQuerySource`. For more information, see [Create a knowledge agent](search-agentic-retrieval-how-to-create.md).
+
+### Test the retrieval
+
+To test your agent's output with a query, use the 2025-08-01-preview of [Knowledge Retrieval - Retrieve (REST API)](/rest/api/searchservice/knowledge-retrieval/retrieve?view=rest-searchservice-2025-08-01-preview&preserve-view=true).
+
+```http
+### Send a query to the agent
+POST https://{{search-url}}/agents/{{agent-name}}/retrieve?api-version=2025-08-01-preview  HTTP/1.1
+    Content-Type: application/json
+    api-key: {{api-key}}
+        
+    {
+      "messages": [
+            {
+                "role": "user",
+                "content" : [
+                    {
+                        "text": "<YourQueryText>",
+                        "type": "text"
+                    }
+                ]
+            }
+        ]
+    }
+```
+
+If the response has a `200 OK` HTTP code, your agent successfully retrieved content from the knowledge source.
+
+### Update code and clients
+
+To complete your migration, follow these cleanup steps:
+
++ Replace all `targetIndexes` references with `knowledgeSources` in configuration files, code, scripts, and tests.
++ Update client calls to use the 2025-08-01-preview.
++ Clear or regenerate cached agent definitions that were created using the old shape.
+
+## Version-specific changes
+
+This section covers breaking and nonbreaking changes for the following REST API versions:
+
++ [2025-08-01-preview](#2025-08-01-preview)
++ [2025-05-01-preview](#2025-05-01-preview)
+
+### 2025-08-01-preview
+
+#### [Breaking changes](#tab/breaking)
+
++ Introduces knowledge sources as the new way to define data sources, supporting both `searchIndex` (one or multiple indexes) and `azureBlob` kinds. For more information, see [Create a search index knowledge source](search-knowledge-source-how-to-index.md) and [Create a blob knowledge source](search-knowledge-source-how-to-blob.md).
+
++ Requires `knowledgeSources` instead of `targetIndexes` in agent definitions. For migration steps, see [How to migrate](#how-to-migrate).
+
++ Removes `defaultMaxDocsForReranker` support. This property previously existed in `targetIndexes`, but there's no replacement in `knowledgeSources`.
+
+#### [Nonbreaking changes](#tab/nonbreaking)
+
++ Adds `knowledgeSources`, `outputConfiguration`, and `retrievalInstructions` to agent definitions. For information about supported properties, see [Create a knowledge agent](search-agentic-retrieval-how-to-create.md).
+
++ Renames `defaultRerankerThreshold` to `rerankerThreshold` and `defaultIncludeReferenceSourceData` to `includeReferenceSourceData`. These properties previously existed in `targetIndexes`, but you now specify them within each knowledge source reference in `knowledgeSources`.
+
+---
+
+### 2025-05-01-preview
+
+This REST API version introduces agentic retrieval and knowledge agents. Each agent definition requires a `targetIndexes` array that specifies a single index and optional properties, such as `defaultRerankerThreshold` and `defaultIncludeReferenceSourceData`.
+
+## Related content
+
++ [Agentic retrieval in Azure AI Search](search-agentic-retrieval-concept.md)
++ [Create a knowledge agent](search-agentic-retrieval-how-to-create.md)
++ [Create a knowledge source](search-knowledge-source-overview.md)

@@ -5,7 +5,7 @@ description: Learn how to design and build a custom agentic retrieval solution w
 author: HeidiSteen
 ms.author: heidist
 manager: nitinme
-ms.date: 06/08/2025
+ms.date: 08/29/2025
 ms.service: azure-ai-search
 ms.topic: how-to
 ms.custom:
@@ -192,7 +192,7 @@ project_client.agents.enable_auto_function_calls(toolset)
 
 ## How to structure messages
 
-The messages sent to the agent tool include instructions for chat history and using the results obtained from [knowledge retrieval](/rest/api/searchservice/knowledge-retrieval/retrieve?view=rest-searchservice-2025-05-01-preview&preserve-view=true) on Azure AI Search. The response is passed as a large single string with no serialization or structure.
+The messages sent to the agent tool include instructions for chat history and using the results obtained from [knowledge retrieval](/rest/api/searchservice/knowledge-retrieval/retrieve?view=rest-searchservice-2025-08-01-preview&preserve-view=true) on Azure AI Search. The response is passed as a large single string with no serialization or structure.
 
 ```python
 def agentic_retrieval() -> str:

@@ -7,7 +7,7 @@ author: HeidiSteen
 ms.author: heidist
 ms.service: azure-ai-search
 ms.topic: how-to
-ms.date: 06/08/2025
+ms.date: 08/29/2025
 ---
 
 # Retrieve data using a knowledge agent in Azure AI Search
@@ -16,7 +16,9 @@ ms.date: 06/08/2025
 
 In Azure AI Search, *agentic retrieval* is a new parallel query architecture that uses a large language model (LLM) for query planning. It generates subqueries that broaden the scope of what's searchable and relevant. It incorporates chat history for context. The LLM studies the query and subdivides it into more targeted queries, using different phrases and terminology for subquery composition.
 
-This article explains how to use the [**retrieve method**](/rest/api/searchservice/knowledge-retrieval/retrieve?view=rest-searchservice-2025-05-01-preview&preserve-view=true) that invokes a knowledge agent and parallel query processing. This article also explains the three components of the retrieval response: 
+This article explains how to use the [**retrieve method**](/rest/api/searchservice/knowledge-retrieval/retrieve?view=rest-searchservice-2025-08-01-preview&preserve-view=true) that invokes a knowledge agent and parallel query processing. It's updated for the new 2025-08-01-preview, which introduces breaking changes from the 2025-05-01-preview. For help with breaking changes, see [Migrate your agentic retrieval code](search-agentic-retrieval-how-to-migrate.md).
+
+This article also explains the three components of the retrieval response: 
 
 + *extracted response for the LLM*
 + *referenced results*
@@ -25,23 +27,25 @@ This article explains how to use the [**retrieve method**](/rest/api/searchservi
 The retrieve request can include instructions for query processing that override the defaults set on the knowledge agent.
 
 > [!NOTE]
-> There's no model-generated "answer" in the response. Instead, you should pass the response to an LLM that grounds its answer based on the content. For an end-to-end example that includes this step, see [Build an agent-to-agent retrieval solution ](search-agentic-retrieval-how-to-pipeline.md) or [Azure OpenAI Demo](https://github.com/Azure-Samples/azure-search-openai-demo).
+> By default, there's no model-generated "answer" in the response and you should pass the extracted response to an LLM so that it can ground its answer based on the search results. For an end-to-end example that includes this step, see [Build an agent-to-agent retrieval solution ](search-agentic-retrieval-how-to-pipeline.md) or [Azure OpenAI Demo](https://github.com/Azure-Samples/azure-search-openai-demo). Alternatively, you can use [answer synthesis](search-agentic-retrieval-how-to-synthesize.md) to bring answer formulation into the agentic pipeline. In this workflow, the knowledge agent output consists of LLM-formulated answers instead of the raw search results.
 
 ## Prerequisites
 
-+ A [knowledge agent](search-agentic-retrieval-how-to-create.md) that represents the chat completion model and a valid target index.
++ A *knowledge source* that wraps a searchable index. It's either a [search index knowledge source](search-knowledge-source-how-to-index.md) or a [blob knowledge source](search-knowledge-source-how-to-blob.md).
+
++ A [knowledge agent](search-agentic-retrieval-how-to-create.md) that represents the chat completion model and one or more knowledge sources.
 
 + Azure AI Search, in any [region that provides semantic ranker](search-region-support.md), on Basic pricing tier and higher. Your search service must have a [managed identity](search-how-to-managed-identities.md) for role-based access to a chat completion model.
 
 + Permissions on Azure AI Search. **Search Index Data Reader** can run queries on Azure AI Search, but the search service managed identity must have **Cognitive Services User** permissions on the Azure OpenAI resource. For more information about local testing and obtaining access tokens, see [Quickstart: Connect without keys](search-get-started-rbac.md).
 
-+ API requirements. To create or use a knowledge agent, use the [2025-05-01-preview](/rest/api/searchservice/operation-groups?view=rest-searchservice-2025-05-01-preview&preserve-view=true) data plane REST API. Or, use a prerelease package of an Azure SDK that provides knowledge agent APIs: [Azure SDK for Python](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/search/azure-search-documents/CHANGELOG.md), [Azure SDK for .NET](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/search/Azure.Search.Documents/CHANGELOG.md#1170-beta3-2025-03-25), [Azure SDK for Java](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/search/azure-search-documents/CHANGELOG.md).
++ API requirements. To create or use a knowledge agent, use the [2025-08-01-preview](/rest/api/searchservice/operation-groups?view=rest-searchservice-2025-08-01-preview&preserve-view=true) data plane REST API. Or, use a prerelease package of an Azure SDK that provides knowledge agent APIs: [Azure SDK for Python](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/search/azure-search-documents/CHANGELOG.md), [Azure SDK for .NET](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/search/Azure.Search.Documents/CHANGELOG.md#1170-beta3-2025-03-25), [Azure SDK for Java](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/search/azure-search-documents/CHANGELOG.md).
 
 To follow the steps in this guide, we recommend [Visual Studio Code](https://code.visualstudio.com/download) with a [REST client](https://marketplace.visualstudio.com/items?itemName=humao.rest-client) for sending REST API calls to Azure AI Search. There's no portal support at this time.
 
 ## Call the retrieve action
 
-Call the **retrieve** action on the knowledge agent object to invoke retrieval and return a response. Use the [2025-05-01-preview](/rest/api/searchservice/operation-groups?view=rest-searchservice-2025-05-01-preview&preserve-view=true) data plane REST API or an Azure SDK prerelease package that provides equivalent functionality for this task.
+Call the **retrieve** action on the knowledge agent object to invoke retrieval and return a response. Use the [2025-08-01-preview](/rest/api/searchservice/operation-groups?view=rest-searchservice-2025-08-01-preview&preserve-view=true) data plane REST API or an Azure SDK prerelease package that provides equivalent functionality for this task.
 
 All `searchable` fields in the search index are in-scope for query execution. If the index includes vector fields, your index should have a valid [vectorizer definition](vector-search-how-to-configure-vectorizer.md) so that it can vectorize the query inputs. Otherwise, vector fields are ignored. The implied query type is `semantic`, and there's no search mode or selection of search fields.
 
@@ -52,7 +56,7 @@ The input for the retrieval route is chat conversation history in natural langua
 @accessToken=<YOUR PERSONAL ID>
 
 # Send grounding request
-POST https://{{search-url}}/agents/{{agent-name}}/retrieve?api-version=2025-05-01-preview
+POST https://{{search-url}}/agents/{{agent-name}}/retrieve?api-version=2025-08-01-preview
     Content-Type: application/json
     Authorization: Bearer {{accessToken}}
 

@@ -0,0 +1,150 @@
+---
+title: Configure Answer Synthesis
+titleSuffix: Azure AI Search
+description: Learn how to configure a knowledge agent to use answer synthesis in Azure AI Search. At query time, the agent uses your deployed chat completion model to produce natural-language answers with citations to your knowledge sources.
+manager: nitinme
+author: haileytap
+ms.author: haileytapia
+ms.service: azure-ai-search
+ms.topic: how-to
+ms.date: 08/26/2025
+---
+
+# Use answer synthesis for citation-backed responses in Azure AI Search
+
+[!INCLUDE [Feature preview](./includes/previews/preview-generic.md)]
+
+By default, a [knowledge agent](search-agentic-retrieval-how-to-create.md) in Azure AI Search performs *data extraction*, which returns raw grounding chunks from your knowledge sources. Data extraction is useful for retrieving specific information, but it lacks the context and reasoning necessary for complex queries.
+
+You can configure the agent to perform *answer synthesis*, which uses your deployed chat completion model to respond to queries in natural language. Each answer includes citations to the retrieved sources and follows any instructions you provide, such as using bulleted lists.
+
+This article explains how to configure and test answer synthesis for an existing agent. Although you can use this configuration for new agents, agent creation is beyond the scope of this article.
+
+> [!IMPORTANT]
+> 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 chat completion model assigned to the agent. For more information, see [Availability and pricing of agentic retrieval](search-agentic-retrieval-concept.md#availability-and-pricing).
+
+## Prerequisites
+
++ A knowledge agent that uses the 2025-08-01-preview syntax, which requires `knowledgeSources` instead of `targetIndexes`.
+
++ [Visual Studio Code](https://code.visualstudio.com/) with the [REST Client extension](https://marketplace.visualstudio.com/items?itemName=humao.rest-client) or a prerelease package of an Azure SDK that provides the knowledge agent REST APIs. Currently, there's no portal support.
+
+## Configure answer synthesis
+
+To configure your knowledge agent for answer synthesis, use the 2025-08-01-preview of [Knowledge Agent - Create or Update (REST API)](/rest/api/searchservice/knowledge-agents/create-or-update?view=rest-searchservice-2025-08-01-preview&preserve-view=true).
+
+In the `outputConfiguration` section:
+
+1. Set `modality` to `answerSynthesis`.
+
+1. (Optional) Use `answerInstructions` to customize the answer output. Our example instructs the agent to `Use concise bulleted lists`.
+
+```http
+@search-url = <YourSearchServiceUrl>
+@agent-name = <YourAgentName>
+@api-key = <YourApiKey>
+
+### Configure answer synthesis
+PUT https://{{search-url}}/knowledgeAgents/{{agent-name}}?api-version=2025-08-01-preview  HTTP/1.1
+    Content-Type: application/json
+    api-key: {{api-key}}
+
+    {
+        "name": "{{agent-name}}",
+        "models": [
+            ... // Redacted for brevity
+        ],
+        "knowledgeSources": [
+            ... // Redacted for brevity
+        ],
+        "outputConfiguration": {
+            "modality": "answerSynthesis",
+            "answerInstructions": "Use concise bulleted lists"
+        }
+    }
+```
+
+> [!IMPORTANT]
+> 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).
+
+<!--
+1. (Optional) Set the `includeReferences` property to `true` or `false`.
+
+    ```http
+          "knowledgeSources" : [
+              {
+                  "name" : "<YourKnowledgeSource>", 
+                  "includeReferences" : true,
+                  "includeReferenceSourceData" : true
+              }
+          ]
+    ```
+
+1. (Optional) Set the `includeActivity` property to `true` to include an activity log in answers.
+
+    ```http
+        	"outputConfiguration": {
+        		"modality": "answerSynthesis",
+        		"answerInstructions": "Use concise bulleted lists",
+        		"includeActivity": true
+        	}
+    ```
+-->
+
+## Get a synthesized answer
+
+After your knowledge agent is configured for answer synthesis, use the 2025-08-01-preview of [Knowledge Retrieval - Retrieve (REST API)](/rest/api/searchservice/knowledge-retrieval/retrieve?view=rest-searchservice-2025-08-01-preview&preserve-view=true) to test its output.
+
+```http
+### Send a query to the agent
+POST https://{{search-url}}/agents/{{agent-name}}/retrieve?api-version=2025-08-01-preview  HTTP/1.1
+    Content-Type: application/json
+    api-key: {{api-key}}
+        
+    {
+      "messages": [
+            {
+                "role": "user",
+                "content" : [
+                    {
+                        "text": "<YourQueryText>",
+                        "type": "text"
+                    }
+                ]
+            }
+        ]
+    }
+```
+
+The response should include a natural-language answer based on your instructions, with citations to your knowledge sources 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:
+
+```json
+{
+  "response": [
+    {
+      "content": [
+        {
+          "type": "text",
+          "text": "- Healthcare encompasses various services provided to patients and the general population ... // Trimmed for brevity
+        }
+      ]
+    }
+  ],
+  ... // Redacted for brevity
+}
+```
+
+The full `text` output is as follows:
+
+```
+"- Healthcare encompasses various services provided to patients and the general population, including primary health services, hospital care, dental care, mental health services, and alternative health services [ref_id:1].\n- It involves the delivery of safe, effective, patient-centered care through different modalities, such as in-person encounters, shared medical appointments, and group education sessions [ref_id:0].\n- Behavioral health is a significant aspect of healthcare, focusing on the connection between behavior and overall health, including mental health and substance use [ref_id:2].\n- The healthcare system aims to ensure quality of care, access to providers, and accountability for positive outcomes while managing costs effectively [ref_id:2].\n- The global health system is evolving to address complex health needs, emphasizing the importance of cross-sectoral collaboration and addressing social determinants of health [ref_id:4]."
+```
+
+Depending on your agent's configuration, the response might include other information, such as activity logs and reference arrays. For more information, see [Create a knowledge agent](search-agentic-retrieval-how-to-create.md).
+
+## Related content
+
++ [Agentic retrieval in Azure AI Search](search-agentic-retrieval-concept.md)
++ [Create a knowledge agent](search-agentic-retrieval-how-to-create.md)
++ [Create a search index knowledge source](search-knowledge-source-how-to-index.md)
++ [Create a blob knowledge source](search-knowledge-source-how-to-blob.md)

@@ -11,7 +11,7 @@ ms.custom:
   - build-2024
   - ignite-2024
 ms.topic: conceptual
-ms.date: 07/31/2025
+ms.date: 08/27/2025
 ---
 
 # Upgrade to the latest REST API in Azure AI Search
@@ -23,7 +23,7 @@ Here are the most recent versions of the REST APIs:
 | Targeted operations | REST API | Status |
 |---------------------|----------|--------|
 | Data plane | [`2024-07-01`](/rest/api/searchservice/search-service-api-versions#2024-07-01) | Stable |
-| Data plane | [`2025-05-01-preview`](/rest/api/searchservice/search-service-api-versions#2025-05-01-preview&preserve-view=true) | Preview |
+| Data plane | [`2025-08-01-preview`](/rest/api/searchservice/search-service-api-versions#2025-08-01-preview&preserve-view=true) | Preview |
 | Control plane | [`2025-05-01`](/rest/api/searchmanagement/operation-groups?view=rest-searchmanagement-2025-05-01&preserve-view=true) | Stable |
 | Control plane | [`2025-02-01-preview`](/rest/api/searchmanagement/operation-groups?view=rest-searchmanagement-2025-02-01-preview&preserve-view=true) | Preview |
 
@@ -40,7 +40,7 @@ We recommend upgrading API versions in succession, working through each version
 
 Azure AI Search breaks backward compatibility as a last resort. Upgrade is necessary when:
 
-+ Your code references a retired or unsupported API version and is subject to one or more breaking changes. You must address breaking changes if your code targets [`2023-07-10-preview`](#code-upgrade-for-vector-indexes-and-queries) for vectors, [`2020-06-01-preview`](#breaking-changes-for-semantic-ranker) for semantic ranker, and [`2019-05-06`](#upgrade-to-2019-05-06) for obsolete skills and workarounds.
++ Your code references a retired or unsupported API version and is subject to one or more breaking changes. You must address breaking changes if your code targets [`2025-05-01-preview`](#breaking-changes-for-knowledge-agents) for knowledge agents, [`2023-07-10-preview`](#code-upgrade-for-vector-indexes-and-queries) for vectors, [`2020-06-01-preview`](#breaking-changes-for-semantic-ranker) for semantic ranker, and [`2019-05-06`](#upgrade-to-2019-05-06) for obsolete skills and workarounds.
 
 + Your code fails when unrecognized properties are returned in an API response. As a best practice, your application should ignore properties that it doesn't understand.
 
@@ -62,6 +62,10 @@ Azure AI Search breaks backward compatibility as a last resort. Upgrade is neces
 
 The following breaking changes apply to data operations.
 
+### Breaking changes for knowledge agents
+
+[Knowledge agents](search-agentic-retrieval-how-to-create.md) were introduced in `2025-05-01-preview`. Breaking changes apply to agents that use `targetIndexes` and `defaultMaxDocsForReranker`, which are deprecated starting in `2025-08-01-preview`. For help with breaking changes, see [Migrate your agentic retrieval code](search-agentic-retrieval-how-to-migrate.md).
+
 ### Breaking changes for client code that reads connection information
 
 Effective March 29, 2024 and applicable to all [supported REST APIs](/rest/api/searchservice/search-service-api-versions):
@@ -86,6 +90,15 @@ See [Migrate from preview version](semantic-code-migration.md) to transition you
 
 Upgrade guidance assumes upgrade from the most recent previous version. If your code is based on an old API version, we recommend upgrading through each successive version to get to the newest version.
 
+### Upgrade to 2025-08-01-preview
+
+[`2025-08-01-preview`](/rest/api/searchservice/search-service-api-versions#2025-08-01-preview) introduces the following breaking changes to knowledge agents created using `2025-05-01-preview`:
+
++ Replaces `targetIndexes` with `knowledgeSources`.
++ Removes `defaultMaxDocsForReranker` without replacement.
+
+Otherwise, there are no behavior changes on existing APIs. You can swap in the new API version and your code runs the same as before.
+
 ### Upgrade to 2025-05-01-preview
 
 [`2025-05-01-preview`](/rest/api/searchservice/search-service-api-versions#2025-05-01-preview) provides new features, but there are no behavior changes on existing APIs. You can swap in the new API version and your code runs the same as before.

@@ -10,7 +10,7 @@ ms.custom:
   - build-2024
   - ignite-2024
 ms.topic: conceptual
-ms.date: 08/18/2025
+ms.date: 08/27/2025
 ---
 
 # Preview features in Azure AI Search
@@ -25,14 +25,18 @@ Preview features are removed from this list if they're retired or transition to
 
 |Feature                          | Category | Description | Availability  |
 |---------|------------------|-------------|---------------|
-| [**Agentic retrieval**](search-agentic-retrieval-concept.md) | Query | Create a conversational search experience powered by large language models (LLMs) and your proprietary data. Agentic retrieval breaks down complex user queries into subqueries, runs the subqueries in parallel, and extracts grounding data from documents indexed in Azure AI Search. The output is intended for agents and custom chat solutions. A new [knowledge agent](search-agentic-retrieval-how-to-create.md) object is introduced in this preview. Its [response payload](search-agentic-retrieval-how-to-retrieve.md) is designed for downstream agent and chat model consumption, with full transparency of the query plan and reference data. To get started, see [Quickstart: Agentic retrieval](search-get-started-agentic-retrieval.md). | [Knowledge Agents (preview)](/rest/api/searchservice/knowledge-agents?view=rest-searchservice-2025-05-01-preview&preserve-view=true) and [Knowledge Retrieval (preview)](/rest/api/searchservice/knowledge-retrieval?view=rest-searchservice-2025-05-01-preview&preserve-view=true)|
-| [**Multivector support**](vector-search-multi-vector-fields.md) | Indexing | Index multiple child vectors within a single document field. You can now use vector types in nested fields of complex collections, effectively allowing multiple vectors to be associated with a single document.| [Create or Update Index (preview)](/rest/api/searchservice/indexes/create-or-update?view=rest-searchservice-2025-05-01-preview&preserve-view=true). |
-| [**Scoring profiles with semantic ranking**](semantic-how-to-enable-scoring-profiles.md) | Relevance | Semantic ranker adds a new field, `@search.rerankerBoostedScore`, to help you maintain consistent relevance and greater control over final ranking outcomes in your search pipeline. | [Create or Update Index (preview)](/rest/api/searchservice/indexes/create-or-update?view=rest-searchservice-2025-05-01-preview&preserve-view=true). |
+| [**"Fast path" for knowledge agents**](search-agentic-retrieval-how-to-create.md) | Agentic search | New `attemptFastPath` boolean for knowledge agents. Enables a shorter processing time if queries are concise and the initial response is sufficiently relevant. | [Knowledge Agents - Create Or Update (preview)](/rest/api/searchservice/knowledge-agents/create-or-update?view=rest-searchservice-2025-08-01-preview&preserve-view=true) |
+| [**Retrieval instructions**](search-agentic-retrieval-how-to-create.md) | Agentic search | New `retrievalInstructions` property for knowledge agents guides query planning in an agentic retrieval workflow. For example, you can specify criteria for including or excluding specific knowledge sources. | [Knowledge Agents - Create Or Update (preview)](/rest/api/searchservice/knowledge-agents/create-or-update?view=rest-searchservice-2025-08-01-preview&preserve-view=true) |
+| [**Improved indexer runtime tracking information**](search-howto-run-reset-indexers.md) | Indexers | New cumulative indexer processing information for the search service and for specific indexers. | [Get Service Statistics (preview)](/rest/api/searchservice/get-service-statistics/get-service-statistics?view=rest-searchservice-2025-08-01-preview&preserve-view=true) and [Get Status - Indexers (preview)](/rest/api/searchservice/get-service-statistics/get-status?view=rest-searchservice-2025-08-01-preview&preserve-view=true) |
+| [**Strict postfiltering for vector queries**](vector-search-filters.md) | Vectors | New `strictPostFilter` mode for the `vectorFilterMode` parameter. When specified, filters are applied after the global top-`k` vector results are identified, ensuring that returned documents are a subset of the unfiltered results. | [Search Documents (preview)](/rest/api/searchservice/documents/search-post?view=rest-searchservice-2025-08-01-preview&preserve-view=true). |
+| [**Agentic retrieval**](search-agentic-retrieval-concept.md) | Query | Create a conversational search experience powered by large language models (LLMs) and your proprietary content. Agentic retrieval breaks down complex user queries into subqueries, runs the subqueries simultaneously, and either extracts grounding data or synthesizes an answer based on documents indexed in Azure AI Search. To get started, see [Quickstart: Agentic retrieval](search-get-started-agentic-retrieval.md).<p>The pipeline involves one or more [knowledge sources](search-knowledge-source-overview.md) and an associated [knowledge agent](search-agentic-retrieval-how-to-create.md), whose [response payload](search-agentic-retrieval-how-to-retrieve.md) provides full transparency into the query plan and reference data. Knowledge sources currently support [search indexes](search-knowledge-source-how-to-index.md) and [Azure blobs](search-knowledge-source-how-to-blob.md). | [Knowledge Sources (preview)](/rest/api/searchservice/knowledge-sources?view=rest-searchservice-2025-08-01-preview&preserve-view=true), [Knowledge Agents (preview)](/rest/api/searchservice/knowledge-agents?view=rest-searchservice-2025-08-01-preview&preserve-view=true), and [Knowledge Retrieval (preview)](/rest/api/searchservice/knowledge-retrieval?view=rest-searchservice-2025-08-01-preview&preserve-view=true). |
+| [**Multivector support**](vector-search-multi-vector-fields.md) | Indexing | Index multiple child vectors within a single document field. You can now use vector types in nested fields of complex collections, effectively allowing multiple vectors to be associated with a single document.| [Create or Update Index (preview)](/rest/api/searchservice/indexes/create-or-update?view=rest-searchservice-2025-08-01-preview&preserve-view=true). |
+| [**Scoring profiles with semantic ranking**](semantic-how-to-enable-scoring-profiles.md) | Relevance | Semantic ranker adds a new field, `@search.rerankerBoostedScore`, to help you maintain consistent relevance and greater control over final ranking outcomes in your search pipeline. | [Create or Update Index (preview)](/rest/api/searchservice/indexes/create-or-update?view=rest-searchservice-2025-08-01-preview&preserve-view=true). |
 | [**Logic Apps integration in the portal wizard**](search-how-to-index-logic-apps-indexers.md) | Indexing | Create an automated indexing pipeline that retrieves content using a logic app workflow. Use the [Import and vectorize data wizard](search-get-started-portal-import-vectors.md) in the Azure portal to build an indexing pipeline based on Logic Apps. | Image and vectorize data wizard in the Azure portal. |
-| [**Document-level access control**](search-document-level-access-overview.md) | Security | Flow document-level permissions from blobs in Azure Data Lake Storage (ADLS) Gen2 to searchable documents in an index. Queries can now filter results based on user identity for selected data sources. | [Create or Update Index (preview)](/rest/api/searchservice/indexes/create-or-update?view=rest-searchservice-2025-05-01-preview&preserve-view=true). |
-| [**GenAI Prompt skill**](cognitive-search-skill-genai-prompt.md) | Skills | A new skill that connects to a large language model (LLM) for information, using a prompt you provide. With this skill, you can populate a searchable field using content from an LLM. A primary use case for this skill is *image verbalization*, using an LLM to describe images and send the description to a searchable field in your index. | [Create or Update Skillset (preview)](/rest/api/searchservice/skillsets/create-or-update?view=rest-searchservice-2025-05-01-preview&preserve-view=true). |
-| [**Document Layout skill**](cognitive-search-skill-document-intelligence-layout.md)| Skills | New parameters are available for this skill if you use the 2025-05-01-preview API version or later. The new parameters support image offset metadata that improves the image search experience. | [Create or Update Skillset (preview)](/rest/api/searchservice/skillsets/create-or-update?view=rest-searchservice-2025-05-01-preview&preserve-view=true). |
-| [**Index "description" support**](/rest/api/searchservice/indexes/create-or-update?view=rest-searchservice-2025-05-01-preview&preserve-view=true#request-body) | REST | The 2025-05-01-preview API version adds a description to an index. A description is useful in agentic solutions, where the agent reads the description to decide whether to run a query or move on to another index. | [Create or Update Index (preview)](/rest/api/searchservice/indexes/create-or-update?view=rest-searchservice-2025-05-01-preview&preserve-view=true). |
+| [**Document-level access control**](search-document-level-access-overview.md) | Security | Flow document-level permissions from blobs in Azure Data Lake Storage (ADLS) Gen2 to searchable documents in an index. Queries can now filter results based on user identity for selected data sources. | [Create or Update Index (preview)](/rest/api/searchservice/indexes/create-or-update?view=rest-searchservice-2025-08-01-preview&preserve-view=true). |
+| [**GenAI Prompt skill**](cognitive-search-skill-genai-prompt.md) | Skills | A new skill that connects to a large language model (LLM) for information, using a prompt you provide. With this skill, you can populate a searchable field using content from an LLM. A primary use case for this skill is *image verbalization*, using an LLM to describe images and send the description to a searchable field in your index. | [Create or Update Skillset (preview)](/rest/api/searchservice/skillsets/create-or-update?view=rest-searchservice-2025-08-01-preview&preserve-view=true). |
+| [**Document Layout skill**](cognitive-search-skill-document-intelligence-layout.md)| Skills | New parameters are available for this skill if you use the 2025-05-01-preview API version or later. The new parameters support image offset metadata that improves the image search experience. | [Create or Update Skillset (preview)](/rest/api/searchservice/skillsets/create-or-update?view=rest-searchservice-2025-08-01-preview&preserve-view=true). |
+| [**Index "description" support**](/rest/api/searchservice/indexes/create-or-update?view=rest-searchservice-2025-08-01-preview&preserve-view=true#request-body) | REST | You can now write descriptions for indexes. A description is useful in agentic solutions, where the agent reads the description to decide whether to run a query or move on to another index. | [Create or Update Index (preview)](/rest/api/searchservice/indexes/create-or-update?view=rest-searchservice-2025-08-01-preview&preserve-view=true). |
 | [**flightingOptIn parameter in a semantic configuration**](semantic-how-to-configure.md#opt-in-for-prerelease-semantic-ranking-models) | Queries| You can opt in to use prerelease semantic ranking models if one is available in a search service region. | [Create or Update Index (preview)](/rest/api/searchservice/indexes/create-or-update?view=rest-searchservice-2025-03-01-preview&preserve-view=true). |
 | [**Rescore vector queries over binary embeddings using full precision vectors**](vector-search-how-to-quantization.md#recommended-rescoring-techniques) | Relevance (scoring) | For vector indexes that contain quantized binary embeddings, you can rescore query results using a full precision query vector. The query engine uses the dot product for rescoring, which improves the quality of search results. Set `enableRescoring` and `discardOriginals` to use this feature.| [Create or Update Index (preview)](/rest/api/searchservice/indexes/create-or-update?view=rest-searchservice-2025-03-01-preview&preserve-view=true). |
 | [**Facet hierarchies, aggregations, and facet filters**](search-faceted-navigation-examples.md) | Queries| New facet query parameters support nested facets. For numeric facetable fields, you can sum the values of each field. You can also specify filters on a facet to add inclusion or exclusion criteria. | [Search Documents (preview)](/rest/api/searchservice/documents/search-post?view=rest-searchservice-2025-03-01-preview&preserve-view=true). |
@@ -92,7 +96,7 @@ If you write code against a preview API, you should prepare to upgrade that code
 
 Preview REST APIs are accessed through the api-version parameter on the URI. Older previews are still operational but become stale over time and aren't updated with new features or bug fixes.
 
-For data plane operation on content, [**`2024-05-01-preview`**](/rest/api/searchservice/search-service-api-versions#2024-05-01-Preview) is the most recent preview version. The following example shows the syntax for [Indexes GET (preview)](/rest/api/searchservice/indexes/get?view=rest-searchservice-2024-05-01-preview&preserve-view=true):
+For data plane operations on content, [**`2025-08-01-preview`**](/rest/api/searchservice/search-service-api-versions#2025-08-01-Preview) is the most recent preview version. The following example shows the syntax for [Indexes GET (preview)](/rest/api/searchservice/indexes/get?view=rest-searchservice-2025-08-01-preview&preserve-view=true):
 
 ```rest
 GET {endpoint}/indexes('{indexName}')?api-version=2024-05-01-Preview

@@ -4,7 +4,7 @@ titleSuffix: Azure AI Search
 description: Learn how to configure Azure AI Search indexers for ingesting Azure Role-Based Access (RBAC) metadata on Azure blobs.
 ms.service: azure-ai-search  
 ms.topic: how-to
-ms.date: 07/16/2025
+ms.date: 09/01/2025
 author: vaishalishah
 ms.author: vaishalishah
 ---  
@@ -13,25 +13,33 @@ ms.author: vaishalishah
 
 [!INCLUDE [Feature preview](./includes/previews/preview-generic.md)]
 
-Azure Storage allows for role-based access on containers in blob storage, where roles like **Storage Blob Data Reader** or **Storage Blob Data Contributor** determine whether someone has access to content. Starting in 2025-05-01-preview, you can now include RBAC scope alongside document ingestion in Azure AI Search and use those permissions to control access to search results. If you have rights to the content, you can see those results in a search query. If you don't have rights (or more specifically, a role assignment on the blob container), you *can't* see those results even if you personally have a **Search Index Data Reader** assignment on the index.
+Azure Storage allows for role-based access on containers in blob storage, where roles like **Storage Blob Data Reader** or **Storage Blob Data Contributor** determine whether someone has access to content. Starting in 2025-05-01-preview, you can now include RBAC scope alongside document ingestion in Azure AI Search and use those permissions to control access to search results. If you have rights to the content, you can see that content in search results. If you don't have rights (or more specifically, a role assignment on the blob container), you *can't* see those results even if you personally have a **Search Index Data Reader** assignment *on the index*.
 
-RBAC scope is set at the container level and flows to all blobs (documents) through permission inheritance. RBAC scope is captured during indexing as permission metadata, You can use the push APIs to upload and index content and permission metadata manually see [Indexing Permissions using the push REST API](search-index-access-control-lists-and-rbac-push-api.md), or you can use an indexer to automate data ingestion. This article focuses on the indexer approach.
+RBAC scope is set at the container level and flows to all blobs (documents) through permission inheritance. RBAC scope is captured during indexing as permission metadata. You can use the push APIs to upload and index content and permission metadata manually (see [Indexing Permissions using the push REST API](search-index-access-control-lists-and-rbac-push-api.md)), or you can use an indexer to automate data ingestion. This article focuses on the indexer approach.
 
 At query time, the identity of the caller is included in the request header via the `x-ms-query-source-authorization` parameter. The identity must match the permission metadata on documents if the user is to see the search results.
 
 The indexer approach is built on this foundation:
 
-+ [Role-based access control (Azure RBAC)](/azure/storage/blobs/data-lake-storage-access-control-model#role-based-access-control-azure-rbac). There's no support for Attribute-based access control (Azure ABAC).
++ [Azure Storage blobs secured using role-based access control (Azure RBAC)](/azure/storage/blobs/data-lake-storage-access-control-model#role-based-access-control-azure-rbac). There's no support for Attribute-based access control (Azure ABAC).
 
-+ [An Azure AI Search indexer for blobs](search-howto-indexing-azure-blob-storage.md) that retrieves and ingests data and metadata, including permission filters. To get permission filter support, you must use the 2025-05-01-preview REST API or a preview package of an Azure SDK that supports the feature.
++ [An Azure AI Search indexer for blobs](search-howto-indexing-azure-blob-storage.md) that retrieves and ingests data and metadata, including permission filters. To get permission filter support, use the latest preview REST API or a preview package of an Azure SDK that supports the feature.
 
-+ [An index in Azure AI Search](search-how-to-create-search-index.md) containing the ingested documents and corresponding permissions. Permission metadata is stored as fields in the index. To set up queries that respect the permission filters, you must use the 2025-05-01-preview REST API or a preview package of an Azure SDK that supports the feature. 
++ [An index in Azure AI Search](search-how-to-create-search-index.md) containing the ingested documents and corresponding permissions. Permission metadata is stored as fields in the index. 
+
++ [A query that uses permission filters](search-query-access-control-rbac-enforcement.md). To set up queries that respect the permission filters, use the latest preview REST API or a preview package of an Azure SDK that supports the feature.
 
 ## Prerequisites
 
 + [Microsoft Entra ID authentication and authorization](/entra/identity/authentication/overview-authentication). Services and apps must be in the same tenant. Users can be in different tenants as long as all of the tenants are Microsoft Entra ID. Role assignments are used for each authenticated connection.
 
-+ Azure AI Search, any region, but you must have a billable tier (basic and higher) see [Service limits](search-limits-quotas-capacity.md) for managed identity support. The search service must be [configured for role-based access](search-security-enable-roles.md) and it must [have a managed identity (either system or user)](search-how-to-managed-identities.md).
++ Azure AI Search, any region, but you must have a billable tier (basic and higher) for managed identity support. The search service must be [configured for role-based access](search-security-enable-roles.md) and it must [have a managed identity (either system or user)](search-how-to-managed-identities.md).
+
++ Azure Storage, Standard performance (general-purpose v2), on hot, cool, and cold access tiers, with RBAC-secured containers or blobs.
+
++ You should understand how indexers work and how to create an index. This article explains the configuration settings for the data source and indexer, but doesn't provide steps for creating the index. For more information about indexes designed for permission filters, see [Create an index with permission filter fields](search-index-access-control-lists-and-rbac-push-api.md#create-an-index-with-permission-filter-fields).
+
+Permission filters aren't supported in the indexers and indexes created through the [Import wizards](search-import-data-portal.md). Use a programmatic approach to create or modify existing objects for document-level access.
 
 ## Configure Blob storage
 
@@ -75,7 +83,7 @@ In Azure AI Search, configure an indexer, data source, and index to pull permiss
   + For connection strings using a [user-assigned managed identity](search-howto-managed-identities-storage.md#user-assigned-managed-identity-preview), you must also specify the `identity` property.
 
 <!-- Question/Comment: check this example -->
-JSON example with system managed identity:
+JSON example with system managed identity and `indexerPermissionOptions`:
 
 ```json
 {
@@ -164,9 +172,19 @@ JSON schema example:
 }
 ```
 
+### Run the indexer
+
+Once your indexer, data source, and index are configured, run the indexer to set the process in motion. If there's a problem with configuration or permissions, those problems will surface in this step.
+
+By default, an indexer runs as soon as you post it to a search service, but if the indexer configuration includes `disabled` set to true, the indexer is posted in a disabled state so that you can run the indexer manually.
+
+We recommend [running the indexer from the Azure portal](search-howto-run-reset-indexers.md#how-to-reset-and-run-indexers) so that you can monitor status and messages.
+
+Assuming no errors, the index is now populated and you can move forward with [queries and testing](search-query-access-control-rbac-enforcement.md).
+
 ## Deletion tracking 
 
-To effectively manage blob deletion, ensure that you have enabled [deletion tracking](search-howto-index-changed-deleted-blobs.md) before your indexer runs for the first time. This feature allows the system to detect deleted blobs from your source and have them deleted from the index.  
+To effectively manage blob deletion, ensure that you have enabled [deletion tracking](search-howto-index-changed-deleted-blobs.md) before your indexer runs for the first time. This feature allows the system to detect deleted blobs from your source and delete the corresponding content from the index.  
 
 ## See also