checkpoint

HeidiSteen · HeidiSteen · commit bd23a4a2f1c8 · 2025-05-30T14:15:11.000-07:00
diff --git a/articles/search/search-agentic-retrieval-how-to-create.md b/articles/search/search-agentic-retrieval-how-to-create.md
@@ -15,19 +15,21 @@ ms.date: 05/30/2025
 
 [!INCLUDE [Feature preview](./includes/previews/preview-generic.md)]
 
-In Azure AI Search, a *knowledge agent* is a top-level resource representing a connection to a chat completion model for use in agentic retrieval workloads. A knowledge agent specifies:
+In Azure AI Search, a *knowledge agent* is a top-level resource representing a connection to a chat completion model for use in agentic retrieval workloads. A knowledge agent is used by the [retrieve method](search-agentic-retrieval-how-to-retrieve.md) in an LLM-powered information retrieval pipeline.
+
+knowledge agent specifies:
 
 + A model that provides reasoning capabilities
-+ A search index used at query time
-+ Parameters on the index for setting default response behavior
++ A target search index used at query time
++ Parameters on the index for setting default behaviors and response shaping
 
 After you can create a knowledge agent, you can update its properties at any time. If the knowledge agent is in use, updates take effect on the next job.
 
 ## Prerequisites
 
 + Familiarity with [agentic retrieval concepts and use cases](search-agentic-retrieval-concept.md).
 
-+ A chat completion model on Azure OpenAI.
++ A [supported chat completion model](#supported-models) on Azure OpenAI.
 
 + Azure AI Search, in any [region that provides semantic ranker](search-region-support.md), on the basic pricing tier or higher. Your search service must have a [managed identity](search-howto-managed-identities-data-sources.md) for role-based access to the model.
 
@@ -104,7 +106,7 @@ You can use API keys if you don't have permission to create role assignments.
    # List Indexes
    GET https://{{search-url}}/indexes?api-version=2025-05-01-preview
       Content-Type: application/json
-      @api-key = <YOUR-SEARCH-SERVICE-API-KEY>
+      @api-key: {{search-api-ke}}
    ```
 
 ## Check for existing knowledge agents
@@ -117,7 +119,7 @@ The following request lists knowledge agents by name on your search service. Wit
 # List knowledge agents
 GET https://{{search-url}}/agents?api-version=2025-05-01-preview
    Content-Type: application/json
-   @token = <a long GUID>
+   Authorization: Bearer {{accessToken}}
 ```
 
 You can also return a single agent by name to review its JSON definition.
@@ -126,7 +128,7 @@ You can also return a single agent by name to review its JSON definition.
 # Get knowledge agent
 GET https://{{search-url}}/agents/{{agent-name}}?api-version=2025-05-01-preview
    Content-Type: application/json
-   @token = <a long GUID>
+   Authorization: Bearer {{accessToken}}
 ```
 
 <!-- --- -->
@@ -145,12 +147,12 @@ To create an agent, use the 2025-05-01-preview data plane REST API or an Azure S
 @agent-name=<YOUR AGENT NAME>
 @index-name=<YOUR INDEX NAME>
 @model-provider-url=<YOUR AZURE OPENAI RESOURCE URI>
-@token = <a long GUID>
+@accessToken = <a long GUID>
 
 # Create knowledge agent
 PUT https://{{search-url}}/agents/{{agent-name}}?api-version=2025-05-01-preview
    Content-Type: application/json
-   @token = <a long GUID>
+   Authorization: Bearer {{accessToken}}
 
 {
     "name" : "{{agent-name}}",
@@ -223,7 +225,7 @@ Replace "What are my vision benefits?" with a query string that's valid for your
 # Send Grounding Request
 POST https://{{search-url}}/agents/{{agent-name}}/retrieve?api-version=2025-05-01-preview
    Content-Type: application/json
-   @token = <a long GUID>
+   Authorization: Bearer {{accessToken}}
 
 {
     "messages" : [
@@ -261,7 +263,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
-   @token = <a long GUID>
+   Authorization: Bearer {{accessToken}}
 ```
 
 ## Related content
diff --git a/articles/search/search-agentic-retrieval-how-to-retrieve.md b/articles/search/search-agentic-retrieval-how-to-retrieve.md
@@ -17,7 +17,7 @@ ms.date: 05/30/2025
 
 In Azure AI Search, *agentic retrieval* is a new parallel query architecture that uses a chat completion model for query planning. It generates subqueries that broaden the scope of what's searchable and relevant.
 
-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-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: 
 
 + *extracted response for the LLM*
 + *referenced results*
@@ -26,7 +26,7 @@ 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, the response provides grounding data used to generate an answer from an LLM. For an end-to-end example, 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).
+> There's no model-generated "answer" in the response. Instead, the response passes content 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).
 
 ## Prerequisites
 
@@ -49,10 +49,13 @@ All `searchable` fields in the search index are in-scope for query execution. If
 The input for the retrieval route is chat conversation history in natural language, where the `messages` array contains the conversation.
 
 ```http
+@search-url=<YOUR SEARCH SERVICE URL>
+@accessToken=<YOUR PERSONAL ID>
+
 # Send Grounding Request
 POST https://{{search-url}}/agents/{{agent-name}}/retrieve?api-version=2025-05-01-preview
-    @accessToken=<YOUR PERSONAL ID>
     Content-Type: application/json
+    Authorization: Bearer {{accessToken}}
 
 {
     "messages" : [
@@ -155,32 +158,32 @@ Here's an example of an activity array.
     {
       "type": "ModelQueryPlanning",
       "id": 0,
-      "inputTokens": 1308,
-      "outputTokens": 141
+      "inputTokens": 1270,
+      "outputTokens": 221
     },
     {
       "type": "AzureSearchQuery",
       "id": 1,
       "targetIndex": "myindex",
       "query": {
-        "search": "hello world programming",
+        "search": "impact of prior authorization process on out-of-pocket costs",
         "filter": null
       },
       "queryTime": "2025-04-25T16:40:08.811Z",
-      "count": 2,
-      "elapsedMs": 867
+      "count": 27,
+      "elapsedMs": 623
     },
     {
       "type": "AzureSearchQuery",
       "id": 2,
       "targetIndex": "myindex",
       "query": {
-        "search": "hello world meaning",
+        "search": "copayment expectations for in-network services",
         "filter": null
       },
       "queryTime": "2025-04-25T16:40:08.955Z",
-      "count": 2,
-      "elapsedMs": 136
+      "count": 22,
+      "elapsedMs": 556
     }
   ],
 ```
@@ -201,7 +204,7 @@ Here's an example of the references array.
   "references": [
     {
       "type": "AzureSearchDoc",
-      "id": "0",
+      "id": "1",
       "activitySource": 2,
       "docKey": "2",
       "sourceData": {
