updates for agentic retrieval plus missing steps in connection quickstart

Author: HeidiSteen

articles/search/includes/quickstarts/search-get-started-rbac-python.md

@@ -33,10 +33,18 @@ To sign in:
 
 1. On your local system, open a command-line tool.
 
-1. Sign in to Azure. If you have multiple subscriptions, select the one whose ID you obtained in [Get service information](#get-service-information).
+1. Check for the active tenant and subscription in your local environment.
 
    ```azurecli
-   az login
+   az account show
+   ```
+
+1. If the active subscription and tenant aren't valid for your search service, change the variables. You can check for the subscription ID on the search service overview page in the Azure portal. You can check for the tenant ID by clicking through to the subscription. In the Azure portal, the tenant ID is referred to as the **Parent management group**. Make a note of the values that are valid for your search service and run the following commands to update your local environment.
+
+   ```azurecli
+    az account set --subscription <your-subscription-id>
+
+    az login --tenant <your-tenant-id>
    ```
 
 ## Connect to Azure AI Search

articles/search/includes/quickstarts/search-get-started-rbac-rest.md

@@ -25,35 +25,39 @@ Keyless connections provide enhanced security through granular permissions and i
 
 [!INCLUDE [Setup](./search-get-started-rbac-setup.md)]
 
-## Get token
-
-Before you connect to your Azure AI Search service, use the Azure CLI to sign in to the subscription that contains your service and generate a Microsoft Entra ID token. You use this token to authenticate requests in the next section.
-
-To get your token:
+## Sign in to Azure
 
-1. On your local system, open a command-line tool.
+Before you connect to your Azure AI Search service, use the Azure CLI to sign in to the subscription that contains your service.
 
 1. Check for the active tenant and subscription in your local environment.
 
    ```azurecli
    az account show
    ```
 
-1. If the active subscription and tenant aren't valid for your search service, change the variables. You can check for the subscription ID on the search service overview page in the Azure portal. You can check for the tenant ID by clicking through to the subscription. Make a note of the values that are valid for your search service and run the following commands to update your local environment.
+1. If the active subscription and tenant aren't valid for your search service, change the variables. You can check for the subscription ID on the search service overview page in the Azure portal. You can check for the tenant ID by clicking through to the subscription. In the Azure portal, the tenant ID is referred to as the **Parent management group**. Make a note of the values that are valid for your search service and run the following commands to update your local environment.
 
    ```azurecli
     az account set --subscription <your-subscription-id>
 
     az login --tenant <your-tenant-id>
    ```
 
+## Get token
+
+REST API calls require the inclusion of a Microsoft Entra ID token. You use this token to authenticate requests in the next section.
+
+To get your token:
+
+1. On your local system, open a command-line tool.
+
 1. Generate an access token.
 
    ```azurecli
    az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv
    ```
 
-1. Make a note of the token output.
+1. Copy the token output.
 
 ## Connect to Azure AI Search
 

articles/search/search-agentic-retrieval-how-to-index.md

@@ -7,7 +7,7 @@ author: HeidiSteen
 ms.author: heidist
 ms.service: azure-ai-search
 ms.topic: how-to
-ms.date: 08/29/2025
+ms.date: 10/01/2025
 ---
 
 # Design an index for agentic retrieval in Azure AI Search
@@ -16,13 +16,13 @@ ms.date: 08/29/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.
 
-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.
+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 the query logic. None of the required elements are new or specific to agentic retrieval, which means you can use an existing index if it meets the criteria identified in this article, even if it was created using earlier API versions.
 
-A search index that's used in agentic retrieval is specified as *knowledge source* and is either:
+A search index that's used in agentic retrieval is specified as *knowledge source* on a *knowledge agent*, 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. 
++ A generated index created from a 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
 
@@ -64,7 +64,7 @@ Here's an example index that works for agentic retrieval. It meets the criteria
       "synonymMaps": []
     },
     {
-      "name": "page_chunk_text_3_large", "type": "Collection(Edm.Single)",
+      "name": "page_chunk_vector_text_3_large", "type": "Collection(Edm.Single)",
       "searchable": true, "retrievable": false, "filterable": false, "sortable": false, "facetable": false,
       "dimensions": 3072,
       "vectorSearchProfile": "hnsw_text_3_large",
@@ -91,9 +91,7 @@ Here's an example index that works for agentic retrieval. It meets the criteria
   "tokenizers": [],
   "tokenFilters": [],
   "charFilters": [],
-  "similarity": {
-    "@odata.type": "#Microsoft.Azure.Search.BM25Similarity"
-  },
+  "similarity": {},
   "semantic": {
     "defaultConfiguration": "semantic_config",
     "configurations": [
@@ -152,21 +150,14 @@ Here's an example index that works for agentic retrieval. It meets the criteria
 
 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).
+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 that produces grounding data, but aren't otherwise strictly required. Azure AI Search has built-in capabilities that [simplify and automate vectorization](vector-search-overview.md).
 
 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.
+The vectorizer defined in the vector search configuration is critical. It determines whether your vector field is used during query execution. The vectorizer encodes string 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.
 
 All `searchable` fields are included in query execution. There's no support for a `select` statement that explicitly states which fields to query.
 
-<!-- 
-> [!div class="checklist"]
-> + A fields collection with `searchable` text and vetor fields, and `retrievable` text fields
-> + Vector fields that are queried are fields having a vectorizer
-> + Fields selected in the response string are semantic fields (title, terms, content)
-> + Fields in reference source data are all `retrievable` fields, assuming reference source data is true -->
-
 ## Add a description
 
 An index `description` field is a user-defined string that you can use to provide guidance to LLMs and Model Context Protocol (MCP) servers when deciding to use a specific index for a query. This human-readable text is invaluable when a system must access several indexes and make a decision based on the description. 

articles/search/search-agentic-retrieval-how-to-retrieve.md

@@ -69,7 +69,7 @@ POST https://{{search-url}}/agents/{{agent-name}}/retrieve?api-version=2025-08-0
                 "content" : [
                   { "type" : "text", "text" : "You can answer questions about the Earth at night.
                     Sources have a JSON format with a ref_id that must be cited in the answer.
-                    If you do not have the answer, respond with 'I don't know'." }
+                    If you do not have the answer, respond with 'I do not know'." }
                 ]
             },
             {

articles/search/search-knowledge-source-overview.md

@@ -7,22 +7,24 @@ author: HeidiSteen
 ms.author: heidist
 ms.service: azure-ai-search
 ms.topic: how-to
-ms.date: 08/29/2025
+ms.date: 10/01/2025
 ---
 
 # Create a knowledge source
 
+[!INCLUDE [Feature preview](./includes/previews/preview-generic.md)]
+
 A knowledge source wraps a search index with extra properties for agentic retrieval. It's a required definition in a knowledge agent. We provide guidance on how to create specific knowledge sources, but generally, you can:
 
 + Create multiple knowledge sources as top-level resources on your search service.
 
-+ Reference one or more knowledge sources in a knowledge agent. In an agentic retrieval pipeline, it's possible to query against multiple knowledge sources in single request. Subqueries are generated for each knowledge sources. Top results are returned in the retrieval response.
++ Reference one or more knowledge sources in a knowledge agent. In an agentic retrieval pipeline, it's possible to query against multiple knowledge sources in single request. Subqueries are generated for each knowledge source. Top results are returned in the retrieval response.
 
-Make sure you have at least one knowledge source before creating a knowledge agent. The full specification of a knowledge agent is in the [REST API reference](/rest/api/searchservice/knowledge-sources/create-or-update?view=rest-searchservice-2025-08-01-preview&preserve-view=true). 
+Make sure you have at least one knowledge source before creating a knowledge agent. The full specification of a knowledge source and a knowledge agent is in the [REST API reference](/rest/api/searchservice). 
 
 ## Key points about a knowledge source
 
-+ Creation path: first create knowledge source, then create knowledge agents. Deletion path: update or delete knowledge agents, delete knowledge sources last.
++ Creation path: first create a knowledge source, then create a knowledge agent. Deletion path: update or delete knowledge agents, delete knowledge sources last.
 
 + A knowledge source, its index, and the knowledge agent must all exist on the same search service.
 
@@ -53,15 +55,15 @@ When you have multiple knowledge sources, set the following properties to bias q
 + Setting `alwaysQuerySource` forces query planning to always include the knowledge source.
 + Setting `retrievalInstructions` provides guidance that includes or excludes a knowledge source. 
 
-Retrieval instructions are sent as a prompt to the large language model (LLM) used for query planning. This prompt is helpful when you have multiple knowledge sources and want to provide guidance on when to use each one. For example, if you have separate indexes for product information, job postings, and technical support, the retrieval instructions might say "use the jobs index only if the question is about a job application."
+Retrieval instructions are sent as a user-defined prompt to the large language model (LLM) used for query planning. This prompt is helpful when you have multiple knowledge sources and want to provide guidance on when to use each one. For example, if you have separate indexes for product information, job postings, and technical support, the retrieval instructions might say "use the jobs index only if the question is about a job application."
 
 The `alwaysQuerySource` property overrides `retrievalInstructions`. You should set `alwaysQuerySource` to false when providing retrieval instructions.
 
 ### Attempt fast path processing
 
 Fast path is opportunistic query processing that approaches the millisecond query performance of regular search. If you enable it, the search engine attempts fast path under the following conditions:
 
-+ `attemptFastPath` is set to true in `knowledgeSourceReferences`.
++ `attemptFastPath` is set to true in `outputConfiguration`.
 
 + The query input is a single message that's fewer than 512 characters.
 
@@ -75,13 +77,19 @@ Under fast path, `retrievalInstructions` are ignored. In general, `alwaysQuerySo
 
 To achieve the fastest possible response times, follow these best practices:
 
-+ Set `modality` to `answerSynthesis` to get a response framed as an LLM-formulated answer. It takes a few extra seconds, but it improves the quality of the response and saves time overall if the answer is usable without further LLM processing.
+1. In the knowledge agent:
+
+   + Set `outputConfiguration.attemptFastPath` to true.
+
+   + Set `outputConfiguration.modality` to `answerSynthesis` to get a response framed as an LLM-formulated answer. It takes a few extra seconds, but it improves the quality of the response and saves time overall if the answer is usable without further LLM processing.
+
+   + Retain `outputConfiguration.includeActivity` set to true (default setting) for insights about query execution and elapsed time.
 
-+ Retain `includeActivity` set to true (default setting) for insights about query execution and elapsed time.
+   + Retain `knowledgeSource.includeReferences` set to true (default setting) for details about each individually scored result.
 
-+ Retain `includeReferences` set to true (default setting) for details about each individually scored result.
+   + Set `knowledgeSource.includeReferenceSourceData` to false if you don't need the verbatim content from the index. Omitting this information simplifies the response and makes it more readable.
 
-+ Set `includeReferenceSourceData` to false if you don't need the verbatim content from the index. Omitting this information simplifies the response and makes it more readable.
+1. In the [retrieve action](search-agentic-retrieval-how-to-retrieve.md), provide a query that's fewer than 512 characters.
 
 ## Delete a knowledge source