Skip to main content

How to See Every Event in a Microsoft Agent Framework Workflow Run in C#

· 9 min read
Jagdish Kumawat
Founder @ Dewiride

A Microsoft Agent Framework workflow reports everything it does as an event: when it starts, when each step begins and ends, when it produces output, and when something fails. Most code only looks at the output. This guide prints every event of a small C# workflow, first after the run and then live, while it runs.

Syntax​

Syntax
// After the run has finished
await using Run <run> = await InProcessExecution.RunAsync(<workflow>, <input>);
foreach (WorkflowEvent <evt> in <run>.NewEvents) { ... }

// While the workflow runs
await using StreamingRun <run> = await InProcessExecution.RunStreamingAsync(<workflow>, <input>);
await foreach (WorkflowEvent <evt> in <run>.WatchStreamAsync()) { ... }
PartWhat it is
<workflow>, <input>The workflow to run, and the value its first step receives
RunAsync and NewEventsRunAsync runs the workflow inside your app. NewEvents returns the events produced since you last read it
RunStreamingAsync and WatchStreamAsync()RunStreamingAsync starts the workflow, and WatchStreamAsync() hands you each event as it happens
WorkflowEventThe base type of every event. Its Data holds the event's value, such as an executor's result

Microsoft's guide to workflow events lists the built-in types, with these descriptions:

EventDescription
WorkflowStartedEventWorkflow execution begins
WorkflowOutputEventWorkflow outputs data
WorkflowErrorEventWorkflow encounters an error
WorkflowWarningEventWorkflow encountered a warning
ExecutorInvokedEventExecutor starts processing
ExecutorCompletedEventExecutor finishes processing
ExecutorFailedEventExecutor encounters an error
AgentResponseEventAn agent run produces output
AgentResponseUpdateEventAn agent run produces a streaming update
SuperStepStartedEventSuperstep begins
SuperStepCompletedEventSuperstep completes
RequestInfoEventA request is issued

The Example​

A console app builds a workflow with two steps: Double doubles a number, then AddOne adds one. It runs the workflow with the number 20. There's no AI model in it, so nothing needs an Azure account.

Prerequisites​

  • The .NET 10 SDK. dotnet --version prints a version that starts with 10.0.

Step 1: Create a Console App​

In a terminal, in the folder where you keep your projects, create a console app, move into it and add the workflows package:

Terminal
dotnet new console -n NumberWorkflow
cd NumberWorkflow
dotnet add package Microsoft.Agents.AI.Workflows --version 1.28.0
Output (first command)
The template "Console App" was created successfully.

Processing post-creation actions...
Restoring /Users/you/source/NumberWorkflow/NumberWorkflow.csproj:
Restore succeeded.

Microsoft.Agents.AI.Workflows is Agent Framework's workflows package, and --version keeps you on the version this guide used. Open the NumberWorkflow folder in VS Code, or NumberWorkflow.csproj in Visual Studio.

Step 2: Run the Workflow and Print Its Output​

Replace everything in Program.cs with:

Program.cs
using Microsoft.Agents.AI.Workflows;

// Two steps: double the number, then add one.
Func<int, int> doubleIt = number => number * 2;
Func<int, int> addOne = number => number + 1;

var doubler = doubleIt.BindAsExecutor("Double");
var adder = addOne.BindAsExecutor("AddOne");

Workflow workflow = new WorkflowBuilder(doubler)
.AddEdge(doubler, adder)
.WithOutputFrom(adder)
.Build();

await using Run run = await InProcessExecution.RunAsync(workflow, 20);
foreach (WorkflowEvent evt in run.NewEvents)
{
if (evt is WorkflowOutputEvent output)
{
Console.WriteLine($"Output: {output.Data}");
}
}
  • BindAsExecutor turns each function into an executor, a step of the workflow, with the name in quotes.
  • AddEdge(doubler, adder) sends what Double returns to AddOne, and WithOutputFrom(adder) makes the result of AddOne the workflow's output.
  • InProcessExecution.RunAsync runs the workflow with the input 20 and returns once it's done.
  • The loop goes over the run's events and prints only the output event.

Run the app:

In the terminal, in the NumberWorkflow folder, run:

Terminal
dotnet run
Output
Output: 41

20 doubled is 40, and one more is 41. That one line hides everything else the workflow did.

Step 3: Print Every Event​

Replace the foreach loop with one that prints every event:

Program.cs (replace the foreach loop)
foreach (WorkflowEvent evt in run.NewEvents)
{
Console.WriteLine(evt switch
{
ExecutorInvokedEvent invoked => $"{evt.GetType().Name}: {invoked.ExecutorId} received {invoked.Data}",
ExecutorCompletedEvent completed => $"{evt.GetType().Name}: {completed.ExecutorId} returned {completed.Data}",
SuperStepStartedEvent started => $"{evt.GetType().Name}: superstep {started.StepNumber}",
SuperStepCompletedEvent finished => $"{evt.GetType().Name}: superstep {finished.StepNumber}",
_ => $"{evt.GetType().Name}: {evt.Data}",
});
}
  • evt.GetType().Name is the event's type.
  • The executor events carry the executor's name in ExecutorId, and its input or result in Data.
  • The superstep events carry the superstep's number in StepNumber.
  • Every other event prints its Data.

Run the app again:

Output
WorkflowStartedEvent:
SuperStepStartedEvent: superstep 0
ExecutorInvokedEvent: Double received 20
ExecutorCompletedEvent: Double returned 40
SuperStepCompletedEvent: superstep 0
SuperStepStartedEvent: superstep 1
ExecutorInvokedEvent: AddOne received 40
ExecutorCompletedEvent: AddOne returned 41
WorkflowOutputEvent: 41
SuperStepCompletedEvent: superstep 1

