Merge pull request #736 from jozkee/docs_workflows

Suggestions for tutorials/workflow

Author: TaoChenOSU

agent-framework/tutorials/agents/agent-as-mcp-tool.md

@@ -24,8 +24,8 @@ For prerequisites see the [Create and run a simple agent](./run-agent.md#prerequ
 To use Microsoft Agent Framework with Azure OpenAI, you need to install the following NuGet packages:
 
 ```dotnetcli
+dotnet add package Azure.AI.OpenAI --prerelease
 dotnet add package Azure.Identity
-dotnet add package Azure.AI.OpenAI
 dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
 ```
 

agent-framework/tutorials/agents/enable-observability.md

@@ -28,8 +28,8 @@ For prerequisites, see the [Create and run a simple agent](./run-agent.md#prereq
 To use Microsoft Agent Framework with Azure OpenAI, you need to install the following NuGet packages:
 
 ```dotnetcli
+dotnet add package Azure.AI.OpenAI --prerelease
 dotnet add package Azure.Identity
-dotnet add package Azure.AI.OpenAI
 dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
 ```
 

agent-framework/tutorials/agents/run-agent.md

@@ -38,8 +38,8 @@ Before you begin, ensure you have the following prerequisites:
 To use Microsoft Agent Framework with Azure OpenAI, you need to install the following NuGet packages:
 
 ```dotnetcli
+dotnet add package Azure.AI.OpenAI --prerelease
 dotnet add package Azure.Identity
-dotnet add package Azure.AI.OpenAI
 dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
 ```
 

agent-framework/tutorials/agents/third-party-chat-history-storage.md

@@ -28,8 +28,8 @@ For prerequisites, see the [Create and run a simple agent](./run-agent.md) step
 To use Microsoft Agent Framework with Azure OpenAI, you need to install the following NuGet packages:
 
 ```dotnetcli
+dotnet add package Azure.AI.OpenAI --prerelease
 dotnet add package Azure.Identity
-dotnet add package Azure.AI.OpenAI
 dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
 ```
 

agent-framework/tutorials/quick-start.md

@@ -39,7 +39,7 @@ Packages will be published to [NuGet Gallery | MicrosoftAgentFramework](https://
 First, add the following Microsoft Agent Framework NuGet packages into your application, using the following commands:
 
 ```dotnetcli
-dotnet add package Azure.AI.OpenAI
+dotnet add package Azure.AI.OpenAI --prerelease
 dotnet add package Azure.Identity
 dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
 ```

agent-framework/tutorials/workflows/agents-in-workflows.md

@@ -29,14 +29,25 @@ You'll create a workflow that:
 
 ## Prerequisites
 
-- .NET 9.0 or later
-- Agent Framework installed via NuGet
-- Azure Foundry project configured with proper environment variables
-- Azure CLI authentication: `az login`
+- [.NET 8.0 SDK or later](https://dotnet.microsoft.com/download)
+- Azure Foundry service endpoint and deployment configured
+- [Azure CLI installed](/cli/azure/install-azure-cli) and [authenticated (for Azure credential authentication)](/cli/azure/authenticate-azure-cli)
+- A new console application
 
-## Step 1: Import Required Dependencies
+## Step 1: Install NuGet packages
+
+First, install the required packages for your .NET project:
+
+```dotnetcli
+dotnet add package Azure.AI.Agents.Persistent --prerelease
+dotnet add package Azure.Identity
+dotnet add package Microsoft.Agents.AI.AzureAI --prerelease
+dotnet add package Microsoft.Agents.AI.Workflows --prerelease
+```
+
+## Step 2: Set Up Azure Foundry Client
 
-Start by importing the necessary components for Azure Foundry agents and workflows:
+Configure the Azure Foundry client with environment variables and authentication:
 
 ```csharp
 using System;
@@ -46,20 +57,13 @@ using Azure.Identity;
 using Microsoft.Agents.AI;
 using Microsoft.Agents.AI.Workflows;
 using Microsoft.Extensions.AI;
-```
-
-## Step 2: Set Up Azure Foundry Client
 
-Configure the Azure Foundry client with environment variables and authentication:
-
-```csharp
 public static class Program
 {
     private static async Task Main()
     {
         // Set up the Azure Foundry client
-        var endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_ENDPOINT")
-            ?? throw new InvalidOperationException("AZURE_FOUNDRY_PROJECT_ENDPOINT is not set.");
+        var endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_ENDPOINT") ?? throw new Exception("AZURE_FOUNDRY_PROJECT_ENDPOINT is not set.");
         var model = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_MODEL_ID") ?? "gpt-4o-mini";
         var persistentAgentsClient = new PersistentAgentsClient(endpoint, new AzureCliCredential());
 ```
@@ -116,11 +120,11 @@ Connect the agents in a sequential workflow using the WorkflowBuilder:
 
 ## Step 6: Execute with Streaming
 
-Run the workflow with streaming to observe real-time updates from both agents:
+Run the workflow with streaming to observe real-time updates from all agents:
 
 ```csharp
         // Execute the workflow
-        StreamingRun run = await InProcessExecution.StreamAsync(workflow, new ChatMessage(ChatRole.User, "Hello World!"));
+        await using StreamingRun run = await InProcessExecution.StreamAsync(workflow, new ChatMessage(ChatRole.User, "Hello World!"));
 
         // Must send the turn token to trigger the agents.
         // The agents are wrapped as executors. When they receive messages,

agent-framework/tutorials/workflows/checkpointing-and-resuming.md

@@ -15,8 +15,21 @@ Checkpointing allows workflows to save their state at specific points and resume
 
 ::: zone pivot="programming-language-csharp"
 
+## Prerequisites
+
+- [.NET 8.0 SDK or later](https://dotnet.microsoft.com/download)
+- A new console application
+
 ## Key Components
 
+## Install NuGet packages
+
+First, install the required packages for your .NET project:
+
+```dotnetcli
+dotnet add package Microsoft.Agents.AI.Workflows --prerelease
+```
+
 ### CheckpointManager
 
 The `CheckpointManager` provides checkpoint storage and retrieval functionality:
@@ -43,44 +56,48 @@ var workflow = await WorkflowHelper.GetWorkflowAsync();
 var checkpointManager = CheckpointManager.Default;
 
 // Execute with checkpointing enabled
-Checkpointed<StreamingRun> checkpointedRun = await InProcessExecution
+await using Checkpointed<StreamingRun> checkpointedRun = await InProcessExecution
     .StreamAsync(workflow, NumberSignal.Init, checkpointManager);
 ```
 
 ## State Persistence
 
 ### Executor State
 
-Executors can persist local state that survives checkpoints using the `ReflectingExecutor` base class:
+Executors can persist local state that survives checkpoints using the `Executor<T>` base class:
 
 ```csharp
-internal sealed class GuessNumberExecutor : ReflectingExecutor<GuessNumberExecutor>, IMessageHandler<NumberSignal>
+internal sealed class GuessNumberExecutor : Executor<NumberSignal>
 {
-    private static readonly StateKey StateKey = new("GuessNumberExecutor.State");
+    private const string StateKey = "GuessNumberExecutor.State";
 
     public int LowerBound { get; private set; }
     public int UpperBound { get; private set; }
 
-    public async ValueTask HandleAsync(NumberSignal message, IWorkflowContext context)
+    public GuessNumberExecutor() : base("GuessNumber")
+    {
+    }
+
+    public override async ValueTask HandleAsync(NumberSignal message, IWorkflowContext context, CancellationToken cancellationToken = default)
     {
         int guess = (LowerBound + UpperBound) / 2;
-        await context.SendMessageAsync(guess);
+        await context.SendMessageAsync(guess, 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, (LowerBound, UpperBound));
+        context.QueueStateUpdateAsync(StateKey, (LowerBound, UpperBound), 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)
     {
-        var state = await context.ReadStateAsync<(int, int)>(StateKey);
+        var state = await context.ReadStateAsync<(int, int)>(StateKey, cancellationToken);
         (LowerBound, UpperBound) = state;
     }
 }
@@ -158,7 +175,7 @@ Resume execution from a checkpoint and stream events in real-time:
 // Resume from a specific checkpoint with streaming
 CheckpointInfo savedCheckpoint = checkpoints[checkpointIndex];
 
-Checkpointed<StreamingRun> resumedRun = await InProcessExecution
+await using Checkpointed<StreamingRun> resumedRun = await InProcessExecution
     .ResumeStreamAsync(workflow, savedCheckpoint, checkpointManager, runId);
 
 await foreach (WorkflowEvent evt in resumedRun.Run.WatchStreamAsync())
@@ -218,7 +235,7 @@ Create a new workflow instance from a checkpoint:
 var newWorkflow = await WorkflowHelper.GetWorkflowAsync();
 
 // Resume with the new instance from a saved checkpoint
-Checkpointed<StreamingRun> newCheckpointedRun = await InProcessExecution
+await using Checkpointed<StreamingRun> newCheckpointedRun = await InProcessExecution
     .ResumeStreamAsync(newWorkflow, savedCheckpoint, checkpointManager, originalRunId);
 
 await foreach (WorkflowEvent evt in newCheckpointedRun.Run.WatchStreamAsync())
@@ -300,7 +317,7 @@ public static class CheckpointingExample
         Console.WriteLine("Starting workflow with checkpointing...");
 
         // Execute workflow with checkpointing
-        Checkpointed<StreamingRun> checkpointedRun = await InProcessExecution
+        await using Checkpointed<StreamingRun> checkpointedRun = await InProcessExecution
             .StreamAsync(workflow, NumberSignal.Init, checkpointManager);
 
         // Monitor execution and collect checkpoints
@@ -357,7 +374,7 @@ public static class CheckpointingExample
 
             Console.WriteLine("Rehydrating from checkpoint 4 with new workflow instance...");
 
-            Checkpointed<StreamingRun> newRun = await InProcessExecution
+            await using Checkpointed<StreamingRun> newRun = await InProcessExecution
                 .ResumeStreamAsync(newWorkflow, rehydrationCheckpoint, checkpointManager, checkpointedRun.Run.RunId);
 
             await foreach (WorkflowEvent evt in newRun.Run.WatchStreamAsync())