Python: .NET: Executor source gen for workflow executor routing #3131

alliscode · 2026-01-08T00:52:24Z

This pull request introduces a new Roslyn source generator project for the Microsoft Agent Framework Workflows, enabling compile-time route configuration for executor classes using the [MessageHandler] attribute. It includes the generator implementation, diagnostics, build configuration, and integration into the solution and dependency management.

Follow-up PRs will update samples and docs to use this new pattern and obsolete the ReflectingExecutor

New Source Generator Project:

Added new project Microsoft.Agents.AI.Workflows.Generators targeting netstandard2.0, with all necessary build and NuGet packaging settings, and Roslyn dependencies for source generator development. [1] [2]

Source Generator Implementation:

Implemented the ExecutorRouteGenerator class, a Roslyn incremental source generator that scans for [MessageHandler] methods and generates partial classes to configure workflow routes at compile time.
Added the SourceBuilder utility to generate the actual C# code for route configuration, including overrides for ConfigureRoutes, ConfigureSentTypes, and ConfigureYieldTypes as needed.

Diagnostics and Analysis:

Introduced DiagnosticDescriptors to define and register custom diagnostics for common usage errors (e.g., missing parameters, invalid return types, non-partial classes, etc.) in handler methods and executor classes.

Solution and Dependency Integration:

Registered the new generator project and its corresponding unit test project in the solution file (agent-framework-dotnet.slnx). [1] [2]
Updated Directory.Packages.props to include Microsoft.CodeAnalysis.Analyzers as a dependency for code analysis support.### Motivation and Context

Contribution Checklist

The code builds clean without any errors or warnings
The PR follows the Contribution Guidelines
All unit tests pass, and I have added new tests where possible
Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

dotnet/src/Microsoft.Agents.AI.Workflows.Generators/Analysis/SemanticAnalyzer.cs

lokitoth · 2026-01-16T14:49:27Z

dotnet/src/Microsoft.Agents.AI.Workflows.Generators/Diagnostics/DiagnosticDescriptors.cs

