.NET: [BREAKING] Unify ExecutorIsh and ExecutorRegistration, unify/simplify APIs #1637

lokitoth · 2025-10-22T19:18:12Z

Motivation and Context

ExecutorIsh, a type built to work around the lack of full support for anonymous discriminated unions in .NET, leads to confusion, and makes it difficult to find how to integrate Executor-like types into a workflow. It also duplicates some functionality with ExecutorRegistration, and now that something broke in F#'s ability to feed the auto-cast types to WorkflowBuilder the value of the split between the two is lowered.

Description

Unifies ExecutorIsh and ExecutorRegistration, relying on the record type hierarchy for sum-type-like behaviour
Normalizes extension methods to convert objects into ExecutorRegistrations: .AsExecutor() and .RegisterExecutor()
Add extra explicit extension methods to correspond to implicit casts
Adds overload to support simpler function-to-executor pattern
Fixes .NET: Cannot reuse Workflow with shared Executor instances that do not implement IResettableExecutor #1613

Breaking:

Removes ExecutorIsh type, in favour of ExecutorRegistration
Obsoletes .ConfigureFactory() and .ConfigureSubworkflow() extension methods in favour of .RegisterExecutor() and .AsExecutor(), respectively

Relevant Issues:

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.

Copilot

Pull Request Overview

This PR removes the ExecutorIsh type and unifies its functionality with ExecutorRegistration, now implemented as a record-based type hierarchy. The change simplifies the API by normalizing extension methods to .AsExecutor() and .RegisterExecutor(), while obsoleting older methods like .ConfigureFactory() and .ConfigureSubworkflow().

Key Changes:

Replaced ExecutorIsh with an abstract ExecutorRegistration record class hierarchy
Added concrete registration types: ExecutorInstanceRegistration, SubworkflowRegistration, RequestPortRegistration, AIAgentRegistration, PlaceholderRegistration, and ConfiguredExecutorRegistration
Updated all extension methods to use .AsExecutor() and .RegisterExecutor() naming conventions

Reviewed Changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated 16 comments.

Show a summary per file

File	Description
ExecutorIsh.cs	Deleted file - entire `ExecutorIsh` type removed
ExecutorRegistration.cs	Converted from internal sealed class to public abstract record class with type hierarchy
ExecutorRegistrationExtensions.cs	New file containing unified extension methods for creating registrations
ExecutorInstanceRegistration.cs	New registration type for executor instances
SubworkflowRegistration.cs	New registration type for workflows used as executors
RequestPortRegistration.cs	New registration type for request ports
AIAgentRegistration.cs	New registration type for AI agents
PlaceholderRegistration.cs	New registration type for unbound executor references
ConfiguredExecutorRegistration.cs	New registration type for configured executors
WorkflowBuilder.cs	Updated to use `ExecutorRegistration` instead of `ExecutorIsh`
Workflow.cs	Updated property names and reset logic for new registration model
Sample files	Updated to use new `.AsExecutor()` and `.RegisterExecutor()` methods

dotnet/src/Microsoft.Agents.AI.Workflows/ExecutorRegistrationExtensions.cs

dotnet/src/Microsoft.Agents.AI.Workflows/ExecutorRegistration.cs

crickman · 2025-10-22T21:29:56Z

Good riddance Executorish (imho).

crickman · 2025-10-22T21:30:03Z

For thew new public registration types, is there sample debt being incurred here? If so, can some issues be created to track new samples that might be desired?

crickman · 2025-10-22T21:30:31Z

Are there any patterns here that should be channeled back into the python platform? @ekzhu?

crickman · 2025-10-22T21:31:06Z

Do we have tests that cover the issues being closed?

lokitoth · 2025-10-22T21:47:54Z

For thew new public registration types, is there sample debt being incurred here?

