-
Notifications
You must be signed in to change notification settings - Fork 3.1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Browse files
Browse the repository at this point in the history
### 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. --> Introduce `AgentGroupChat` to the `Core` project. ### Description <!-- Describe your changes, the overall approach, the underlying design. These notes will help understanding how your code works. Thanks! --> Adds `AgentGroupChat` along with associated settings, strategies, unit-test, and example.  ### Outstanding Tasks - In Order (each a future PR) - [X] AgentChat (our "GroupChat") - [ ] Agent-as-a-Plugin - [ ] OpenAIAssistantAgent - [ ] OpenAIAssistantAgent Citiation Content - [ ] Port AutoGen examples - [ ] Streaming - [ ] YAML Templates ### 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 😄
- Loading branch information
Showing
19 changed files
with
1,055 additions
and
45 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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); | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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)); | ||
| } | ||
| } |
Oops, something went wrong.