[BREAKING] .NET: Workflow Off-Thread Execution Mode (#1233)

* Updates to async run loop.

* fix: Workflow Onwership can be release by nonowner

* fix: Incorrect handling of blockOnPending in StreamingRun

Depending on whether we are running in streaming on non-streaming mode, we may be using the StreamingRun in different ways. Unfortunately, the only place we can really know what is the actual state of execution is in the RunEventStream implementations.

This resulted in blocking where blocking was unneeded and occasionally not-blocking when blocking was needed.

The fix is to move the logic of handling this blocking into RunEventStream implementations.

* fix: Fix cleanup on error and end run

This ensures we clean up the background resources correctly.

* fix: Ensure we let the run loop proceed when shutting down

* fix: Add timeout for Input Waiting

* fix: Make the samples properly clean up `Run`s and `StreamingRun`s

* fix: Simplify Declarative Workflow Run disposal pattern

* Also fixes missing .Disposal() in Integration tests

---------

Co-authored-by: Ben Thomas <ben.thomas@microsoft.com>

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/Sample/01_Simple_Workflow_Sequential.cs

@@ -1,9 +1,12 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using System;
 using System.IO;
 using System.Linq;
 using System.Threading.Tasks;
+using Microsoft.Agents.AI.Workflows.InProc;
 using Microsoft.Agents.AI.Workflows.Reflection;
+using Microsoft.Agents.AI.Workflows.UnitTests;
 
 namespace Microsoft.Agents.AI.Workflows.Sample;
 
@@ -23,9 +26,11 @@ internal static class Step1EntryPoint
         }
     }
 
