Understanding Durable Workflows in the Microsoft Agent Framework: Key Questions Answered

The Microsoft Agent Framework (MAF) is an open-source, multi-language platform for building and orchestrating AI agents. Its workflow programming model enables developers to compose agents into multi-step pipelines with capabilities like parallel execution, conditional branching, and human approvals. Below we answer common questions about MAF's workflow system, from basic concepts to implementation details.

What exactly is the Microsoft Agent Framework and its workflow model?

The Microsoft Agent Framework (MAF) is an open-source framework that supports multiple programming languages for creating, coordinating, and deploying AI agents. Its recently added workflow programming model allows you to combine multiple agents and other tasks into multi-step pipelines. You define individual steps called executors, arrange them into a directed graph using a workflow builder, and the framework manages execution, data transfer between steps, and error handling. This model supports sequential chains, parallel fan-out/fan-in patterns, conditional branching, and human-in-the-loop approvals. A lightweight in-process runner is included for quick local development, executing workflows entirely in memory. The framework is designed to be extensible, enabling you to add durability, parallel AI agents, and serverless hosting with Azure Functions.

How do you define executors in a MAF workflow?

An executor is the fundamental unit of work in MAF. To create one, you subclass Executor<TInput, TOutput> and override the HandleAsync method. This method receives typed input, performs processing—such as database lookups, AI calls, or business logic—and returns typed output. For example, an OrderLookup executor takes an OrderCancelRequest and returns an Order object after simulating a lookup. Each executor is named using a string identifier in its constructor, which is used for logging and debugging. The IWorkflowContext parameter provides access to shared workflow state and dependencies. Executors are lightweight and can be chained together using the workflow builder to form complex pipelines. They also support cancellation tokens for graceful shutdown.

What types of workflow patterns does MAF support?

MAF allows you to model a wide variety of workflow patterns out of the box. You can create sequential pipelines where one executor runs after another, and parallel fan-out/fan-in patterns where multiple executors run concurrently and their results are merged. Conditional branching enables decision points that route execution based on intermediate data, while human-in-the-loop approvals pause execution until a human actor confirms or rejects a step. The directed graph structure also supports loops, retries, and compensation actions. These patterns are defined declaratively using the workflow builder API, making it easy to visualize and modify the execution flow. Each pattern is implemented as a special executor that orchestrates child steps, giving you fine-grained control over concurrency and error recovery.

How does the workflow builder work?

The workflow builder is a fluent API that lets you construct a directed acyclic graph (DAG) of executors. You start by creating a WorkflowBuilder instance, then add executors and define edges between them using methods like From and To. For example, you can connect an OrderLookup executor to an OrderCancel executor, specifying that the output of the first becomes the input of the second. The builder handles type matching and validates the graph structure at build time. It also supports parallel branches, conditional edges based on output properties, and error handlers. Once the graph is defined, you call Build to create a Workflow object that can be executed using the in-process runner. The builder ensures data flow contracts between executors, so mismatched types are caught early.

How do I get started with MAF workflows in a .NET console app?

To begin, create a new .NET console application and add the Microsoft.Agents.AI and Microsoft.Agents.AI.Workflows NuGet packages. Then implement your first executors by subclassing Executor<TInput, TOutput> as described earlier. Next, use the WorkflowBuilder to chain them together. For instance, you can define a simple order cancellation workflow: OrderLookup → OrderCancel → SendEmail. Once built, instantiate the WorkflowRunner and call RunAsync with the initial input. The runner executes steps synchronously in-memory by default, ideal for testing. From there, you can extend the workflow with durability by adding a persistent store, or scale it to Azure Functions for serverless execution. The framework provides extension points for logging, retry policies, and state persistence.

How does MAF add durability to workflows?

Durability in MAF is achieved by persisting the execution state of a workflow to an external storage backend, such as Azure Cosmos DB, SQL Server, or a simple file system. When durability is enabled, the workflow runner records the progress of each executor, including its input, output, and any errors. If the process crashes or is restarted, the runner can resume the workflow from the last completed step rather than starting over. This is particularly important for long-running workflows that involve human approvals or external API calls. The durable execution model uses event sourcing: all state changes are stored as events, allowing replay and debugging. To enable it, you configure a IWorkflowStore implementation in the runner's dependency injection. The workflow builder then automatically integrates checkpointing and recovery logic, making your workflows resilient to failures.

Can you provide a complete example of a MAF workflow?

Sure. Consider an order cancellation workflow with three executors: OrderLookup, OrderCancel, and SendEmail. The OrderLookup executor takes a cancel request and returns an Order object. OrderCancel receives that Order and sets its IsCancelled property to true. SendEmail then accepts the updated Order and outputs a confirmation string. Using the workflow builder, you wire them: builder.From(OrderLookup).To(OrderCancel); builder.From(OrderCancel).To(SendEmail);. After building, run with var result = await runner.RunAsync(workflow, new OrderCancelRequest(...));. The result contains the final output and a history of each step. This pattern can be extended with parallelism (e.g., multiple email notifiers) or conditional branches (e.g., skip cancellation if order is already shipped). Each executor remains focused on a single responsibility, and the framework handles orchestration, data flow, and error propagation transparently.