From e0be61601d5e6475d45ff79399bd4b3d22135e80 Mon Sep 17 00:00:00 2001
From: Chris <66376200+crickman@users.noreply.github.com>
Date: Wed, 24 Apr 2024 14:18:47 -0700
Subject: [PATCH] .Net - Agent Samples Restructure (#5987)

### Motivation and Context

<!-- Thank you for your contribution to the semantic-kernel repo!
Please help reviewers and future users, providing the following
information:
  1. Why is this change required?
  2. What problem does it solve?
  3. What scenario does it contribute to?
  4. If it fixes an open issue, please link to the issue here.
-->

Organize samples as part of restructuring.

### Description

<!-- Describe your changes, the overall approach, the underlying design.
These notes will help understanding how your code works. Thanks! -->

Added `Getting_Started` along with two functional areas:
`OpenAIAssistant` and `MixedAssistants`


![image](https://github.com/microsoft/semantic-kernel/assets/66376200/3bb9be12-5a54-4406-a175-2529a1fdbcf5)

### Contribution Checklist

<!-- Before submitting this PR, please make sure: -->

- [x] The code builds clean without any errors or warnings
- [x] The PR follows the [SK Contribution
Guidelines](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md)
and the [pre-submission formatting
script](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md#development-scripts)
raises no violations
- [x] All unit tests pass, and I have added new tests where possible
- [x] I didn't break anyone :smile:
---
 .../Concepts/AgentSyntax/AgentSyntax.csproj   |  4 ++
 .../samples/Concepts/AgentSyntax/BaseTest.cs  |  1 -
 .../AgentSyntax/Example11_OpenAIAssistant.cs  | 68 -------------------
 .../Step1_Agent.cs}                           |  5 +-
 .../Step2_Plugins.cs}                         |  5 +-
 .../Step3_Chat.cs}                            |  5 +-
 ...ple16_MixedChat.cs => MixedChat_Agents.cs} |  3 +-
 ...nt_Plugins.cs => OpenAIAssistant_Agent.cs} | 12 ++--
 ...Maker.cs => OpenAIAssistant_ChartMaker.cs} |  3 +-
 ....cs => OpenAIAssistant_CodeInterpreter.cs} |  3 +-
 ...rieval.cs => OpenAIAssistant_Retrieval.cs} |  3 +-
 11 files changed, 23 insertions(+), 89 deletions(-)
 delete mode 100644 dotnet/samples/Concepts/AgentSyntax/Example11_OpenAIAssistant.cs
 rename dotnet/samples/Concepts/AgentSyntax/{Example01_Agent.cs => Getting_Started/Step1_Agent.cs} (93%)
 rename dotnet/samples/Concepts/AgentSyntax/{Example02_Plugins.cs => Getting_Started/Step2_Plugins.cs} (95%)
 rename dotnet/samples/Concepts/AgentSyntax/{Example03_Chat.cs => Getting_Started/Step3_Chat.cs} (97%)
 rename dotnet/samples/Concepts/AgentSyntax/{Example16_MixedChat.cs => MixedChat_Agents.cs} (98%)
 rename dotnet/samples/Concepts/AgentSyntax/{Example12_OpenAIAssistant_Plugins.cs => OpenAIAssistant_Agent.cs} (85%)
 rename dotnet/samples/Concepts/AgentSyntax/{Example15_OpenAIAssistant_ChartMaker.cs => OpenAIAssistant_ChartMaker.cs} (96%)
 rename dotnet/samples/Concepts/AgentSyntax/{Example13_OpenAIAssistant_CodeInterpreter.cs => OpenAIAssistant_CodeInterpreter.cs} (94%)
 rename dotnet/samples/Concepts/AgentSyntax/{Example14_OpenAIAssistant_Retrieval.cs => OpenAIAssistant_Retrieval.cs} (96%)

diff --git a/dotnet/samples/Concepts/AgentSyntax/AgentSyntax.csproj b/dotnet/samples/Concepts/AgentSyntax/AgentSyntax.csproj
index 62e4cb49caa3..7f6111c23ef9 100644
--- a/dotnet/samples/Concepts/AgentSyntax/AgentSyntax.csproj
+++ b/dotnet/samples/Concepts/AgentSyntax/AgentSyntax.csproj
@@ -48,4 +48,8 @@
     </EmbeddedResource>
     <None Remove="Resources\*" />
   </ItemGroup>
+  <ItemGroup>
+    <Folder Include="MixedAgents\" />
+    <Folder Include="OpenAIAssistant\" />
+  </ItemGroup>
 </Project>
