Microsoft Agent Framework Workflows Overview

Microsoft Agent Framework Workflows is a system for building intelligent automation that blends AI agents with business processes. It provides a type-safe, graph-based architecture that allows you to orchestrate complex workflows without infrastructure complexity.

Agent vs. Workflow

An agent is typically driven by a large language model (LLM) and has access to various tools. The steps an agent takes are dynamic and determined by the LLM based on the conversation context and available tools.

A workflow, on the other hand, is a predefined sequence of operations that can include AI agents as components. Workflows are designed to handle complex business processes involving multiple agents, human interactions, and integrations with external systems. The flow of a workflow is explicitly defined, giving you more control over the execution path.

Key Features

1. Type Safety - Strong typing ensures messages flow correctly between components with comprehensive validation that prevents runtime errors.
2. Flexible Control Flow - Graph-based architecture allows intuitive modeling of complex workflows with executors and edges. Conditional routing, parallel processing, and dynamic execution paths are all supported.
3. External Integration - Built-in request/response patterns for seamless integration with external APIs and human-in-the-loop scenarios.
4. Checkpointing - Save workflow states via checkpoints, enabling recovery and resumption of long-running processes.
5. Multi-Agent Orchestration - Built-in patterns for coordinating multiple AI agents, including sequential, concurrent, hand-off, and magentic patterns.

Core Concepts

Executors

Executors are the fundamental building blocks of a workflow. They are autonomous processing units that receive typed messages, perform operations, and produce output messages or events. Each executor has a unique identifier and can handle specific message types.

In C#, executors derive from the Executor base class and use the [MessageHandler] attribute on methods within a partial class. This uses compile-time source generation for handler registration, providing better performance and Native AOT compatibility.

An executor can return a value (which is automatically sent to connected executors), or manually send messages using context.SendMessageAsync(). An executor can also handle multiple input types by defining multiple [MessageHandler] methods.

For simple cases, you can create an executor from a function using the BindExecutor extension method:

Edges

Edges define how messages flow between executors. They represent connections in the workflow graph and determine data flow paths. The framework supports several edge patterns:

Conditional edges allow routing decisions based on message content. You supply a condition parameter (a function returning bool) when adding an edge. The condition is evaluated at runtime for each message.

Events

The workflow event system provides observability into execution. Events are emitted at key points and can be consumed in real-time via streaming. Built-in event types include:

1. WorkflowStartedEvent / WorkflowOutputEvent / WorkflowErrorEvent - Workflow lifecycle events
2. ExecutorInvokedEvent / ExecutorCompletedEvent / ExecutorFailedEvent - Executor processing events
3. SuperStepStartedEvent / SuperStepCompletedEvent - Superstep boundary events
4. AgentResponseEvent / AgentResponseUpdateEvent - Agent output events

Events are consumed using await foreach on run.WatchStreamAsync(), and you can define custom events by deriving from WorkflowEvent.

Workflow Builder and Execution

The WorkflowBuilder class provides a fluent API for constructing workflows. You specify a starting executor, add edges between executors, and call Build() to create the workflow.

Workflows support both streaming and non-streaming execution:

1. Streaming - InProcessExecution.StreamAsync(workflow, input) returns a StreamingRun that emits events as they happen.
2. Non-streaming - InProcessExecution.RunAsync(workflow, input) returns a Run after the workflow completes.

Supersteps (Execution Model)

The framework uses a modified Pregel execution model - a Bulk Synchronous Parallel (BSP) approach with superstep-based processing. Each superstep:

1. Collects all pending messages from the previous superstep.
2. Routes messages to target executors based on edge definitions.
3. Runs all target executors concurrently within the superstep.
4. Waits for all executors to complete (synchronization barrier) before advancing.
5. Queues any new messages emitted by executors for the next superstep.

This model provides deterministic execution (same input always produces same execution order), reliable checkpointing (state saved at superstep boundaries), and simpler reasoning (no race conditions between supersteps).