Merge pull request #606 from westey-m/connector-lang-and-immutable-kernel

Update language around vectordata and add immutable kernel warning

Author: westey-m

semantic-kernel/Frameworks/agent/agent-contextual-function-selection.md

@@ -22,6 +22,10 @@ Contextual Function Selection is an advanced capability in the Semantic Kernel A
 
 This approach addresses the challenge of function selection when dealing with a large number of available functions, where AI models may otherwise struggle to choose the appropriate function, leading to confusion and suboptimal performance.
 
+> [!WARNING]
+> When using the `ContextualFunctionProvider`, the `UseImmutableKernel` setting on the agent has to be set to `true` as the feature requires cloning the kernel when invoking the agent.
+> Note that setting `UseImmutableKernel` to `true` will mean that any kernel data modifications done during the agent invocation by e.g. plugins, will not be retained after the invocation completes.
+
 ## How Contextual Function Selection Works
 
 When an agent is configured with contextual function selection, it leverages a vector store and an embedding generator to semantically match the current conversation context (including previous messages and user input) with the descriptions and names of available functions. The most relevant functions, up to the specified limit, are then advertised to the AI model for invocation.
@@ -50,7 +54,9 @@ ChatCompletionAgent agent = new()
     Name = "ReviewGuru",
     Instructions = "You are a friendly assistant that summarizes key points and sentiments from customer reviews. For each response, list available functions.",
     Kernel = kernel,
-    Arguments = new(new PromptExecutionSettings { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto(options: new FunctionChoiceBehaviorOptions { RetainArgumentTypes = true }) })
+    Arguments = new(new PromptExecutionSettings { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto(options: new FunctionChoiceBehaviorOptions { RetainArgumentTypes = true }) }),
+    // This setting must be set to true when using the ContextualFunctionProvider
+    UseImmutableKernel = true
 };
 
 // Create the agent thread and register the contextual function provider

semantic-kernel/Frameworks/agent/agent-rag.md

@@ -57,7 +57,9 @@ ChatCompletionAgent agent = new()
 {
     Name = "FriendlyAssistant",
     Instructions = "You are a friendly assistant",
-    Kernel = kernel
+    Kernel = kernel,
+    // This setting must be set to true when using the on-demand RAG feature
+    UseImmutableKernel = true
 };
 
 // Create an agent thread and add the TextSearchProvider.
