.Net - DESIGN REVIEW: Agent Chat Filters

dotnet/samples/GettingStartedWithAgents/Step6_Filters.cs

@@ -0,0 +1,107 @@
+// Copyright (c) Microsoft. All rights reserved.
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.Agents;
+using Microsoft.SemanticKernel.Agents.Chat;
+using Microsoft.SemanticKernel.Agents.Filters;
+using Microsoft.SemanticKernel.ChatCompletion;
+
+namespace GettingStarted;
+
+/// <summary>
+/// Demonstrate usage of <see cref="AgentChat"/> with <see cref="IAgentChatFilter"/>.
+/// </summary>
+public class Step6_Filters(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],
+ }
+ },
+ Filters =
+ {
+ new ExampleChatFilter(base.Output)
+ }
+ };
+
+ // 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);
+ }
+
+ private sealed class ExampleChatFilter(ITestOutputHelper output) : IAgentChatFilter
+ {
+ public void OnAgentInvoked(AgentChatFilterInvokedContext context)
+ {
+ output.WriteLine($"$ FILTER - {context.Agent.Name}: {nameof(OnAgentInvoked)} #{context.Message.Content?.Length ?? 0}");
+ }
+
+ public void OnAgentInvoking(AgentChatFilterInvokingContext context)
+ {
+ output.WriteLine($"$ FILTER - {context.Agent.Name}: {nameof(OnAgentInvoking)}");
+ }
+ }
+}

dotnet/src/Agents/Abstractions/AgentChat.cs

@@ -7,6 +7,7 @@
 using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Logging.Abstractions;
 using Microsoft.SemanticKernel.Agents.Extensions;
+using Microsoft.SemanticKernel.Agents.Filters;
 using Microsoft.SemanticKernel.Agents.Internal;
 using Microsoft.SemanticKernel.ChatCompletion;
 
@@ -26,6 +27,7 @@ public abstract class AgentChat
  private readonly Dictionary<Agent, string> _channelMap; // Map agent to its channel-hash: one entry per agent.
 
  private int _isActive;
+ private List<IAgentChatFilter>? _filters;
  private ILogger? _logger;
 
  /// <summary>
@@ -44,6 +46,11 @@ public abstract class AgentChat
  /// </summary>
  protected ILogger Logger => this._logger ??= this.LoggerFactory.CreateLogger(this.GetType());
 
+ /// <summary>
+ /// %%%
+ /// </summary>
+ public IList<IAgentChatFilter> Filters => this._filters ??= [];
+
  /// <summary>
  /// Exposes the internal history to subclasses.
  /// </summary>
