.NET: [BREAKING] Unify ExecutorIsh and ExecutorRegistration, unify/simplify APIs by lokitoth · Pull Request #1637 · microsoft/agent-framework

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

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?

* Switch to more modern Record type-tree for Sum Types * Unify APIs for getting ExecutorBinding * 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.

mikeholczer · 2025-11-05T18:03:14Z

I hope this is an OK place to ask this, but I'm seeing that in these changes in AIAgentBinding that the ExecutorBinding constructor is passed the AIAgent's Name if it;'s not null and otherwise the AIAgent's Id and in ExecutorBinding.CheckId there is a check that the Executor's Id matches the ExecutorBinding's Id. On the otherhand the AIAgentHostExecutor's constructor always passes the AIAgent's Id to it's base classes constructor. That creates a mismatch if an AIAgent has it's Name and Id set to different values.

I don't know if that's a bug, or if it's not intended that one would set both the Name and Id of a AIAgent.

mikeholczer · 2025-11-06T18:57:46Z

Looks like #1840 addressed the issue I was having.

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.

…mplify APIs (microsoft#1637) * refactor: Unify ExecutorIsh and ExecutorRegistration => ExecutorBinding * Switch to more modern Record type-tree for Sum Types * Unify APIs for getting ExecutorBinding * 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. * feat: Simplify function-to-executor pattern * refactor: Normalize API naming

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

markwallace-microsoft added .NET Usage: [Issues, PRs], Target: .Net workflows Usage: [Issues, PRs], Target: Workflows 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 Usage: [PRs], Target: all PRs that introduce changes that are not backward compatible 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 added this to Agent Framework Oct 22, 2025

crickman moved this to In Review in Agent Framework 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

markwallace-microsoft added the documentation Usage: [Issues, PRs], Target: documentation in the code base and learn docs label Oct 30, 2025

lokitoth temporarily deployed to integration October 30, 2025 15:25 — with GitHub Actions Inactive

lokitoth force-pushed the dev/dotnet_workflow/executor_registration_api branch from 83af7d5 to c45bb5c Compare November 3, 2025 14:24

lokitoth temporarily deployed to integration November 3, 2025 14:25 — with GitHub Actions Inactive

lokitoth force-pushed the dev/dotnet_workflow/executor_registration_api branch from c45bb5c to 6bcac73 Compare November 3, 2025 15:53

lokitoth temporarily deployed to integration November 3, 2025 15:53 — with GitHub Actions Inactive

TaoChenOSU approved these changes Nov 3, 2025

View reviewed changes

Comment thread dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/WorkflowInfo.cs Outdated

Comment thread dotnet/src/Microsoft.Agents.AI.Workflows/Visualization/WorkflowVisualizer.cs Outdated

Comment thread dotnet/src/Microsoft.Agents.AI.Workflows/ExecutorBindingExtensions.cs Outdated

lokitoth force-pushed the dev/dotnet_workflow/executor_registration_api branch from 6bcac73 to 42cde51 Compare November 3, 2025 17:24

lokitoth temporarily deployed to integration November 3, 2025 17:24 — with GitHub Actions Inactive

alliscode approved these changes Nov 3, 2025

View reviewed changes

lokitoth added 3 commits November 3, 2025 13:13

feat: Simplify function-to-executor pattern

8fa77ef

refactor: Normalize API naming

a333131

lokitoth force-pushed the dev/dotnet_workflow/executor_registration_api branch from 42cde51 to a333131 Compare November 3, 2025 18:13

lokitoth temporarily deployed to integration November 3, 2025 18:13 — with GitHub Actions Inactive

lokitoth added this pull request to the merge queue Nov 3, 2025

Merged via the queue into main with commit b25b0af Nov 3, 2025
15 checks passed

github-project-automation Bot moved this from In Review to Done in Agent Framework Nov 3, 2025

crickman deleted the dev/dotnet_workflow/executor_registration_api branch November 11, 2025 16:22

alliscode mentioned this pull request Jun 2, 2026

.NET: Latest release changes WorkflowBuilder API #1305

Closed

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mikeholczer commented Nov 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mikeholczer commented Nov 6, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

10 participants

lokitoth commented Oct 22, 2025 •

edited

Loading

mikeholczer commented Nov 5, 2025 •

edited

Loading