@@ -124,6 +126,10 @@ var options = new TextSearchProviderOptions
 var provider = new TextSearchProvider(mockTextSearch.Object, options: options);
 ```
 
+> [!WARNING]
+> When using the `TextSearchProvider` with `OnDemandFunctionCalling`, the `UseImmutableKernel` setting on the agent has to be set to `true` as the feature requires cloning the kernel when invoking the agent.
+> Note that setting `UseImmutableKernel` to `true` will mean that any kernel data modifications done during the agent invocation by e.g. plugins, will not be retained after the invocation completes.
+
 ## TextSearchProvider options
 
 The `TextSearchProvider` can be configured with various options to customize its behavior. Options are provided using the `TextSearchProviderOptions` class to the `TextSearchProvider` constructor.

semantic-kernel/concepts/TOC.yml

@@ -6,7 +6,7 @@
   href: ai-services/TOC.yml
 - name: Enterprise Components
   href: enterprise-readiness/TOC.yml
-- name: Memory (Vector Stores)
+- name: Vector Stores
   href: vector-store-connectors/TOC.yml
 - name: Prompts
   href: prompts/TOC.yml

semantic-kernel/concepts/vector-store-connectors/index.md

@@ -1,5 +1,5 @@
 ---
-title: What are Semantic Kernel Vector Store connectors? (Preview)
+title: What are Semantic Kernel Vector Stores? (Preview)
 description: Describes what a Semantic Kernel Vector Store is, and provides a basic example of how to use one and how to get started.
 zone_pivot_groups: programming-languages
 author: westey-m
@@ -8,7 +8,7 @@ ms.author: westey
 ms.date: 07/08/2024
 ms.service: semantic-kernel
 ---
-# What are Semantic Kernel Vector Store connectors? (Preview)
+# What are Semantic Kernel Vector Stores? (Preview)
 
 ::: zone pivot="programming-language-csharp"
 
@@ -35,24 +35,30 @@ One use case for storing information in a vector database is to enable large lan
 
 For example, if you want to write a blog post about the latest trends in AI, you can use a vector database to store the latest information about that topic and pass the information along with the ask to a LLM in order to generate a blog post that leverages the latest information.
 
-Semantic Kernel and .net provides an abstraction for interacting with Vector Stores and a list of out-of-the-box connectors that implement these abstractions. Features include creating, listing and deleting collections of records, and uploading, retrieving and deleting records. The abstraction makes it easy to experiment with a free or locally hosted Vector Store and then switch to a service when needing to scale up.
+Semantic Kernel and .net provides an abstraction for interacting with Vector Stores and a list of out-of-the-box implementations that implement these abstractions for various databases. Features include creating, listing and deleting collections of records, and uploading, retrieving and deleting records. The abstraction makes it easy to experiment with a free or locally hosted Vector Store and then switch to a service when needing to scale up.
+
+The out-of-the-box implementations can be used with Semantic Kernel, but do not depend on the core Semantic Kernel stack and can also therefore be used completely independently if required.
+The Semantic Kernel provided imlementations are referred to as 'connectors'.
 
 ::: zone pivot="programming-language-csharp"
 
 ## Retrieval Augmented Generation (RAG) with Vector Stores
 
-The vector store abstractions are a low level api for adding and retrieving data from vector stores.
+The vector store abstraction is a low level api for adding and retrieving data from vector stores.
 Semantic Kernel has built-in support for using any one of the Vector Store implementations for RAG.
 This is achieved by wrapping `IVectorSearchable<TRecord>` and exposing it as a Text Search implementation.
 
 > [!TIP]
 > To learn more about how to use vector stores for RAG see [How to use Vector Stores with Semantic Kernel Text Search](../text-search/text-search-vector-stores.md).
 > [!TIP]
 > To learn more about text search see [What is Semantic Kernel Text Search?](../text-search/index.md)
+> [!TIP]
+> To learn more about how to quickly add RAG into your agent see [Adding Retrieval Augmented Generation (RAG) to Semantic Kernel Agents](../../Frameworks/agent/agent-rag.md).
 
 ## The Vector Store Abstraction
 
-The main abstract base classes and interfaces in the Vector Store abstraction are the following.
+The Vector Store abstractions are provided in the [`Microsoft.Extensions.VectorData.Abstractions`](https://www.nuget.org/packages/Microsoft.Extensions.VectorData.Abstractions/) nuget package.
+The following are the main abstract base classes and interfaces.
 
 ### Microsoft.Extensions.VectorData.VectorStore
 
@@ -120,7 +126,7 @@ by select connectors.
 
 ::: zone-end
 
-## Getting started with Vector Store connectors
+## Getting started with Vector Stores
 
 ::: zone pivot="programming-language-csharp"
 
@@ -143,7 +149,7 @@ dotnet add package Microsoft.Extensions.VectorData.Abstractions
 
 ### Define your data model
 
-The Semantic Kernel Vector Store connectors use a model first approach to interacting with databases. This means that the first step is to define a data model that maps to the storage schema. To help the connectors create collections of records and map to the storage schema, the model can be annotated to indicate the function of each property.
+The Vector Store abstractions use a model first approach to interacting with databases. This means that the first step is to define a data model that maps to the storage schema. To help the implementations create collections of records and map to the storage schema, the model can be annotated to indicate the function of each property.
 
 ::: zone pivot="programming-language-csharp"
 
@@ -340,7 +346,7 @@ public class Main {
 ::: zone-end
 
 > [!TIP]
-> For more information on what key and field types each Vector Store connector supports, refer to [the documentation for each connector](./out-of-the-box-connectors/index.md).
+> For more information on what key and field types each Vector Store implementation supports, refer to [the documentation for each implementation](./out-of-the-box-connectors/index.md).
 
 ::: zone pivot="programming-language-csharp"