.Net - Update Agent Readme

dotnet/samples/Concepts/Agents/ComplexChat_NestedShopper.cs

@@ -96,7 +96,7 @@ Select which participant will take the next turn based on the conversation histo
     [Fact]
     public async Task RunAsync()
     {
-        this.WriteLine($"! {Model}");
+        Console.WriteLine($"! {Model}");
 
         OpenAIPromptExecutionSettings jsonSettings = new() { ResponseFormat = ChatCompletionsResponseFormat.JsonObject };
         OpenAIPromptExecutionSettings autoInvokeSettings = new() { ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions };
@@ -137,9 +137,9 @@ public async Task RunAsync()
             };
 
         // Invoke chat and display messages.
-        this.WriteLine("\n######################################");
-        this.WriteLine("# DYNAMIC CHAT");
-        this.WriteLine("######################################");
+        Console.WriteLine("\n######################################");
+        Console.WriteLine("# DYNAMIC CHAT");
+        Console.WriteLine("######################################");
 
         await InvokeChatAsync("Can you provide three original birthday gift ideas.  I don't want a gift that someone else will also pick.");
 
@@ -150,27 +150,27 @@ public async Task RunAsync()
             await InvokeChatAsync("He likes photography.");
         }
 
-        this.WriteLine("\n\n>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>");
-        this.WriteLine(">>>> AGGREGATED CHAT");
-        this.WriteLine(">>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>");
+        Console.WriteLine("\n\n>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>");
+        Console.WriteLine(">>>> AGGREGATED CHAT");
+        Console.WriteLine(">>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>");
 
         await foreach (var content in chat.GetChatMessagesAsync(personalShopperAgent).Reverse())
         {
-            this.WriteLine($">>>> {content.Role} - {content.AuthorName ?? "*"}: '{content.Content}'");
+            Console.WriteLine($">>>> {content.Role} - {content.AuthorName ?? "*"}: '{content.Content}'");
         }
 
         async Task InvokeChatAsync(string input)
         {
             chat.AddChatMessage(new ChatMessageContent(AuthorRole.User, input));
 
-            this.WriteLine($"# {AuthorRole.User}: '{input}'");
+            Console.WriteLine($"# {AuthorRole.User}: '{input}'");
 
             await foreach (var content in chat.InvokeAsync(personalShopperAgent))
             {
-                this.WriteLine($"# {content.Role} - {content.AuthorName ?? "*"}: '{content.Content}'");
+                Console.WriteLine($"# {content.Role} - {content.AuthorName ?? "*"}: '{content.Content}'");
             }
 
-            this.WriteLine($"\n# IS COMPLETE: {chat.IsComplete}");
+            Console.WriteLine($"\n# IS COMPLETE: {chat.IsComplete}");
         }
 
         ChatCompletionAgent CreateAgent(string agentName, string agentInstructions) =>
@@ -198,7 +198,7 @@ AgentGroupChat CreateChat() =>
                                             string? agentName = string.IsNullOrWhiteSpace(jsonResult?.name) ? null : jsonResult?.name;
                                             agentName ??= InternalGiftIdeaAgentName;
 
-                                            this.WriteLine($"\t>>>> INNER TURN: {agentName}");
+                                            Console.WriteLine($"\t>>>> INNER TURN: {agentName}");
 
                                             return agentName;
                                         }

dotnet/samples/Concepts/Agents/README.md

@@ -1,36 +1,89 @@
 # Semantic Kernel: Agent syntax examples
+This project contains a collection of examples on how to use _Semantic Kernel Agents_.
 