@@ -209,6 +216,9 @@ public void AddChatMessages(IReadOnlyList<ChatMessageContent> messages)
 
  try
  {
+ // %%%
+ this.OnAgentInvokingFilter(agent, this.History);
+
  // Get or create the required channel and block until channel is synchronized.
  // Will throw exception when propagating a processing failure.
  AgentChannel channel = await GetOrCreateChannelAsync().ConfigureAwait(false);
@@ -217,11 +227,17 @@ public void AddChatMessages(IReadOnlyList<ChatMessageContent> messages)
  List<ChatMessageContent> messages = [];
  await foreach (ChatMessageContent message in channel.InvokeAsync(agent, cancellationToken).ConfigureAwait(false))
  {
+ // Invoke filter
+ AgentChatFilterInvokedContext? context = this.OnAgentInvokedFilter(agent, this.History, message);
+
+ // Capture potential message replacement
+ ChatMessageContent effectiveMessage = context?.Message ?? message;
+
  this.Logger.LogTrace("[{MethodName}] Agent message {AgentType}: {Message}", nameof(InvokeAgentAsync), agent.GetType(), message);
 
  // Add to primary history
- this.History.Add(message);
- messages.Add(message);
+ this.History.Add(effectiveMessage);
+ messages.Add(effectiveMessage);
 
  // Don't expose function-call and function-result messages to caller.
  if (message.Items.All(i => i is FunctionCallContent || i is FunctionResultContent))
@@ -230,7 +246,7 @@ await foreach (ChatMessageContent message in channel.InvokeAsync(agent, cancella
  }
 
  // Yield message to caller
- yield return message;
+ yield return effectiveMessage;
  }
 
  // Broadcast message to other channels (in parallel)
@@ -328,6 +344,40 @@ private string GetAgentHash(Agent agent)
  return channel;
  }
 
+ private AgentChatFilterInvokingContext? OnAgentInvokingFilter(Agent agent, IReadOnlyList<ChatMessageContent> history)
+ {
+ AgentChatFilterInvokingContext? context = null;
+
+ if (this._filters is { Count: > 0 })
+ {
+ context = new(agent, history);
+
+ for (int i = 0; i < this._filters.Count; i++)
+ {
+ this._filters[i].OnAgentInvoking(context);
+ }
+ }
+
+ return context;
+ }
+
+ private AgentChatFilterInvokedContext? OnAgentInvokedFilter(Agent agent, IReadOnlyList<ChatMessageContent> history, ChatMessageContent message)
+ {
+ AgentChatFilterInvokedContext? context = null;
+
+ if (this._filters is { Count: > 0 })
+ {
+ context = new(agent, history, message);
+
+ for (int i = 0; i < this._filters.Count; i++)
+ {
+ this._filters[i].OnAgentInvoked(context);
+ }
+ }
+
+ return context;
+ }
+
  /// <summary>
  /// Initializes a new instance of the <see cref="AgentChat"/> class.
  /// </summary>

dotnet/src/Agents/Abstractions/Filters/AgentChatFilterContext.cs

@@ -0,0 +1,31 @@
+// Copyright (c) Microsoft. All rights reserved.
+using System.Collections.Generic;
+
+namespace Microsoft.SemanticKernel.Agents.Filters;
+
+/// <summary>
+/// Base class with data related to <see cref="IAgentChatFilter"/>.
+/// </summary>
+public abstract class AgentChatFilterContext
+{
+ /// <summary>
+ /// Gets the <see cref="Agent"/> with which this filter is associated.
+ /// </summary>
+ public Agent Agent { get; }
+
+ /// <summary>
+ /// Gets the message history with which this filter is associated.
+ /// </summary>
+ public IReadOnlyList<ChatMessageContent> History { get; }
+
+ /// <summary>
+ /// Initializes a new instance of the <see cref="AgentChatFilterContext"/> class.
+ /// </summary>
+ /// <param name="agent"></param>
+ /// <param name="history"></param>
+ internal AgentChatFilterContext(Agent agent, IReadOnlyList<ChatMessageContent> history)
+ {
+ this.Agent = agent;
+ this.History = history;
+ }
+}

dotnet/src/Agents/Abstractions/Filters/AgentChatFilterInvokedContext.cs

@@ -0,0 +1,27 @@
+// Copyright (c) Microsoft. All rights reserved.
+using System.Collections.Generic;
+
+namespace Microsoft.SemanticKernel.Agents.Filters;
+
+/// <summary>
+/// Context associated with to <see cref="IAgentChatFilter.OnAgentInvoked"/>.
+/// </summary>
+public sealed class AgentChatFilterInvokedContext : AgentChatFilterContext
+{
+ /// <summary>
+ /// %%%
+ /// </summary>
+ public ChatMessageContent Message { get; set; }
+
+ /// <summary>
+ /// Initializes a new instance of the <see cref="AgentChatFilterInvokedContext"/> class.
+ /// </summary>
+ /// <param name="agent"></param>
+ /// <param name="history"></param>
+ /// <param name="message"></param>
+ internal AgentChatFilterInvokedContext(Agent agent, IReadOnlyList<ChatMessageContent> history, ChatMessageContent message)
+ : base(agent, history)
+ {
+ this.Message = message;
+ }
+}

dotnet/src/Agents/Abstractions/Filters/AgentChatFilterInvokingContext.cs

@@ -0,0 +1,19 @@
+// Copyright (c) Microsoft. All rights reserved.
+using System.Collections.Generic;
+
+namespace Microsoft.SemanticKernel.Agents.Filters;
+
+/// <summary>
+/// Context associated with to <see cref="IAgentChatFilter.OnAgentInvoking"/>.
+/// </summary>
+public sealed class AgentChatFilterInvokingContext : AgentChatFilterContext
+{
+ /// <summary>
+ /// Initializes a new instance of the <see cref="AgentChatFilterInvokingContext"/> class.
+ /// </summary>
+ /// <param name="agent"></param>
+ /// <param name="history"></param>
+ internal AgentChatFilterInvokingContext(Agent agent, IReadOnlyList<ChatMessageContent> history)
+ : base(agent, history)
+ { }
+}

dotnet/src/Agents/Abstractions/Filters/IAgentChatFilter.cs

@@ -0,0 +1,20 @@
+// Copyright (c) Microsoft. All rights reserved.
+namespace Microsoft.SemanticKernel.Agents.Filters;
+
+/// <summary>
+/// Interface for filtering actions during agent chat.
+/// </summary>
+public interface IAgentChatFilter
+{
+ /// <summary>
+ /// Method which is executed before invoking agent.
+ /// </summary>
+ /// <param name="context">Data related to agent before invoking.</param>
+ void OnAgentInvoking(AgentChatFilterInvokingContext context);
+
+ /// <summary>
+ /// Method which is executed after invoking agent as each response is processed.
+ /// </summary>
+ /// <param name="context">Data related to agent after invoking.</param>
+ void OnAgentInvoked(AgentChatFilterInvokedContext context);
+}

dotnet/src/Agents/UnitTests/AgentChatTests.cs

@@ -7,7 +7,9 @@
 using Microsoft.Extensions.Logging;
 using Microsoft.SemanticKernel;
 using Microsoft.SemanticKernel.Agents;
+using Microsoft.SemanticKernel.Agents.Filters;
 using Microsoft.SemanticKernel.ChatCompletion;
+using Moq;
 using Xunit;
 
 namespace SemanticKernel.Agents.UnitTests;
@@ -109,6 +111,36 @@ async Task SynchronizedInvokeAsync()
  }
  }
 