Ten events tell the whole story. The workflow started, ran Double in superstep 0 and AddOne in superstep 1, and produced 41 before the second superstep ended. Microsoft's guide explains supersteps: Workflow execution is organized into discrete supersteps, and the workflow does not advance to the next superstep until every executor completes. Executors that receive a message in the same superstep run at the same time, and when checkpoints are switched on, they're saved between supersteps.

Step 4: Watch the Events While the Workflow Runs​

RunAsync hands you the events once the workflow has finished. For a workflow that takes a while, such as one with agents in it, you'll want to see each event as it happens. Replace these two lines:

Program.cs (replace)
await using Run run = await InProcessExecution.RunAsync(workflow, 20);
foreach (WorkflowEvent evt in run.NewEvents)

with:

Program.cs (new)
await using StreamingRun run = await InProcessExecution.RunStreamingAsync(workflow, 20);
await foreach (WorkflowEvent evt in run.WatchStreamAsync())
  • RunStreamingAsync starts the workflow and returns a StreamingRun right away.
  • WatchStreamAsync() gives you each event as the workflow emits it, and ends when the workflow does. Microsoft's events guide uses it with await foreach, as here.

Run the app again:

Output
WorkflowStartedEvent:
SuperStepStartedEvent: superstep 0
ExecutorInvokedEvent: Double received 20
ExecutorCompletedEvent: Double returned 40
SuperStepCompletedEvent: superstep 0
SuperStepStartedEvent: superstep 1
ExecutorInvokedEvent: AddOne received 40
ExecutorCompletedEvent: AddOne returned 41
WorkflowOutputEvent: 41
SuperStepCompletedEvent: superstep 1

macOS-style terminal window titled Terminal — NumberWorkflow showing dotnet run printing ten workflow events: WorkflowStartedEvent, superstep 0 with Double receiving 20 and returning 40, superstep 1 with AddOne receiving 40 and returning 41, WorkflowOutputEvent: 41 and the end of superstep 1

The same ten events in the same order. The difference is when you get them: as they happen, instead of all at once at the end.

The Complete File​

Program.cs
using Microsoft.Agents.AI.Workflows;

// Two steps: double the number, then add one.
Func<int, int> doubleIt = number => number * 2;
Func<int, int> addOne = number => number + 1;

var doubler = doubleIt.BindAsExecutor("Double");
var adder = addOne.BindAsExecutor("AddOne");

Workflow workflow = new WorkflowBuilder(doubler)
.AddEdge(doubler, adder)
.WithOutputFrom(adder)
.Build();

await using StreamingRun run = await InProcessExecution.RunStreamingAsync(workflow, 20);
await foreach (WorkflowEvent evt in run.WatchStreamAsync())
{
Console.WriteLine(evt switch
{
ExecutorInvokedEvent invoked => $"{evt.GetType().Name}: {invoked.ExecutorId} received {invoked.Data}",
ExecutorCompletedEvent completed => $"{evt.GetType().Name}: {completed.ExecutorId} returned {completed.Data}",
SuperStepStartedEvent started => $"{evt.GetType().Name}: superstep {started.StepNumber}",
SuperStepCompletedEvent finished => $"{evt.GetType().Name}: superstep {finished.StepNumber}",
_ => $"{evt.GetType().Name}: {evt.Data}",
});
}

macOS-style code window titled Program.cs — NumberWorkflow showing two functions bound as the executors Double and AddOne, a WorkflowBuilder with an edge between them, and InProcessExecution.RunStreamingAsync with the input 20, whose WatchStreamAsync loop prints each event by type

Common Mistakes​

MistakeWhat happensDo this instead
Reading NewEvents twiceThe second read is empty: NewEvents returns only the events since the last read. When I read it twice after a run, the first read returned every event and the second noneRead it once and keep what you need, or use OutgoingEvents, which returns every event of the run
Looking only for WorkflowOutputEventA step that fails looks like a run that produced nothingAlso handle ExecutorFailedEvent and WorkflowErrorEvent

Troubleshooting​

SymptomLikely causeFix
No WorkflowOutputEvent, and no exceptionA step threw. RunAsync doesn't throw for it: the failure is in the eventsPrint every event: an ExecutorFailedEvent and a WorkflowErrorEvent hold the exception in Data

FAQ​

What happens when a step fails?​

I made AddOne throw an exception for numbers over 30 to see it. RunAsync returned normally, without throwing. The events stopped after ExecutorInvokedEvent: AddOne received 40 with an ExecutorFailedEvent, which held the exception, and a WorkflowErrorEvent, which held it wrapped in a TargetInvocationException. There was no output event, and the run's status was Ended.

Why is the output event before the end of the superstep?​

Because AddOne produced the output during superstep 1, and the superstep ends only after that. The output belongs to the superstep that produced it.

Can my own executors send events?​

Yes. Microsoft's events guide shows how: derive a class from WorkflowEvent, and call AddEventAsync on the workflow context from inside an executor. Your events then arrive in the same loop as the built-in ones.

Conclusion​

A workflow's events show everything it did: when it started, each executor with its input and result, the supersteps, the output and any failure. Read them after the run with RunAsync and NewEvents, or as they happen with RunStreamingAsync and WatchStreamAsync(). Print all of them while you build a workflow, and handle the failure events in code that runs for real.

Additional Resources​