Upgrading to AOT Workflows in Microsoft Agent Framework (RC2)

This post shows how to set up, configure, and upgrade Microsoft Agent Framework Workflow Ahead-of-Time (AOT) compiled message handlers.

As of this post, the Microsoft Agent Framework is a Release Candidate (1.0.0-rc2). For performance reasons, it is now recommended to use AOT code generators for messaging instead of the previous reflection-based approach. This shift is essential for high-scale deployments and environments where minimizing cold-start latency is a priority.

Let's take a look at how to do this...

Required Packages

To create workflows using the recommended AOT approach, you need to install the following NuGet packages:

• Microsoft.Agents.AI.Workflows (1.0.0-rc2)
• Microsoft.Agents.AI.Workflows.Generators (1.0.0-rc2)

Important: The Generators package is the most critical piece. It is often omitted in early documentation or basic samples, but without it, the required routing code will not be generated, resulting in compilation errors or runtime failures.

The Workflow Executor

The Workflow Executor is the core of your agent workflow logic. When moving to an AOT-compatible workflow, there are two primary changes you need to make to your class definitions.

Partial Keyword for Code Generation

You must add the partial keyword to your executor class definition. This is a requirement for .NET Source Generators; it allows the tooling to generate a companion partial class containing the necessary boilerplate for message routing.

public partial class DemoExecutor() : Executor("Demo")

Simplified Class Definitions

If you are upgrading from previous versions of the Microsoft Agent Framework, you will notice that message generics (e.g., Executor<TIn, TOut>) are no longer required in the base executor definition. The AOT code generators now parse your methods directly to determine the expected types, making your class signatures much cleaner.

The Message Handler Attribute

The [MessageHandler] attribute is the signal that tells the code generator which methods should be part of the workflow. In an AOT environment, this replaces the runtime reflection used to discover handlers.

By tagging a method with this attribute, the generator inspects the method signature—looking at the input parameter and the return type—to automatically build the routing map for your executor.

[MessageHandler]
private async ValueTask<bool> HandleAsync(
              string message, 
              IWorkflowContext context, 
              CancellationToken cancellationToken = default)

Manual Message Sending

In certain scenarios, you may want to send a custom message along a specific edge that doesn't match your method's return value. You can achieve this by using the workflow context to call SendMessageAsync directly.

await context.SendMessageAsync("message", cancellationToken: cancellationToken);

When using AOT code generation, the [MessageHandler] attribute by default only generates routing logic for the types explicitly defined in the method signature (the input and the return). If you try to call SendMessageAsync with a type that isn't in that signature, the code will fail at runtime. The exception will inform you that your executor is not configured to send messages of that specific type.

This happens because the source generator didn't "see" the manual call inside your method body and therefore didn't generate the necessary metadata in the partial class.

How to Fix It

To resolve this, you must explicitly inform the code generator about any additional types you plan to send manually using the Send property on the attribute:

[MessageHandler(Send = [typeof(string)])]
private async ValueTask<bool> HandleAsync(string message, IWorkflowContext context, 
                                      CancellationToken cancellationToken = default)
{
      await context.SendMessageAsync("message", cancellationToken: cancellationToken);
}

Until Next Time

Moving to AOT-compiled workflows is a significant step forward for the Microsoft Agent Framework. Although it requires more explicit configuration regarding the partial keyword and manual message types, the trade-off is a much more robust and performant system.

By following these steps, you ensure your agents are ready for production-scale environments where efficiency is key.