-This project contains a collection of examples on how to use SK Agents.
+#### NuGet:
+- [Microsoft.SemanticKernel.Agents.Abstractions](https://www.nuget.org/packages/Microsoft.SemanticKernel.Agents.Abstractions)
+- [Microsoft.SemanticKernel.Agents.Core](https://www.nuget.org/packages/Microsoft.SemanticKernel.Agents.Core)
+- [Microsoft.SemanticKernel.Agents.OpenAI](https://www.nuget.org/packages/Microsoft.SemanticKernel.Agents.OpenAI)
+
+#### Source
+- [Semantic Kernel Agent Framework](https://github.com/microsoft/semantic-kernel/tree/main/dotnet/src/Agents)
 
 The examples can be run as integration tests but their code can also be copied to stand-alone programs.
 
-## Running Examples with Filters
+## Examples
 
-You can run specific examples in the KernelSyntaxExamples project by using test filters (dotnet test --filter).
-Type "dotnet test --help" at the command line for more details.
+The concept agents examples are grouped by prefix:
 
-## Configuring Secrets
+Prefix|Description
+---|---
+OpenAIAssistant|How to use agents based on the [Open AI Assistant API](https://platform.openai.com/docs/assistants).
+MixedChat|How to combine different agent types.
+ComplexChat|How to deveop complex agent chat solutions.
+Legacy|How to use the legacy _Experimental Agent API_.
+
+## Legacy Agents
 
-Most of the examples will require secrets and credentials, to access OpenAI, Azure OpenAI,
-Bing and other resources. We suggest using .NET
-[Secret Manager](https://learn.microsoft.com/en-us/aspnet/core/security/app-secrets)
-to avoid the risk of leaking secrets into the repository, branches and pull requests.
-You can also use environment variables if you prefer.
+Support for the OpenAI Assistant API was originally published in `Microsoft.SemanticKernel.Experimental.Agents` package:
+[Microsoft.SemanticKernel.Experimental.Agents](https://github.com/microsoft/semantic-kernel/tree/main/dotnet/src/Experimental/Agents)
 
-To set your secrets with Secret Manager:
+This package has been superseded by _Semantic Kernel Agents_, which includes support for Open AI Assistant agents.
 
+## Running Examples
+Examples may be explored and ran within _Visual Studio_ using _Test Explorer_.
+
+You can also run specific examples via the command-line by using test filters (`dotnet test --filter`). Type `dotnet test --help` at the command line for more details.
+
+Example:
+
+```
+dotnet test --filter OpenAIAssistant_CodeInterpreter
 ```
-cd dotnet/samples/AgentSyntaxExamples
 
-dotnet user-secrets init
+## Configuring Secrets
 
-dotnet user-secrets set "OpenAI:ChatModelId" "..."
-dotnet user-secrets set "OpenAI:ApiKey" "..."
+Each example requires secrets / credentials to access OpenAI or Azure OpenAI.
 
-dotnet user-secrets set "AzureOpenAI:DeploymentName" "..."
-dotnet user-secrets set "AzureOpenAI:ChatDeploymentName" "..."
-dotnet user-secrets set "AzureOpenAI:Endpoint" "https://... .openai.azure.com/"
-dotnet user-secrets set "AzureOpenAI:ApiKey" "..."
+We suggest using .NET [Secret Manager](https://learn.microsoft.com/en-us/aspnet/core/security/app-secrets) to avoid the risk of leaking secrets into the repository, branches and pull requests. You can also use environment variables if you prefer.
 
-```
+To set your secrets with .NET Secret Manager:
+
+1. Navigate the console to the project folder:
+
+    ```
+    cd dotnet/samples/GettingStartedWithAgents
+    ```
+
+2. Examine existing secret definitions:
 
+    ```
+    dotnet user-secrets list
+    ```
+
+3. If needed, perform first time initialization:
+
+    ```
+    dotnet user-secrets init
+    ```
+
+4. Define secrets for either Open AI:
+
+    ```
+    dotnet user-secrets set "OpenAI:ChatModelId" "..."
+    dotnet user-secrets set "OpenAI:ApiKey" "..."
+    ```
+
+5. Or Azure Open AI:
+
+    ```
+    dotnet user-secrets set "AzureOpenAI:DeploymentName" "..."
+    dotnet user-secrets set "AzureOpenAI:ChatDeploymentName" "..."
+    dotnet user-secrets set "AzureOpenAI:Endpoint" "https://... .openai.azure.com/"
+    dotnet user-secrets set "AzureOpenAI:ApiKey" "..."
+    ```
+
+> NOTE: Azure secrets will take precedence, if both Open AI and Azure Open AI secrets are defined, unless `ForceOpenAI` is set:
+
+```
+protected override bool ForceOpenAI => true;
+```

dotnet/samples/GettingStartedWithAgents/GettingStartedWithAgents.csproj

@@ -37,6 +37,7 @@
 
   <ItemGroup>
     <ProjectReference Include="..\..\src\Agents\Core\Agents.Core.csproj" />
+    <ProjectReference Include="..\..\src\Agents\OpenAI\Agents.OpenAI.csproj" />
     <ProjectReference Include="..\..\src\Connectors\Connectors.OpenAI\Connectors.OpenAI.csproj" />
     <ProjectReference Include="..\..\src\SemanticKernel.Abstractions\SemanticKernel.Abstractions.csproj" />
     <ProjectReference Include="..\..\src\SemanticKernel.Core\SemanticKernel.Core.csproj" />

dotnet/samples/GettingStartedWithAgents/README.md

@@ -1,35 +1,95 @@
 # Semantic Kernel Agents - Getting Started
 
-This project contains a collection of examples on how to use SK Agents.
+This project contains a step by step guide to get started with  _Semantic Kernel Agents_.
+
+
+#### NuGet:
+- [Microsoft.SemanticKernel.Agents.Abstractions](https://www.nuget.org/packages/Microsoft.SemanticKernel.Agents.Abstractions)
+- [Microsoft.SemanticKernel.Agents.Core](https://www.nuget.org/packages/Microsoft.SemanticKernel.Agents.Core)
+- [Microsoft.SemanticKernel.Agents.OpenAI](https://www.nuget.org/packages/Microsoft.SemanticKernel.Agents.OpenAI)
+
+#### Source
+- [Semantic Kernel Agent Framework](https://github.com/microsoft/semantic-kernel/tree/main/dotnet/src/Agents)
 
 The examples can be run as integration tests but their code can also be copied to stand-alone programs.
 
+## Examples
+
+The getting started with agents examples include:
+
+Example|Description
+---|---
+[Step1_Agent](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/GettingStartedWithAgents/Step1_Agent.cs)|How to create and use an agent.
+[Step2_Plugins](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/GettingStartedWithAgents/Step2_Plugins.cs)|How to associate plug-ins with an agent.
+[Step3_Chat](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/GettingStartedWithAgents/Step3_Chat.cs)|How to create a conversation between agents.
+[Step4_KernelFunctionStrategies](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Step4_KernelFunctionStrategies/Step1_Agent.cs)|How to utilize a `KernelFunction` as a _chat strategy_.
+[Step5_JsonResult](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/GettingStartedWithAgents/Step5_JsonResult.cs)|How to have an agent produce JSON.
+[Step6_DependencyInjection](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/GettingStartedWithAgents/Step6_DependencyInjection.cs)|How to define dependency injection patterns for agents.
+[Step7_OpenAIAssistant](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/GettingStartedWithAgents/Step7_OpenAIAssistant.cs)|How to create an Open AI Assistant agent.
+
+## Legacy Agents
+
+Support for the OpenAI Assistant API was originally published in `Microsoft.SemanticKernel.Experimental.Agents` package:
+[Microsoft.SemanticKernel.Experimental.Agents](https://github.com/microsoft/semantic-kernel/tree/main/dotnet/src/Experimental/Agents)
+
+This package has been superseded by _Semantic Kernel Agents_, which includes support for Open AI Assistant agents.
+
+
 ## Running Examples with Filters
+Examples may be explored and ran within _Visual Studio_ using _Test Explorer_.
+
+You can also run specific examples via the command-line by using test filters (`dotnet test --filter`). Type `dotnet test --help` at the command line for more details.
+
+Example:
 
-You can run specific examples in the project by using test filters (dotnet test --filter).
-Type "dotnet test --help" at the command line for more details.
+```
+dotnet test --filter Step3_Chat
+```
 
 ## Configuring Secrets
 
-Most of the examples will require secrets and credentials, to access OpenAI, Azure OpenAI,
-Bing and other resources. We suggest using .NET
-[Secret Manager](https://learn.microsoft.com/en-us/aspnet/core/security/app-secrets)
-to avoid the risk of leaking secrets into the repository, branches and pull requests.
-You can also use environment variables if you prefer.
+Each example requires secrets / credentials to access OpenAI or Azure OpenAI.
 
-To set your secrets with Secret Manager:
+We suggest using .NET [Secret Manager](https://learn.microsoft.com/en-us/aspnet/core/security/app-secrets) to avoid the risk of leaking secrets into the repository, branches and pull requests. You can also use environment variables if you prefer.
 
-```
-cd dotnet/samples/AgentSyntaxExamples
+To set your secrets with .NET Secret Manager:
+
+1. Navigate the console to the project folder:
+
+    ```
+    cd dotnet/samples/GettingStartedWithAgents
+    ```
+
+2. Examine existing secret definitions:
 
-dotnet user-secrets init
+    ```
+    dotnet user-secrets list
+    ```
 
-dotnet user-secrets set "OpenAI:ChatModelId" "..."
-dotnet user-secrets set "OpenAI:ApiKey" "..."
+3. If needed, perform first time initialization:
 
-dotnet user-secrets set "AzureOpenAI:DeploymentName" "..."
-dotnet user-secrets set "AzureOpenAI:ChatDeploymentName" "..."
-dotnet user-secrets set "AzureOpenAI:Endpoint" "https://... .openai.azure.com/"
-dotnet user-secrets set "AzureOpenAI:ApiKey" "..."
+    ```
+    dotnet user-secrets init
+    ```
 
+4. Define secrets for either Open AI:
+
+    ```
+    dotnet user-secrets set "OpenAI:ChatModelId" "..."
+    dotnet user-secrets set "OpenAI:ApiKey" "..."
+    ```
+
+5. Or Azure Open AI:
+
+    ```
+    dotnet user-secrets set "AzureOpenAI:DeploymentName" "..."
+    dotnet user-secrets set "AzureOpenAI:ChatDeploymentName" "..."
+    dotnet user-secrets set "AzureOpenAI:Endpoint" "https://... .openai.azure.com/"
+    dotnet user-secrets set "AzureOpenAI:ApiKey" "..."
+    ```
+
+> NOTE: Azure secrets will take precedence, if both Open AI and Azure Open AI secrets are defined, unless `ForceOpenAI` is set:
+
+```
+protected override bool ForceOpenAI => true;
 ```

dotnet/samples/GettingStartedWithAgents/Step6_DependencyInjection.cs

@@ -80,11 +80,11 @@ public async Task RunAsync()
         // Local function to invoke agent and display the conversation messages.
         async Task WriteAgentResponse(string input)
         {
-            this.WriteLine($"# {AuthorRole.User}: {input}");
+            Console.WriteLine($"# {AuthorRole.User}: {input}");
 
             await foreach (var content in agentClient.RunDemoAsync(input))
             {
-                this.WriteLine($"# {content.Role} - {content.AuthorName ?? "*"}: '{content.Content}'");
+                Console.WriteLine($"# {content.Role} - {content.AuthorName ?? "*"}: '{content.Content}'");
             }
         }
     }

dotnet/samples/Concepts/Agents/OpenAIAssistant_Agent.cs → dotnet/samples/GettingStartedWithAgents/Step7_OpenAIAssistant.cs

@@ -1,21 +1,18 @@
 // Copyright (c) Microsoft. All rights reserved.
+using System.ComponentModel;
 using Microsoft.SemanticKernel;
 using Microsoft.SemanticKernel.Agents;
 using Microsoft.SemanticKernel.Agents.OpenAI;
 using Microsoft.SemanticKernel.ChatCompletion;
-using Plugins;
 
-namespace Agents;
+namespace GettingStarted;
+
 /// <summary>
-/// Demonstrate creation of <see cref="OpenAIAssistantAgent"/> and
-/// eliciting its response to three explicit user messages.
-/// </summary>
-/// <remarks>
 /// This example demonstrates that outside of initialization (and cleanup), using
 /// <see cref="OpenAIAssistantAgent"/> is no different from <see cref="ChatCompletionAgent"/>
 /// even with with a <see cref="KernelPlugin"/>.
-/// </remarks>
-public class OpenAIAssistant_Agent(ITestOutputHelper output) : BaseTest(output)
+/// </summary>
+public class Step7_OpenAIAssistant(ITestOutputHelper output) : BaseTest(output)
 {
     private const string HostName = "Host";
     private const string HostInstructions = "Answer questions about the menu.";
@@ -68,4 +65,32 @@ async Task InvokeAgentAsync(string input)
             }
         }
     }
+
+    private sealed class MenuPlugin
+    {
+        public const string CorrelationIdArgument = "correlationId";
+
+        private readonly List<string> _correlationIds = [];
+
+        public IReadOnlyList<string> CorrelationIds => this._correlationIds;
+
+        [KernelFunction, Description("Provides a list of specials from the menu.")]
+        [System.Diagnostics.CodeAnalysis.SuppressMessage("Design", "CA1024:Use properties where appropriate", Justification = "Too smart")]
+        public string GetSpecials()
+        {
+            return @"
+Special Soup: Clam Chowder
+Special Salad: Cobb Salad
+Special Drink: Chai Tea
+";
+        }
+
+        [KernelFunction, Description("Provides the price of the requested menu item.")]
+        public string GetItemPrice(
+            [Description("The name of the menu item.")]
+            string menuItem)
+        {
+            return "$9.99";
+        }
+    }
 }