Not really: It's the same thing as with ExecutorIsh before, just broken out into a type hierarchy, and merged with ExecutorRegistration. Not really expected to be used directly, vs. using the .AsExecutor(), RegisterExecutor() and implicits. There is an issue I am leaving opened referenced here that will be used to track to finish the documentation of the FunctionExecutor APIs and helpers. (#1505)

Do we have tests that cover the issues being closed?

Yes, the test was updated to cover the scenario that discovered this.

* Switch to more modern Record type-tree for Sum Types * Unify APIs for getting ExecutorRegistration * Fix an issue where workflows consisting entirely of cross-run shareable executors which are not instance-resettable do not properly clear state when running non-concurrently.

ReubenBond · 2025-10-22T23:10:47Z

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/RepresentationTests.cs

-            Assert.Fail("Not all ExecutorIsh types were tested.");
-        }
+        // It would be great if there was a way to test exhaustion for record-based Sum Types
+        // TODO: Unit tests don't have to be AOT-compatible, so...


Looks like there's a proposal for "closed hierarchies" https://github.com/dotnet/csharplang/blob/7603e3bee2ea3edb53e6a3b27efbaf24949b609f/proposals/closed-hierarchies.md

Nice, that could help with certainty of exhaustiveness!

Would still probably need reflection to count them, which is more what I was getting at in the TODO.

crickman · 2025-10-23T00:20:17Z

For thew new public registration types, is there sample debt being incurred here?

Not really: It's the same thing as with ExecutorIsh before, just broken out into a type hierarchy, and merged with ExecutorRegistration. Not really expected to be used directly, vs. using the .AsExecutor(), RegisterExecutor() and implicits. There is an issue I am leaving opened referenced here that will be used to track to finish the documentation of the FunctionExecutor APIs and helpers. (#1505)

Do we have tests that cover the issues being closed?

Yes, the test was updated to cover the scenario that discovered this.

if its not expected / intended to be used directly, then why public?

stephentoub · 2025-10-23T02:48:55Z

dotnet/samples/GettingStarted/Workflows/_Foundational/01_ExecutorsAndEdges/Program.cs

+        Func<string, string> uppercaseFunc = s => s.ToUpperInvariant();
+        var uppercase = uppercaseFunc.AsExecutor("UppercaseExecutor");


If this were instead just a static method like Executor.Create, it could instead be:

var uppercase = Executor.Create<string, string>(s => s.ToUpperInvariant(), "UppercaseExecutor");

Is there a reason to prefer Executor.Create<TIn, TOut> over Executor<TIn, TOut>.Create?

Also, one can just do new FunctionExecutor<TIn, TOut>(s => s.ToUpperInvariant(), "..."), or even better, get rid of var, put the type on the left, and use typeless new(...). Maybe we should remove the .AsExecutor() overloads for functions and instead put the overloads on the FunctionExecutor ctors?

(I was genuinely disappointed when I realized that it cannot be applied directly to a method, or a lambda in parens, so less valuable as an API than I had thought it would be. Feels like a very low-hanging fruit to be able to bind that way, especially in the extensions-everything world - but then, this is the "implicit cast" thing again, and I know your stance on that :))

Is there a reason to prefer Executor.Create<TIn, TOut> over Executor<TIn, TOut>.Create?

The main benefit of the former is you get generic type inference if the compiler can discern it, e.g. with the former you can write:

Executor.Create((string s) => s.ToUpperInvariant(), "UppercaseExecutor");

but not with the latter. The former also lets you avoid having the extra type with two generic type parameters if we don't already have it.

stephentoub · 2025-10-23T02:49:25Z

dotnet/samples/GettingStarted/Workflows/_Foundational/06_SubWorkflows/Program.cs


        // Step 2: Configure the sub-workflow as an executor for use in the parent workflow
-        ExecutorIsh subWorkflowExecutor = subWorkflow.ConfigureSubWorkflow("TextProcessingSubWorkflow");
+        ExecutorRegistration subWorkflowExecutor = subWorkflow.AsExecutor("TextProcessingSubWorkflow");


