Orchestrating Complex Tasks with Microsoft Agent Framework Workflows

On this page
Microsoft Agent Framework
Workflows
are graph-based, developer-defined processes: a fixed set of steps
(executors) connected by edges that run in a predictable order. Use them
instead of a conversational ChatAgent when specific steps must always
run, approvals must happen at the right points, and you need to trace
afterwards what happened. In this guide we build a four-step IT ticket
workflow in Python, run it from the console and in the DevUI, and then
add conditional edges that route high-priority tickets to an alert.
In our previous
article, we built
a practical IT Helpdesk agent using the Microsoft Agent
Framework.
The ChatAgent interacted with users, used tools to check system
statuses and managed a conversation's state. It understood user intent
and took immediate, reactive steps.
Real-world business processes are rarely that simple, though. What happens when a process spans several days, like a manager's approval for a new software license? How do you handle a task that must pause, wait for a human decision, and then resume without losing context? What about a multi-step data pipeline where each step must succeed before the next one begins, and the whole sequence needs to be auditable?
This is where the conversational ChatAgent reaches its limits. A
ChatAgent handles ad-hoc requests dynamically and decides what to do
based on its input. A Workflow defines a fixed, graph-based sequence of
steps. Workflows are designed for complex, long-running processes where
reliability and auditability are requirements.
This post covers the orchestration engine itself: how to build, run and inspect workflows, with linear and conditional paths. Durability and the "human-in-the-loop" pattern, which make enterprise AI a bit more complex but trustworthy, are out of scope here.
Update (November 2026): Several APIs used below changed in 2026. Per Microsoft's
Python upgrade guide,
ChatAgent is now Agent and set_start_executor() was removed (both in python-1.0.0b260210), so the
start node now goes into the constructor as WorkflowBuilder(start_executor=...). AzureOpenAIResponsesClient
was removed in python-1.0.0rc6, and since 1.0.0 the core agent-framework packages install without --pre.
ChatAgent vs. Workflow: choosing the right tool
Before writing code, you need to make a basic architectural decision in
the Microsoft Agent Framework: when to use a conversational ChatAgent
and when to build a structured Workflow. The two are not
interchangeable. Each solves a different class of problems.
ChatAgent: the conversationalist
As shown in our previous guide, the ChatAgent is good at open-ended,
dynamic interaction. The Large Language Model at its core steers its
behavior. You give it instructions, a set of tools and a user prompt, and
the agent reasons about the best course of action. Its path isn't
predetermined; it emerges from the dialogue.
A ChatAgent fits user-facing conversational interfaces (chatbots,
copilots), ad-hoc tasks where the user's intent guides the process, and
cases where flexibility and natural language understanding matter more
than a rigid, repeatable process.
The driving logic is the LLM's turn-by-turn reasoning: it plans, executes
a tool, observes the result and re-plans in a loop. The agent's state
lives in the AgentThread, which holds the conversation history. That is
ideal for the context of a single, continuous interaction, but it isn't
designed for long-term persistence across system restarts without extra
engineering. The main strength of a ChatAgent is flexibility: it adapts
to unexpected requests and handles complex conversations without a
script.
Workflow: the structured orchestrator
A Workflow, by contrast, is a deterministic, graph-based process defined by the developer. If an agent is a smart employee given a goal, a workflow is the documented business process that employee has to follow.
The control flow is explicit: a series of nodes (Executors) connected
by edges. An LLM can be used within a node to perform an intelligent
task, but it doesn't control the overall direction of the process. In our
view, this explicit structure is what enables the framework's best
enterprise features.
Workflows fit established business processes (expense approvals, user onboarding), long-running tasks that need to pause and resume (waiting for human input, running a multi-hour data job), and cases where auditability, reliability and a predictable execution path are non-negotiable.
The driving logic is a developer-defined execution graph. The flow moves
from one Executor to the next based on predefined connections and
conditional logic. Workflows are built for durability: they are designed
to be checkpointed, so their state can be serialized and saved to
persistent storage (like a database) at any point. That lets them survive
restarts and wait indefinitely for external events. The main strength of
a Workflow is reliability: the process is predictable, auditable and
resilient to interruption.
Embedding agents in workflows
You don't have to choose one or the other. The most sophisticated
solutions often combine both patterns: a Workflow orchestrates the
high-level process, and one of its nodes is a ChatAgent that handles a
specific, agent-like sub-task.
Consider a document processing pipeline:
- Workflow Node 1 (Executor): A simple function fetches a new PDF from a SharePoint folder. This step is deterministic and reliable.
- Workflow Node 2 (Agent): The PDF is passed to a
ChatAgentwith the instruction: "You are a legal analyst. Read this document, summarize the key clauses, and extract the names of all involved parties into a JSON object." This step uses the LLM's reasoning for a complex, unstructured task. - Workflow Node 3 (Executor): The structured JSON output from the agent is saved into a database. This is another deterministic, reliable step.
Note: We see many projects where people simply use an agent for
exactly this process. Why not slap a PDF reading tool and a database
writing tool onto an agent and call it a day? Because LLMs are
nondeterministic across hundreds and thousands of executions. The more
decisions you leave to the LLM, the higher the risk of failure. And it
will fail. A Workflow that orchestrates the overall process makes sure
the critical steps (fetching the PDF, saving to the database) always
run, while the ChatAgent still handles the complex task of document
understanding.
Incoming customer orders are a common candidate for this kind of pipeline. At Meusburger, 96% of orders arriving by email, PDF or Excel go into the system without correction.
This hybrid approach combines the auditable orchestration of a Workflow with the flexible reasoning of an agent for specific, well-contained tasks. We describe more patterns like this in building high-quality AI agent systems.
Here is a simple rule of thumb for making the choice:
| Use a ChatAgent when... | Use a Workflow when... |
|---|---|
| The primary interface is a conversation with a user. | You are automating a back-end, multi-step business process. |
| The sequence of steps is unpredictable and LLM-driven. | The sequence of steps is known and should be predictable. |
| The task is relatively short-lived (seconds to minutes). | The process could be long-running (hours or days). |
| You need maximum flexibility to handle diverse inputs. | You need maximum reliability, auditability, and control. |
Note: As always, treat such tables as guidelines, not hard rules.
Core workflow concepts: executors, edges and context
To build a workflow, you construct an executable directed acyclic graph (DAG). The Microsoft Agent Framework provides a clear set of components for defining the nodes, edges and data flow of this graph. You need to understand them to design modular, maintainable automated processes.
Executors: the nodes of the graph
An Executor is the basic unit of computation in a workflow: a single, self-contained node in the execution graph. Each executor should have a single responsibility: receive an input, perform a specific operation and produce an output. This keeps the workflow modular and testable.
The framework supports two implementation patterns for executors:
- Class-based Executors: For components with complex logic, internal
state or significant configuration, define a class that inherits from
agent_framework.Executor. This object-oriented approach suits non-trivial business logic. - Function-based Executors: For stateless, single-purpose
transformations, define an
asyncfunction and apply the@executordecorator. This lightweight pattern suits simple data mapping, filtering or routing nodes.
Handlers (@handler): the execution entry point
Within a class-based Executor, the @handler decorator marks the
async method that the workflow engine invokes. This method is the entry
point for the node's logic.
For function-based executors, the function itself is implicitly the
handler, so the @executor decorator is enough. @handler explicitly
declares the execution logic within a class.
WorkflowBuilder and edges: defining the graph topology
A collection of executors isn't a workflow until its structure is
defined. The WorkflowBuilder is the fluent API for defining the
graph's topology: the directed edges that dictate the flow of control and
data between executors.
The WorkflowBuilder API has declarative methods for constructing the
graph:
set_start_executor(executor): Specifies the entry point node for the workflow.add_edge(source_executor, destination_executor): Establishes a directed edge. When thesource_executoremits a message, the workflow engine routes it as input to thedestination_executor.add_edge(source_executor, destination_executor, condition=...): Creates branches in the graph. Theconditionfunction receives the message and decides whether the edge is taken, so data is routed based on its content. You need this for business rules and conditional logic.
This approach separates the orchestration logic (the graph structure) from the business logic (the executor implementations), which keeps the system maintainable.
WorkflowContext: the interface to the workflow engine
Executors don't interact with each other directly. They are fully
decoupled and communicate through the workflow engine via the
WorkflowContext object (ctx), which is passed as an argument to
every handler.
WorkflowContext provides two methods for controlling data flow:
ctx.send_message(data): Emits output from the current executor. The engine intercepts this call and routes thedatapayload to all downstream nodes connected by outgoing edges. This is the standard way to pass data between nodes.ctx.yield_output(data): Used by terminal nodes to publish a final result for the entire workflow. Any data passed toyield_outputis collected and returned to the external client that started the workflow run. A workflow can have multiple terminal nodes and can yield multiple outputs.
Hands-on part 1: building a multi-step IT request workflow
The best way to understand workflows is to build one. We'll create a multi-step workflow that automates the initial processing, enrichment and logging of an IT support request.
The workflow is a four-step pipeline:
- Categorize: An LLM analyzes a raw user request and extracts structured details like the problem area and priority.
- Enrich: The workflow takes the extracted category and "enriches" the ticket by looking up the responsible IT support team in a predefined knowledge base.
- Format: It combines all this information into a clean JSON object, ready for an API.
- Create Ticket: Finally, it simulates a call to an external ticketing system API and yields a final confirmation message.
We'll first build and run the workflow from the command line to see the end-to-end process. Then we'll use the framework's built-in Dev Web UI as a visual interface for debugging and interaction.
Prerequisites
Before you begin, make sure your environment has all the necessary components, including those for the web UI.
-
Install the necessary packages:
-
Configure Azure OpenAI Environment Variables: The workflow uses the
AzureOpenAIResponsesClient. Make sure the following are set:AZURE_OPENAI_ENDPOINTAZURE_OPENAI_CHAT_DEPLOYMENT_NAMEAZURE_OPENAI_RESPONSES_DEPLOYMENT_NAMEAZURE_OPENAI_API_KEY
Step 1: Define the data models and executors
The workflow passes strongly typed data between nodes using Pydantic models. We define four executors, one for each step of the pipeline.
Create a file named executors.py.
Step 2: Build and run the workflow from the console
With the four executors defined, we can wire them together and run the workflow directly to test the end-to-end logic.
Create a main.py file with the following content.
Now run it from your terminal: python main.py. You will see the log
output from each of the four nodes in sequence, confirming that the
workflow executed correctly.
Expected Console Output:
Step 3: Visualize the workflow with the DevUI
Running from the console is fine for validation, but the framework also ships a very nice tool for development and debugging: the Dev Web UI. It visualizes the execution graph, shows the data flowing between nodes and lets you run the workflow interactively.
Let's adapt main.py to launch this UI.
1. Create the Workflow Object: First, define a reusable workflow object outside of the main execution block.
2. Modify main.py to Serve the UI: Replace the run_workflow
function and the main execution block with the code to serve the UI.
Now run the updated script: python main.py. A browser window opens at
http://localhost:8091.
First, you'll see your workflow in an interactive graph view.
DevUI graph of the four-step IT ticket triage workflow
Click the "Configure & Run" button to enter a sample user request and execute the workflow.
DevUI dialog for entering the workflow input and running it
During execution, you can watch the data flow through each node, inspect inputs and outputs, and verify that each step behaves as expected.
DevUI execution timeline with all four nodes completed and final output
Hands-on part 2: conditional edges for high-priority alerts
Linear workflows are a good starting point, but real business processes often need branching. A critical support request should not follow the same path as a routine one. The Microsoft Agent Framework handles this with conditional edges, which route data based on its content.
Next, we extend the IT triage workflow to handle high-priority tickets differently. If a ticket is classified as "High" priority, the workflow branches and sends it to a separate "Send Alert" notification node (which we simulate). Low and Medium priority tickets follow the standard ticket creation path.
This adds a decision point to the graph, so the automation responds to the urgency of each request.
Step 1: Add an alert executor and condition functions
We need a new executor for sending alerts and functions that define the
routing logic. Both go into the existing executors.py file.
1. Add the New SendAlertExecutor
This is a new terminal node for the high-priority branch.
2. Create the Condition Function
A condition function is a simple boolean function that inspects the data flowing through an edge and decides whether that path should be taken.
Update your executors.py file with the following additions:
Step 2: Build the branched workflow
Now we update main.py to construct the new, non-linear graph. We use
add_edge with the condition parameter to create two branches after
the enrich_node:
- The
enrich_nodebecomes the decision point. - If
is_high_priorityreturnsTrue, the data flows tosend_alert_executor. - If
is_normal_priorityreturnsTrue, the data flows to the originalformat_ticket_executorpath.
Modify your main.py to reflect this new structure.
Step 3: Test both branches in the DevUI
Run the updated main.py script. The DevUI now displays the branched
graph.
DevUI graph with separate format-and-create and send-alert branches
Test Case 1: Normal Priority
Enter I need to reset my password for the HR portal, I forgot the old one.
and click "Run Workflow". The LLM should classify this as "Low" or
"Medium" priority. In the DevUI graph, the workflow executes the upper
branch, Enrich -> Format -> Create Ticket, and the final output is the
standard ticket creation confirmation.
Test Case 2: High Priority
Enter The entire payment processing service is down! We cannot process any customer credit cards!
and click "Run Workflow". The LLM will classify this as "High"
priority, and the workflow executes the lower branch, Enrich -> Send Alert.
The final output in the UI is the high-priority alert message.
With conditional edges, the workflow is no longer a simple pipeline: it changes its behavior based on the data it processes. You'll need this pattern for automations that deal with the variability of real-world requests.
Summary: from pipelines to processes
In this guide, we moved from the conversational ChatAgent to the
structured orchestration of Workflows. We started with a linear pipeline
that chains four executors to turn unstructured user input into enriched,
structured data for a downstream system.
We then added conditional logic. Branching on the data's content (in our case, ticket priority) turned the pipeline into a business process that treats urgent and routine requests differently. Explicit, auditable and conditional execution paths like these are the basis of reliable enterprise automation.
The workflows built so far are still self-contained and run from start to finish in a single run. The most critical enterprise processes often don't work this way. They need to persist state across system restarts, pause for long periods to wait for external events, and, most importantly, incorporate human judgment for critical decisions.
The framework has building blocks for these production requirements too:
- Durability and State Management: Workflows can use checkpointing to become durable. A workflow can then be paused, its state persisted to a database, and resumed hours or even days later, which protects it against system interruptions.
- Human-in-the-Loop Integration: An approval step lets the workflow pause and wait for an external signal, such as a manager's decision, before proceeding. This is how you build trustworthy AI systems that combine the speed of automation with human oversight.
The official workflow documentation linked below covers both.
Official resources
- Official Documentation on Workflows: The definitive source for workflow concepts, advanced patterns and API references.
- GitHub Repository: Explore the source code, find more examples (including the ones used in this article), and contribute to the project.
- Introductory Blog Post: Read the original announcement from Microsoft for more context on the vision and strategy behind the framework.
Interested in building high-quality AI agent systems?
We prepared a comprehensive guide based on cutting-edge research for how to build robust, reliable AI agent systems that actually work in production. This guide covers:
- Understanding the 14 systematic failure modes in multi-agent systems
- Evidence-based best practices for agent design
- Structured communication protocols and verification mechanisms
Further reading
- Building Enterprise-Grade AI Agents with Microsoft's Agent
Framework: The
first article in this series and the starting point for understanding
the
ChatAgentpattern and the framework's core enterprise features. - AI Agents From Scratch: A guide to the core concepts of how AI agents work, from planning to tool execution, which gives context for the agentic components you can embed within workflows.
- Langfuse: The Open Source Observability Platform: Observability is critical for production systems. This post covers the tools and techniques for monitoring and debugging complex LLM applications and workflows.
- Building a RAG Pipeline with Azure AI Search: How to power your agents and workflows with internal knowledge by building a retrieval-augmented generation system on Azure.
- AI Agents with n8n: A different, low-code approach to building agentic workflows, useful as a comparison for process automation.
- Using SharePoint Lists as Knowledge Sources in Copilot Studio: The low-code route in the Microsoft stack: a Copilot Studio agent with agent flow tools that query SharePoint data.
- LLM Tracing with Opik: Traces, evaluations and monitoring dashboards for LLM applications, as an alternative to Langfuse.
- Azure OpenAI Content Filters: What the default filters block in business scenarios and how to configure them before your workflows hit them in production.


