{"id":60055,"date":"2026-05-06T10:00:00","date_gmt":"2026-05-06T17:00:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/dotnet\/?p=60055"},"modified":"2026-05-03T21:37:30","modified_gmt":"2026-05-04T04:37:30","slug":"durable-workflows-in-microsoft-agent-framework","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/dotnet\/durable-workflows-in-microsoft-agent-framework\/","title":{"rendered":"Durable Workflows in the Microsoft Agent Framework"},"content":{"rendered":"

The Microsoft Agent Framework (MAF)<\/a>\nis an open-source, multi-language framework for building, orchestrating, and\ndeploying AI agents. Since its\npreview announcement<\/a>,\nthe framework has added a workflow programming model<\/strong> that lets you compose\nmultiple agents and other units of work into multi-step pipelines. You define\nindividual steps called executors<\/em>, wire them into a directed graph using a\nworkflow builder<\/em>, and the framework handles execution, data flow between\nsteps, and error propagation. Workflows can model sequential chains, parallel\nfan-out\/fan-in patterns, conditional branching, human-in-the-loop approvals,\nand more.<\/p>\n

The core workflow package includes a lightweight in-process runner<\/strong> that\nexecutes workflows entirely in memory. It’s perfect for getting started\nquickly and for local development. In this post, we’ll start by building a\nsimple workflow in a .NET console app, then progressively add durability,\nparallel AI agents, and Azure Functions hosting.<\/p>\n

The Workflow Programming Model<\/h2>\n

To get started, create a new console app project and add the following NuGet packages:<\/p>\n

dotnet add package Microsoft.Agents.AI\r\ndotnet add package Microsoft.Agents.AI.Workflows<\/code><\/pre>\n
Let’s start with the core building blocks of a MAF workflow.<\/p>\n
Executors<\/h3>\n
An Executor<\/strong> is the fundamental unit of work. It receives a typed input,\nprocesses it, and produces output. You create one by subclassing\nExecutor<TInput, TOutput><\/code>:<\/p>\n
using Microsoft.Agents.AI.Workflows;\r\n\r\ninternal sealed class OrderLookup()\r\n    : Executor<OrderCancelRequest, Order>(\"OrderLookup\")\r\n{\r\n    public override async ValueTask<Order> HandleAsync(\r\n        OrderCancelRequest message,\r\n        IWorkflowContext context,\r\n        CancellationToken cancellationToken = default)\r\n    {\r\n        \/\/ Simulate looking up an order by ID\r\n        await Task.Delay(TimeSpan.FromMilliseconds(100), cancellationToken);\r\n\r\n        return new Order(\r\n            Id: message.OrderId,\r\n            OrderDate: DateTime.UtcNow.AddDays(-1),\r\n            IsCancelled: false,\r\n            CancelReason: message.Reason,\r\n            Customer: new Customer(\r\n                Name: \"Jerry\", Email: \"jerry@example.com\"));\r\n    }\r\n}\r\n\r\ninternal sealed class OrderCancel()\r\n    : Executor<Order, Order>(\"OrderCancel\")\r\n{\r\n    public override async ValueTask<Order> HandleAsync(\r\n        Order message,\r\n        IWorkflowContext context,\r\n        CancellationToken cancellationToken = default)\r\n    {\r\n        await Task.Delay(TimeSpan.FromMilliseconds(200), cancellationToken);\r\n        return message with { IsCancelled = true };\r\n    }\r\n}\r\n\r\ninternal sealed class SendEmail()\r\n    : Executor<Order, string>(\"SendEmail\")\r\n{\r\n    public override ValueTask<string> HandleAsync(\r\n        Order message,\r\n        IWorkflowContext context,\r\n        CancellationToken cancellationToken = default)\r\n    {\r\n        return ValueTask.FromResult(\r\n            $\"Cancellation email sent for order {message.Id} \"\r\n            + $\"to {message.Customer.Email}.\");\r\n    }\r\n}\r\n\r\ninternal sealed record OrderCancelRequest(string OrderId, string Reason);\r\ninternal sealed record Order(\r\n    string Id, DateTime OrderDate, bool IsCancelled,\r\n    string? CancelReason, Customer Customer);\r\ninternal sealed record Customer(string Name, string Email);<\/code><\/pre>\n
The generic type parameters define each executor’s contract: TInput<\/code> is\nwhat it receives from the previous step (or the workflow’s initial input),\nand TOutput<\/code> is what it passes downstream. The string in the base\nconstructor (e.g., \"OrderLookup\"<\/code>) is the executor’s unique ID within\nthe workflow.<\/p>\n
WorkflowBuilder<\/h3>\n
The WorkflowBuilder<\/strong> wires executors into a directed graph. You define\nedges between executors to control the flow of data, and the builder produces\nan immutable Workflow<\/code> object. Here is what the CancelOrder workflow graph\nlooks like:<\/p>\n
OrderLookup \u2500\u2500\u25ba OrderCancel \u2500\u2500\u25ba SendEmail<\/code><\/pre>\n
OrderLookup orderLookup = new();\r\nOrderCancel orderCancel = new();\r\nSendEmail sendEmail = new();\r\n\r\nWorkflow cancelOrder = new WorkflowBuilder(orderLookup)\r\n    .WithName(\"CancelOrder\")\r\n    .WithDescription(\"Cancel an order and notify the customer\")\r\n    .AddEdge(orderLookup, orderCancel)\r\n    .AddEdge(orderCancel, sendEmail)\r\n    .Build();<\/code><\/pre>\n
The TOutput<\/code> of each executor must match the TInput<\/code> of the executor\nit flows into, and the framework enforces this at compile time.<\/p>\n
Running In-Process<\/h3>\n
The quickest way to run a workflow is in-process with\nInProcessExecution.RunStreamingAsync<\/code>. This returns a StreamingRun<\/code>\nthat emits events as each step completes:<\/p>\n
var cancelRequest = new OrderCancelRequest(\r\n    OrderId: \"123\", Reason: \"Wrong color\");\r\n\r\nawait using StreamingRun run =\r\n    await InProcessExecution.RunStreamingAsync(\r\n        cancelOrder, input: cancelRequest);\r\n\r\nawait foreach (WorkflowEvent evt in run.WatchStreamAsync())\r\n{\r\n    if (evt is ExecutorCompletedEvent completed)\r\n    {\r\n        Console.WriteLine(\r\n            $\"{completed.ExecutorId}: {completed.Data}\");\r\n    }\r\n}<\/code><\/pre>\n
This is all it takes to run a workflow. No external dependencies, no\ninfrastructure setup, just a .NET console app. Run it with:<\/p>\n
dotnet run<\/code><\/pre>\n
Making Workflows Durable<\/h2>\n
The in-process runner executes everything in memory, so if the process\nexits (whether from a crash, a restart, or simply reaching the end of a\nlong-running step), all workflow state is lost. Real-world AI agent\nworkflows often need to survive process restarts, run for extended\nperiods, and be observable from external tooling. The\nMicrosoft.Agents.AI.DurableTask<\/code> package adds all of this to any MAF\nworkflow without changing the workflow definition. It is powered by the\nDurable Task tech stack<\/a>.<\/p>\n
Install the package:<\/p>\n
dotnet add package Microsoft.Agents.AI.DurableTask --prerelease<\/code><\/pre>\n
The durable runtime provides:<\/p>\n