Does AsExecutor return an "Executor" or an "ExecutorRegistration"?

ToRegistration would be more accurate, but my thinking was that AsExecutor is more obviously relevant when browsing IntelliSense. Will think more on the name today, to see if I can come up with something better.

stephentoub · 2025-10-23T02:49:36Z

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Interpreter/WorkflowModelBuilder.cs

    }

-    private static ExecutorIsh GetExecutorIsh(IModeledAction action) =>
+    private static ExecutorRegistration GetExecutorIsh(IModeledAction action) =>


stephentoub · 2025-10-23T02:50:39Z

dotnet/src/Microsoft.Agents.AI.Workflows/AgentWorkflowBuilder.cs

        // provenance tracking exposed in the workflow context passed to a handler.
-        ExecutorIsh[] agentExecutors = (from agent in agents select (ExecutorIsh)new AgentRunStreamingExecutor(agent, includeInputInOutput: false)).ToArray();
-        ExecutorIsh[] accumulators = [.. from agent in agentExecutors select (ExecutorIsh)new CollectChatMessagesExecutor($"Batcher/{agent.Id}")];
+        ExecutorRegistration[] agentExecutors = (from agent in agents select (ExecutorRegistration)new AgentRunStreamingExecutor(agent, includeInputInOutput: false)).ToArray();


"Executors"... these are now "Registrations"?

Until we get real anonymous union types we need to model the type explicitly. We need a way to allow passing information about future Executors without encouraging passing Executor instances to WorkflowBuilder, but also without disallowing it.

We are trying to avoid having to do .RegisterExecutor() on the builder object, as it feels more heavy-weight for the developer, and we already have much more ceremony than Python due to limitations stemming from AOT, among other things.

At some point we have to make compromises somewhere due to the limits of the expressivity of the language.

I am with @stephentoub how about WorkflowExecutor or a similar name? thus adding parity to the naming in Python?

What do people think about WorkflowNode or ExecutorUnion, or BoundExecutor (especially since I just realized we need to add object-ownership semantics to executor instances too if we want to be really careful)?

TODO: Need to add ownership semantics to Executor to avoid cross-workflow sharing. (In a separate PR)

Had a bit of an epiphany overnight. New object name: ExecutorBinding. It is more than a factory, and carries some state information with it, but it is not yet "registered" so Registration is not a good name for it - as pointed out above.

stephentoub · 2025-10-23T02:52:42Z

dotnet/src/Microsoft.Agents.AI.Workflows/ConfiguredExecutorRegistration.cs

+namespace Microsoft.Agents.AI.Workflows;
+
+// TODO: Unwrap the Configured object, just like for WorkflowRegistration
+internal record ConfiguredExecutorRegistration(Configured<Executor> ConfiguredExecutor, Type ExecutorType)


Is "Configured" still needed? I guess I don't understand its purpose separate from these registrations (and its name is fairly ambiguous).

A way to smuggle options objects and certain other important information and avoid having to constantly break the interface for developers, but that did not last long as a conviction, due to the arrival of RunId, which is not available when the configuration objects are created.

This is probably the next place to "fix" as we review the APIs.

stephentoub · 2025-10-23T02:58:17Z

dotnet/src/Microsoft.Agents.AI.Workflows/ExecutorRegistrationExtensions.cs

+    /// </remarks>
+    /// <param name="executor">The executor instance.</param>
+    /// <returns>An <see cref="ExecutorRegistration"/> instance wrapping the specified <see cref="Executor"/>.</returns>
+    public static ExecutorInstanceRegistration RegisterExecutor(this Executor executor)


ExecutorInstanceRegistration instead of ExecutorRegistration?

At one point I got a CodeAnalysis performance complaint about something similar where I was returning a more specific type, and I flipped all of them. Doesn't seem to be triggering now, so must have had some other reason to fire and I did not understand it right.

stephentoub · 2025-10-23T03:00:25Z