-    public static async ValueTask RunAsync(TextWriter writer)
+    public static async ValueTask RunAsync(TextWriter writer, ExecutionMode executionMode)
     {
-        StreamingRun run = await InProcessExecution.StreamAsync(WorkflowInstance, "Hello, World!").ConfigureAwait(false);
+        InProcessExecutionEnvironment env = executionMode.GetEnvironment();
+
+        StreamingRun run = await env.StreamAsync(WorkflowInstance, "Hello, World!").ConfigureAwait(false);
 
         await foreach (WorkflowEvent evt in run.WatchStreamAsync().ConfigureAwait(false))
         {

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/Sample/01a_Simple_Workflow_Sequential.cs

@@ -2,16 +2,18 @@
 
 using System.IO;
 using System.Threading.Tasks;
-
+using Microsoft.Agents.AI.Workflows.InProc;
+using Microsoft.Agents.AI.Workflows.UnitTests;
 using static Microsoft.Agents.AI.Workflows.Sample.Step1EntryPoint;
 
 namespace Microsoft.Agents.AI.Workflows.Sample;
 
 internal static class Step1aEntryPoint
 {
-    public static async ValueTask RunAsync(TextWriter writer)
+    public static async ValueTask RunAsync(TextWriter writer, ExecutionMode executionMode)
     {
-        Run run = await InProcessExecution.RunAsync(WorkflowInstance, "Hello, World!").ConfigureAwait(false);
+        InProcessExecutionEnvironment env = executionMode.GetEnvironment();
+        Run run = await env.RunAsync(WorkflowInstance, "Hello, World!").ConfigureAwait(false);
 
         Assert.Equal(RunStatus.Idle, await run.GetStatusAsync());
 

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/Sample/02_Simple_Workflow_Condition.cs

@@ -4,7 +4,9 @@ using System;
 using System.IO;
 using System.Linq;
 using System.Threading.Tasks;
+using Microsoft.Agents.AI.Workflows.InProc;
 using Microsoft.Agents.AI.Workflows.Reflection;
+using Microsoft.Agents.AI.Workflows.UnitTests;
 
 namespace Microsoft.Agents.AI.Workflows.Sample;
 
@@ -28,9 +30,10 @@ internal static class Step2EntryPoint
         }
     }
 
-    public static async ValueTask<string> RunAsync(TextWriter writer, string input = "This is a spam message.")
+    public static async ValueTask<string> RunAsync(TextWriter writer, ExecutionMode executionMode, string input = "This is a spam message.")
     {
-        StreamingRun handle = await InProcessExecution.StreamAsync(WorkflowInstance, input).ConfigureAwait(false);
+        InProcessExecutionEnvironment env = executionMode.GetEnvironment();
+        StreamingRun handle = await env.StreamAsync(WorkflowInstance, input).ConfigureAwait(false);
         await foreach (WorkflowEvent evt in handle.WatchStreamAsync().ConfigureAwait(false))
         {
             switch (evt)

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/Sample/03_Simple_Workflow_Loop.cs

@@ -4,7 +4,9 @@ using System;
 using System.IO;
 using System.Threading;
 using System.Threading.Tasks;
+using Microsoft.Agents.AI.Workflows.InProc;
 using Microsoft.Agents.AI.Workflows.Reflection;
+using Microsoft.Agents.AI.Workflows.UnitTests;
 
 namespace Microsoft.Agents.AI.Workflows.Sample;
 
@@ -25,9 +27,10 @@ internal static class Step3EntryPoint
         }
     }
 
-    public static async ValueTask<string> RunAsync(TextWriter writer)
+    public static async ValueTask<string> RunAsync(TextWriter writer, ExecutionMode executionMode)
     {
-        StreamingRun run = await InProcessExecution.StreamAsync(WorkflowInstance, NumberSignal.Init).ConfigureAwait(false);
+        InProcessExecutionEnvironment env = executionMode.GetEnvironment();
+        StreamingRun run = await env.StreamAsync(WorkflowInstance, NumberSignal.Init).ConfigureAwait(false);
 
         await foreach (WorkflowEvent evt in run.WatchStreamAsync().ConfigureAwait(false))
         {

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/Sample/04_Simple_Workflow_ExternalRequest.cs

@@ -4,6 +4,8 @@ using System;
 using System.Collections.Generic;
 using System.IO;
 using System.Threading.Tasks;
+using Microsoft.Agents.AI.Workflows.InProc;
+using Microsoft.Agents.AI.Workflows.UnitTests;
 
 namespace Microsoft.Agents.AI.Workflows.Sample;
 
@@ -37,13 +39,14 @@ internal static class Step4EntryPoint
         }
     }
 
-    public static async ValueTask<string> RunAsync(TextWriter writer, Func<string, int> userGuessCallback)
+    public static async ValueTask<string> RunAsync(TextWriter writer, Func<string, int> userGuessCallback, ExecutionMode executionMode)
     {
         NumberSignal signal = NumberSignal.Init;
         string? prompt = UpdatePrompt(null, signal);
 
         Workflow workflow = WorkflowInstance;
-        StreamingRun handle = await InProcessExecution.StreamAsync(workflow, NumberSignal.Init).ConfigureAwait(false);
+        InProcessExecutionEnvironment env = executionMode.GetEnvironment();
+        StreamingRun handle = await env.StreamAsync(workflow, NumberSignal.Init).ConfigureAwait(false);
 
         List<ExternalRequest> requests = [];
         await foreach (WorkflowEvent evt in handle.WatchStreamAsync().ConfigureAwait(false))

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/Sample/05_Simple_Workflow_Checkpointing.cs

@@ -6,12 +6,14 @@ using System.IO;
 using System.Threading;
 using System.Threading.Tasks;
 using FluentAssertions;
+using Microsoft.Agents.AI.Workflows.InProc;
+using Microsoft.Agents.AI.Workflows.UnitTests;
 
 namespace Microsoft.Agents.AI.Workflows.Sample;
 
 internal static class Step5EntryPoint
 {
-    public static async ValueTask<string> RunAsync(TextWriter writer, Func<string, int> userGuessCallback, bool rehydrateToRestore = false, CheckpointManager? checkpointManager = null)
+    public static async ValueTask<string> RunAsync(TextWriter writer, Func<string, int> userGuessCallback, ExecutionMode executionMode, bool rehydrateToRestore = false, CheckpointManager? checkpointManager = null)
     {
         Dictionary<CheckpointInfo, (NumberSignal signal, string? prompt)> checkpointedOutputs = [];
 
@@ -21,9 +23,11 @@ internal static class Step5EntryPoint
         checkpointManager ??= CheckpointManager.Default;
 
         Workflow workflow = Step4EntryPoint.CreateWorkflowInstance(out JudgeExecutor judge);
+
+        InProcessExecutionEnvironment env = executionMode.GetEnvironment();
         Checkpointed<StreamingRun> checkpointed =
-            await InProcessExecution.StreamAsync(workflow, NumberSignal.Init, checkpointManager)
-                                    .ConfigureAwait(false);
+            await env.StreamAsync(workflow, NumberSignal.Init, checkpointManager)
+                     .ConfigureAwait(false);
 
         List<CheckpointInfo> checkpoints = [];
         CancellationTokenSource cancellationSource = new();
@@ -40,10 +44,10 @@ internal static class Step5EntryPoint
         Console.WriteLine($"Restoring to checkpoint {targetCheckpoint} from run {targetCheckpoint.RunId}");
         if (rehydrateToRestore)
         {
-            await handle.EndRunAsync().ConfigureAwait(false);
+            await handle.DisposeAsync().ConfigureAwait(false);
 
-            checkpointed = await InProcessExecution.ResumeStreamAsync(workflow, targetCheckpoint, checkpointManager, runId: handle.RunId, cancellationToken: CancellationToken.None)
-                                                   .ConfigureAwait(false);
+            checkpointed = await env.ResumeStreamAsync(workflow, targetCheckpoint, checkpointManager, runId: handle.RunId, cancellationToken: CancellationToken.None)
+                                    .ConfigureAwait(false);
             handle = checkpointed.Run;
         }
         else
@@ -112,20 +116,21 @@ internal static class Step5EntryPoint
                         {
                             Console.WriteLine($"*** Max step {maxStep} reached, cancelling.");
                             cancellationSource.Cancel();
+                            return null;
                         }
-                        else
-                        {
-                            Console.WriteLine($"*** Processing {requests.Count} queued requests.");
-                            foreach (ExternalRequest request in requests)
-                            {
-                                ExternalResponse response = ExecuteExternalRequest(request, userGuessCallback, prompt);
-                                Console.WriteLine($"!!! Sending response: {response}");
-                                await handle.SendResponseAsync(response).ConfigureAwait(false);
-                            }
 
-                            requests.Clear();
-                            Console.WriteLine("*** Completed processing requests.");
+                        Console.WriteLine($"*** Processing {requests.Count} queued requests.");
+                        foreach (ExternalRequest request in requests)
+                        {
+                            ExternalResponse response = ExecuteExternalRequest(request, userGuessCallback, prompt);
+                            Console.WriteLine($"!!! Sending response: {response}");
+                            await handle.SendResponseAsync(response).ConfigureAwait(false);
                         }
+
+                        requests.Clear();
+
+                        Console.WriteLine("*** Completed processing requests.");
+
                         break;
 
                     case ExecutorCompletedEvent executorCompleteEvt:

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/Sample/06_GroupChat_Workflow.cs

@@ -10,6 +10,8 @@ using System.Text;
 using System.Text.Json;
 using System.Threading;
 using System.Threading.Tasks;
+using Microsoft.Agents.AI.Workflows.InProc;
+using Microsoft.Agents.AI.Workflows.UnitTests;
 using Microsoft.Extensions.AI;
 
 namespace Microsoft.Agents.AI.Workflows.Sample;
@@ -22,12 +24,13 @@ internal static class Step6EntryPoint
             .AddParticipants(new HelloAgent(), new EchoAgent())
             .Build();
 
-    public static async ValueTask RunAsync(TextWriter writer, int maxSteps = 2)
+    public static async ValueTask RunAsync(TextWriter writer, ExecutionMode executionMode, int maxSteps = 2)
     {
         Workflow workflow = CreateWorkflow(maxSteps);
 
-        StreamingRun run = await InProcessExecution.StreamAsync(workflow, Array.Empty<ChatMessage>())
-                                                   .ConfigureAwait(false);
+        InProcessExecutionEnvironment env = executionMode.GetEnvironment();
+        StreamingRun run = await env.StreamAsync(workflow, Array.Empty<ChatMessage>())
+                                    .ConfigureAwait(false);
         await run.TrySendMessageAsync(new TurnToken(emitEvents: true));
 
         await foreach (WorkflowEvent evt in run.WatchStreamAsync().ConfigureAwait(false))

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/Sample/07_GroupChat_Workflow_HostAsAgent.cs

@@ -1,6 +1,5 @@
 // Copyright (c) Microsoft. All rights reserved.
 
-using System;
 using System.Collections.Generic;
 using System.IO;
 using System.Threading.Tasks;
@@ -26,7 +25,6 @@ internal static class Step7EntryPoint
                                    ?? update.AgentId
                                    ?? update.Role.ToString()
                                    ?? ChatRole.Assistant.ToString()}: {update.Text}";
-            Console.WriteLine(updateText);
             writer.WriteLine(updateText);
         }
     }

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/Sample/08_Subworkflow_Simple.cs

@@ -7,6 +7,8 @@ using System.Linq;
 using System.Threading;
 using System.Threading.Tasks;
 using FluentAssertions;
+using Microsoft.Agents.AI.Workflows.InProc;
+using Microsoft.Agents.AI.Workflows.UnitTests;
 
 namespace Microsoft.Agents.AI.Workflows.Sample;
 
@@ -26,7 +28,7 @@ internal static class Step8EntryPoint
             "   Spaces   around   text   ",
         ];
 
-    public static async ValueTask<List<TextProcessingResult>> RunAsync(TextWriter writer, List<string> textsToProcess)
+    public static async ValueTask<List<TextProcessingResult>> RunAsync(TextWriter writer, ExecutionMode executionMode, List<string> textsToProcess)
     {
         Func<TextProcessingRequest, IWorkflowContext, CancellationToken, ValueTask> processTextAsyncFunc = ProcessTextAsync;
         ExecutorIsh processText = processTextAsyncFunc.AsExecutor("TextProcessor");
@@ -41,7 +43,8 @@ internal static class Step8EntryPoint
             .AddEdge(textProcessor, orchestrator)
             .Build();
 
-        Run workflowRun = await InProcessExecution.RunAsync(workflow, textsToProcess);
+        InProcessExecutionEnvironment env = executionMode.GetEnvironment();
+        Run workflowRun = await env.RunAsync(workflow, textsToProcess);
 
         RunStatus status = await workflowRun.GetStatusAsync();
         status.Should().Be(RunStatus.Idle);

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/Sample/09_Subworkflow_ExternalRequest.cs

@@ -7,6 +7,8 @@ using System.Linq;
 using System.Threading;
 using System.Threading.Tasks;
 using FluentAssertions;
+using Microsoft.Agents.AI.Workflows.InProc;
+using Microsoft.Agents.AI.Workflows.UnitTests;
 
 namespace Microsoft.Agents.AI.Workflows.Sample;
 
@@ -170,12 +172,13 @@ internal static class Step9EntryPoint
                              .Select(request => Part2FinishedResponses[request.Id])
                              .OrderBy(request => request.Id)];
 
-    public static async ValueTask<List<RequestFinished>> RunAsync(TextWriter writer)
+    public static async ValueTask<List<RequestFinished>> RunAsync(TextWriter writer, ExecutionMode executionMode)
     {
         RunStatus runStatus;
         List<RequestFinished> results = [];
 
-        Run workflowRun = await InProcessExecution.RunAsync(WorkflowInstance, RequestsToProcess.ToList());
+        InProcessExecutionEnvironment env = executionMode.GetEnvironment();
+        Run workflowRun = await env.RunAsync(WorkflowInstance, RequestsToProcess.ToList());
 
         RunStatus part1Status = ExpectedResponsesPart2.Length > 0 ? RunStatus.PendingRequests : RunStatus.Idle;
         runStatus = await workflowRun.GetStatusAsync();