A programming framework for agentic AI
feat: Implement AgentChat.NET Termination Conditions (#5839)
Jacob Albercf1365763ca5
diff --git a/dotnet/src/Microsoft.AutoGen/AgentChat/Abstractions/Messages.cs b/dotnet/src/Microsoft.AutoGen/AgentChat/Abstractions/Messages.csindex fcc1871bb..97e1d5b76 100644--- a/dotnet/src/Microsoft.AutoGen/AgentChat/Abstractions/Messages.cs+++ b/dotnet/src/Microsoft.AutoGen/AgentChat/Abstractions/Messages.cs@@ -25,6 +25,11 @@ public abstract class AgentMessage/// </summary>public required string Source { get; set; }+ /// <summary>+ /// The <see cref="IChatClient"/> usage incurred when producing this message.+ /// </summary>+ public RequestUsage? ModelUsage { get; set; }+// IMPORTANT NOTE: Unlike the ITypeMarshal<AgentMessage, WireProtocol.AgentMessage> implementation in ProtobufTypeMarshal,// the .ToWire() call on this is intended to be used for directly converting a concrete message type to its leaf representation.// In the context of Protobuf these may not be the same due to discriminated union types being real types, as opposed to@@ -495,6 +500,11 @@ public class FunctionExecutionResult/// </summary>public required string Id { get; set; }+ /// <summary>+ /// The name of the function that was called.+ /// </summary>+ public required string Name { get; set; }+/// <summary>/// The result of calling the function./// </summary>diff --git a/dotnet/src/Microsoft.AutoGen/AgentChat/Abstractions/Termination.cs b/dotnet/src/Microsoft.AutoGen/AgentChat/Abstractions/Termination.csindex 352b25298..21027cc36 100644--- a/dotnet/src/Microsoft.AutoGen/AgentChat/Abstractions/Termination.cs+++ b/dotnet/src/Microsoft.AutoGen/AgentChat/Abstractions/Termination.cs@@ -3,6 +3,29 @@namespace Microsoft.AutoGen.AgentChat.Abstractions;+public static class TerminationConditionExtensions+{+ /// <summary>+ /// Combine this termination condition with another using a logical OR.+ /// </summary>+ /// <param name="other">Another termination condition.</param>+ /// <returns>The combined termination condition, with appropriate short-circuiting.</returns>+ public static ITerminationCondition Or(this ITerminationCondition this_, ITerminationCondition other)+ {+ return new CombinerCondition(CombinerCondition.Or, this_, other);+ }++ /// <summary>+ /// Combine this termination condition with another using a logical AND.+ /// </summary>+ /// <param name="other">Another termination condition.</param>+ /// <returns>The combined termination condition, with appropriate short-circuiting.</returns>+ public static ITerminationCondition And(this ITerminationCondition this_, ITerminationCondition other)+ {+ return new CombinerCondition(CombinerCondition.And, this_, other);+ }+}+/// <summary>/// A stateful condition that determines when a conversation should be terminated.///@@ -12,7 +35,8 @@ namespace Microsoft.AutoGen.AgentChat.Abstractions;////// Once a termination condition has been reached, it must be <see cref="Reset()"/> before it can be used again.///-/// Termination conditions can be combined using the <see cref="Or"/> and <see cref="And"/> methods.+/// Termination conditions can be combined using the <see cref="TerminationConditionExtensions.Or"/> and+/// <see cref="TerminationConditionExtensions.And"/> methods./// </summary>public interface ITerminationCondition{@@ -38,23 +62,37 @@ public interface ITerminationConditionpublic void Reset();/// <summary>- /// Combine this termination condition with another using a logical OR.+ /// Combine two termination conditions with another using an associative, short-circuiting OR./// </summary>- /// <param name="other">Another termination condition.</param>- /// <returns>The combined termination condition, with appropriate short-circuiting.</returns>- public ITerminationCondition Or(ITerminationCondition other)+ /// <param name="left">+ /// The left-hand side termination condition. If this condition is already a disjunction, the RHS condition is added to the list of clauses.+ /// </param>+ /// <param name="right">+ /// The right-hand side termination condition. If the LHS condition is already a disjunction, this condition is added to the list of clauses.+ /// </param>+ /// <returns>+ /// The combined termination condition, with appropriate short-circuiting.+ /// </returns>+ public static ITerminationCondition operator |(ITerminationCondition left, ITerminationCondition right){- return new CombinerCondition(CombinerCondition.Or, this, other);+ return left.Or(right);}/// <summary>- /// Combine this termination condition with another using a logical AND.+ /// Combine two termination conditions with another using an associative, short-circuiting AND./// </summary>- /// <param name="other">Another termination condition.</param>- /// <returns>The combined termination condition, with appropriate short-circuiting.</returns>- public ITerminationCondition And(ITerminationCondition other)+ /// <param name="left">+ /// The left-hand side termination condition. If this condition is already a conjunction, the RHS condition is added to the list of clauses.+ /// </param>+ /// <param name="right">+ /// The right-hand side termination condition. If the LHS condition is already a conjunction, this condition is added to the list of clauses.+ /// </param>+ /// <returns>+ /// The combined termination condition, with appropriate short-circuiting.+ /// </returns>+ public static ITerminationCondition operator &(ITerminationCondition left, ITerminationCondition right){- return new CombinerCondition(CombinerCondition.And, this, other);+ return left.And(right);}}@@ -167,38 +205,4 @@ internal sealed class CombinerCondition : ITerminationConditionreturn null;}-- /// <inheritdoc cref="ITerminationCondition.Or" />- /// <remarks>- /// If this condition is already a disjunction, the new condition is added to the list of clauses.- /// </remarks>- ITerminationCondition ITerminationCondition.Or(ITerminationCondition other)- {- if (this.conjunction == Or)- {- this.clauses.Add(other);- return this;- }- else- {- return new CombinerCondition(Or, this, new CombinerCondition(Or, other));- }- }-- /// <inheritdoc cref="ITerminationCondition.And" />- /// <remarks>- /// If this condition is already a conjunction, the new condition is added to the list of clauses.- /// </remarks>- ITerminationCondition ITerminationCondition.And(ITerminationCondition other)- {- if (this.conjunction == And)- {- this.clauses.Add(other);- return this;- }- else- {- return new CombinerCondition(And, this, new CombinerCondition(And, other));- }- }}diff --git a/dotnet/src/Microsoft.AutoGen/AgentChat/Abstractions/Usage.cs b/dotnet/src/Microsoft.AutoGen/AgentChat/Abstractions/Usage.csnew file mode 100644index 000000000..78d04221d--- /dev/null+++ b/dotnet/src/Microsoft.AutoGen/AgentChat/Abstractions/Usage.cs@@ -0,0 +1,10 @@+// Copyright (c) Microsoft Corporation. All rights reserved.+// Usage.cs++namespace Microsoft.AutoGen.AgentChat.Abstractions;++public struct RequestUsage+{+ public int PromptTokens { get; set; }+ public int CompletionTokens { get; set; }+}diff --git a/dotnet/src/Microsoft.AutoGen/AgentChat/Terminations/ExternalTermination.cs b/dotnet/src/Microsoft.AutoGen/AgentChat/Terminations/ExternalTermination.csnew file mode 100644index 000000000..9d2155ce0--- /dev/null+++ b/dotnet/src/Microsoft.AutoGen/AgentChat/Terminations/ExternalTermination.cs@@ -0,0 +1,53 @@+// Copyright (c) Microsoft Corporation. All rights reserved.+// ExternalTermination.cs++using Microsoft.AutoGen.AgentChat.Abstractions;++namespace Microsoft.AutoGen.AgentChat.Terminations;++/// <summary>+/// A <see cref="ITerminationCondition"/> that is externally controlled by calling the <see cref="Set"/> method.+/// </summary>+public sealed class ExternalTermination : ITerminationCondition+{+ public ExternalTermination()+ {+ this.TerminationQueued = false;+ this.IsTerminated = false;+ }++ public bool TerminationQueued { get; private set; }+ public bool IsTerminated { get; private set; }++ /// <summary>+ /// Set the termination condition to terminated.+ /// </summary>+ public void Set()+ {+ this.TerminationQueued = true;+ }++ public ValueTask<StopMessage?> CheckAndUpdateAsync(IList<AgentMessage> messages)+ {+ if (this.IsTerminated)+ {+ throw new TerminatedException();+ }++ if (this.TerminationQueued)+ {+ this.IsTerminated = true;+ string message = "External termination requested.";+ StopMessage result = new() { Content = message, Source = nameof(ExternalTermination) };+ return ValueTask.FromResult<StopMessage?>(result);+ }++ return ValueTask.FromResult<StopMessage?>(null);+ }++ public void Reset()+ {+ this.TerminationQueued = false;+ this.IsTerminated = false;+ }+}diff --git a/dotnet/src/Microsoft.AutoGen/AgentChat/Terminations/FunctionCallTermination.cs b/dotnet/src/Microsoft.AutoGen/AgentChat/Terminations/FunctionCallTermination.csnew file mode 100644index 000000000..20dd93769--- /dev/null+++ b/dotnet/src/Microsoft.AutoGen/AgentChat/Terminations/FunctionCallTermination.cs@@ -0,0 +1,51 @@+// Copyright (c) Microsoft Corporation. All rights reserved.+// FunctionCallTermination.cs++using Microsoft.AutoGen.AgentChat.Abstractions;++namespace Microsoft.AutoGen.AgentChat.Terminations;++/// <summary>+/// Terminate the conversation if a <see cref="ToolCallExecutionEvent"/> with a specific name is received.+/// </summary>+public sealed class FunctionCallTermination : ITerminationCondition+{+ /// <summary>+ /// Initializes a new instance of the <see cref="FunctionCallTermination"/> class.+ /// </summary>+ /// <param name="functionName">The name of the function to look for in the messages.</param>+ public FunctionCallTermination(string functionName)+ {+ this.FunctionName = functionName;+ this.IsTerminated = false;+ }++ public string FunctionName { get; }+ public bool IsTerminated { get; private set; }++ public ValueTask<StopMessage?> CheckAndUpdateAsync(IList<AgentMessage> messages)+ {+ if (this.IsTerminated)+ {+ throw new TerminatedException();+ }++ foreach (AgentMessage item in messages)+ {+ if (item is ToolCallExecutionEvent toolCallEvent && toolCallEvent.Content.Any(execution => execution.Name == this.FunctionName))+ {+ this.IsTerminated = true;+ string message = $"Function '{this.FunctionName}' was executed.";+ StopMessage result = new() { Content = message, Source = nameof(FunctionCallTermination) };+ return ValueTask.FromResult<StopMessage?>(result);+ }+ }++ return ValueTask.FromResult<StopMessage?>(null);+ }++ public void Reset()+ {+ this.IsTerminated = false;+ }+}diff --git a/dotnet/src/Microsoft.AutoGen/AgentChat/Terminations/HandoffTermination.cs b/dotnet/src/Microsoft.AutoGen/AgentChat/Terminations/HandoffTermination.csnew file mode 100644index 000000000..229466963--- /dev/null+++ b/dotnet/src/Microsoft.AutoGen/AgentChat/Terminations/HandoffTermination.cs@@ -0,0 +1,53 @@+// Copyright (c) Microsoft Corporation. All rights reserved.+// HandoffTermination.cs++using Microsoft.AutoGen.AgentChat.Abstractions;++namespace Microsoft.AutoGen.AgentChat.Terminations;++/// <summary>+/// Terminate the conversation if a <see cref="HandoffMessage"/> with the given <see cref="HandoffMessage.Target"/>+/// is received.+/// </summary>+public sealed class HandoffTermination : ITerminationCondition+{+ /// <summary>+ /// Initializes a new instance of the <see cref="HandoffTermination"/> class.+ /// </summary>+ /// <param name="target">The target of the handoff message.</param>+ public HandoffTermination(string target)+ {+ this.Target = target;+ this.IsTerminated = false;+ }++ public string Target { get; }+ public bool IsTerminated { get; private set; }++ public ValueTask<StopMessage?> CheckAndUpdateAsync(IList<AgentMessage> messages)+ {+ if (this.IsTerminated)+ {+ throw new TerminatedException();+ }++ foreach (AgentMessage item in messages)+ {+ if (item is HandoffMessage handoffMessage && handoffMessage.Target == this.Target)+ {+ this.IsTerminated = true;++ string message = $"Handoff to {handoffMessage.Target} from {handoffMessage.Source} detected.";+ StopMessage result = new() { Content = message, Source = nameof(HandoffTermination) };+ return ValueTask.FromResult<StopMessage?>(result);+ }+ }++ return ValueTask.FromResult<StopMessage?>(null);+ }++ public void Reset()+ {+ this.IsTerminated = false;+ }+}diff --git a/dotnet/src/Microsoft.AutoGen/AgentChat/Terminations/MaxMessageTermination.cs b/dotnet/src/Microsoft.AutoGen/AgentChat/Terminations/MaxMessageTermination.csnew file mode 100644index 000000000..fa2275f46--- /dev/null+++ b/dotnet/src/Microsoft.AutoGen/AgentChat/Terminations/MaxMessageTermination.cs@@ -0,0 +1,52 @@+// Copyright (c) Microsoft Corporation. All rights reserved.+// MaxMessageTermination.cs++using Microsoft.AutoGen.AgentChat.Abstractions;++namespace Microsoft.AutoGen.AgentChat.Terminations;++/// <summary>+/// Terminate the conversation after a maximum number of messages have been exchanged.+/// </summary>+public sealed class MaxMessageTermination : ITerminationCondition+{+ /// <summary>+ /// Initializes a new instance of the <see cref="MaxMessageTermination"/> class.+ /// </summary>+ /// <param name="maxMessages">The maximum number of messages allowed in the conversation.</param>+ public MaxMessageTermination(int maxMessages, bool includeAgentEvent = false)+ {+ this.MaxMessages = maxMessages;+ this.MessageCount = 0;+ this.IncludeAgentEvent = includeAgentEvent;+ }++ public int MaxMessages { get; }+ public int MessageCount { get; private set; }+ public bool IncludeAgentEvent { get; }++ public bool IsTerminated => this.MessageCount >= this.MaxMessages;++ public ValueTask<StopMessage?> CheckAndUpdateAsync(IList<AgentMessage> messages)+ {+ if (this.IsTerminated)+ {+ throw new TerminatedException();+ }++ this.MessageCount += messages.Where(m => this.IncludeAgentEvent || m is not AgentEvent).Count();++ if (this.IsTerminated)+ {+ StopMessage result = new() { Content = "Max message count reached", Source = nameof(MaxMessageTermination) };+ return ValueTask.FromResult<StopMessage?>(result);+ }++ return ValueTask.FromResult<StopMessage?>(null);+ }++ public void Reset()+ {+ this.MessageCount = 0;+ }+}diff --git a/dotnet/src/Microsoft.AutoGen/AgentChat/Terminations/SourceMatchTermination.cs b/dotnet/src/Microsoft.AutoGen/AgentChat/Terminations/SourceMatchTermination.csnew file mode 100644index 000000000..e938e0e78--- /dev/null+++ b/dotnet/src/Microsoft.AutoGen/AgentChat/Terminations/SourceMatchTermination.cs@@ -0,0 +1,50 @@+// Copyright (c) Microsoft Corporation. All rights reserved.+// SourceMatchTermination.cs++using Microsoft.AutoGen.AgentChat.Abstractions;++namespace Microsoft.AutoGen.AgentChat.Terminations;++/// <summary>+/// Terminate the conversation after a specific source responds.+/// </summary>+public sealed class SourceMatchTermination : ITerminationCondition+{+ /// <summary>+ /// Initializes a new instance of the <see cref="SourceMatchTermination"/> class.+ /// </summary>+ /// <param name="sources">List of source names to terminate the conversation.</param>+ public SourceMatchTermination(params IEnumerable<string> sources)+ {+ this.Sources = [.. sources];+ }++ public HashSet<string> Sources { get; }+ public bool IsTerminated { get; private set; }++ public ValueTask<StopMessage?> CheckAndUpdateAsync(IList<AgentMessage> messages)+ {+ if (this.IsTerminated)+ {+ throw new TerminatedException();+ }++ foreach (AgentMessage item in messages)+ {+ if (this.Sources.Contains(item.Source))+ {+ this.IsTerminated = true;+ string message = $"'{item.Source}' answered.";+ StopMessage result = new() { Content = message, Source = nameof(SourceMatchTermination) };+ return ValueTask.FromResult<StopMessage?>(result);+ }+ }++ return ValueTask.FromResult<StopMessage?>(null);+ }++ public void Reset()+ {+ this.IsTerminated = false;+ }+}diff --git a/dotnet/src/Microsoft.AutoGen/AgentChat/Terminations/TextMentionTermination.cs b/dotnet/src/Microsoft.AutoGen/AgentChat/Terminations/TextMentionTermination.csnew file mode 100644index 000000000..95684a2bb--- /dev/null+++ b/dotnet/src/Microsoft.AutoGen/AgentChat/Terminations/TextMentionTermination.cs@@ -0,0 +1,76 @@+// Copyright (c) Microsoft Corporation. All rights reserved.+// TextMentionTermination.cs++using Microsoft.AutoGen.AgentChat.Abstractions;+using Microsoft.Extensions.AI;++namespace Microsoft.AutoGen.AgentChat.Terminations;++/// <summary>+/// Terminate the conversation if a specific text is mentioned.+/// </summary>+public sealed class TextMentionTermination : ITerminationCondition+{+ /// <summary>+ /// Initializes a new instance of the <see cref="TextMentionTermination"/> class.+ /// </summary>+ /// <param name="targetText">The text to look for in the messages.</param>+ /// <param name="sources">Check only the messages of the specified agents for the text to look for.</param>+ public TextMentionTermination(string targetText, IEnumerable<string>? sources = null)+ {+ this.TargetText = targetText;+ this.Sources = sources != null ? [.. sources] : null;+ this.IsTerminated = false;+ }++ public string TargetText { get; }+ public HashSet<string>? Sources { get; }++ public bool IsTerminated { get; private set; }++ private bool CheckMultiModalData(MultiModalData data)+ {+ return data.ContentType == MultiModalData.Type.String &&+ ((TextContent)data.AIContent).Text.Contains(this.TargetText);+ }++ public ValueTask<StopMessage?> CheckAndUpdateAsync(IList<AgentMessage> messages)+ {+ if (this.IsTerminated)+ {+ throw new TerminatedException();+ }++ foreach (AgentMessage item in messages)+ {+ if (this.Sources != null && !this.Sources.Contains(item.Source))+ {+ continue;+ }++ bool hasMentions = item switch+ {+ TextMessage textMessage => textMessage.Content.Contains(this.TargetText),+ MultiModalMessage multiModalMessage => multiModalMessage.Content.Any(CheckMultiModalData),+ StopMessage stopMessage => stopMessage.Content.Contains(this.TargetText),+ ToolCallSummaryMessage toolCallSummaryMessage => toolCallSummaryMessage.Content.Contains(this.TargetText),++ _ => false+ };++ if (hasMentions)+ {+ this.IsTerminated = true;+ StopMessage result = new() { Content = "Text mention received", Source = nameof(TextMentionTermination) };+ return ValueTask.FromResult<StopMessage?>(result);+ }+ }++ return ValueTask.FromResult<StopMessage?>(null);+ }++ public void Reset()+ {+ this.IsTerminated = false;+ }+}diff --git a/dotnet/src/Microsoft.AutoGen/AgentChat/Terminations/TextMessageTermination.cs b/dotnet/src/Microsoft.AutoGen/AgentChat/Terminations/TextMessageTermination.csnew file mode 100644index 000000000..392bd281f--- /dev/null+++ b/dotnet/src/Microsoft.AutoGen/AgentChat/Terminations/TextMessageTermination.cs@@ -0,0 +1,63 @@+// Copyright (c) Microsoft Corporation. All rights reserved.+// TextMessageTermination.cs++using Microsoft.AutoGen.AgentChat.Abstractions;++namespace Microsoft.AutoGen.AgentChat.Terminations;++/// <summary>+/// Terminate the conversation if a <see cref="TextMessage"/> is received.+///+/// This termination condition checks for TextMessage instances in the message sequence. When a TextMessage is found,+/// it terminates the conversation if either:+///+/// <list type="bullet">+/// <item>No source was specified (terminates on any <see cref="TextMessage"/>)</item>+/// <item>The message source matches the specified source</item>+/// </list>+///+/// </summary>+public sealed class TextMessageTermination : ITerminationCondition+{+ /// <summary>+ /// Initializes a new instance of the <see cref="TextMessageTermination"/> class.+ /// </summary>+ /// <param name="source">+ /// The source name to match against incoming messages. If <c>null</c>, matches any source.+ /// Defaults to <c>null</c>.+ /// </param>+ public TextMessageTermination(string? source = null)+ {+ this.Source = source;+ this.IsTerminated = false;+ }++ public string? Source { get; }+ public bool IsTerminated { get; private set; }++ public ValueTask<StopMessage?> CheckAndUpdateAsync(IList<AgentMessage> messages)+ {+ if (this.IsTerminated)+ {+ throw new TerminatedException();+ }++ foreach (AgentMessage item in messages)+ {+ if (item is TextMessage textMessage && (this.Source == null || textMessage.Source == this.Source))+ {+ this.IsTerminated = true;+ string message = $"Text message received from '{textMessage.Source}'.";+ StopMessage result = new() { Content = message, Source = nameof(TextMessageTermination) };+ return ValueTask.FromResult<StopMessage?>(result);+ }+ }++ return ValueTask.FromResult<StopMessage?>(null);+ }++ public void Reset()+ {+ this.IsTerminated = false;+ }+}diff --git a/dotnet/src/Microsoft.AutoGen/AgentChat/Terminations/TimeoutTermination.cs b/dotnet/src/Microsoft.AutoGen/AgentChat/Terminations/TimeoutTermination.csnew file mode 100644index 000000000..015709d2e--- /dev/null+++ b/dotnet/src/Microsoft.AutoGen/AgentChat/Terminations/TimeoutTermination.cs@@ -0,0 +1,59 @@+// Copyright (c) Microsoft Corporation. All rights reserved.+// TimeoutTermination.cs++using Microsoft.AutoGen.AgentChat.Abstractions;++namespace Microsoft.AutoGen.AgentChat.Terminations;++/// <summary>+/// Terminate the conversation after the specified duration has passed.+/// </summary>+public sealed class TimeoutTermination : ITerminationCondition+{+ /// <summary>+ /// Initializes a new instance of the <see cref="TimeoutTermination"/> class.+ /// </summary>+ /// <param name="timeout">The maximum duration before terminating the conversation.</param>+ public TimeoutTermination(TimeSpan timeout)+ {+ this.Timeout = timeout;+ this.StartTime = DateTime.UtcNow;+ }++ /// <summary>+ /// Initializes a new instance of the <see cref="TimeoutTermination"/> class.+ /// </summary>+ /// <param name="seconds">The maximum duration in seconds before terminating the conversation.</param>+ public TimeoutTermination(float seconds) : this(TimeSpan.FromSeconds(seconds))+ {+ }++ public TimeSpan Timeout { get; }+ public DateTime StartTime { get; private set; }++ public bool IsTerminated { get; private set; }++ public ValueTask<StopMessage?> CheckAndUpdateAsync(IList<AgentMessage> messages)+ {+ if (this.IsTerminated)+ {+ throw new TerminatedException();+ }++ if (DateTime.UtcNow - this.StartTime >= this.Timeout)+ {+ this.IsTerminated = true;+ string message = $"Timeout of {this.Timeout.TotalSeconds} seconds reached.";+ StopMessage result = new() { Content = message, Source = nameof(TimeoutTermination) };+ return ValueTask.FromResult<StopMessage?>(result);+ }++ return ValueTask.FromResult<StopMessage?>(null);+ }++ public void Reset()+ {+ this.IsTerminated = false;+ this.StartTime = DateTime.UtcNow;+ }+}diff --git a/dotnet/src/Microsoft.AutoGen/AgentChat/Terminations/TokenUsageTermination.cs b/dotnet/src/Microsoft.AutoGen/AgentChat/Terminations/TokenUsageTermination.csnew file mode 100644index 000000000..a20ca4da2--- /dev/null+++ b/dotnet/src/Microsoft.AutoGen/AgentChat/Terminations/TokenUsageTermination.cs@@ -0,0 +1,73 @@+// Copyright (c) Microsoft Corporation. All rights reserved.+// TokenUsageTermination.cs++using Microsoft.AutoGen.AgentChat.Abstractions;++namespace Microsoft.AutoGen.AgentChat.Terminations;++/// <summary>+/// Terminate the conversation if the token usage limit is reached.+/// </summary>+public sealed class TokenUsageTermination : ITerminationCondition+{+ /// <summary>+ /// Initializes a new instance of the <see cref="TokenUsageTermination"/> class.+ /// </summary>+ /// <param name="maxTotalTokens">The maximum total number of tokens allowed in the conversation.</param>+ /// <param name="maxPromptTokens">The maximum number of prompt tokens allowed in the conversation.</param>+ /// <param name="maxCompletionTokens">The maximum number of completion tokens allowed in the conversation.</param>+ public TokenUsageTermination(int? maxTotalTokens = null, int? maxPromptTokens = null, int? maxCompletionTokens = null)+ {+ this.MaxTotalTokens = maxTotalTokens;+ this.MaxPromptTokens = maxPromptTokens;+ this.MaxCompletionTokens = maxCompletionTokens;++ this.PromptTokenCount = 0;+ this.CompletionTokenCount = 0;+ }++ public int? MaxTotalTokens { get; }+ public int? MaxPromptTokens { get; }+ public int? MaxCompletionTokens { get; }++ public int TotalTokenCount => this.PromptTokenCount + this.CompletionTokenCount;+ public int PromptTokenCount { get; private set; }+ public int CompletionTokenCount { get; private set; }++ public bool IsTerminated =>+ (this.MaxTotalTokens != null && this.TotalTokenCount >= this.MaxTotalTokens) ||+ (this.MaxPromptTokens != null && this.PromptTokenCount >= this.MaxPromptTokens) ||+ (this.MaxCompletionTokens != null && this.CompletionTokenCount >= this.MaxCompletionTokens);++ public ValueTask<StopMessage?> CheckAndUpdateAsync(IList<AgentMessage> messages)+ {+ if (this.IsTerminated)+ {+ throw new TerminatedException();+ }++ foreach (AgentMessage item in messages)+ {+ if (item.ModelUsage is RequestUsage usage)+ {+ this.PromptTokenCount += usage.PromptTokens;+ this.CompletionTokenCount += usage.CompletionTokens;+ }+ }++ if (this.IsTerminated)+ {+ string message = $"Token usage limit reached, total token count: {this.TotalTokenCount}, prompt token count: {this.PromptTokenCount}, completion token count: {this.CompletionTokenCount}.";+ StopMessage result = new() { Content = message, Source = nameof(TokenUsageTermination) };+ return ValueTask.FromResult<StopMessage?>(result);+ }++ return ValueTask.FromResult<StopMessage?>(null);+ }++ public void Reset()+ {+ this.PromptTokenCount = 0;+ this.CompletionTokenCount = 0;+ }+}diff --git a/dotnet/test/Microsoft.AutoGen.AgentChat.Tests/AgentChatSmokeTest.cs b/dotnet/test/Microsoft.AutoGen.AgentChat.Tests/AgentChatSmokeTest.csindex 97305b28b..1c9262e43 100644--- a/dotnet/test/Microsoft.AutoGen.AgentChat.Tests/AgentChatSmokeTest.cs+++ b/dotnet/test/Microsoft.AutoGen.AgentChat.Tests/AgentChatSmokeTest.cs@@ -12,6 +12,7 @@ using Xunit;namespace Microsoft.AutoGen.AgentChat.Tests;+[Trait("Category", "UnitV2")]public class AgentChatSmokeTest{public class SpeakMessageAgent : ChatAgentBasediff --git a/dotnet/test/Microsoft.AutoGen.AgentChat.Tests/LifecycleObjectTests.cs b/dotnet/test/Microsoft.AutoGen.AgentChat.Tests/LifecycleObjectTests.csindex 4e8f4cdc5..5daa0de29 100644--- a/dotnet/test/Microsoft.AutoGen.AgentChat.Tests/LifecycleObjectTests.cs+++ b/dotnet/test/Microsoft.AutoGen.AgentChat.Tests/LifecycleObjectTests.cs@@ -72,6 +72,7 @@ internal sealed class LifecycleObjectFixture : LifecycleObject}}+[Trait("Category", "UnitV2")]public class LifecycleObjectTests{/*diff --git a/dotnet/test/Microsoft.AutoGen.AgentChat.Tests/RunContextStackTests.cs b/dotnet/test/Microsoft.AutoGen.AgentChat.Tests/RunContextStackTests.csindex fde9ecdca..89e8b4d66 100644--- a/dotnet/test/Microsoft.AutoGen.AgentChat.Tests/RunContextStackTests.cs+++ b/dotnet/test/Microsoft.AutoGen.AgentChat.Tests/RunContextStackTests.cs@@ -8,6 +8,7 @@ using Xunit;namespace Microsoft.AutoGen.AgentChat.Tests;+[Trait("Category", "UnitV2")]public class RunContextStackTests{public static IRunContextLayer CreateLayer(Action<Mock<IRunContextLayer>>? setupAction = null)diff --git a/dotnet/test/Microsoft.AutoGen.AgentChat.Tests/TerminationConditionTests.cs b/dotnet/test/Microsoft.AutoGen.AgentChat.Tests/TerminationConditionTests.csnew file mode 100644index 000000000..db54e456a--- /dev/null+++ b/dotnet/test/Microsoft.AutoGen.AgentChat.Tests/TerminationConditionTests.cs@@ -0,0 +1,476 @@+// Copyright (c) Microsoft Corporation. All rights reserved.+// TerminationConditionTests.cs++using FluentAssertions;+using Microsoft.AutoGen.AgentChat.Abstractions;+using Microsoft.AutoGen.AgentChat.Terminations;+using Microsoft.Extensions.AI;+using Xunit;++namespace Microsoft.AutoGen.AgentChat.Tests;++[Trait("Category", "UnitV2")]+public static class TerminationExtensions+{+ public static async Task InvokeExpectingNullAsync<TTermination>(this TTermination termination, IList<AgentMessage> messages, bool reset = true)+ where TTermination : ITerminationCondition+ {+ (await termination.CheckAndUpdateAsync(messages)).Should().BeNull();+ termination.IsTerminated.Should().BeFalse();++ if (reset)+ {+ termination.Reset();+ }+ }++ private static readonly HashSet<string> AnonymousTerminationConditions = ["CombinerCondition", nameof(ITerminationCondition)];+ public static async Task InvokeExpectingStopAsync<TTermination>(this TTermination termination, IList<AgentMessage> messages, bool reset = true)+ where TTermination : ITerminationCondition+ {+ StopMessage? stopMessage = await termination.CheckAndUpdateAsync(messages);+ stopMessage.Should().NotBeNull();++ string name = typeof(TTermination).Name;+ if (!AnonymousTerminationConditions.Contains(name))+ {+ stopMessage!.Source.Should().Be(typeof(TTermination).Name);+ }++ termination.IsTerminated.Should().BeTrue();++ if (reset)+ {+ termination.Reset();+ }+ }++ public static async Task InvokeExpectingFailureAsync<TTermination>(this TTermination termination, IList<AgentMessage> messages, bool reset = true)+ where TTermination : ITerminationCondition+ {+ Func<Task> failureAction = () => termination.CheckAndUpdateAsync(messages).AsTask();+ await failureAction.Should().ThrowAsync<TerminatedException>();+ termination.IsTerminated.Should().BeTrue();++ if (reset)+ {+ termination.Reset();+ }+ }+}++public class TerminationConditionTests+{+ [Fact]+ public async Task Test_HandoffTermination()+ {+ HandoffTermination termination = new("target");+ termination.IsTerminated.Should().BeFalse();++ TextMessage textMessage = new() { Content = "Hello", Source = "user" };+ HandoffMessage targetHandoffMessage = new() { Target = "target", Source = "user", Context = "Hello" };+ HandoffMessage otherHandoffMessage = new() { Target = "another", Source = "user", Context = "Hello" };++ await termination.InvokeExpectingNullAsync([]);+ await termination.InvokeExpectingNullAsync([textMessage]);+ await termination.InvokeExpectingStopAsync([targetHandoffMessage]);+ await termination.InvokeExpectingNullAsync([otherHandoffMessage]);+ await termination.InvokeExpectingStopAsync([textMessage, targetHandoffMessage], reset: false);++ await termination.InvokeExpectingFailureAsync([], reset: false);++ termination.Reset();+ termination.IsTerminated.Should().BeFalse();+ }++ [Fact]+ public async Task StopMessageTermination()+ {+ StopMessageTermination termination = new();+ termination.IsTerminated.Should().BeFalse();++ TextMessage textMessage = new() { Content = "Hello", Source = "user" };+ TextMessage otherMessage = new() { Content = "World", Source = "aser" };+ StopMessage stopMessage = new() { Content = "Stop", Source = "user" };++ await termination.InvokeExpectingNullAsync([]);+ await termination.InvokeExpectingNullAsync([textMessage]);+ await termination.InvokeExpectingStopAsync([stopMessage]);+ await termination.InvokeExpectingNullAsync([textMessage, otherMessage]);+ await termination.InvokeExpectingStopAsync([textMessage, stopMessage], reset: false);++ await termination.InvokeExpectingFailureAsync([], reset: false);++ termination.Reset();+ termination.IsTerminated.Should().BeFalse();+ }++ [Fact]+ public async Task Test_TextMesssageTermination()+ {+ TextMessageTermination termination = new();+ termination.IsTerminated.Should().BeFalse();++ TextMessage userMessage = new() { Content = "Hello", Source = "user" };+ TextMessage agentMessage = new() { Content = "World", Source = "agent" };+ StopMessage stopMessage = new() { Content = "Stop", Source = "user" };++ await termination.InvokeExpectingNullAsync([]);+ await termination.InvokeExpectingStopAsync([userMessage]);+ await termination.InvokeExpectingStopAsync([agentMessage]);+ await termination.InvokeExpectingNullAsync([stopMessage]);++ termination = new("user");++ await termination.InvokeExpectingNullAsync([agentMessage]);+ await termination.InvokeExpectingNullAsync([stopMessage]);+ await termination.InvokeExpectingStopAsync([userMessage], reset: false);++ await termination.InvokeExpectingFailureAsync([], reset: false);++ termination.Reset();+ termination.IsTerminated.Should().BeFalse();+ }++ [Fact]+ public async Task MaxMessageTermination()+ {+ MaxMessageTermination termination = new(2);+ termination.IsTerminated.Should().BeFalse();++ TextMessage textMessage = new() { Content = "Hello", Source = "user" };+ TextMessage otherMessage = new() { Content = "World", Source = "agent" };+ UserInputRequestedEvent uiRequest = new() { Source = "agent", RequestId = "1" };++ await termination.InvokeExpectingNullAsync([]);+ await termination.InvokeExpectingNullAsync([textMessage]);+ await termination.InvokeExpectingStopAsync([textMessage, otherMessage]);+ await termination.InvokeExpectingNullAsync([textMessage, uiRequest]);++ termination = new(2, includeAgentEvent: true);++ await termination.InvokeExpectingStopAsync([textMessage, uiRequest], reset: false);++ await termination.InvokeExpectingFailureAsync([], reset: false);++ termination.Reset();+ termination.IsTerminated.Should().BeFalse();+ }++ [Fact]+ public async Task Test_TextMentionTermination()+ {+ TextMentionTermination termination = new("stop");+ termination.IsTerminated.Should().BeFalse();++ TextMessage textMessage = new() { Content = "Hello", Source = "user" };+ TextMessage userStopMessage = new() { Content = "stop", Source = "user" };+ TextMessage agentStopMessage = new() { Content = "stop", Source = "agent" };++ await termination.InvokeExpectingNullAsync([]);+ await termination.InvokeExpectingNullAsync([textMessage]);+ await termination.InvokeExpectingStopAsync([userStopMessage]);++ termination = new("stop", sources: ["agent"]);++ await termination.InvokeExpectingNullAsync([textMessage]);+ await termination.InvokeExpectingNullAsync([userStopMessage]);+ await termination.InvokeExpectingStopAsync([agentStopMessage], reset: false);++ await termination.InvokeExpectingFailureAsync([], reset: false);++ termination.Reset();+ termination.IsTerminated.Should().BeFalse();+ }++ [Fact]+ public async Task Text_TokenUsageTermination()+ {+ TokenUsageTermination termination = new(10);+ termination.IsTerminated.Should().BeFalse();++ RequestUsage usage_10_10 = new() { CompletionTokens = 10, PromptTokens = 10 };+ RequestUsage usage_01_01 = new() { CompletionTokens = 1, PromptTokens = 1 };+ RequestUsage usage_05_00 = new() { CompletionTokens = 5, PromptTokens = 0 };+ RequestUsage usage_00_05 = new() { CompletionTokens = 0, PromptTokens = 5 };++ await termination.InvokeExpectingNullAsync([]);++ await termination.InvokeExpectingStopAsync([+ new TextMessage { Content = "Hello", Source = "user", ModelUsage = usage_10_10 },+ ]);++ await termination.InvokeExpectingNullAsync([+ new TextMessage { Content = "Hello", Source = "user", ModelUsage = usage_01_01 },+ new TextMessage { Content = "World", Source = "agent", ModelUsage = usage_01_01 },+ ]);++ await termination.InvokeExpectingStopAsync([+ new TextMessage { Content = "Hello", Source = "user", ModelUsage = usage_05_00 },+ new TextMessage { Content = "World", Source = "agent", ModelUsage = usage_00_05 },+ ], reset: false);++ await termination.InvokeExpectingFailureAsync([], reset: false);++ termination.Reset();+ termination.IsTerminated.Should().BeFalse();+ }++ public class AgentTextEvent : AgentEvent+ {+ public required string Content { get; set; }++ public override Extensions.AI.ChatMessage ToCompletionClientMessage(ChatRole role)+ {+ return new Extensions.AI.ChatMessage(ChatRole.Assistant, this.Content);+ }+ }++ [Fact]+ public async Task Text_Termination_AndCombinator()+ {+ ITerminationCondition lhsClause = new MaxMessageTermination(2);+ ITerminationCondition rhsClause = new TextMentionTermination("stop");++ ITerminationCondition termination = lhsClause & rhsClause;+ termination.IsTerminated.Should().BeFalse();++ TextMessage userMessage = new() { Content = "Hello", Source = "user" };+ AgentTextEvent agentMessage = new() { Content = "World", Source = "agent" };++ TextMessage userStopMessage = new() { Content = "stop", Source = "user" };++ await termination.InvokeExpectingNullAsync([]);++ await termination.InvokeExpectingNullAsync([userMessage]);++ await termination.InvokeExpectingNullAsync([userMessage, agentMessage], reset: false);+ lhsClause.IsTerminated.Should().BeFalse();+ rhsClause.IsTerminated.Should().BeFalse();++ await termination.InvokeExpectingStopAsync([userStopMessage], reset: false);++ lhsClause.IsTerminated.Should().BeTrue();+ rhsClause.IsTerminated.Should().BeTrue();+ termination.IsTerminated.Should().BeTrue();++ await termination.InvokeExpectingFailureAsync([], reset: false);++ lhsClause.IsTerminated.Should().BeTrue();+ rhsClause.IsTerminated.Should().BeTrue();+ termination.IsTerminated.Should().BeTrue();++ termination.Reset();+ termination.IsTerminated.Should().BeFalse();++ await termination.InvokeExpectingNullAsync([userMessage, agentMessage], reset: false);+ lhsClause.IsTerminated.Should().BeFalse();+ rhsClause.IsTerminated.Should().BeFalse();++ await termination.InvokeExpectingNullAsync([userMessage], reset: false);++ lhsClause.IsTerminated.Should().BeTrue();+ rhsClause.IsTerminated.Should().BeFalse();+ termination.IsTerminated.Should().BeFalse();++ await termination.InvokeExpectingNullAsync([userMessage], reset: false);++ lhsClause.IsTerminated.Should().BeTrue();+ rhsClause.IsTerminated.Should().BeFalse();+ termination.IsTerminated.Should().BeFalse();++ await termination.InvokeExpectingStopAsync([userStopMessage], reset: false);++ lhsClause.IsTerminated.Should().BeTrue();+ rhsClause.IsTerminated.Should().BeTrue();+ termination.IsTerminated.Should().BeTrue();++ await termination.InvokeExpectingFailureAsync([], reset: false);++ lhsClause.IsTerminated.Should().BeTrue();+ rhsClause.IsTerminated.Should().BeTrue();+ termination.IsTerminated.Should().BeTrue();++ termination.Reset();+ termination.IsTerminated.Should().BeFalse();++ await termination.InvokeExpectingNullAsync([agentMessage, userStopMessage], reset: false);++ lhsClause.IsTerminated.Should().BeFalse();+ rhsClause.IsTerminated.Should().BeTrue();+ termination.IsTerminated.Should().BeFalse();++ await termination.InvokeExpectingStopAsync([userMessage], reset: false);+ lhsClause.IsTerminated.Should().BeTrue();+ rhsClause.IsTerminated.Should().BeTrue();+ termination.IsTerminated.Should().BeTrue();++ await termination.InvokeExpectingFailureAsync([], reset: false);+ lhsClause.IsTerminated.Should().BeTrue();+ rhsClause.IsTerminated.Should().BeTrue();+ termination.IsTerminated.Should().BeTrue();++ termination.Reset();+ termination.IsTerminated.Should().BeFalse();+ }++ [Fact]+ public async Task Test_Termination_OrCombiner()+ {+ ITerminationCondition lhsClause = new MaxMessageTermination(3);+ ITerminationCondition rhsClause = new TextMentionTermination("stop");++ ITerminationCondition termination = lhsClause | rhsClause;+ termination.IsTerminated.Should().BeFalse();++ TextMessage userMessage = new() { Content = "Hello", Source = "user" };+ AgentTextEvent agentMessage = new() { Content = "World", Source = "agent" };+ TextMessage userStopMessage = new() { Content = "stop", Source = "user" };++ await termination.InvokeExpectingNullAsync([]);+ await termination.InvokeExpectingNullAsync([userMessage]);+ await termination.InvokeExpectingNullAsync([userMessage, agentMessage]);++ await termination.InvokeExpectingNullAsync([userMessage, agentMessage, userMessage], reset: false);+ lhsClause.IsTerminated.Should().BeFalse();+ rhsClause.IsTerminated.Should().BeFalse();+ termination.IsTerminated.Should().BeFalse();++ termination.Reset();+ termination.IsTerminated.Should().BeFalse();++ await termination.InvokeExpectingStopAsync([userMessage, agentMessage, userStopMessage], reset: false);+ lhsClause.IsTerminated.Should().BeFalse();+ rhsClause.IsTerminated.Should().BeTrue();+ termination.IsTerminated.Should().BeTrue();++ await termination.InvokeExpectingFailureAsync([], reset: false);+ lhsClause.IsTerminated.Should().BeFalse();+ rhsClause.IsTerminated.Should().BeTrue();+ termination.IsTerminated.Should().BeTrue();++ termination.Reset();+ termination.IsTerminated.Should().BeFalse();++ await termination.InvokeExpectingStopAsync([userMessage, userMessage, userMessage], reset: false);+ lhsClause.IsTerminated.Should().BeTrue();+ rhsClause.IsTerminated.Should().BeFalse();+ termination.IsTerminated.Should().BeTrue();++ await termination.InvokeExpectingFailureAsync([], reset: false);+ lhsClause.IsTerminated.Should().BeTrue();+ rhsClause.IsTerminated.Should().BeFalse();+ termination.IsTerminated.Should().BeTrue();++ termination.Reset();+ termination.IsTerminated.Should().BeFalse();+ }++ [Fact]+ public async Task Test_TimeoutTermination()+ {+ TextMessage userMessage = new() { Content = "Hello", Source = "user" };++ TimeoutTermination termination = new(0.15f);+ termination.IsTerminated.Should().BeFalse();++ await termination.InvokeExpectingNullAsync([]);++ await Task.Delay(TimeSpan.FromSeconds(0.20f));++ await termination.InvokeExpectingStopAsync([], reset: false);++ await termination.InvokeExpectingFailureAsync([], reset: false);++ termination.Reset();+ termination.IsTerminated.Should().BeFalse();++ await termination.InvokeExpectingNullAsync([userMessage]);++ await Task.Delay(TimeSpan.FromSeconds(0.20f));++ await termination.InvokeExpectingStopAsync([], reset: false);+ }++ [Fact]+ public async Task Test_ExternalTermination()+ {+ ExternalTermination termination = new();+ termination.IsTerminated.Should().BeFalse();++ TextMessage userMessage = new() { Content = "Hello", Source = "user" };++ await termination.InvokeExpectingNullAsync([]);+ await termination.InvokeExpectingNullAsync([userMessage]);++ termination.Set();+ termination.IsTerminated.Should().BeFalse(); // We only terminate on the next check++ await termination.InvokeExpectingStopAsync([], reset: false);+ await termination.InvokeExpectingFailureAsync([], reset: false);++ termination.Reset();+ termination.IsTerminated.Should().BeFalse();++ await termination.InvokeExpectingNullAsync([userMessage]);+ }++ private ToolCallRequestEvent CreateFunctionRequest(string functionName, string id = "1", string arguments = "")+ {+ ToolCallRequestEvent result = new ToolCallRequestEvent+ {+ Source = "agent"+ };++ result.Content.Add(+ new FunctionCall+ {+ Id = id,+ Name = functionName,+ Arguments = arguments,+ });++ return result;+ }++ private ToolCallExecutionEvent CreateFunctionResponse(string functionName, string id = "1", string content = "")+ {+ ToolCallExecutionEvent result = new ToolCallExecutionEvent+ {+ Source = "agent"+ };++ result.Content.Add(+ new FunctionExecutionResult+ {+ Id = id,+ Name = functionName,+ Content = content,+ });++ return result;+ }++ [Fact]+ public async Task Test_FunctionCallTermination()+ {+ FunctionCallTermination termination = new("test_function");+ termination.IsTerminated.Should().BeFalse();++ TextMessage userMessage = new() { Content = "Hello", Source = "user" };+ ToolCallRequestEvent toolCallRequest = CreateFunctionRequest("test_function");+ ToolCallExecutionEvent testExecution = CreateFunctionResponse("test_function");+ ToolCallExecutionEvent otherExecution = CreateFunctionResponse("other_function");++ await termination.InvokeExpectingNullAsync([]);+ await termination.InvokeExpectingNullAsync([userMessage]);+ await termination.InvokeExpectingNullAsync([toolCallRequest]);+ await termination.InvokeExpectingNullAsync([otherExecution]);+ await termination.InvokeExpectingStopAsync([testExecution], reset: false);++ await termination.InvokeExpectingFailureAsync([], reset: false);++ termination.Reset();+ termination.IsTerminated.Should().BeFalse();+ }+}