.Net - Introducing AgentGroupChat (Step #2)

dotnet/samples/AgentSyntaxExamples/Example01_Agent.cs

@@ -1,6 +1,4 @@
 // Copyright (c) Microsoft. All rights reserved.
-using System.Collections.Generic;
-using System.Threading;
 using System.Threading.Tasks;
 using Microsoft.SemanticKernel;
 using Microsoft.SemanticKernel.Agents;
@@ -32,7 +30,7 @@ public async Task RunAsync()
             };
 
         // Create a chat for agent interaction. For more, see: Example03_Chat.
-        var chat = new TestChat();
+        AgentGroupChat chat = new();
 
         // Respond to user input
         await InvokeAgentAsync("Fortune favors the bold.");
@@ -52,18 +50,4 @@ async Task InvokeAgentAsync(string input)
             }
         }
     }
-
-    /// <summary>
-    /// A simple chat for the agent example.
-    /// </summary>
-    /// <remarks>
-    /// For further exploration of <see cref="AgentChat"/>, see: Example03_Chat.
-    /// </remarks>
-    private sealed class TestChat : AgentChat
-    {
-        public IAsyncEnumerable<ChatMessageContent> InvokeAsync(
-            Agent agent,
-            CancellationToken cancellationToken = default) =>
-                base.InvokeAgentAsync(agent, cancellationToken);
-    }
 }

dotnet/samples/AgentSyntaxExamples/Example02_Plugins.cs

@@ -1,6 +1,4 @@
 // Copyright (c) Microsoft. All rights reserved.
-using System.Collections.Generic;
-using System.Threading;
 using System.Threading.Tasks;
 using Microsoft.SemanticKernel;
 using Microsoft.SemanticKernel.Agents;
@@ -39,7 +37,7 @@ public async Task RunAsync()
         agent.Kernel.Plugins.Add(plugin);
 
         // Create a chat for agent interaction. For more, see: Example03_Chat.
-        var chat = new TestChat();
+        AgentGroupChat chat = new();
 
         // Respond to user input, invoking functions where appropriate.
         await InvokeAgentAsync("Hello");
@@ -59,19 +57,4 @@ async Task InvokeAgentAsync(string input)
             }
         }
     }
-
-    /// <summary>
-    ///
-    /// A simple chat for the agent example.
-    /// </summary>
-    /// <remarks>
-    /// For further exploration of <see cref="AgentChat"/>, see: Example03_Chat.
-    /// </remarks>
-    private sealed class TestChat : AgentChat
-    {
-        public IAsyncEnumerable<ChatMessageContent> InvokeAsync(
-            Agent agent,
-            CancellationToken cancellationToken = default) =>
-                base.InvokeAgentAsync(agent, cancellationToken);
-    }
 }

dotnet/samples/AgentSyntaxExamples/Example03_Chat.cs

@@ -0,0 +1,97 @@
+// Copyright (c) Microsoft. All rights reserved.
+using System;
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.Agents;
+using Microsoft.SemanticKernel.Agents.Chat;
+using Microsoft.SemanticKernel.ChatCompletion;
+using Xunit;
+using Xunit.Abstractions;
+
+namespace Examples;
+
+/// <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)
+{
+    private const string ReviewerName = "ArtDirector";
+    private const string ReviewerInstructions =
+        """
+        You are an art director who has opinions about copywriting born of a love for David Ogilvy.
+        The goal is to determine is the given copy is acceptable to print.
+        If so, state that it is approved.
+        If not, provide insight on how to refine suggested copy without example.
+        """;
+
+    private const string CopyWriterName = "Writer";
+    private const string CopyWriterInstructions =
+        """
+        You are a copywriter with ten years of experience and are known for brevity and a dry humor.
+        You're laser focused on the goal at hand. Don't waste time with chit chat.
+        The goal is to refine and decide on the single best copy as an expert in the field.
+        Consider suggestions when refining an idea.
+        """;
+
+    [Fact]
+    public async Task RunAsync()
+    {
+        // Define the agents
+        ChatCompletionAgent agentReviewer =
+            new()
+            {
+                Instructions = ReviewerInstructions,
+                Name = ReviewerName,
+                Kernel = this.CreateKernelWithChatCompletion(),
+            };
+
+        ChatCompletionAgent agentWriter =
+            new()
+            {
+                Instructions = CopyWriterInstructions,
+                Name = CopyWriterName,
+                Kernel = this.CreateKernelWithChatCompletion(),
+            };
+
+        // Create a chat for agent interaction.
+        AgentGroupChat chat =
+            new(agentWriter, agentReviewer)
+            {
+                ExecutionSettings =
+                    new()
+                    {
+                        // Here a TerminationStrategy subclass is used that will terminate when
+                        // an assistant message contains the term "approve".
+                        TerminationStrategy =
+                            new ApprovalTerminationStrategy()
+                            {
+                                // Only the art-director may approve.
+                                Agents = [agentReviewer],
+                            }
+                    }
+            };
+
+        // Invoke chat and display messages.
+        string input = "concept: maps made out of egg cartons.";
+        chat.AddChatMessage(new ChatMessageContent(AuthorRole.User, input));
+        this.WriteLine($"# {AuthorRole.User}: '{input}'");
+
+        await foreach (var content in chat.InvokeAsync())
+        {
+            this.WriteLine($"# {content.Role} - {content.AuthorName ?? "*"}: '{content.Content}'");
+        }
+
+        this.WriteLine($"# IS COMPLETE: {chat.IsComplete}");
+    }
+
+    private sealed class ApprovalTerminationStrategy : TerminationStrategy
+    {
+        // Terminate when the final message contains the term "approve"
+        protected override Task<bool> ShouldAgentTerminateAsync(Agent agent, IReadOnlyList<ChatMessageContent> history, CancellationToken cancellationToken)
+            => Task.FromResult(history[history.Count - 1].Content?.Contains("approve", StringComparison.OrdinalIgnoreCase) ?? false);
+    }
+}