+ /// <summary>
+ /// Verify behavior of <see cref="AgentChat"/> usage of <see cref="IAgentChatFilter"/>.
+ /// </summary>
+ [Fact]
+ public async Task VerifyAgentChatFiltersAsync()
+ {
+ // Create a filter
+ Mock<IAgentChatFilter> mockFilter = new();
+
+ // Create chat
+ TestChat chat = new()
+ {
+ Filters =
+ {
+ mockFilter.Object
+ }
+ };
+
+ // Verify initial state
+ mockFilter.Verify(f => f.OnAgentInvoking(It.IsAny<AgentChatFilterInvokingContext>()), Times.Never);
+ mockFilter.Verify(f => f.OnAgentInvoked(It.IsAny<AgentChatFilterInvokedContext>()), Times.Never);
+
+ // Invoke with input & verify (agent joins chat)
+ chat.AddChatMessage(new ChatMessageContent(AuthorRole.User, "hi"));
+ await chat.InvokeAsync().ToArrayAsync();
+ Assert.Equal(1, chat.Agent.InvokeCount);
+ mockFilter.Verify(f => f.OnAgentInvoking(It.IsAny<AgentChatFilterInvokingContext>()), Times.Once);
+ mockFilter.Verify(f => f.OnAgentInvoked(It.IsAny<AgentChatFilterInvokedContext>()), Times.Once);
+ }
+
  private async Task VerifyHistoryAsync(int expectedCount, IAsyncEnumerable<ChatMessageContent> history)
  {
  if (expectedCount == 0)

dotnet/src/Agents/UnitTests/Filters/AgentChatFilterInvokedContextTests.cs

@@ -0,0 +1,32 @@
+// Copyright (c) Microsoft. All rights reserved.
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.Agents;
+using Microsoft.SemanticKernel.Agents.Filters;
+using Microsoft.SemanticKernel.ChatCompletion;
+using Moq;
+using Xunit;
+
+namespace SemanticKernel.Agents.UnitTests.OpenAI;
+
+/// <summary>
+/// Unit testing of <see cref="AgentChatFilterInvokedContext"/>.
+/// </summary>
+public class AgentChatFilterInvokedContextTests
+{
+ /// <summary>
+ /// Verify initial state.
+ /// </summary>
+ [Fact]
+ public void VerifyAgentChatFilterInvokedContextState()
+ {
+ Mock<Agent> agent = new();
+ ChatHistory history = [];
+ ChatMessageContent message = new(AuthorRole.User, "hi");
+
+ AgentChatFilterInvokedContext context = new(agent.Object, history, message);
+
+ Assert.NotNull(context.Agent);
+ Assert.NotNull(context.History);
+ Assert.NotNull(context.Message);
+ }
+}