+    /// </summary>
+    public static readonly DiagnosticDescriptor MissingWorkflowContext = Register(new(
+        id: "MAFGENWF001",
+        title: "Handler missing IWorkflowContext parameter",


We don't need to localize these strings, right?

dotnet/src/Microsoft.Agents.AI.Workflows.Generators/Analysis/SemanticAnalyzer.cs

lokitoth · 2026-01-16T14:59:28Z

dotnet/src/Microsoft.Agents.AI.Workflows.Generators/ExecutorRouteGenerator.cs

+    public void Initialize(IncrementalGeneratorInitializationContext context)
+    {
+        // Step 1: Use ForAttributeWithMetadataName to efficiently find methods with [MessageHandler] attribute. For each method found, build a MethodAnalysisResult.
+        var methodAnalysisResults = context.SyntaxProvider


Rooting the analysis on the methods annotated by [MessageHandler] is likely simpler than starting with extends(Executor), but it has the drawback that if we only want to use SourceGeneration for the Send/Yield types, and manually create the routes, we ignore that Executor class;

We should also do a bit of perf work here, after we settle on the API surface (attributes, what gets generated / not).

Agreed that we should update this to handle Send/Yield types even with manual routing, but I don't think we'd want to root on extends(Executor). Rooting on an attribute with ForAttributeWithMetadataName claims to be at least 99x faster.

I've updated things to handle this case while still rooting on ForAttributeWithMetadataName .

lokitoth · 2026-01-16T15:08:37Z

dotnet/src/Microsoft.Agents.AI.Workflows.Generators/Generation/SourceBuilder.cs

+        sb.AppendLine($"{indent}partial class {info.ClassName}{info.GenericParameters}");
+        sb.AppendLine($"{indent}{{");
+
+        var memberIndent = indent + "    ";


We may want to consider using the AnalyzerConfigOptionsProvider mechanism to get the indent style / spacecount from .editorconfig, so that the generated code matches the general project style.

Interesting idea. By default, these generated "files" are not written to actual files and even in VS/Code you have to look in the package dependency to see the virtual file. I'm not sure I see the value in trying to match spacecount etc.

lokitoth · 2026-01-16T15:14:43Z

dotnet/src/Microsoft.Agents.AI.Workflows.Generators/Analysis/SemanticAnalyzer.cs

+    {
+        var builder = ImmutableArray.CreateBuilder<string>();
+
+        foreach (var attr in classSymbol.GetAttributes())


Does this always get iterated in the same order?

Since we are creating immutable arrays that are presumably used as some form of comparator somewhere, do we want/need to ensure this is permutation invariant?

Good call out. They are consistent (source order) for a given file, but the partial classes may break that. I've added explicit sort to this and other places that have this issue.

lokitoth · 2026-01-16T15:26:19Z

dotnet/src/Microsoft.Agents.AI.Workflows.Generators/Generation/SourceBuilder.cs

+                AppendHandlerGenericArgs(sb, handler);
+                sb.Append($"(this.{handler.MethodName})");
+
+                if (isLast)


If you pull this out of the loop you can avoid the conditional and just do sb.AppendLine(";");.

Pulled it out and added a line to clean up the extra newline

dotnet/tests/Microsoft.Agents.AI.Workflows.Generators.UnitTests/ExecutorRouteGeneratorTests.cs

dotnet/src/Microsoft.Agents.AI.Workflows/Attributes/YieldsMessageAttribute.cs

…uteGenerator.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…next.

…ine caching.

peibekwe · 2026-01-16T20:29:05Z

dotnet/src/Microsoft.Agents.AI.Workflows.Generators/Analysis/SemanticAnalyzer.cs

+
+            foreach (var namedArg in attr.NamedArguments)
+            {
+                if (namedArg.Key == "Yield" && !namedArg.Value.IsNull)


nit: Should this be a case sensitive comparison just to be safe?

peibekwe · 2026-01-16T21:33:18Z

dotnet/src/Microsoft.Agents.AI.Workflows.Generators/ExecutorRouteGenerator.cs

+    {
+        var sb = new StringBuilder();
+
+        if (!string.IsNullOrEmpty(info.Namespace))


nit: Probably better to use IsNullOrWhitespace or is whitespace a valid namespace?

peibekwe · 2026-01-16T21:34:23Z

dotnet/src/Microsoft.Agents.AI.Workflows.Generators/Generation/SourceBuilder.cs

+        sb.AppendLine();
+
+        // Namespace
+        if (!string.IsNullOrEmpty(info.Namespace))


Same comment for this.

markwallace-microsoft added documentation Improvements or additions to documentation .NET workflows Related to Workflows in agent-framework labels Jan 8, 2026

alliscode had a problem deploying to integration January 8, 2026 00:52 — with GitHub Actions Failure

github-actions bot changed the title ~~Initial working version with tests.~~ .NET: Initial working version with tests. Jan 8, 2026

alliscode changed the title ~~.NET: Initial working version with tests.~~ .NET: Draft- Executor source gen for workflows Jan 8, 2026

alliscode had a problem deploying to integration January 8, 2026 16:15 — with GitHub Actions Failure

alliscode temporarily deployed to integration January 8, 2026 16:15 — with GitHub Actions Inactive

alliscode had a problem deploying to integration January 8, 2026 17:34 — with GitHub Actions Failure

alliscode temporarily deployed to integration January 8, 2026 19:11 — with GitHub Actions Inactive

alliscode temporarily deployed to integration January 8, 2026 19:29 — with GitHub Actions Inactive

alliscode temporarily deployed to integration January 8, 2026 22:34 — with GitHub Actions Inactive

alliscode had a problem deploying to integration January 8, 2026 22:34 — with GitHub Actions Failure

alliscode temporarily deployed to integration January 9, 2026 00:31 — with GitHub Actions Inactive

alliscode had a problem deploying to integration January 9, 2026 00:31 — with GitHub Actions Failure

alliscode temporarily deployed to integration January 9, 2026 00:59 — with GitHub Actions Inactive

alliscode had a problem deploying to integration January 9, 2026 00:59 — with GitHub Actions Failure

alliscode had a problem deploying to integration January 9, 2026 22:39 — with GitHub Actions Failure

alliscode temporarily deployed to integration January 9, 2026 22:39 — with GitHub Actions Inactive

alliscode temporarily deployed to integration January 10, 2026 01:06 — with GitHub Actions Inactive

alliscode had a problem deploying to integration January 10, 2026 01:06 — with GitHub Actions Failure

alliscode force-pushed the wf-source-gen branch from 0ed461a to 46bb208 Compare January 12, 2026 17:46

alliscode had a problem deploying to integration January 12, 2026 17:47 — with GitHub Actions Failure

alliscode had a problem deploying to integration January 12, 2026 17:47 — with GitHub Actions Error

alliscode force-pushed the wf-source-gen branch from 46bb208 to 97c7f78 Compare January 12, 2026 17:57

alliscode marked this pull request as ready for review January 12, 2026 17:57

alliscode had a problem deploying to integration January 12, 2026 22:36 — with GitHub Actions Failure

alliscode temporarily deployed to integration January 12, 2026 22:48 — with GitHub Actions Inactive

alliscode had a problem deploying to integration January 12, 2026 22:48 — with GitHub Actions Failure

alliscode temporarily deployed to integration January 12, 2026 23:02 — with GitHub Actions Inactive

alliscode force-pushed the wf-source-gen branch from 3930d93 to d675f46 Compare January 12, 2026 23:23

alliscode temporarily deployed to integration January 12, 2026 23:23 — with GitHub Actions Inactive

alliscode temporarily deployed to integration January 14, 2026 17:34 — with GitHub Actions Inactive

lokitoth mentioned this pull request Jan 15, 2026

.NET: Reconcile Executor Configure and ConfigureXYZ methods #3242

Open

lokitoth reviewed Jan 16, 2026

View reviewed changes

alliscode requested a review from a team as a code owner January 16, 2026 20:34

markwallace-microsoft added python lab Agent Framework Lab labels Jan 16, 2026

github-actions bot changed the title ~~.NET: Executor source gen for workflow executor routing~~ Python: .NET: Executor source gen for workflow executor routing Jan 16, 2026

alliscode had a problem deploying to integration January 16, 2026 20:35 — with GitHub Actions Error

alliscode and others added 5 commits January 16, 2026 12:39

Roslyn Source Generators for Workflow Executor Routing.

90a2ab0

Update dotnet/src/Microsoft.Agents.AI.Workflows.Generators/ExecutorRo…

d40ed1b

…uteGenerator.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

WIP.

b9c2588

All fixed up except dangling sends/yields attriutes, working on that …

27824ed

…next.

Add protocol-only generation for SendsMessage/YieldsOutput attributes

7878562

alliscode force-pushed the wf-source-gen branch from 7da1da4 to 7878562 Compare January 16, 2026 20:42

alliscode temporarily deployed to integration January 16, 2026 20:43 — with GitHub Actions Inactive

Ensuring collections that can change order are sorted to enable pipel…

8acbd99

…ine caching.

alliscode temporarily deployed to integration January 16, 2026 21:01 — with GitHub Actions Inactive

peibekwe approved these changes Jan 16, 2026

View reviewed changes

Python: .NET: Executor source gen for workflow executor routing #3131

Are you sure you want to change the base?

Python: .NET: Executor source gen for workflow executor routing #3131

Uh oh!

Conversation

alliscode commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Follow-up PRs will update samples and docs to use this new pattern and obsolete the ReflectingExecutor

Contribution Checklist

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

alliscode commented Jan 8, 2026 •

edited

Loading