.NET: [Feature Branch] Add Human In the Loop support for durable workflows

dotnet/agent-framework-dotnet.slnx

@@ -55,10 +55,12 @@
     <Project Path="samples/Durable/Workflow/ConsoleApps/05_WorkflowEvents/05_WorkflowEvents.csproj" />
     <Project Path="samples/Durable/Workflow/ConsoleApps/06_WorkflowSharedState/06_WorkflowSharedState.csproj" />
     <Project Path="samples/Durable/Workflow/ConsoleApps/07_SubWorkflows/07_SubWorkflows.csproj" />
+    <Project Path="samples/Durable/Workflow/ConsoleApps/08_WorkflowHITL/08_WorkflowHITL.csproj" />
   </Folder>
   <Folder Name="/Samples/Durable/Workflows/AzureFunctions/">
     <Project Path="samples/Durable/Workflow/AzureFunctions/01_SequentialWorkflow/01_SequentialWorkflow.csproj" />
     <Project Path="samples/Durable/Workflow/AzureFunctions/02_ConcurrentWorkflow/02_ConcurrentWorkflow.csproj" />
+    <Project Path="samples/Durable/Workflow/AzureFunctions/03_WorkflowHITL/03_WorkflowHITL.csproj" />
   </Folder>
   <Folder Name="/Samples/GettingStarted/">
     <File Path="samples/GettingStarted/README.md" />
@@ -475,4 +477,4 @@
     <Project Path="tests/Microsoft.Agents.AI.Workflows.Generators.UnitTests/Microsoft.Agents.AI.Workflows.Generators.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Workflows.UnitTests/Microsoft.Agents.AI.Workflows.UnitTests.csproj" />
   </Folder>
-</Solution>
+</Solution>

dotnet/samples/Durable/Workflow/AzureFunctions/03_WorkflowHITL/03_WorkflowHITL.csproj

@@ -0,0 +1,43 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
+    <OutputType>Exe</OutputType>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <!-- The Functions build tools don't like namespaces that start with a number -->
+    <AssemblyName>WorkflowHITLFunctions</AssemblyName>
+    <RootNamespace>WorkflowHITLFunctions</RootNamespace>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <FrameworkReference Include="Microsoft.AspNetCore.App" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="local.settings.json" />
+  </ItemGroup>
+
+  <!-- Azure Functions packages -->
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Azure.Functions.Worker" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask.AzureManaged" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+
+  <!-- Local projects that should be switched to package references when using the sample outside of this MAF repo -->
+  <!--
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Agents.AI.Hosting.AzureFunctions" />
+  </ItemGroup>
+  -->
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Hosting.AzureFunctions\Microsoft.Agents.AI.Hosting.AzureFunctions.csproj" />
+  </ItemGroup>
+</Project>

dotnet/samples/Durable/Workflow/AzureFunctions/03_WorkflowHITL/Executors.cs

@@ -0,0 +1,63 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace WorkflowHITLFunctions;
+
+/// <summary>Expense approval request passed to the RequestPort.</summary>
+public record ApprovalRequest(string ExpenseId, decimal Amount, string EmployeeName);
+
+/// <summary>Approval response received from the RequestPort.</summary>
+public record ApprovalResponse(bool Approved, string? Comments);
+
+/// <summary>Looks up expense details and creates an approval request.</summary>
+internal sealed class CreateApprovalRequest() : Executor<string, ApprovalRequest>("RetrieveRequest")
+{
+    public override ValueTask<ApprovalRequest> HandleAsync(
+        string message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        // In a real scenario, this would look up expense details from a database
+        return new ValueTask<ApprovalRequest>(new ApprovalRequest(message, 1500.00m, "Jerry"));
+    }
+}
+
+/// <summary>Prepares the approval request for finance review after manager approval.</summary>
+internal sealed class PrepareFinanceReview() : Executor<ApprovalResponse, ApprovalRequest>("PrepareFinanceReview")
+{
+    public override ValueTask<ApprovalRequest> HandleAsync(
+        ApprovalResponse message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        if (!message.Approved)
+        {
+            throw new InvalidOperationException("Cannot proceed to finance review — manager denied the expense.");
+        }
+
+        // In a real scenario, this would retrieve the original expense details
+        return new ValueTask<ApprovalRequest>(new ApprovalRequest("EXP-2025-001", 1500.00m, "Jerry"));
+    }
+}
+
+/// <summary>Processes the expense reimbursement based on the parallel approval responses.</summary>
+internal sealed class ExpenseReimburse() : Executor<ApprovalResponse[], string>("Reimburse")
+{
+    public override async ValueTask<string> HandleAsync(
+        ApprovalResponse[] message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        // Check that all parallel approvals passed
+        ApprovalResponse? denied = Array.Find(message, r => !r.Approved);
+        if (denied is not null)
+        {
+            return $"Expense reimbursement denied. Comments: {denied.Comments}";
+        }
+
+        // Simulate payment processing
+        await Task.Delay(1000, cancellationToken);
+        return $"Expense reimbursed at {DateTime.UtcNow:O}";
+    }
+}