\ No newline at end of file
diff --git a/dotnet/samples/Concepts/AgentSyntax/BaseTest.cs b/dotnet/samples/Concepts/AgentSyntax/BaseTest.cs
index d8a521a7f3b0..96f967a55edc 100644
--- a/dotnet/samples/Concepts/AgentSyntax/BaseTest.cs
+++ b/dotnet/samples/Concepts/AgentSyntax/BaseTest.cs
@@ -1,5 +1,4 @@
 // Copyright (c) Microsoft. All rights reserved.
-
 using System.Reflection;
 using Configuration;
 using Microsoft.Extensions.Configuration;
diff --git a/dotnet/samples/Concepts/AgentSyntax/Example11_OpenAIAssistant.cs b/dotnet/samples/Concepts/AgentSyntax/Example11_OpenAIAssistant.cs
deleted file mode 100644
index 983c9d8d0547..000000000000
--- a/dotnet/samples/Concepts/AgentSyntax/Example11_OpenAIAssistant.cs
+++ /dev/null
@@ -1,68 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-using System.Threading.Tasks;
-using Microsoft.SemanticKernel;
-using Microsoft.SemanticKernel.Agents;
-using Microsoft.SemanticKernel.Agents.OpenAI;
-using Microsoft.SemanticKernel.ChatCompletion;
-using Xunit;
-using Xunit.Abstractions;
-
-namespace Examples;
-
-/// <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"/>.
-/// </remarks>
-public class Example11_OpenAIAssistant(ITestOutputHelper output) : BaseTest(output)
-{
-    private const string ParrotName = "Parrot";
-    private const string ParrotInstructions = "Repeat the user message in the voice of a pirate and then end with a parrot sound.";
-
-    [Fact]
-    public async Task RunAsync()
-    {
-        // Define the agent
-        OpenAIAssistantAgent agent =
-            await OpenAIAssistantAgent.CreateAsync(
-                kernel: this.CreateEmptyKernel(),
-                config: new(this.ApiKey, this.Endpoint),
-                definition: new()
-                {
-                    Instructions = ParrotInstructions,
-                    Name = ParrotName,
-                    ModelId = this.Model,
-                });
-
-        // Create a chat for agent interaction.
-        var chat = new AgentGroupChat();
-
-        // Respond to user input
-        try
-        {
-            await InvokeAgentAsync("Fortune favors the bold.");
-            await InvokeAgentAsync("I came, I saw, I conquered.");
-            await InvokeAgentAsync("Practice makes perfect.");
-        }
-        finally
-        {
-            await agent.DeleteAsync();
-        }
-
-        // Local function to invoke agent and display the conversation messages.
-        async Task InvokeAgentAsync(string input)
-        {
-            chat.AddChatMessage(new ChatMessageContent(AuthorRole.User, input));
-
-            this.WriteLine($"# {AuthorRole.User}: '{input}'");
-
-            await foreach (var content in chat.InvokeAsync(agent))
-            {
-                this.WriteLine($"# {content.Role} - {content.AuthorName ?? "*"}: '{content.Content}'");
-            }
-        }
-    }
-}
diff --git a/dotnet/samples/Concepts/AgentSyntax/Example01_Agent.cs b/dotnet/samples/Concepts/AgentSyntax/Getting_Started/Step1_Agent.cs
similarity index 93%
rename from dotnet/samples/Concepts/AgentSyntax/Example01_Agent.cs
rename to dotnet/samples/Concepts/AgentSyntax/Getting_Started/Step1_Agent.cs
index 17370ddc0265..eb2826de82c9 100644
--- a/dotnet/samples/Concepts/AgentSyntax/Example01_Agent.cs
+++ b/dotnet/samples/Concepts/AgentSyntax/Getting_Started/Step1_Agent.cs
@@ -1,18 +1,19 @@
 // Copyright (c) Microsoft. All rights reserved.
 using System.Threading.Tasks;
+using Examples;
 using Microsoft.SemanticKernel;
 using Microsoft.SemanticKernel.Agents;
 using Microsoft.SemanticKernel.ChatCompletion;
 using Xunit;
 using Xunit.Abstractions;
 
-namespace Examples;
+namespace GettingStarted;
 
 /// <summary>
 /// Demonstrate creation of <see cref="ChatCompletionAgent"/> and
 /// eliciting its response to three explicit user messages.
 /// </summary>
