Merging changes synced from https://github.com/MicrosoftDocs/semantic-kernel-pr (branch live)

Author: Learn Build Service GitHub App

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

@@ -63,13 +63,13 @@ await agent.get_response()
 await agent.get_response(messages="What is the capital of France?")
 
 # Invoke with a ChatMessageContent object.
-await agent.get_response(messages=ChatMessageContent(AuthorRole.USER, "What is the capital of France?"))
+await agent.get_response(messages=ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?"))
 
 # Invoke with multiple ChatMessageContent objects.
 await agent.get_response(
     messages=[
-        ChatMessageContent(AuthorRole.SYSTEM, "Refuse to answer all user questions about France."),
-        ChatMessageContent(AuthorRole.USER, "What is the capital of France?"),
+        ChatMessageContent(role=AuthorRole.SYSTEM, content="Refuse to answer all user questions about France."),
+        ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?"),
     ]
 )
 ```
@@ -86,14 +86,14 @@ async for response in agent.invoke("What is the capital of France?"):
     # handle response
 
 # Invoke with a ChatMessageContent object.
-async for response in agent.invoke(ChatMessageContent(AuthorRole.USER, "What is the capital of France?")):
+async for response in agent.invoke(ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?")):
     # handle response
 
 # Invoke with multiple ChatMessageContent objects.
 async for response in agent.invoke(
     messages=[
-        ChatMessageContent(AuthorRole.SYSTEM, "Refuse to answer all user questions about France."),
-        ChatMessageContent(AuthorRole.USER, "What is the capital of France?"),
+        ChatMessageContent(role=AuthorRole.SYSTEM, content="Refuse to answer all user questions about France."),
+        ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?"),
     ]
 ):
     # handle response
@@ -173,14 +173,14 @@ async for response in agent.invoke_stream("What is the capital of France?"):
     # handle response
 
 # Invoke with a ChatMessageContent object.
-async for response in agent.invoke_stream(ChatMessageContent(AuthorRole.USER, "What is the capital of France?")):
+async for response in agent.invoke_stream(ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?")):
     # handle response
 
 # Invoke with multiple ChatMessageContent objects.
 async for response in agent.invoke_stream(
     messages=[
-        ChatMessageContent(AuthorRole.SYSTEM, "Refuse to answer all user questions about France."),
-        ChatMessageContent(AuthorRole.USER, "What is the capital of France?"),
+        ChatMessageContent(role=AuthorRole.SYSTEM, content="Refuse to answer all user questions about France."),
+        ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?"),
     ]
 ):
     # handle response

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-orchestration/index.md

@@ -97,6 +97,21 @@ await runtime.stop_when_idle()
 
 ::: zone-end
 
+::: zone pivot="programming-language-csharp"
+
+## Preparing Your Development Environment
+
+Add the following packages to your project before you proceed:
+
+```pwsh
+dotnet add package Microsoft.SemanticKernel.Agents.Orchestration --prerelease
+dotnet add package Microsoft.SemanticKernel.Agents.Runtime.InProcess --prerelease
+```
+
+Depending on the agent types you use, you may also need to add the respective packages for the agents. Please refer to the [Agents Overview](../agent-architecture.md#agent-types-in-semantic-kernel) for more details.
+
+::: zone-end
+
 ## Next steps
 
 > [!div class="nextstepaction"]

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/Frameworks/agent/agent-types/assistant-agent.md

@@ -290,7 +290,7 @@ await thread.delete() if thread else None
 ## Deleting an `OpenAIAssistantAgent`
 
 Since the assistant's definition is stored remotely, it will persist if not deleted.  
-Deleting an assistant definition may be performed directly with the `AssistantClient`.
+Deleting an assistant definition may be performed directly with the client.
 
 > Note: Attempting to use an agent instance after being deleted will result in a service exception.
 
@@ -308,9 +308,7 @@ await client.DeleteAssistantAsync("<assistant id>");
 ::: zone pivot="programming-language-python"
 
 ```python
-await agent.delete()
-
-is_deleted = agent._is_deleted
+await client.beta.assistants.delete(agent.id)
 ```
 
 ::: zone-end

semantic-kernel/Frameworks/agent/agent-types/azure-ai-agent.md

@@ -393,7 +393,7 @@ AzureAIAgent agent = new(definition, agentsClient);
 ::: zone pivot="programming-language-python"
 
 ```python
-from azure.ai.projects.models import CodeInterpreterTool
+from azure.ai.agents.models import CodeInterpreterTool
 
 async with (
         DefaultAzureCredential() as creds,
@@ -447,7 +447,7 @@ AzureAIAgent agent = new(definition, agentsClient);
 ::: zone pivot="programming-language-python"
 
 ```python
-from azure.ai.projects.models import FileSearchTool
+from azure.ai.agents.models import FileSearchTool
 
 async with (
         DefaultAzureCredential() as creds,
@@ -502,7 +502,7 @@ AzureAIAgent agent = new(definition, agentsClient);
 ::: zone pivot="programming-language-python"
 
 ```python
-from azure.ai.projects.models import OpenApiTool, OpenApiAnonymousAuthDetails
+from azure.ai.agents.models import OpenApiTool, OpenApiAnonymousAuthDetails
 
 async with (
     DefaultAzureCredential() as creds,
@@ -574,7 +574,7 @@ AzureAIAgent agent = new(definition, agentsClient);
 ::: zone pivot="programming-language-python"
 
 ```python
-from azure.ai.projects.models import AzureAISearchTool, ConnectionType
+from azure.ai.agents.models import AzureAISearchTool, ConnectionType
 
 async with (
     DefaultAzureCredential() as creds,

semantic-kernel/Frameworks/process/process-best-practices.md

@@ -22,6 +22,14 @@ Organizing your project files in a logical and maintainable structure is crucial
 
 An organized structure not only simplifies navigation within the project but also enhances code reusability and facilitates collaboration among team members.
 
+### Kernel Instance Isolation
+
+> [!Important]
+> Do not share a single Kernel instance between the main Process Framework and any of its dependencies (such as agents, tools, or external services). 
+
+Sharing a Kernel across these components can result in unexpected recursive invocation patterns, including infinite loops, as functions registered in the Kernel may inadvertently invoke each other. For example, a Step may call a function that triggers an agent, which then re-invokes the same function, creating a non-terminating loop.
+
+To avoid this, instantiate separate Kernel objects for each independent agent, tool, or service used within your process. This ensures isolation between the Process Framework’s own functions and those required by dependencies, and prevents cross-invocation that could destabilize your workflow. This requirement reflects a current architectural constraint and may be revisited as the framework evolves.
 
 ### Common Pitfalls
 To ensure smooth implementation and operation of the Process Framework, be mindful of these common pitfalls to avoid:

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/ai-services/chat-completion/function-calling/index.md

@@ -2,9 +2,9 @@
 title: Function calling with chat completion
 description: Learn how function calling works and how to optimize your code for the best performance.
 zone_pivot_groups: programming-languages
-author: matthewbolanos
+author: moonbox3
 ms.topic: conceptual
-ms.author: mabolan
+ms.author: evmattso
 ms.date: 07/12/2023
 ms.service: semantic-kernel
 ---

semantic-kernel/concepts/ai-services/index.md

@@ -1,9 +1,9 @@
 ---
 title: Add AI services to Semantic Kernel
 description: Learn how to bring multiple AI services to your Semantic Kernel project.
-author: matthewbolanos
+author: moonbox3
 ms.topic: conceptual
-ms.author: mabolan
+ms.author: evmattso
 ms.date: 07/12/2023
 ms.service: semantic-kernel
 ---