dotnet/src/Agents/Abstractions/AgentChat.cs

@@ -19,10 +19,14 @@ public abstract class AgentChat
     private readonly BroadcastQueue _broadcastQueue;
     private readonly Dictionary<string, AgentChannel> _agentChannels;
     private readonly Dictionary<Agent, string> _channelMap;
-    private readonly ChatHistory _history;
 
     private int _isActive;
 
+    /// <summary>
+    /// Exposes the internal history to subclasses.
+    /// </summary>
+    protected ChatHistory History { get; }
+
     /// <summary>
     /// Retrieve the message history, either the primary history or
     /// an agent specific version.
@@ -34,7 +38,7 @@ public IAsyncEnumerable<ChatMessageContent> GetChatMessagesAsync(Agent? agent =
     {
         if (agent == null)
         {
-            return this._history.ToDescendingAsync();
+            return this.History.ToDescendingAsync();
         }
 
         var channelKey = this.GetAgentHash(agent);
@@ -80,7 +84,7 @@ public void AddChatMessages(IReadOnlyList<ChatMessageContent> messages)
         }
 
         // Append to chat history
-        this._history.AddRange(messages);
+        this.History.AddRange(messages);
 
         // Broadcast message to other channels (in parallel)
         var channelRefs = this._agentChannels.Select(kvp => new ChannelReference(kvp.Value, kvp.Key));
@@ -114,7 +118,7 @@ protected async IAsyncEnumerable<ChatMessageContent> InvokeAgentAsync(
             await foreach (var message in channel.InvokeAsync(agent, cancellationToken).ConfigureAwait(false))
             {
                 // Add to primary history
-                this._history.Add(message);
+                this.History.Add(message);
                 messages.Add(message);
 
                 // Yield message to caller
@@ -146,9 +150,9 @@ private async Task<AgentChannel> GetChannelAsync(Agent agent, CancellationToken
         {
             channel = await agent.CreateChannelAsync(cancellationToken).ConfigureAwait(false);
 
-            if (this._history.Count > 0)
+            if (this.History.Count > 0)
             {
-                await channel.ReceiveAsync(this._history, cancellationToken).ConfigureAwait(false);
+                await channel.ReceiveAsync(this.History, cancellationToken).ConfigureAwait(false);
             }
 
             this._agentChannels.Add(channelKey, channel);
@@ -179,6 +183,6 @@ protected AgentChat()
         this._agentChannels = [];
         this._broadcastQueue = new();
         this._channelMap = [];
-        this._history = [];
+        this.History = [];
     }
 }

dotnet/src/Agents/Core/AgentGroupChat.cs

@@ -0,0 +1,148 @@
+// Copyright (c) Microsoft. All rights reserved.
+using System.Collections.Generic;
+using System.Linq;
+using System.Runtime.CompilerServices;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.SemanticKernel.Agents.Chat;
+using Microsoft.SemanticKernel.ChatCompletion;
+
+namespace Microsoft.SemanticKernel.Agents;
+
+/// <summary>
+/// A an <see cref="AgentChat"/> that supports multi-turn interactions.
+/// </summary>
+public sealed class AgentGroupChat : AgentChat
+{
+    private readonly HashSet<string> _agentIds; // Efficient existence test
+    private readonly List<Agent> _agents; // Maintain order
+
+    /// <summary>
+    /// Indicates if completion criteria has been met.  If set, no further
+    /// agent interactions will occur.  Clear to enable more agent interactions.
+    /// </summary>
+    public bool IsComplete { get; set; }
+
+    /// <summary>
+    /// Settings for defining chat behavior.
+    /// </summary>
+    public AgentGroupChatSettings ExecutionSettings { get; set; } = new AgentGroupChatSettings();
+
+    /// <summary>
+    /// The agents participating in the chat.
+    /// </summary>
+    public IReadOnlyList<Agent> Agents => this._agents.AsReadOnly();
+
+    /// <summary>
+    /// Add a <see cref="Agent"/> to the chat.
+    /// </summary>
+    /// <param name="agent">The <see cref="KernelAgent"/> to add.</param>
+    public void AddAgent(Agent agent)
+    {
+        if (this._agentIds.Add(agent.Id))
+        {
+            this._agents.Add(agent);
+        }
+    }
+
+    /// <summary>
+    /// Process a series of interactions between the <see cref="AgentGroupChat.Agents"/> that have joined this <see cref="AgentGroupChat"/>.
+    /// The interactions will proceed according to the <see cref="SelectionStrategy"/> and the <see cref="TerminationStrategy"/>
+    /// defined via <see cref="AgentGroupChat.ExecutionSettings"/>.
+    /// In the absence of an <see cref="AgentGroupChatSettings.SelectionStrategy"/>, this method will not invoke any agents.
+    /// Any agent may be explicitly selected by calling <see cref="AgentGroupChat.InvokeAsync(Agent, bool, CancellationToken)"/>.
+    /// </summary>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>Asynchronous enumeration of messages.</returns>
+    public async IAsyncEnumerable<ChatMessageContent> InvokeAsync([EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        if (this.IsComplete)
+        {
+            // Throw exception if chat is completed and automatic-reset is not enabled.
+            if (!this.ExecutionSettings.TerminationStrategy.AutomaticReset)
+            {
+                throw new KernelException("Agent Failure - Chat has completed.");
+            }
+
+            this.IsComplete = false;
+        }
+
+        for (int index = 0; index < this.ExecutionSettings.TerminationStrategy.MaximumIterations; index++)
+        {
+            // Identify next agent using strategy
+            Agent agent = await this.ExecutionSettings.SelectionStrategy.NextAsync(this.Agents, this.History, cancellationToken).ConfigureAwait(false);
+
+            // Invoke agent and process messages along with termination
+            await foreach (var message in base.InvokeAgentAsync(agent, cancellationToken).ConfigureAwait(false))
+            {
+                if (message.Role == AuthorRole.Assistant)
+                {
+                    var task = this.ExecutionSettings.TerminationStrategy.ShouldTerminateAsync(agent, this.History, cancellationToken);
+                    this.IsComplete = await task.ConfigureAwait(false);
+                }
+
+                yield return message;
+            }
+
+            if (this.IsComplete)
+            {
+                break;
+            }
+        }
+    }
+
+    /// <summary>
+    /// Process a single interaction between a given <see cref="Agent"/> an a <see cref="AgentGroupChat"/>.
+    /// </summary>
+    /// <param name="agent">The agent actively interacting with the chat.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>Asynchronous enumeration of messages.</returns>
+    /// <remark>
+    /// Specified agent joins the chat.
+    /// </remark>>
+    public IAsyncEnumerable<ChatMessageContent> InvokeAsync(
+        Agent agent,
+        CancellationToken cancellationToken = default) =>
+        this.InvokeAsync(agent, isJoining: true, cancellationToken);
+
+    /// <summary>
+    /// Process a single interaction between a given <see cref="KernelAgent"/> an a <see cref="AgentGroupChat"/> irregardless of
+    /// the <see cref="SelectionStrategy"/> defined via <see cref="AgentGroupChat.ExecutionSettings"/>.  Likewise, this does
+    /// not regard <see cref="TerminationStrategy.MaximumIterations"/> as it only takes a single turn for the specified agent.
+    /// </summary>
+    /// <param name="agent">The agent actively interacting with the chat.</param>
+    /// <param name="isJoining">Optional flag to control if agent is joining the chat.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>Asynchronous enumeration of messages.</returns>
+    public async IAsyncEnumerable<ChatMessageContent> InvokeAsync(
+        Agent agent,
+        bool isJoining,
+        [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        if (isJoining)
+        {
+            this.AddAgent(agent);
+        }
+
+        await foreach (var message in base.InvokeAgentAsync(agent, cancellationToken).ConfigureAwait(false))
+        {
+            if (message.Role == AuthorRole.Assistant)
+            {
+                var task = this.ExecutionSettings.TerminationStrategy.ShouldTerminateAsync(agent, this.History, cancellationToken);
+                this.IsComplete = await task.ConfigureAwait(false);
+            }
+
+            yield return message;
+        }
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AgentGroupChat"/> class.
+    /// </summary>
+    /// <param name="agents">The agents initially participating in the chat.</param>
+    public AgentGroupChat(params Agent[] agents)
+    {
+        this._agents = new(agents);
+        this._agentIds = new(this._agents.Select(a => a.Id));
+    }
+}