Skip to content

A programming framework for agentic AI

feat: Enable Reset in AgentChat.NET (#5855)

Jacob Alber05b14f197aa1
diff --git a/dotnet/src/Microsoft.AutoGen/AgentChat/GroupChat/ChatAgentRouter.cs b/dotnet/src/Microsoft.AutoGen/AgentChat/GroupChat/ChatAgentRouter.cs
index a195cd4d6..443cf8315 100644
--- a/dotnet/src/Microsoft.AutoGen/AgentChat/GroupChat/ChatAgentRouter.cs
+++ b/dotnet/src/Microsoft.AutoGen/AgentChat/GroupChat/ChatAgentRouter.cs
@@ -66,7 +66,6 @@ internal sealed class ChatAgentRouter : HostableAgentAdapter,
// place.
await foreach (ChatStreamFrame frame in this.agent.StreamAsync(this.MessageBuffer, messageContext.CancellationToken))
{
- // TODO: call publish message
switch (frame.Type)
{
case ChatStreamFrame.FrameType.Response:
diff --git a/dotnet/src/Microsoft.AutoGen/AgentChat/GroupChat/GroupChatBase.cs b/dotnet/src/Microsoft.AutoGen/AgentChat/GroupChat/GroupChatBase.cs
index f6ec12ca8..c21a89e66 100644
--- a/dotnet/src/Microsoft.AutoGen/AgentChat/GroupChat/GroupChatBase.cs
+++ b/dotnet/src/Microsoft.AutoGen/AgentChat/GroupChat/GroupChatBase.cs
@@ -78,7 +78,8 @@ public abstract class GroupChatBase<TManager> : ITeam where TManager : GroupChat
private GroupChatOptions GroupChatOptions { get; }
- private readonly List<AgentMessage> messageThread = new();
+ private readonly RuntimeLayer runtimeLayer;
+
private Dictionary<string, AgentChatConfig> Participants { get; } = new();
protected GroupChatBase(List<IChatAgent> participants, ITerminationCondition? terminationCondition = null, int? maxTurns = null)
@@ -96,9 +97,10 @@ public abstract class GroupChatBase<TManager> : ITeam where TManager : GroupChat
this.GroupChatOptions.Participants[participant.Name] = new GroupParticipant(config.ParticipantTopicType, participant.Description);
}
- this.messageThread = new List<AgentMessage>(); // TODO: Allow injecting this
-
this.TeamId = Guid.NewGuid().ToString().ToLowerInvariant();
+
+ this.runtimeLayer = new RuntimeLayer(this);
+ this.RunManager = new(this.InitializationLayersInternal);
}
public string TeamId
@@ -128,18 +130,57 @@ public abstract class GroupChatBase<TManager> : ITeam where TManager : GroupChat
throw new Exception("Could not create chat manager; make sure that it contains a ctor() or ctor(GroupChatOptions), or override the CreateChatManager method");
}
- // TODO: Turn this into an IDisposable-based utility
- private int running; // = 0
- private bool EnsureSingleRun()
+ private sealed class RuntimeLayer(GroupChatBase<TManager> groupChat) : IRunContextLayer
{
- return Interlocked.CompareExchange(ref running, 1, 0) == 0;
- }
+ public GroupChatBase<TManager> GroupChat { get; } = groupChat;
+ public InProcessRuntime? Runtime { get; private set; }
+ public OutputSink? OutputSink { get; private set; }
- private void EndRun()
- {
- this.running = 0;
+ public Task? InitOnceTask { get; set; }
+ public Task ShutdownTask { get; set; } = Task.CompletedTask;
+
+ public async ValueTask DeinitializeAsync()
+ {
+ await this.ShutdownTask;
+ }
+
+ private async Task CreateRuntime()
+ {
+ this.Runtime = new InProcessRuntime();
+
+ foreach (AgentChatConfig config in this.GroupChat.Participants.Values)
+ {
+ await this.Runtime.RegisterChatAgentAsync(config);
+ }
+
+ await this.Runtime.RegisterGroupChatManagerAsync(this.GroupChat.GroupChatOptions, this.GroupChat.TeamId, this.GroupChat.CreateChatManager);
+
+ this.OutputSink = new OutputSink();
+ await this.Runtime.RegisterOutputCollectorAsync(this.OutputSink, this.GroupChat.GroupChatOptions.OutputTopicType);
+ }
+
+ public async ValueTask InitializeAsync()
+ {
+ if (this.InitOnceTask == null)
+ {
+ this.InitOnceTask = this.CreateRuntime();
+ }
+
+ await this.InitOnceTask;
+
+ await this.Runtime!.StartAsync();
+ }
}
+ private IRunContextLayer[] InitializationLayersInternal =>
+ [
+ this.runtimeLayer, ..this.InitializationLayers
+ ];
+
+ protected virtual IEnumerable<IRunContextLayer> InitializationLayers => [];
+
+ private RunManager RunManager { get; }
+
public IAsyncEnumerable<TaskFrame> StreamAsync(string task, CancellationToken cancellationToken)
{
if (String.IsNullOrEmpty(task))
@@ -157,79 +198,99 @@ public abstract class GroupChatBase<TManager> : ITeam where TManager : GroupChat
return this.StreamAsync(taskStart, cancellationToken);
}
- public ValueTask ResetAsync(CancellationToken cancel)
+ private InProcessRuntime? Runtime => this.runtimeLayer.Runtime;
+ private OutputSink? OutputSink => this.runtimeLayer.OutputSink;
+
+ private Task ShutdownTask
{
- return ValueTask.CompletedTask;
+ get => this.runtimeLayer.ShutdownTask;
+ set => this.runtimeLayer.ShutdownTask = value;
}
- public async IAsyncEnumerable<TaskFrame> StreamAsync(ChatMessage? task, [EnumeratorCancellation] CancellationToken cancellationToken = default)
+ private Func<CancellationToken, ValueTask> PrepareStream(ChatMessage task)
{
- if (task == null)
+ GroupChatStart taskMessage = new GroupChatStart
{
- throw new ArgumentNullException(nameof(task));
- }
+ Messages = [task]
+ };
- if (!this.EnsureSingleRun())
+ return async (CancellationToken cancellationToken) =>
{
- throw new InvalidOperationException("The task is already running.");
- }
+ AgentId chatManagerId = new AgentId(GroupChatManagerTopicType, this.TeamId);
+ await this.Runtime!.SendMessageAsync(taskMessage, chatManagerId, cancellationToken: cancellationToken);
+ this.ShutdownTask = Task.Run(this.Runtime!.RunUntilIdleAsync);
+ };
+ }
- // TODO: How do we allow the user to configure this?
- //AgentsAppBuilder builder = new AgentsAppBuilder().UseInProcessRuntime();
- InProcessRuntime runtime = new InProcessRuntime();
+ private async IAsyncEnumerable<TaskFrame> StreamOutput([EnumeratorCancellation] CancellationToken cancellationToken)
+ {
+ List<AgentMessage> runMessages = new();
- foreach (AgentChatConfig config in this.Participants.Values)
+ while (true)
{
- await runtime.RegisterChatAgentAsync(config);
- }
+ OutputSink.SinkFrame frame = await this.OutputSink!.WaitForDataAsync(cancellationToken);
+ runMessages.AddRange(frame.Messages);
- await runtime.RegisterGroupChatManagerAsync(this.GroupChatOptions, this.TeamId, this.CreateChatManager);
+ foreach (AgentMessage message in frame.Messages)
+ {
+ yield return new TaskFrame(message);
+ }
- OutputSink outputSink = new OutputSink();
- await runtime.RegisterOutputCollectorAsync(outputSink, this.GroupChatOptions.OutputTopicType);
+ if (frame.IsTerminal)
+ {
+ TaskResult result = new TaskResult(runMessages);
+ yield return new TaskFrame(result);
+ break;
+ }
+ }
+ }
- await runtime.StartAsync();
+ public IAsyncEnumerable<TaskFrame> StreamAsync(ChatMessage? task, CancellationToken cancellationToken = default)
+ {
+ if (task == null)
+ {
+ throw new ArgumentNullException(nameof(task));
+ }
- Task shutdownTask = Task.CompletedTask;
+ const string TaskAlreadyRunning = "The task is already running";
+ return this.RunManager.StreamAsync(
+ this.StreamOutput,
+ cancellationToken,
+ this.PrepareStream(task),
+ TaskAlreadyRunning);
+ }
+ private async ValueTask ResetInternalAsync(CancellationToken cancel)
+ {
try
{
- // TODO: Protos
- GroupChatStart taskMessage = new GroupChatStart
+ foreach (var participant in this.Participants.Values)
{
- Messages = [task]
- };
-
- List<AgentMessage> runMessages = new();
-
- AgentId chatManagerId = new AgentId(GroupChatManagerTopicType, this.TeamId);
- await runtime.SendMessageAsync(taskMessage, chatManagerId, cancellationToken: cancellationToken);
+ await this.Runtime!.SendMessageAsync(
+ new GroupChatReset(),
+ new AgentId(participant.ParticipantTopicType, this.TeamId),
+ cancellationToken: cancel);
+ }
- shutdownTask = Task.Run(runtime.RunUntilIdleAsync);
+ await this.Runtime!.SendMessageAsync(
+ new GroupChatReset(),
+ new AgentId(GroupChatManagerTopicType, this.TeamId),
+ cancellationToken: cancel);
- while (true)
- {
- OutputSink.SinkFrame frame = await outputSink.WaitForDataAsync(cancellationToken);
- runMessages.AddRange(frame.Messages);
-
- foreach (AgentMessage message in frame.Messages)
- {
- yield return new TaskFrame(message);
- }
-
- if (frame.IsTerminal)
- {
- TaskResult result = new TaskResult(runMessages);
- yield return new TaskFrame(result);
- break;
- }
- }
+ await this.Runtime!.RunUntilIdleAsync();
}
finally
{
- this.EndRun();
-
- await shutdownTask;
+ this.OutputSink?.Reset();
}
}
+
+ public ValueTask ResetAsync(CancellationToken cancel)
+ {
+ const string TaskAlreadyRunning = "The group chat is currently running. It must be stopped before it can be reset.";
+ return this.RunManager.RunAsync(
+ this.ResetInternalAsync,
+ cancel,
+ message: TaskAlreadyRunning);
+ }
}
diff --git a/dotnet/src/Microsoft.AutoGen/AgentChat/GroupChat/OutputCollectorAgent.cs b/dotnet/src/Microsoft.AutoGen/AgentChat/GroupChat/OutputCollectorAgent.cs
index 3c9fd6101..845bdce74 100644
--- a/dotnet/src/Microsoft.AutoGen/AgentChat/GroupChat/OutputCollectorAgent.cs
+++ b/dotnet/src/Microsoft.AutoGen/AgentChat/GroupChat/OutputCollectorAgent.cs
@@ -82,6 +82,14 @@ internal sealed class OutputSink : IOutputCollectionSink
await this.semapohre.WaitAsync(cancellation);
}
}
+
+ internal void Reset()
+ {
+ lock (this.sync)
+ {
+ this.receivingSinkFrame = null;
+ }
+ }
}
// TODO: Abstract the core logic of this out into the equivalent of ClosureAgent, because that seems like a
diff --git a/dotnet/src/Microsoft.AutoGen/AgentChat/GroupChat/RunContext.cs b/dotnet/src/Microsoft.AutoGen/AgentChat/GroupChat/RunContext.cs
new file mode 100644
index 000000000..3dc09add0
--- /dev/null
+++ b/dotnet/src/Microsoft.AutoGen/AgentChat/GroupChat/RunContext.cs
@@ -0,0 +1,297 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// RunContext.cs
+
+using System.Diagnostics;
+using System.Runtime.CompilerServices;
+
+namespace Microsoft.AutoGen.AgentChat.GroupChat;
+
+public abstract class LifecycleObject
+{
+ private int initialized;
+
+ private void PrepareInitialize(Action errorAction)
+ {
+ if (Interlocked.CompareExchange(ref this.initialized, 1, 0) != 0)
+ {
+ errorAction();
+ }
+ }
+
+ private void PrepareDeinitialize(Action errorAction)
+ {
+ if (Interlocked.CompareExchange(ref this.initialized, 0, 1) != 1)
+ {
+ errorAction();
+ }
+ }
+
+ protected bool IsInitialized => Volatile.Read(ref this.initialized) == 1;
+
+ protected virtual void OnInitializeError() => throw new InvalidOperationException($"Error initializing: {this.GetType().FullName}; already initialized.");
+ protected virtual void OnDeinitializeError() => throw new InvalidOperationException($"Error deinitializing: {this.GetType().FullName}; not initialized.");
+
+ public ValueTask InitializeAsync()
+ {
+ this.PrepareInitialize(this.OnInitializeError);
+ return this.InitializeCore();
+ }
+
+ public ValueTask DeinitializeAsync()
+ {
+ this.PrepareDeinitialize(this.OnDeinitializeError);
+ return this.DeinitializeCore();
+ }
+
+ protected abstract ValueTask InitializeCore();
+ protected abstract ValueTask DeinitializeCore();
+}
+
+public interface IRunContextLayer
+{
+ public ValueTask InitializeAsync();
+ public ValueTask DeinitializeAsync();
+}
+
+public sealed class RunContextStack : LifecycleObject, IRunContextLayer
+{
+ private Stack<IRunContextLayer> Uninitialized { get; } = new();
+ private Stack<IRunContextLayer> Initialized { get; } = new();
+
+ public RunContextStack(params IEnumerable<IRunContextLayer> contextLayers)
+ {
+ this.Uninitialized = new Stack<IRunContextLayer>(contextLayers);
+ }
+
+ // TODO: There is probably a way to have a sound manner by which pushing/popping a layer when initialized
+ // would be allowed. But this is not necessary for now, so we will keep it simple.
+ public void PushLayer(IRunContextLayer layer)
+ {
+ if (this.IsInitialized)
+ {
+ throw new InvalidOperationException("Cannot push a layer while the context is initialized.");
+ }
+
+ this.Uninitialized.Push(layer);
+ }
+
+ public void PopLayer()
+ {
+ if (this.IsInitialized)
+ {
+ throw new InvalidOperationException("Cannot pop a layer while the context is initialized.");
+ }
+ }
+
+ private Action? initializeError;
+ protected override void OnInitializeError()
+ {
+ (this.initializeError ?? base.OnInitializeError)();
+ }
+
+ private Action? deinitializeError;
+ protected override void OnDeinitializeError()
+ {
+ (this.deinitializeError ?? base.OnDeinitializeError)();
+ }
+
+ public static IRunContextLayer OverrideErrors(Action? initializeError = null, Action? deinitializeError = null)
+ {
+ return new ErrorOverrideLayer(initializeError, deinitializeError);
+ }
+
+ private sealed class ErrorOverrideLayer(Action? initializeError = null, Action? deinitializeError = null)
+ : IRunContextLayer
+ {
+ public RunContextStack? Target { get; set; }
+
+ private Action? initializeErrorPrev;
+ private Action? deinitializeErrorPrev;
+
+ public ValueTask InitializeAsync()
+ {
+ if (initializeError != null)
+ {
+ this.initializeErrorPrev = Interlocked.CompareExchange(ref this.Target!.initializeError, initializeError, null);
+ }
+
+ if (deinitializeError != null)
+ {
+ this.deinitializeErrorPrev = Interlocked.CompareExchange(ref this.Target!.deinitializeError, deinitializeError, null);
+ }
+
+ return ValueTask.CompletedTask;
+ }
+
+ public ValueTask DeinitializeAsync()
+ {
+ if (this.initializeErrorPrev != null)
+ {
+ Interlocked.CompareExchange(ref this.Target!.initializeError, this.initializeErrorPrev, initializeError);
+ }
+
+ if (this.deinitializeErrorPrev != null)
+ {
+ Interlocked.CompareExchange(ref this.Target!.deinitializeError, this.deinitializeErrorPrev, deinitializeError);
+ }
+
+ return ValueTask.CompletedTask;
+ }
+ }
+
+ public ValueTask<IAsyncDisposable> Enter()
+ {
+ return RunTicket.Enter(this);
+ }
+
+ protected override async ValueTask InitializeCore()
+ {
+ while (this.Uninitialized.Count > 0)
+ {
+ IRunContextLayer layer = this.Uninitialized.Pop();
+ if (layer is ErrorOverrideLayer errorOverrideLayer)
+ {
+ errorOverrideLayer.Target = this;
+ }
+
+ await layer.InitializeAsync();
+ this.Initialized.Push(layer);
+ }
+ }
+
+ protected override async ValueTask DeinitializeCore()
+ {
+ while (this.Initialized.Count > 0)
+ {
+ IRunContextLayer layer = this.Initialized.Pop();
+ await layer.DeinitializeAsync();
+ this.Uninitialized.Push(layer);
+ }
+ }
+
+ private sealed class RunTicket : IAsyncDisposable
+ {
+ private RunContextStack contextStack;
+ private int disposed;
+
+ private RunTicket(RunContextStack contextStack)
+ {
+ Debug.Assert(contextStack.IsInitialized, "The context stack must be initialized.");
+ this.contextStack = contextStack;
+ }
+
+ public static async ValueTask<IAsyncDisposable> Enter(RunContextStack contextStack)
+ {
+ await contextStack.InitializeAsync();
+ return new RunTicket(contextStack);
+ }
+
+ public ValueTask DisposeAsync()
+ {
+ if (Interlocked.CompareExchange(ref this.disposed, 1, 0) == 0)
+ {
+ return this.contextStack.DeinitializeAsync();
+ }
+
+ return ValueTask.CompletedTask;
+ }
+ }
+}
+
+public sealed class RunManager
+{
+ private RunContextStack runContextStack;
+
+ public RunManager(params IEnumerable<IRunContextLayer> contextLayers)
+ {
+ this.runContextStack = new RunContextStack(contextLayers);
+ }
+
+ private ValueTask<IAsyncDisposable> PrepareRunAsync(string? message = null)
+ {
+ if (message != null)
+ {
+ IRunContextLayer errorOverride = RunContextStack.OverrideErrors(() => throw new InvalidOperationException(message));
+ this.runContextStack.PushLayer(errorOverride);
+ }
+
+ return this.runContextStack.Enter();
+ }
+
+ private async ValueTask EndRunAsync(IAsyncDisposable? runDisposable, bool hadMessage)
+ {
+ if (runDisposable != null)
+ {
+ await runDisposable.DisposeAsync().ConfigureAwait(false);
+ }
+
+ if (hadMessage)
+ {
+ this.runContextStack.PopLayer();
+ }
+ }
+
+ public async ValueTask RunAsync(Func<CancellationToken, ValueTask> asyncAction, CancellationToken cancellation = default, Func<CancellationToken, ValueTask>? prepareAction = null, string? message = null)
+ {
+ IAsyncDisposable? runDisposable = null;
+ try
+ {
+ runDisposable = await this.PrepareRunAsync(message).ConfigureAwait(false);
+
+ if (prepareAction != null)
+ {
+ await prepareAction(cancellation).ConfigureAwait(false);
+ }
+
+ await asyncAction(cancellation).ConfigureAwait(false);
+ }
+ finally
+ {
+ await this.EndRunAsync(runDisposable, message != null).ConfigureAwait(false);
+ }
+ }
+
+ public async ValueTask<T> RunAsync<T>(Func<CancellationToken, ValueTask<T>> asyncAction, CancellationToken cancellation = default, Func<CancellationToken, ValueTask>? prepareAction = null, string? message = null)
+ {
+ IAsyncDisposable? runDisposable = null;
+ try
+ {
+ runDisposable = await this.PrepareRunAsync(message).ConfigureAwait(false);
+
+ if (prepareAction != null)
+ {
+ await prepareAction(cancellation).ConfigureAwait(false);
+ }
+
+ return await asyncAction(cancellation).ConfigureAwait(false);
+ }
+ finally
+ {
+ await this.EndRunAsync(runDisposable, message != null).ConfigureAwait(false);
+ }
+ }
+
+ public async IAsyncEnumerable<TItem> StreamAsync<TItem>(Func<CancellationToken, IAsyncEnumerable<TItem>> streamAction, [EnumeratorCancellation] CancellationToken cancellation = default, Func<CancellationToken, ValueTask>? prepareAction = null, string? message = null)
+ {
+ IAsyncDisposable? runDisposable = null;
+ try
+ {
+ runDisposable = await this.PrepareRunAsync(message).ConfigureAwait(false);
+
+ if (prepareAction != null)
+ {
+ await prepareAction(cancellation).ConfigureAwait(false);
+ }
+
+ await foreach (TItem item in streamAction(cancellation))
+ {
+ yield return item;
+ }
+ }
+ finally
+ {
+ await this.EndRunAsync(runDisposable, message != null).ConfigureAwait(false);
+ }
+ }
+}
+
diff --git a/dotnet/src/Microsoft.AutoGen/Core/InProcessRuntime.cs b/dotnet/src/Microsoft.AutoGen/Core/InProcessRuntime.cs
index fdd390d2d..21baa25e0 100644
--- a/dotnet/src/Microsoft.AutoGen/Core/InProcessRuntime.cs
+++ b/dotnet/src/Microsoft.AutoGen/Core/InProcessRuntime.cs
@@ -300,12 +300,15 @@ public sealed class InProcessRuntime : IAgentRuntime, IHostedService
return ValueTask.CompletedTask;
}
- public Task RunUntilIdleAsync()
+ public async Task RunUntilIdleAsync()
{
+ Func<bool> oldShouldContinue = this.shouldContinue;
this.shouldContinue = () => !this.messageDeliveryQueue.IsEmpty;
// TODO: Do we want detach semantics?
- return this.messageDeliveryTask;
+ await this.messageDeliveryTask;
+
+ this.shouldContinue = oldShouldContinue;
}
private async Task FinishAsync(CancellationToken token)
@@ -317,6 +320,9 @@ public sealed class InProcessRuntime : IAgentRuntime, IHostedService
await agent.CloseAsync();
}
}
+
+ this.shutdownSource = null;
+ this.finishSource = null;
}
Task IHostedService.StartAsync(CancellationToken cancellationToken) => this.StartAsync(cancellationToken).AsTask();
diff --git a/dotnet/test/Microsoft.AutoGen.AgentChat.Tests/AgentChatSmokeTest.cs b/dotnet/test/Microsoft.AutoGen.AgentChat.Tests/AgentChatSmokeTest.cs
index 018f80cae..072bf1b5a 100644
--- a/dotnet/test/Microsoft.AutoGen.AgentChat.Tests/AgentChatSmokeTest.cs
+++ b/dotnet/test/Microsoft.AutoGen.AgentChat.Tests/AgentChatSmokeTest.cs
@@ -84,23 +84,42 @@ public class AgentChatSmokeTest
}
}
- [Fact]
- public async Task Test_RoundRobin_SpeakAndTerminating()
+ private ValueTask<TaskResult> RunChatAsync(TerminatingAgent terminatingAgent, out ITeam chat)
{
- TerminatingAgent terminatingAgent = new("Terminate", "Terminate");
-
- ITeam chat = new RoundRobinGroupChat(
+ chat = new RoundRobinGroupChat(
[
new SpeakMessageAgent("Speak", "Speak", "Hello"),
terminatingAgent
],
terminationCondition: new StopMessageTermination());
- TaskResult result = await chat.RunAsync("");
+ return chat.RunAsync("");
+ }
+
+ [Fact]
+ public async Task Test_RoundRobin_SpeakAndTerminating()
+ {
+ TerminatingAgent terminatingAgent = new("Terminate", "Terminate");
+
+ TaskResult result = await this.RunChatAsync(terminatingAgent, out _);
Assert.Equal(3, result.Messages.Count);
Assert.Equal("", Assert.IsType<TextMessage>(result.Messages[0]).Content);
Assert.Equal("Hello", Assert.IsType<TextMessage>(result.Messages[1]).Content);
Assert.Equal("Terminating; got: Hello", Assert.IsType<StopMessage>(result.Messages[2]).Content);
}
+
+ [Fact]
+ public async Task Test_RoundRobin_SpeakTerminateReset()
+ {
+ TerminatingAgent terminatingAgent = new("Terminate", "Terminate");
+
+ await this.RunChatAsync(terminatingAgent, out ITeam chat);
+
+ Assert.NotNull(terminatingAgent.IncomingMessages);
+
+ await chat.ResetAsync();
+
+ Assert.Null(terminatingAgent.IncomingMessages);
+ }
}
diff --git a/dotnet/test/Microsoft.AutoGen.AgentChat.Tests/LifecycleObjectTests.cs b/dotnet/test/Microsoft.AutoGen.AgentChat.Tests/LifecycleObjectTests.cs
new file mode 100644
index 000000000..4e8f4cdc5
--- /dev/null
+++ b/dotnet/test/Microsoft.AutoGen.AgentChat.Tests/LifecycleObjectTests.cs
@@ -0,0 +1,193 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// LifecycleObjectTests.cs
+
+using FluentAssertions;
+using Microsoft.AutoGen.AgentChat.GroupChat;
+using Xunit;
+
+namespace Microsoft.AutoGen.AgentChat.Tests;
+
+internal sealed class LifecycleObjectFixture : LifecycleObject
+{
+ public enum LifecycleState
+ {
+ Deinitialized,
+ Initialized
+ }
+
+ public LifecycleState State { get; private set; }
+
+ public Func<ValueTask> DeinitializeOverride { get; set; } = () => ValueTask.CompletedTask;
+ public Func<ValueTask> InitializeOverride { get; set; } = () => ValueTask.CompletedTask;
+
+ public Action InitializeErrorOverride { get; set; }
+ public Action DeinitializeErrorOverride { get; set; }
+
+ private int initializeCallCount;
+ private int deinitializeCallCount;
+ private int initializeErrorCount;
+ private int deinitializeErrorCount;
+
+ public int InitializeCallCount => this.initializeCallCount;
+ public int DeinitializeCallCount => this.deinitializeCallCount;
+ public int InitializeErrorCount => this.initializeErrorCount;
+ public int DeinitializeErrorCount => this.deinitializeErrorCount;
+
+ public LifecycleObjectFixture()
+ {
+ this.State = LifecycleState.Deinitialized;
+
+ this.InitializeErrorOverride = base.OnInitializeError;
+ this.DeinitializeErrorOverride = base.OnDeinitializeError;
+ }
+
+ protected override void OnInitializeError()
+ {
+ Interlocked.Increment(ref this.initializeErrorCount);
+
+ this.InitializeErrorOverride();
+ }
+
+ protected override void OnDeinitializeError()
+ {
+ Interlocked.Increment(ref this.deinitializeErrorCount);
+
+ this.DeinitializeErrorOverride();
+ }
+
+ protected sealed override ValueTask DeinitializeCore()
+ {
+ Interlocked.Increment(ref this.deinitializeCallCount);
+ this.State = LifecycleState.Deinitialized;
+
+ return DeinitializeOverride();
+ }
+
+ protected sealed override ValueTask InitializeCore()
+ {
+ Interlocked.Increment(ref this.initializeCallCount);
+ this.State = LifecycleState.Initialized;
+
+ return InitializeOverride();
+ }
+}
+
+public class LifecycleObjectTests
+{
+ /*
+ We should be testing the following conditions:
+ - SmokeTest: Happy path: Initialize, Deinitialize, Initialize, Deinitialize, validate states and call counts
+ - Error handling: Initialize, Initialize; Deinitialize; Initialize, Deinitialize, Deinitialize
+ */
+
+ [Fact]
+ public async Task InitializeAndDeinitialize_SucceedsTwice()
+ {
+ // Arrange
+ LifecycleObjectFixture fixture = new();
+
+ // Validate preconditions
+ fixture.State.Should().Be(LifecycleObjectFixture.LifecycleState.Deinitialized, "LifecycleObject should be in Deinitialized state initially");
+ fixture.InitializeCallCount.Should().Be(0, "Initialize should not have been called yet");
+ fixture.DeinitializeCallCount.Should().Be(0, "Deinitialize should not have been called yet");
+ fixture.InitializeErrorCount.Should().Be(0, "there should be no initialization errors");
+ fixture.DeinitializeErrorCount.Should().Be(0, "there should be no deinitialization errors");
+
+ // Act
+ await fixture.InitializeAsync();
+
+ // Validate postconditions 1
+ fixture.State.Should().Be(LifecycleObjectFixture.LifecycleState.Initialized, "LifecycleObject should be in Initialized state after Initialize");
+ fixture.InitializeCallCount.Should().Be(1, "Initialize should have been called once");
+ fixture.DeinitializeCallCount.Should().Be(0, "Deinitialize should not have been called yet");
+ fixture.InitializeErrorCount.Should().Be(0, "there should be no initialization errors");
+ fixture.DeinitializeErrorCount.Should().Be(0, "there should be no deinitialization errors");
+
+ // Act 2
+ await fixture.DeinitializeAsync();
+
+ // Validate postconditions 2
+ fixture.State.Should().Be(LifecycleObjectFixture.LifecycleState.Deinitialized, "LifecycleObject should be in Deinitialized state after Deinitialize");
+ fixture.InitializeCallCount.Should().Be(1, "Initialize should have been called once");
+ fixture.DeinitializeCallCount.Should().Be(1, "Deinitialize should have been called once");
+ fixture.InitializeErrorCount.Should().Be(0, "there should be no initialization errors");
+ fixture.DeinitializeErrorCount.Should().Be(0, "there should be no deinitialization errors");
+
+ // Act 3
+
+ await fixture.InitializeAsync();
+
+ // Validate postconditions 3
+
+ fixture.State.Should().Be(LifecycleObjectFixture.LifecycleState.Initialized, "LifecycleObject should be in Initialized state after Initialize");
+ fixture.InitializeCallCount.Should().Be(2, "Initialize should have been called twice");
+ fixture.DeinitializeCallCount.Should().Be(1, "Deinitialize should have been called once");
+ fixture.InitializeErrorCount.Should().Be(0, "there should be no initialization errors");
+ fixture.DeinitializeErrorCount.Should().Be(0, "there should be no deinitialization errors");
+
+ // Act 4
+
+ await fixture.DeinitializeAsync();
+
+ // Validate postconditions 4
+
+ fixture.State.Should().Be(LifecycleObjectFixture.LifecycleState.Deinitialized, "LifecycleObject should be in Deinitialized state after Deinitialize");
+ fixture.InitializeCallCount.Should().Be(2, "Initialize should have been called twice");
+ fixture.DeinitializeCallCount.Should().Be(2, "Deinitialize should have been called twice");
+ fixture.InitializeErrorCount.Should().Be(0, "there should be no initialization errors");
+ fixture.DeinitializeErrorCount.Should().Be(0, "there should be no deinitialization errors");
+ }
+
+ [Fact]
+ public async Task Initialize_FailsWhenInitialized()
+ {
+ // Testing two things: We should expect InvalidOperationException by default, and that we called into the override
+
+ // Arrange
+ LifecycleObjectFixture fixture = new();
+ await fixture.InitializeAsync();
+
+ // Act
+ Func<Task> secondInitialization = async () => await fixture.InitializeAsync();
+
+ // Assert
+ await secondInitialization.Should().ThrowAsync<InvalidOperationException>("LifecycleObject.InitializeAsync should throw InvalidOperationException when initialized");
+
+ fixture.InitializeCallCount.Should().Be(1, "Initialize should have been called once successfully");
+ fixture.InitializeErrorCount.Should().Be(1, "there should be one initialization error");
+ fixture.DeinitializeCallCount.Should().Be(0, "Deinitialize should not have been called yet");
+ fixture.DeinitializeErrorCount.Should().Be(0, "there should be no deinitialization errors");
+ }
+
+ [Fact]
+ public async Task Deinitialize_FailsWhenNotInitialized()
+ {
+ // Arrange
+ LifecycleObjectFixture fixture = new();
+
+ // Act
+ Func<Task> deinitialization = async () => await fixture.DeinitializeAsync();
+
+ // Assert
+ await deinitialization.Should().ThrowAsync<InvalidOperationException>("LifecycleObject.DeinitializeAsync should throw InvalidOperationException when not initialized");
+
+ fixture.InitializeCallCount.Should().Be(0, "Initialize should not have been called yet");
+ fixture.InitializeErrorCount.Should().Be(0, "there should be no initialization errors");
+ fixture.DeinitializeCallCount.Should().Be(0, "Deinitialize should not have been called successfully yet");
+ fixture.DeinitializeErrorCount.Should().Be(1, "there should be one deinitialization error");
+
+ // Act 2
+ await fixture.InitializeAsync();
+ await fixture.DeinitializeAsync();
+
+ Func<Task> secondDeinitialization = async () => await fixture.DeinitializeAsync();
+
+ // Assert 2
+ await secondDeinitialization.Should().ThrowAsync<InvalidOperationException>("LifecycleObject.DeinitializeAsync should throw InvalidOperationException when not initialized");
+
+ fixture.InitializeCallCount.Should().Be(1, "Initialize should have been called once successfully");
+ fixture.InitializeErrorCount.Should().Be(0, "there should be no initialization errors");
+ fixture.DeinitializeCallCount.Should().Be(1, "Deinitialize should have been called successfully once");
+ fixture.DeinitializeErrorCount.Should().Be(2, "there should be two deinitialization errors");
+ }
+}
diff --git a/dotnet/test/Microsoft.AutoGen.AgentChat.Tests/RunContextStackTests.cs b/dotnet/test/Microsoft.AutoGen.AgentChat.Tests/RunContextStackTests.cs
new file mode 100644
index 000000000..fde9ecdca
--- /dev/null
+++ b/dotnet/test/Microsoft.AutoGen.AgentChat.Tests/RunContextStackTests.cs
@@ -0,0 +1,264 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// RunContextStackTests.cs
+
+using FluentAssertions;
+using Microsoft.AutoGen.AgentChat.GroupChat;
+using Moq;
+using Xunit;
+
+namespace Microsoft.AutoGen.AgentChat.Tests;
+
+public class RunContextStackTests
+{
+ public static IRunContextLayer CreateLayer(Action<Mock<IRunContextLayer>>? setupAction = null)
+ {
+ Mock<IRunContextLayer> layer = new();
+
+ if (setupAction != null)
+ {
+ setupAction(layer);
+ }
+ else
+ {
+ layer.Setup(l => l.InitializeAsync()).Returns(ValueTask.CompletedTask);
+ layer.Setup(l => l.DeinitializeAsync()).Returns(ValueTask.CompletedTask);
+ }
+
+ return layer.Object;
+ }
+
+ [Fact]
+ public async Task Initialize_SucceedsWithNoLayers()
+ {
+ // Arrange
+ RunContextStack stack = new RunContextStack();
+
+ // Act
+ Func<Task> func = async () => await stack.InitializeAsync();
+
+ // Assert
+ await func.Should().NotThrowAsync("RunContextStack should work without context frames");
+ }
+
+ [Fact]
+ public async Task Deinitialize_SucceedsWithNoLayers()
+ {
+ // Arrange
+ RunContextStack stack = new RunContextStack();
+ await stack.InitializeAsync();
+
+ // Act
+ Func<Task> func = async () => await stack.DeinitializeAsync();
+
+ // Assert
+ await func.Should().NotThrowAsync("RunContextStack should work without context frames");
+ }
+
+ [Fact]
+ public async Task PushLayer_FailsWhenInitialized()
+ {
+ // Arrange
+ RunContextStack stack = new RunContextStack();
+ await stack.InitializeAsync();
+
+ // Act
+ Action pushLayerAction = () => stack.PushLayer(CreateLayer());
+
+ // Assert
+ pushLayerAction.Should().Throw<InvalidOperationException>("RunContextStack should not allow pushing layers when initialized");
+ }
+
+ [Fact]
+ public async Task PopLayer_FailsWhenInitialized()
+ {
+ // Arrange
+ RunContextStack stack = new RunContextStack();
+ await stack.InitializeAsync();
+
+ // Act
+ Action popLayerAction = stack.PopLayer;
+
+ // Assert
+ popLayerAction.Should().Throw<InvalidOperationException>("RunContextStack should not allow popping layers when initialized");
+ }
+
+ [Fact]
+ public Task InitializeDeinitialize_ShouldInvokeLayersInOrder_WhenPushed()
+ {
+ return PrepareAndRun_LayerOrderTest(Arrange);
+
+ static RunContextStack Arrange(IEnumerable<IRunContextLayer> layers)
+ {
+ RunContextStack stack = new RunContextStack();
+
+ foreach (IRunContextLayer layer in layers)
+ {
+ stack.PushLayer(layer);
+ }
+
+ return stack;
+ }
+ }
+
+ [Fact]
+ public Task InitializeDeinitialize_ShouldInvokeLayersInOrder_WhenConstructed()
+ {
+ return PrepareAndRun_LayerOrderTest(Arrange);
+
+ static RunContextStack Arrange(IEnumerable<IRunContextLayer> layers)
+ {
+ return new RunContextStack([.. layers]);
+ }
+ }
+
+ private async Task PrepareAndRun_LayerOrderTest(Func<IEnumerable<IRunContextLayer>, RunContextStack> arrangeStack)
+ {
+ bool bottomLayerInit = false;
+ bool bottomLayerDeinit = false;
+
+ bool topLayerInit = false;
+ bool topLayerDeinit = false;
+
+ // Arrange
+ IRunContextLayer topLayer = CreateLayer(mock =>
+ {
+ mock.Setup(l => l.InitializeAsync()).Callback(
+ () =>
+ {
+ topLayerInit.Should().BeFalse("Top Layer should not have been initialized yet");
+ bottomLayerInit.Should().BeFalse("Bottom Layer should not have been initialized yet");
+
+ topLayerInit = true;
+ }
+ ).Returns(ValueTask.CompletedTask).Verifiable();
+ mock.Setup(l => l.DeinitializeAsync()).Callback(
+ () =>
+ {
+ topLayerInit.Should().BeTrue("Top Layer should have been initialized");
+ bottomLayerInit.Should().BeTrue("Bottom Layer should have been initialized");
+
+ bottomLayerDeinit.Should().BeTrue("Bottom Layer should be deinitialized before Top Layer");
+ topLayerDeinit.Should().BeFalse("Top Layer should not have been deinitialized yet");
+
+ topLayerDeinit = true;
+ }).Returns(ValueTask.CompletedTask).Verifiable();
+ });
+
+ IRunContextLayer bottomLayer = CreateLayer(mock =>
+ {
+ mock.Setup(l => l.InitializeAsync()).Callback(
+ () =>
+ {
+ topLayerInit.Should().BeTrue("Top Layer should have been initialized before Bottom Layer");
+ bottomLayerInit.Should().BeFalse("Bottom Layer should not have been initialized yet");
+
+ bottomLayerInit = true;
+ }
+ ).Returns(ValueTask.CompletedTask).Verifiable();
+ mock.Setup(l => l.DeinitializeAsync()).Callback(
+ () =>
+ {
+ topLayerInit.Should().BeTrue("Top Layer should have been initialized");
+ bottomLayerInit.Should().BeTrue("Bottom Layer should have been initialized");
+
+ bottomLayerDeinit.Should().BeFalse("Bottom Layer should not have been deinitialized yet");
+ topLayerDeinit.Should().BeFalse("Top Layer should not have been deinitialized yet");
+
+ bottomLayerDeinit = true;
+ }).Returns(ValueTask.CompletedTask).Verifiable();
+ });
+
+ RunContextStack stack = arrangeStack([bottomLayer, topLayer]);
+
+ // Act
+ await stack.InitializeAsync();
+
+ // Assert
+ Mock.Get(topLayer).Verify(l => l.InitializeAsync(), Times.Once);
+ Mock.Get(bottomLayer).Verify(l => l.InitializeAsync(), Times.Once);
+
+ bottomLayerInit.Should().BeTrue("Top Layer should have been initialized");
+ topLayerInit.Should().BeTrue("Bottom Layer should have been initialized");
+
+ // Act 2
+ await stack.DeinitializeAsync();
+
+ // Assert 2
+ Mock.Get(bottomLayer).Verify(l => l.DeinitializeAsync(), Times.Once);
+ Mock.Get(topLayer).Verify(l => l.DeinitializeAsync(), Times.Once);
+
+ topLayerDeinit.Should().BeTrue("Bottom Layer should have been deinitialized");
+ bottomLayerDeinit.Should().BeTrue("Top Layer should have been deinitialized");
+ }
+
+ [Fact]
+ public async Task CreateOverrides_GetsInvokedOnError()
+ {
+ int initializeErrors = 0;
+ int deinitializeErrors = 0;
+
+ // Arrange
+ IRunContextLayer overrides = RunContextStack.OverrideErrors(
+ initializeError: () => initializeErrors++,
+ deinitializeError: () => deinitializeErrors++);
+
+ RunContextStack stack = new RunContextStack(overrides);
+
+ // Act
+ Func<Task> deinitializeAction = async () => await stack.DeinitializeAsync();
+
+ // Assert
+ // The first Deinitialize should throw because we only override after the top layer it initialized
+ await deinitializeAction.Should().ThrowAsync<InvalidOperationException>("Deinitialize should throw an exception");
+
+ // Act 2
+ await stack.InitializeAsync();
+ Func<Task> initializeAgainAction = async () => await stack.InitializeAsync();
+
+ // Assert 2
+ // The second Initialize should not throw, because the overrides should be applied
+ await initializeAgainAction.Should().NotThrowAsync("Initialize should not throw an exception");
+
+ initializeErrors.Should().Be(1, "There should be one initialization error");
+ deinitializeErrors.Should().Be(0, "There should not have been an overriden invocation of a deinitialize error.");
+ }
+
+ [Fact]
+ public async Task Enter_DisposableWorksIdempotently()
+ {
+ int initializeCount = 0;
+ int deinitializeCount = 0;
+
+ // Arrange
+ IRunContextLayer layer = CreateLayer(mock =>
+ {
+ mock.Setup(l => l.InitializeAsync()).Callback(() => initializeCount++).Returns(ValueTask.CompletedTask);
+ mock.Setup(l => l.DeinitializeAsync()).Callback(() => deinitializeCount++).Returns(ValueTask.CompletedTask);
+ });
+
+ RunContextStack stack = new RunContextStack(layer);
+
+ // Act
+ IAsyncDisposable exitDisposable = await stack.Enter();
+
+ // Assert
+ initializeCount.Should().Be(1, "Layer should have been initialized once");
+ deinitializeCount.Should().Be(0, "Layer should not have been deinitialized yet");
+
+ // Act 2
+ await exitDisposable.DisposeAsync();
+
+ // Assert 2
+ initializeCount.Should().Be(1, "Layer should have been initialized once");
+ deinitializeCount.Should().Be(1, "Layer should have been deinitialized once");
+
+ // Act 3
+ Func<Task> disposeAgain = async () => await exitDisposable.DisposeAsync();
+
+ // Assert 3
+ await disposeAgain.Should().NotThrowAsync("Dispose should be idempotent");
+
+ initializeCount.Should().Be(1, "Layer should have been initialized once");
+ deinitializeCount.Should().Be(1, "Layer should have been deinitialized once");
+ }
+}