dotnet/samples/Durable/Workflow/AzureFunctions/03_WorkflowHITL/Program.cs

@@ -0,0 +1,51 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates a Human-in-the-Loop (HITL) workflow hosted in Azure Functions.
+//
+// ┌──────────────────────┐   ┌────────────────┐   ┌─────────────────────┐    ┌────────────────────┐
+// │ CreateApprovalRequest│──►│ManagerApproval │──►│PrepareFinanceReview │──┬►│  BudgetApproval    │──┐
+// └──────────────────────┘   │ (RequestPort)  │   └─────────────────────┘  │ │  (RequestPort)     │  │
+//                            └────────────────┘                            │ └────────────────────┘  │  ┌─────────────────┐
+//                                                                          │                         ├─►│ExpenseReimburse │
+//                                                                          │ ┌────────────────────┐  │  └─────────────────┘
+//                                                                          └►│ComplianceApproval  │──┘
+//                                                                            │  (RequestPort)     │
+//                                                                            └────────────────────┘
+//
+// The workflow pauses at three RequestPorts — one for the manager, then two in parallel for finance.
+// After manager approval, BudgetApproval and ComplianceApproval run concurrently via fan-out/fan-in.
+// The framework auto-generates three HTTP endpoints for each workflow:
+//   POST /api/workflows/{name}/run          - Start the workflow
+//   GET  /api/workflows/{name}/status/{id}  - Check status and pending approvals
+//   POST /api/workflows/{name}/respond/{id} - Send approval response to resume
+
+using Microsoft.Agents.AI.Hosting.AzureFunctions;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Azure.Functions.Worker.Builder;
+using Microsoft.Extensions.Hosting;
+using WorkflowHITLFunctions;
+
+// Define executors and RequestPorts for the three HITL pause points
+CreateApprovalRequest createRequest = new();
+RequestPort<ApprovalRequest, ApprovalResponse> managerApproval = RequestPort.Create<ApprovalRequest, ApprovalResponse>("ManagerApproval");
+PrepareFinanceReview prepareFinanceReview = new();
+RequestPort<ApprovalRequest, ApprovalResponse> budgetApproval = RequestPort.Create<ApprovalRequest, ApprovalResponse>("BudgetApproval");
+RequestPort<ApprovalRequest, ApprovalResponse> complianceApproval = RequestPort.Create<ApprovalRequest, ApprovalResponse>("ComplianceApproval");
+ExpenseReimburse reimburse = new();
+
+// Build the workflow: CreateApprovalRequest -> ManagerApproval -> PrepareFinanceReview -> [BudgetApproval AND ComplianceApproval] -> ExpenseReimburse
+Workflow expenseApproval = new WorkflowBuilder(createRequest)
+    .WithName("ExpenseReimbursement")
+    .WithDescription("Expense reimbursement with manager and parallel finance approvals")
+    .AddEdge(createRequest, managerApproval)
+    .AddEdge(managerApproval, prepareFinanceReview)
+    .AddFanOutEdge(prepareFinanceReview, [budgetApproval, complianceApproval])
+    .AddFanInEdge([budgetApproval, complianceApproval], reimburse)
+    .Build();
+
+using IHost app = FunctionsApplication
+    .CreateBuilder(args)
+    .ConfigureFunctionsWebApplication()
+    .ConfigureDurableWorkflows(workflows => workflows.AddWorkflow(expenseApproval, exposeStatusEndpoint: true))
+    .Build();
+app.Run();