dotnet/src/Microsoft.Agents.AI.Workflows/ExecutorRegistrationExtensions.cs

+    /// <typeparam name="TExecutor">The type of the resulting executor</typeparam>
+    /// <param name="factoryAsync">The factory method.</param>
+    /// <returns>An <see cref="ExecutorRegistration"/> instance that resolves to the result of the factory call when messages get sent to it.</returns>
+    public static ExecutorRegistration RegisterExecutor<TExecutor>(this Func<string, string, ValueTask<TExecutor>> factoryAsync)


"Register" makes it sound like something is being stored somewhere, some existing object is being mutated to hold this new record, etc., like on CancellationToken. But this is only creating the ExecutorRegistration instance, right? It's not actually registering it with something?

No, but I could not come up with a clearly better name for it. The thinking around "registration" was in the sense of being the "registration" one submits when trying to get registered for something, not the established "registration" after the fact.

I need a name for an object that represents a future executor (or a placeholder for one - so factory is not really a good term, as it only deals with one part), with certain info about its underlying type that get erased by the time it is in that object, and the ability to create and "reset" it (if shared).

Maybe "ExecutorProvider"? Though it goes a fair bit beyond "Providing" an Executor, so it does not really fit either.

Aside: The Registration bit would be internal to the Workflow/Builder, but previous name for such a thing was ...Ish, and that was pretty polarizing.

I believe that the process mostly is doing is assigning ownership of the workflow instance so it cannot be used while "taken" or "assigned", so I am all in with finding a suitable name that clearly shows what is happening. And IMHO it is not exactly "registration" its more an assignation, or giving ownership of this workflow executor.
But I am all a newbie here so can be completely wrong...

stephentoub · 2025-10-23T03:01:18Z

dotnet/src/Microsoft.Agents.AI.Workflows/ExecutorRegistrationExtensions.cs

+    /// <typeparam name="TExecutor">The type of the resulting executor</typeparam>
+    /// <param name="factoryAsync">The factory method.</param>
+    /// <returns>An <see cref="ExecutorRegistration"/> instance that resolves to the result of the factory call when messages get sent to it.</returns>
+    [Obsolete("Use RegisterExecutor() instead.")]


Is this to give folks time to migrate off of it? Consider also adding EditorBrowsableState.Never

Yes: I intend to remove it when we get to the "RC-like" phase or before. And good call on Browsable.

stephentoub · 2025-10-23T03:02:32Z

dotnet/src/Microsoft.Agents.AI.Workflows/ExecutorRegistration.cs

+    /// Defines an implicit conversion from an AIAgent to an ExecutorRegistrationIsh instance.
+    /// </summary>
+    /// <param name="agent"></param>
+    public static implicit operator ExecutorRegistration(AIAgent agent) => agent.AsExecutor();


You know my opinion on these, but I'll stop commenting on it.

I think we're going to have to agree to disagree on this point, yeah :).

I promise to remove it is as soon as I can replace it anonymous type unions that work across languages, though, and not add more except in specifically cases like these.

lokitoth · 2025-10-23T15:33:10Z

if its not expected / intended to be used directly, then why public?

I need a type to use on a public API that has the property of being a type-union of the types I actually want people to use. That's why Ish was, in my opinion, a better name.

Concurrent run support was recently added to workflows, but Orchestrations did not fully update to support it. A few executors were missing Cross-Run Shareable annotations, and the ConcurrentEnd executor needed to be factory-instantiated. This also ports the fix for #1613 from #1637, to avoid waiting on that PR.

Concurrent run support was recently added to workflows, but Orchestrations did not fully update to support it. A few executors were missing Cross-Run Shareable annotations, and the ConcurrentEnd executor needed to be factory-instantiated. This also ports the fix for microsoft#1613 from microsoft#1637, to avoid waiting on that PR.

Copilot AI review requested due to automatic review settings October 22, 2025 19:18

