Principle:Microsoft Agent framework Workflow Graph Construction

Knowledge Sources	Microsoft Agent Framework
Domains	Workflow_Engine
Last Updated	2026-02-11 00:00 GMT

Overview

A graph construction pattern that assembles a directed acyclic graph (DAG) of executors into an immutable, validated workflow using a fluent builder API. The WorkflowBuilder class is the primary mechanism in the Microsoft Agent Framework for wiring executors together with typed edges, supporting fan-out, fan-in, and conditional branching topologies before compiling the graph into a sealed Workflow instance.

Description

The WorkflowBuilder provides a declarative, fluent interface for constructing directed graphs of executors. Rather than requiring users to manually assemble adjacency lists or manage graph state, the builder exposes chainable methods that incrementally define the topology of the workflow.

The construction process follows three phases:

1. Initialization -- The builder is created with a designated start executor, optional output executors, and workflow-level configuration such as maximum iteration count, name, description, and checkpoint storage.
2. Edge wiring -- Callers use add_edge, add_fan_out_edges, and add_fan_in_edges to connect executors. Each method registers directed edges in the internal graph representation.
3. Compilation -- The build() method validates the assembled graph and produces an immutable Workflow instance that is ready for execution.

Edge Types

The builder supports three fundamental edge patterns:

Pattern	Method	Description
Sequential	add_edge(source, target)	Connects a single source executor to a single target executor. Optionally accepts a condition callable for conditional routing.
Fan-out	add_fan_out_edges(source, targets)	Connects a single source executor to multiple target executors. All targets receive the output of the source and execute concurrently.
Fan-in	add_fan_in_edges(sources, target)	Connects multiple source executors to a single target executor. The target waits until all sources have completed before executing.

Type Compatibility Validation

During edge wiring and at build time, the builder validates that connected executors have compatible I/O types. When a source executor's output type does not match the target executor's expected input type, the builder raises a validation error. This ensures that type mismatches are caught at graph construction time rather than at runtime, following a fail-fast design philosophy.

Conditional Edges

The add_edge method accepts an optional condition parameter -- a callable that receives the source executor's output and returns a boolean. When a condition is present, the edge is only traversed if the condition evaluates to True. This enables dynamic branching within the workflow graph without requiring a separate router abstraction.

Immutability

The build() method produces a sealed Workflow object. Once built, the graph topology cannot be modified. This guarantees that concurrent executions of the same workflow operate on a stable, unchanging graph structure, eliminating an entire class of race conditions and mutation-related bugs.

Theoretical Basis

The Workflow Graph Construction principle is grounded in directed graph composition:

workflow = start_executor -> [edge(source, target)]* -> output_executors

Key design properties:

• Builder pattern: The WorkflowBuilder separates the construction of a complex object (the workflow graph) from its representation. Callers incrementally configure the graph through a fluent API and receive the finished product via build().
• Fluent interface: Every wiring method returns Self, enabling method chaining that reads as a declarative specification of the graph topology.
• Structural validation: Type compatibility checks at edge-wiring time enforce that the graph is well-formed before execution, shifting errors from runtime to construction time.
• Fan-out / fan-in duality: The explicit support for both divergence (fan-out) and convergence (fan-in) patterns allows complex parallel topologies to be expressed without auxiliary orchestration code.

Usage

Linear Pipeline

from agent_framework import WorkflowBuilder

workflow = (
    WorkflowBuilder(start_executor=step1)
    .add_edge(step1, step2)
    .add_edge(step2, step3)
    .build()
)

Fan-Out / Fan-In Diamond

from agent_framework import WorkflowBuilder

workflow = (
    WorkflowBuilder(start_executor=dispatcher)
    .add_fan_out_edges(dispatcher, [analyst_a, analyst_b, analyst_c])
    .add_fan_in_edges([analyst_a, analyst_b, analyst_c], aggregator)
    .build()
)

Conditional Branching

from agent_framework import WorkflowBuilder

workflow = (
    WorkflowBuilder(start_executor=classifier)
    .add_edge(classifier, positive_handler, condition=lambda out: out.label == "positive")
    .add_edge(classifier, negative_handler, condition=lambda out: out.label == "negative")
    .build()
)

Related Pages

Implemented By

• Implementation:Microsoft_Agent_framework_WorkflowBuilder_Init