chore: import upstream snapshot with attribution

dotnet/samples/03-workflows/Checkpoint/CheckpointWithHumanInTheLoop/CheckpointWithHumanInTheLoop.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/03-workflows/Checkpoint/CheckpointWithHumanInTheLoop/Program.cs

@@ -0,0 +1,153 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace WorkflowCheckpointWithHumanInTheLoopSample;
+
+/// <summary>
+/// This sample demonstrates how to create a workflow with human-in-the-loop interaction and
+/// checkpointing support. The workflow plays a number guessing game where the user provides
+/// guesses based on feedback from the workflow. The workflow state is checkpointed at the end
+/// of each super step, allowing it to be restored and resumed later.
+/// Each RequestPort request and response cycle takes two super steps:
+/// 1. The RequestPort sends a RequestInfoEvent to request input from the external world.
+/// 2. The external world sends a response back to the RequestPort.
+/// Thus, two checkpoints are created for each human-in-the-loop interaction.
+/// </summary>
+/// <remarks>
+/// Pre-requisites:
+/// - Foundational samples should be completed first.
+/// - This sample builds upon the HumanInTheLoopBasic sample. It's recommended to go through that
+///   sample first to understand the basics of human-in-the-loop workflows.
+/// - This sample also builds upon the CheckpointAndResume sample. It's recommended to
+///   go through that sample first to understand the basics of checkpointing and resuming workflows.
+/// </remarks>
+public static class Program
+{
+    private static async Task Main()
+    {
+        // Create the workflow
+        var workflow = WorkflowFactory.BuildWorkflow();
+
+        // Create checkpoint manager
+        var checkpointManager = CheckpointManager.Default;
+        var checkpoints = new List<CheckpointInfo>();
+
+        // Execute the workflow and save checkpoints
+        await using StreamingRun checkpointedRun = await InProcessExecution
+            .RunStreamingAsync(workflow, new SignalWithNumber(NumberSignal.Init), checkpointManager)
+            ;
+        await foreach (WorkflowEvent evt in checkpointedRun.WatchStreamAsync())
+        {
+            switch (evt)
+            {
+                case RequestInfoEvent requestInputEvt:
+                    // Handle `RequestInfoEvent` from the workflow
+                    ExternalResponse response = HandleExternalRequest(requestInputEvt.Request);
+                    await checkpointedRun.SendResponseAsync(response);
+                    break;
+                case ExecutorCompletedEvent executorCompletedEvt:
+                    Console.WriteLine($"* Executor {executorCompletedEvt.ExecutorId} completed.");
+                    break;
+                case SuperStepCompletedEvent superStepCompletedEvt:
+                    // Checkpoints are automatically created at the end of each super step when a
+                    // checkpoint manager is provided. You can store the checkpoint info for later use.
+                    CheckpointInfo? checkpoint = superStepCompletedEvt.CompletionInfo!.Checkpoint;
+                    if (checkpoint is not null)
+                    {
+                        checkpoints.Add(checkpoint);
+                        Console.WriteLine($"** Checkpoint created at step {checkpoints.Count}.");
+                    }
+                    break;
+                case WorkflowOutputEvent workflowOutputEvt:
+                    Console.WriteLine($"Workflow completed with result: {workflowOutputEvt.Data}");
+                    break;
+                case WorkflowErrorEvent workflowError:
+                    Console.ForegroundColor = ConsoleColor.Red;
+                    Console.Error.WriteLine(workflowError.Exception?.ToString() ?? "Unknown workflow error occurred.");
+                    Console.ResetColor();
+                    break;
+                case ExecutorFailedEvent executorFailed:
+                    Console.ForegroundColor = ConsoleColor.Red;
+                    Console.Error.WriteLine($"Executor '{executorFailed.ExecutorId}' failed with {(executorFailed.Data == null ? "unknown error" : $"exception {executorFailed.Data}")}.");
+                    Console.ResetColor();
+                    break;
+            }
+        }
+
+        if (checkpoints.Count == 0)
+        {
+            throw new InvalidOperationException("No checkpoints were created during the workflow execution.");
+        }
+        Console.WriteLine($"Number of checkpoints created: {checkpoints.Count}");
+
+        // Restoring from a checkpoint and resuming execution
+        const int CheckpointIndex = 1;
+        Console.WriteLine($"\n\nRestoring from the {CheckpointIndex + 1}th checkpoint.");
+        CheckpointInfo savedCheckpoint = checkpoints[CheckpointIndex];
+        // Note that we are restoring the state directly to the same run instance.
+        await checkpointedRun.RestoreCheckpointAsync(savedCheckpoint, CancellationToken.None);
+        await foreach (WorkflowEvent evt in checkpointedRun.WatchStreamAsync())
+        {
+            switch (evt)
+            {
+                case RequestInfoEvent requestInputEvt:
+                    // Handle `RequestInfoEvent` from the workflow
+                    ExternalResponse response = HandleExternalRequest(requestInputEvt.Request);
+                    await checkpointedRun.SendResponseAsync(response);
+                    break;
+                case ExecutorCompletedEvent executorCompletedEvt:
+                    Console.WriteLine($"* Executor {executorCompletedEvt.ExecutorId} completed.");
+                    break;
+                case WorkflowOutputEvent workflowOutputEvt:
+                    Console.WriteLine($"Workflow completed with result: {workflowOutputEvt.Data}");
+                    break;
+                case WorkflowErrorEvent workflowError:
+                    Console.ForegroundColor = ConsoleColor.Red;
+                    Console.Error.WriteLine(workflowError.Exception?.ToString() ?? "Unknown workflow error occurred.");
+                    Console.ResetColor();
+                    break;
+                case ExecutorFailedEvent executorFailed:
+                    Console.ForegroundColor = ConsoleColor.Red;
+                    Console.Error.WriteLine($"Executor '{executorFailed.ExecutorId}' failed with {(executorFailed.Data == null ? "unknown error" : $"exception {executorFailed.Data}")}.");
+                    Console.ResetColor();
+                    break;
+            }
+        }
+    }
+
+    private static ExternalResponse HandleExternalRequest(ExternalRequest request)
+    {
+        if (request.TryGetDataAs<SignalWithNumber>(out var signal))
+        {
+            switch (signal.Signal)
+            {
+                case NumberSignal.Init:
+                    int initialGuess = ReadIntegerFromConsole("Please provide your initial guess: ");
+                    return request.CreateResponse(initialGuess);
+                case NumberSignal.Above:
+                    int lowerGuess = ReadIntegerFromConsole($"You previously guessed {signal.Number} too large. Please provide a new guess: ");
+                    return request.CreateResponse(lowerGuess);
+                case NumberSignal.Below:
+                    int higherGuess = ReadIntegerFromConsole($"You previously guessed {signal.Number} too small. Please provide a new guess: ");
+                    return request.CreateResponse(higherGuess);
+            }
+        }
+
+        throw new NotSupportedException($"Request {request.PortInfo.RequestType} is not supported");
+    }
+
+    private static int ReadIntegerFromConsole(string prompt)
+    {
+        while (true)
+        {
+            Console.Write(prompt);
+            string? input = Console.ReadLine();
+            if (int.TryParse(input, out int value))
+            {
+                return value;
+            }
+            Console.WriteLine("Invalid input. Please enter a valid integer.");
+        }
+    }
+}

