.NET: ExecutorIsh is confusingly named and hard to discover how to use

https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.Workflows/ExecutorIsh.cs

The name is hard to understand, with "Ish" as a suffix.

Also when looking at APIs that accept one, like WorkflowBuilder's constructor, it's hard to figure out how to get one. It relies on implicit cast operators to turn other things into this... and such implicit operators are also something we recommend folks avoid:
https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/operator-overloads#conversion-operators

The implicit operators also make it so that reference identity breaks, because code like:

AIAgent agent = ...;
ExecutorIsh e1 = agent;
ExecutorIsh e2 = agent;

ends up allocating new objects as part of those implicit casts.

I don't understand why Executorish is necessary at all. Why can't everything just be in terms of Executor? If we want convenience methods for creating Executors for really common cases, they can be static factories on the base Executor, or AsExecutor methods on the relevant types.

We should really get rid of it.

Ben Thomas (@alliscode)

cc: Ben Thomas (@alliscode), Jacob Alber (@lokitoth)

It was initially in place to allow creation of late-binding "slots" for executors. E.g. if you want to create a workflow template, then fill in "well-known-PARTs". Not sure if it is still relevant, or if can be entirely replaced by Configured<T> (or whatever it gets renamed to).

Fundamentally it only exists because it is impossible to create a type union of string and T in .NET.

Stephen Toub (@stephentoub)

love this, I support strongly using Executor as the name, if possible, for simplicity.

Also, this issues are related:

.NET: Provide explicit API to convert AIAgent to Executor for workflow composition #1494
.NET: API inconsistency with Python - ConfigureSubWorkflow vs WorkflowExecutor for workflow composition #1502

Stephen Toub (@stephentoub) with this code suggested in Issue 1494 (but changing ExecutorIsh to Executor):

Executor physicistExecutor = physicist.AsExecutor(
    name: "PhysicistAgent_v1",           // Override display name for workflows
    description: "Physics domain expert"  // Add description for documentation
);

we could control if we create or not a new instance of an executor to wrap an agent, as otherwise how do we assign unique names that we want? (as you are doing in the agent Orchestrations) - using a GUID or the name plus a guid or, if an existing executor for this agent exists, reuse it.
But what if we want to have a new executor wrapping another instance of that agent? only way is to control the Executor creation... (please correct me if wrong, I may be).

Hope it helps.

We cannot simply use Executor because that would encourage people to pass AIAgent-hosting executors (and similar for RequestInfoExecutor) as instances, which will make their workflows instances single-usable. Having ~~ExecutorIsh~~ (now ExecutorRegistration) lets us force the factory behaviour in these known cases, while still allowing (in C#) a very lightweight API.

The "Ish" suffix on this API name gave me pause when I encountered it. Frankly, I assumed this was an intended-to-be-internal type that was accidentally exposed on the public API surface. If a type is needed to represent this union, I recommend considering different approaches for interfaces, a base class, or something along those lines.

The Framework Design Guidelines say to "✔️ DO favor readability over brevity," and more generally that the goal is, "to provide a consistent set of naming conventions that results in names that make immediate sense to developers." My feedback is the 'Ish' suffix misses that mark.

After posting that comment; I see there's an open PR. Yay! Sorry I overlooked that before commenting.

Navigation Menu

Repository navigation

.NET: ExecutorIsh is confusingly named and hard to discover how to use #758

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

.NET: ExecutorIsh is confusingly named and hard to discover how to use #758

Description

Activity

stephentoub commented on Sep 27, 2025

stephentoub commented on Sep 27, 2025

lokitoth commented on Oct 7, 2025

joslat commented on Oct 15, 2025

lokitoth commented on Oct 22, 2025

jeffhandley commented on Oct 29, 2025

jeffhandley commented on Oct 29, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions