Merge pull request #6894 from HeidiSteen/release-aug-2

Knowledge agent updates

Author: prmerger-automator[bot]

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

@@ -241,18 +241,73 @@ PUT {{search-url}}/agents/{{agent-name}}?api-version=2025-08-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 "What are my vision benefits?" with a query string that's valid for your search index.
+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}}
 
+{
+  "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.
+
+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 {{search-url}}/agents/{{agent-name}}/retrieve?api-version=2025-08-01-preview
+   Content-Type: application/json
+   Authorization: Bearer {{accessToken}}
+
 {
     "messages" : [
             {
@@ -278,7 +333,7 @@ POST {{search-url}}/agents/{{agent-name}}/retrieve?api-version=2025-08-01-previe
         } 
     ]
 }
-```
+``` -->
 
 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).
 

articles/search/search-knowledge-source-how-to-blob.md

@@ -211,10 +211,12 @@ We recommend using the Azure portal to validate output creation.
 
 ## Assign to a knowledge agent
 
-If you're satisfied with the index, continue to the next step: specifying the knowledge source in a [knowledge agent](search-agentic-retrieval-how-to-create.md).
+If you're satisfied with the index, continue to the next step: specify the knowledge source in a [knowledge agent](search-agentic-retrieval-how-to-create.md).
 
 Within the knowledge agent, there are more properties to set on the knowledge source that are specific to query operations.
 
+After the knowledge agent is configured, use the retrieve action to query the knowledge source.
+
 ## Delete a knowledge source
 
 If you no longer need the knowledge source, or if you need to rebuild it on the search service, use this request to delete the current object.

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

@@ -22,6 +22,8 @@ Make sure you have at least one knowledge source before creating a knowledge age
 
 ## 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.
+
 + A knowledge source, its index, and the knowledge agent must all exist on the same search service.
 
 + Each knowledge source points to exactly one index, and that index must [meet the criteria for agentic retrieval](search-agentic-retrieval-how-to-index.md).
@@ -80,3 +82,36 @@ To achieve the fastest possible response times, follow these best practices:
 + Retain `includeReferences` set to true (default setting) for details about each individually scored result.
 
 + 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.
+
+## Delete a knowledge source
+
+Before you can delete a knowledge source, you must delete or update any knowledge agent that references it. The associated index is a standalone object in Azure AI Search and doesn't need to be deleted or updated in tandem with the knowledge source, but no references to the knowledge source can exist if you want to delete it.
+
+If you try to delete a knowledge source that's in use, the action fails and a list of affected knowledge agents is returned.
+
+1. Get the knowledge agent definition to confirm knowledge source references.
+
+    ```http
+    ### Get the knowledge agent
+    GET {{search-endpoint}}/agents/hotels-index-ka?api-version=2025-08-01-preview
+    api-key: {{api-key}}
+    Content-Type: application/json
+    ```
+
+1. Either update the knowledge agent by removing the knowledge source, or delete the knowledge agent. This example shows deletion.
+
+    ```http
+    ### Delete knowledge agent
+    DELETE {{search-endpoint}}/agents/hotels-index-ka?api-version=2025-08-01-preview
+    api-key: {{api-key}}
+    Content-Type: application/json
+    ```
+
+1. Delete the knowledge source.
+
+    ```http
+    ### Delete a knowledge source definition
+    GET {{search-endpoint}}/knowledgeSources/hotels-index-ks?api-version=2025-08-01-preview
+    api-key: {{api-key}}
+    Content-Type: application/json
+    ```