dotnet/samples/03-workflows/Checkpoint/CheckpointWithHumanInTheLoop/WorkflowFactory.cs

@@ -0,0 +1,103 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace WorkflowCheckpointWithHumanInTheLoopSample;
+
+internal static class WorkflowFactory
+{
+    /// <summary>
+    /// Get a workflow that plays a number guessing game with human-in-the-loop interaction.
+    /// An input port allows the external world to provide inputs to the workflow upon requests.
+    /// </summary>
+    internal static Workflow BuildWorkflow()
+    {
+        // Create the executors
+        RequestPort numberRequest = RequestPort.Create<SignalWithNumber, int>("GuessNumber");
+        JudgeExecutor judgeExecutor = new(42);
+
+        // Build the workflow by connecting executors in a loop
+        return new WorkflowBuilder(numberRequest)
+            .AddEdge(numberRequest, judgeExecutor)
+            .AddEdge(judgeExecutor, numberRequest)
+            .WithOutputFrom(judgeExecutor)
+            .Build();
+    }
+}
+
+/// <summary>
+/// Signals indicating if the guess was too high, too low, or an initial guess.
+/// </summary>
+internal enum NumberSignal
+{
+    Init,
+    Above,
+    Below,
+}
+
+/// <summary>
+/// Signals used for communication between guesses and the JudgeExecutor.
+/// </summary>
+internal sealed class SignalWithNumber
+{
+    public NumberSignal Signal { get; }
+    public int? Number { get; }
+
+    public SignalWithNumber(NumberSignal signal, int? number = null)
+    {
+        this.Signal = signal;
+        this.Number = number;
+    }
+}
+
+/// <summary>
+/// Executor that judges the guess and provides feedback.
+/// </summary>
+[SendsMessage(typeof(SignalWithNumber))]
+[YieldsOutput(typeof(string))]
+internal sealed class JudgeExecutor() : Executor<int>("Judge")
+{
+    private readonly int _targetNumber;
+    private int _tries;
+    private const string StateKey = "JudgeExecutorState";
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="JudgeExecutor"/> class.
+    /// </summary>
+    /// <param name="targetNumber">The number to be guessed.</param>
+    public JudgeExecutor(int targetNumber) : this()
+    {
+        this._targetNumber = targetNumber;
+    }
+
+    public override async ValueTask HandleAsync(int message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        this._tries++;
+        if (message == this._targetNumber)
+        {
+            await context.YieldOutputAsync($"{this._targetNumber} found in {this._tries} tries!", cancellationToken);
+        }
+        else if (message < this._targetNumber)
+        {
+            await context.SendMessageAsync(new SignalWithNumber(NumberSignal.Below, message), cancellationToken: cancellationToken);
+        }
+        else
+        {
+            await context.SendMessageAsync(new SignalWithNumber(NumberSignal.Above, message), cancellationToken: cancellationToken);
+        }
+    }
+
+    /// <summary>
+    /// Checkpoint the current state of the executor.
+    /// This must be overridden to save any state that is needed to resume the executor.
+    /// </summary>
+    protected override ValueTask OnCheckpointingAsync(IWorkflowContext context, CancellationToken cancellationToken = default) =>
+        context.QueueStateUpdateAsync(StateKey, this._tries, cancellationToken: cancellationToken);
+
+    /// <summary>
+    /// Restore the state of the executor from a checkpoint.
+    /// This must be overridden to restore any state that was saved during checkpointing.
+    /// </summary>
+    protected override async ValueTask OnCheckpointRestoredAsync(IWorkflowContext context, CancellationToken cancellationToken = default) =>
+        this._tries = await context.ReadStateAsync<int>(StateKey, cancellationToken: cancellationToken);
+}