test

dotnet/samples/GettingStarted/Workflows/Checkpoint/CheckpointAndResume/CheckpointAndResume.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/GettingStarted/Workflows/Checkpoint/CheckpointAndResume/Program.cs

@@ -0,0 +1,87 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace WorkflowCheckpointAndResumeSample;
+
+/// <summary>
+/// This sample introduces the concepts of check points and shows how to save and restore
+/// the state of a workflow using checkpoints.
+/// This sample demonstrates checkpoints, which allow you to save and restore a workflow's state.
+/// Key concepts:
+/// - Super Steps: A workflow executes in stages called "super steps". Each super step runs
+///   one or more executors and completes when all those executors finish their work.
+/// - Checkpoints: The system automatically saves the workflow's state at the end of each
+///   super step. You can use these checkpoints to resume the workflow from any saved point.
+/// - Resume: If needed, you can restore a checkpoint and continue execution from that state.
+/// </summary>
+/// <remarks>
+/// Pre-requisites:
+/// - Foundational samples should be completed first.
+/// </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 Checkpointed<StreamingRun> checkpointedRun = await InProcessExecution
+            .StreamAsync(workflow, NumberSignal.Init, checkpointManager)
+            ;
+        await foreach (WorkflowEvent evt in checkpointedRun.Run.WatchStreamAsync())
+        {
+            if (evt is ExecutorCompletedEvent executorCompletedEvt)
+            {
+                Console.WriteLine($"* Executor {executorCompletedEvt.ExecutorId} completed.");
+            }
+
+            if (evt is 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}.");
+                }
+            }
+
+            if (evt is WorkflowOutputEvent workflowOutputEvt)
+            {
+                Console.WriteLine($"Workflow completed with result: {workflowOutputEvt.Data}");
+            }
+        }
+
+        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 = 5;
+        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.Run.WatchStreamAsync())
+        {
+            if (evt is ExecutorCompletedEvent executorCompletedEvt)
+            {
+                Console.WriteLine($"* Executor {executorCompletedEvt.ExecutorId} completed.");
+            }
+
+            if (evt is WorkflowOutputEvent workflowOutputEvt)
+            {
+                Console.WriteLine($"Workflow completed with result: {workflowOutputEvt.Data}");
+            }
+        }
+    }
+}

dotnet/samples/GettingStarted/Workflows/Checkpoint/CheckpointAndResume/WorkflowFactory.cs

@@ -0,0 +1,152 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace WorkflowCheckpointAndResumeSample;
+
+internal static class WorkflowFactory
+{
+    /// <summary>
+    /// Get a workflow that plays a number guessing game with checkpointing support.
+    /// The workflow consists of two executors that are connected in a feedback loop:
+    /// 1. GuessNumberExecutor: Makes a guess based on the current known bounds.
+    /// 2. JudgeExecutor: Evaluates the guess and provides feedback.
+    /// The workflow continues until the correct number is guessed.
+    /// </summary>
+    internal static Workflow BuildWorkflow()
+    {
+        // Create the executors
+        GuessNumberExecutor guessNumberExecutor = new(1, 100);
+        JudgeExecutor judgeExecutor = new(42);
+
+        // Build the workflow by connecting executors in a loop
+        return new WorkflowBuilder(guessNumberExecutor)
+            .AddEdge(guessNumberExecutor, judgeExecutor)
+            .AddEdge(judgeExecutor, guessNumberExecutor)
+            .WithOutputFrom(judgeExecutor)
+            .Build();
+    }
+}
+
+/// <summary>
+/// Signals used for communication between GuessNumberExecutor and JudgeExecutor.
+/// </summary>
+internal enum NumberSignal
+{
+    Init,
+    Above,
+    Below,
+}
+
+/// <summary>
+/// Executor that makes a guess based on the current bounds.
+/// </summary>
+internal sealed class GuessNumberExecutor() : Executor<NumberSignal>("Guess")
+{
+    /// <summary>
+    /// The lower bound of the guessing range.
+    /// </summary>
+    public int LowerBound { get; private set; }
+
+    /// <summary>
+    /// The upper bound of the guessing range.
+    /// </summary>
+    public int UpperBound { get; private set; }
+
+    private const string StateKey = "GuessNumberExecutorState";
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="GuessNumberExecutor"/> class.
+    /// </summary>
+    /// <param name="lowerBound">The initial lower bound of the guessing range.</param>
+    /// <param name="upperBound">The initial upper bound of the guessing range.</param>
+    public GuessNumberExecutor(int lowerBound, int upperBound) : this()
+    {
+        this.LowerBound = lowerBound;
+        this.UpperBound = upperBound;
+    }
+
+    private int NextGuess => (this.LowerBound + this.UpperBound) / 2;
+
+    public override async ValueTask HandleAsync(NumberSignal message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        switch (message)
+        {
+            case NumberSignal.Init:
+                await context.SendMessageAsync(this.NextGuess, cancellationToken: cancellationToken);
+                break;
+            case NumberSignal.Above:
+                this.UpperBound = this.NextGuess - 1;
+                await context.SendMessageAsync(this.NextGuess, cancellationToken: cancellationToken);
+                break;
+            case NumberSignal.Below:
+                this.LowerBound = this.NextGuess + 1;
+                await context.SendMessageAsync(this.NextGuess, cancellationToken: cancellationToken);
+                break;
+        }
+    }
+
+    /// <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.LowerBound, this.UpperBound), 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.LowerBound, this.UpperBound) = await context.ReadStateAsync<(int, int)>(StateKey, cancellationToken: cancellationToken);
+}
+
+/// <summary>
+/// Executor that judges the guess and provides feedback.
+/// </summary>
+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(NumberSignal.Below, cancellationToken: cancellationToken);
+        }
+        else
+        {
+            await context.SendMessageAsync(NumberSignal.Above, 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);
+}