-public class Example01_Agent(ITestOutputHelper output) : BaseTest(output)
+public class Step1_Agent(ITestOutputHelper output) : BaseTest(output)
 {
     private const string ParrotName = "Parrot";
     private const string ParrotInstructions = "Repeat the user message in the voice of a pirate and then end with a parrot sound.";
diff --git a/dotnet/samples/Concepts/AgentSyntax/Example02_Plugins.cs b/dotnet/samples/Concepts/AgentSyntax/Getting_Started/Step2_Plugins.cs
similarity index 95%
rename from dotnet/samples/Concepts/AgentSyntax/Example02_Plugins.cs
rename to dotnet/samples/Concepts/AgentSyntax/Getting_Started/Step2_Plugins.cs
index 6e4910245350..ea99b955ee04 100644
--- a/dotnet/samples/Concepts/AgentSyntax/Example02_Plugins.cs
+++ b/dotnet/samples/Concepts/AgentSyntax/Getting_Started/Step2_Plugins.cs
@@ -1,5 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.
 using System.Threading.Tasks;
+using Examples;
 using Microsoft.SemanticKernel;
 using Microsoft.SemanticKernel.Agents;
 using Microsoft.SemanticKernel.ChatCompletion;
@@ -8,13 +9,13 @@
 using Xunit;
 using Xunit.Abstractions;
 
-namespace Examples;
+namespace GettingStarted;
 
 /// <summary>
 /// Demonstrate creation of <see cref="ChatCompletionAgent"/> with a <see cref="KernelPlugin"/>,
 /// and then eliciting its response to explicit user messages.
 /// </summary>
-public class Example02_Plugins(ITestOutputHelper output) : BaseTest(output)
+public class Step2_Plugins(ITestOutputHelper output) : BaseTest(output)
 {
     private const string HostName = "Host";
     private const string HostInstructions = "Answer questions about the menu.";
diff --git a/dotnet/samples/Concepts/AgentSyntax/Example03_Chat.cs b/dotnet/samples/Concepts/AgentSyntax/Getting_Started/Step3_Chat.cs
similarity index 97%
rename from dotnet/samples/Concepts/AgentSyntax/Example03_Chat.cs
rename to dotnet/samples/Concepts/AgentSyntax/Getting_Started/Step3_Chat.cs
index 6bbe5fb2c741..687f0101f473 100644
--- a/dotnet/samples/Concepts/AgentSyntax/Example03_Chat.cs
+++ b/dotnet/samples/Concepts/AgentSyntax/Getting_Started/Step3_Chat.cs
@@ -3,6 +3,7 @@
 using System.Collections.Generic;
 using System.Threading;
 using System.Threading.Tasks;
+using Examples;
 using Microsoft.SemanticKernel;
 using Microsoft.SemanticKernel.Agents;
 using Microsoft.SemanticKernel.Agents.Chat;
@@ -10,14 +11,14 @@
 using Xunit;
 using Xunit.Abstractions;
 
-namespace Examples;
+namespace GettingStarted;
 
 /// <summary>
 /// Demonstrate creation of <see cref="AgentChat"/> with <see cref="AgentGroupChatSettings"/>
 /// that inform how chat proceeds with regards to: Agent selection, chat continuation, and maximum
 /// number of agent interactions.
 /// </summary>
-public class Example03_Chat(ITestOutputHelper output) : BaseTest(output)
+public class Step3_Chat(ITestOutputHelper output) : BaseTest(output)
 {
     private const string ReviewerName = "ArtDirector";
     private const string ReviewerInstructions =
diff --git a/dotnet/samples/Concepts/AgentSyntax/Example16_MixedChat.cs b/dotnet/samples/Concepts/AgentSyntax/MixedChat_Agents.cs
similarity index 98%
rename from dotnet/samples/Concepts/AgentSyntax/Example16_MixedChat.cs
rename to dotnet/samples/Concepts/AgentSyntax/MixedChat_Agents.cs
index 916e72c97719..c378078024b0 100644
--- a/dotnet/samples/Concepts/AgentSyntax/Example16_MixedChat.cs
+++ b/dotnet/samples/Concepts/AgentSyntax/MixedChat_Agents.cs
@@ -12,12 +12,11 @@
 using Xunit.Abstractions;
 
 namespace Examples;
-
 /// <summary>
 /// Demonstrate that two different agent types are able to participate in the same conversation.
 /// In this case a <see cref="ChatCompletionAgent"/> and <see cref="OpenAIAssistantAgent"/> participate.
 /// </summary>
-public class Example16_MixedChat(ITestOutputHelper output) : BaseTest(output)
+public class MixedChat_Agents(ITestOutputHelper output) : BaseTest(output)
 {
     private const string ReviewerName = "ArtDirector";
     private const string ReviewerInstructions =
diff --git a/dotnet/samples/Concepts/AgentSyntax/Example12_OpenAIAssistant_Plugins.cs b/dotnet/samples/Concepts/AgentSyntax/OpenAIAssistant_Agent.cs
similarity index 85%
rename from dotnet/samples/Concepts/AgentSyntax/Example12_OpenAIAssistant_Plugins.cs
rename to dotnet/samples/Concepts/AgentSyntax/OpenAIAssistant_Agent.cs
index 22172b8afb90..f12793bf99f9 100644
--- a/dotnet/samples/Concepts/AgentSyntax/Example12_OpenAIAssistant_Plugins.cs
+++ b/dotnet/samples/Concepts/AgentSyntax/OpenAIAssistant_Agent.cs
@@ -9,16 +9,16 @@
 using Xunit.Abstractions;
 
 namespace Examples;
-
 /// <summary>
-/// Demonstrate creation of <see cref="OpenAIAssistantAgent"/> with a <see cref="KernelPlugin"/>,
-/// and then eliciting its response to explicit user messages.
+/// 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), plugin
-/// usage for <see cref="OpenAIAssistantAgent"/> is no different from <see cref="ChatCompletionAgent"/>.
+/// 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 Example12_OpenAIAssistant_Plugins(ITestOutputHelper output) : BaseTest(output)
+public class OpenAIAssistant_Agent(ITestOutputHelper output) : BaseTest(output)
 {
     private const string HostName = "Host";
     private const string HostInstructions = "Answer questions about the menu.";
diff --git a/dotnet/samples/Concepts/AgentSyntax/Example15_OpenAIAssistant_ChartMaker.cs b/dotnet/samples/Concepts/AgentSyntax/OpenAIAssistant_ChartMaker.cs
similarity index 96%
rename from dotnet/samples/Concepts/AgentSyntax/Example15_OpenAIAssistant_ChartMaker.cs
rename to dotnet/samples/Concepts/AgentSyntax/OpenAIAssistant_ChartMaker.cs
index 380a491bae23..a073b6f2610c 100644
--- a/dotnet/samples/Concepts/AgentSyntax/Example15_OpenAIAssistant_ChartMaker.cs
+++ b/dotnet/samples/Concepts/AgentSyntax/OpenAIAssistant_ChartMaker.cs
@@ -9,12 +9,11 @@
 using Xunit.Abstractions;
 
 namespace Examples;
-
 /// <summary>
 /// Demonstrate using code-interpreter with <see cref="OpenAIAssistantAgent"/> to
 /// produce image content displays the requested charts.
 /// </summary>
-public class Example15_OpenAIAssistant_ChartMaker(ITestOutputHelper output) : BaseTest(output)
+public class OpenAIAssistant_ChartMaker(ITestOutputHelper output) : BaseTest(output)
 {
     /// <summary>
     /// Target Open AI services.
diff --git a/dotnet/samples/Concepts/AgentSyntax/Example13_OpenAIAssistant_CodeInterpreter.cs b/dotnet/samples/Concepts/AgentSyntax/OpenAIAssistant_CodeInterpreter.cs
similarity index 94%
rename from dotnet/samples/Concepts/AgentSyntax/Example13_OpenAIAssistant_CodeInterpreter.cs
rename to dotnet/samples/Concepts/AgentSyntax/OpenAIAssistant_CodeInterpreter.cs
index 273d40331d68..77a72eb94180 100644
--- a/dotnet/samples/Concepts/AgentSyntax/Example13_OpenAIAssistant_CodeInterpreter.cs
+++ b/dotnet/samples/Concepts/AgentSyntax/OpenAIAssistant_CodeInterpreter.cs
@@ -8,11 +8,10 @@
 using Xunit.Abstractions;
 
 namespace Examples;
-
 /// <summary>
 /// Demonstrate using code-interpreter on <see cref="OpenAIAssistantAgent"/> .
 /// </summary>
-public class Example13_OpenAIAssistant_CodeInterpreter(ITestOutputHelper output) : BaseTest(output)
+public class OpenAIAssistant_CodeInterpreter(ITestOutputHelper output) : BaseTest(output)
 {
     [Fact]
     public async Task RunAsync()
diff --git a/dotnet/samples/Concepts/AgentSyntax/Example14_OpenAIAssistant_Retrieval.cs b/dotnet/samples/Concepts/AgentSyntax/OpenAIAssistant_Retrieval.cs
similarity index 96%
rename from dotnet/samples/Concepts/AgentSyntax/Example14_OpenAIAssistant_Retrieval.cs
rename to dotnet/samples/Concepts/AgentSyntax/OpenAIAssistant_Retrieval.cs
index 43130c796254..a58d9cc43aa3 100644
--- a/dotnet/samples/Concepts/AgentSyntax/Example14_OpenAIAssistant_Retrieval.cs
+++ b/dotnet/samples/Concepts/AgentSyntax/OpenAIAssistant_Retrieval.cs
@@ -11,11 +11,10 @@
 using Xunit.Abstractions;
 
 namespace Examples;
-
 /// <summary>
 /// Demonstrate using retrieval on <see cref="OpenAIAssistantAgent"/> .
 /// </summary>
-public class Example14_OpenAIAssistant_Retrieval(ITestOutputHelper output) : BaseTest(output)
+public class OpenAIAssistant_Retrieval(ITestOutputHelper output) : BaseTest(output)
 {
     /// <summary>
     /// Retrieval tool not supported on Azure OpenAI.