markwallace-microsoft added .NET workflows Related to Workflows in agent-framework labels Oct 22, 2025

lokitoth had a problem deploying to integration October 22, 2025 19:18 — with GitHub Actions Error

lokitoth changed the title ~~.NET: [BREAKING]~~ .NET: [BREAKING] Unify ExecutorIsh and ExecutorRegistration, unify/simplify APIs Oct 22, 2025

lokitoth force-pushed the dev/dotnet_workflow/executor_registration_api branch from 8d015db to b2978c4 Compare October 22, 2025 19:20

lokitoth added the breaking change Introduces changes that are not backward compatible and may require updates to dependent code. label Oct 22, 2025

Copilot AI reviewed Oct 22, 2025

View reviewed changes

lokitoth had a problem deploying to integration October 22, 2025 19:21 — with GitHub Actions Error

lokitoth force-pushed the dev/dotnet_workflow/executor_registration_api branch from b2978c4 to 8549eae Compare October 22, 2025 19:24

lokitoth had a problem deploying to integration October 22, 2025 19:25 — with GitHub Actions Error

lokitoth force-pushed the dev/dotnet_workflow/executor_registration_api branch from 8549eae to 240deb3 Compare October 22, 2025 19:27

lokitoth temporarily deployed to integration October 22, 2025 19:28 — with GitHub Actions Inactive

crickman assigned crickman and lokitoth and unassigned crickman Oct 22, 2025

crickman requested a review from ekzhu October 22, 2025 21:30

crickman approved these changes Oct 22, 2025

View reviewed changes

lokitoth force-pushed the dev/dotnet_workflow/executor_registration_api branch from 240deb3 to 7cab9ad Compare October 22, 2025 21:43

lokitoth temporarily deployed to integration October 22, 2025 21:43 — with GitHub Actions Inactive

lokitoth added 2 commits October 22, 2025 18:01

feat: Simplify function-to-executor pattern

4a13466

lokitoth force-pushed the dev/dotnet_workflow/executor_registration_api branch from 7cab9ad to 4a13466 Compare October 22, 2025 22:01

lokitoth temporarily deployed to integration October 22, 2025 22:02 — with GitHub Actions Inactive

ReubenBond reviewed Oct 22, 2025

View reviewed changes

stephentoub reviewed Oct 23, 2025

View reviewed changes

lokitoth mentioned this pull request Oct 23, 2025

.NET: API inconsistency with Python - ConfigureSubWorkflow vs WorkflowExecutor for workflow composition #1502

Open

lokitoth mentioned this pull request Oct 24, 2025

.NET: Fix Concurrency Support for Orchestrations #1689

Merged

4 tasks

		Func<string, string> uppercaseFunc = s => s.ToUpperInvariant();
		var uppercase = uppercaseFunc.AsExecutor("UppercaseExecutor");

Uh oh!

.NET: [BREAKING] Unify ExecutorIsh and ExecutorRegistration, unify/simplify APIs #1637

Are you sure you want to change the base?

.NET: [BREAKING] Unify ExecutorIsh and ExecutorRegistration, unify/simplify APIs #1637

Uh oh!

Conversation

lokitoth commented Oct 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

Description

Contribution Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

crickman commented Oct 22, 2025

Uh oh!

crickman commented Oct 22, 2025

Uh oh!

crickman commented Oct 22, 2025

Uh oh!

crickman commented Oct 22, 2025

Uh oh!

lokitoth commented Oct 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

crickman commented Oct 23, 2025

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!

lokitoth Oct 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lokitoth Oct 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

lokitoth commented Oct 22, 2025 •

edited

Loading

lokitoth commented Oct 22, 2025 •

edited

Loading

lokitoth Oct 23, 2025 •

edited

Loading

lokitoth Oct 23, 2025 •

edited

Loading

lokitoth Oct 23, 2025 •

edited

Loading

lokitoth Oct 23, 2025 •

edited

Loading