Skip to content

Comments

.NET: [BREAKING] Workflows API Review Naming Changes (Part 1?)#4090

Merged
dmytrostruk merged 7 commits intomainfrom
dev/dotnet_workflow/api_review_naming_changes
Feb 20, 2026
Merged

.NET: [BREAKING] Workflows API Review Naming Changes (Part 1?)#4090
dmytrostruk merged 7 commits intomainfrom
dev/dotnet_workflow/api_review_naming_changes

Conversation

@lokitoth
Copy link
Member

@lokitoth lokitoth commented Feb 19, 2026

Description

Update names to take into account feedback from API Review, with the underlying goal of normalizing names between single agent and workflows, make the semantics of session vs. run clearer at the workflow level, and prevent a future breaking change in the FanIn APIs.

Contains many breaking changes.

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.

@lokitoth lokitoth added .NET workflows Related to Workflows in agent-framework breaking change Introduces changes that are not backward compatible and may require updates to dependent code. labels Feb 19, 2026
@lokitoth lokitoth moved this to In Review in Agent Framework Feb 19, 2026
@lokitoth lokitoth force-pushed the dev/dotnet_workflow/api_review_naming_changes branch from fc41dd3 to c0cef4a Compare February 19, 2026 16:06
@lokitoth lokitoth force-pushed the dev/dotnet_workflow/api_review_naming_changes branch from c0cef4a to f6a842b Compare February 19, 2026 16:43
@lokitoth lokitoth force-pushed the dev/dotnet_workflow/api_review_naming_changes branch from f6a842b to 7b451aa Compare February 19, 2026 17:12
alliscode
alliscode reviewed Feb 19, 2026
View reviewed changes
@lokitoth lokitoth marked this pull request as ready for review February 19, 2026 17:35
Copilot AI review requested due to automatic review settings February 19, 2026 17:35
Copilot AI reviewed Feb 19, 2026
View reviewed changes
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR applies API-review-driven naming changes across the .NET Workflows surface to better distinguish sessions vs runs, normalize naming with single-agent APIs, and clarify Fan-In semantics.

Changes:

  • Renames workflow execution identifiers from RunId to SessionId across runtime, checkpointing, tests, and samples.
  • Renames streaming entry points to OpenStreamingAsync / RunStreamingAsync / ResumeStreamingAsync and updates call sites.
  • Renames fan-in workflow edges to AddFanInBarrierEdge and updates usages in tests/samples/builders.

Reviewed changes

Copilot reviewed 63 out of 63 changed files in this pull request and generated 8 comments.

Show a summary per file
File Description
dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/WorkflowVisualizerTests.cs Updates visualization tests to use AddFanInBarrierEdge.
dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/TestRequestAgent.cs Updates request payload extraction to TryGetDataAs.
dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/Sample/13_Subworkflow_Checkpointing.cs Updates streaming run/resume method names.
dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/Sample/09_Subworkflow_ExternalRequest.cs Updates PortableValue/TryGetDataAs usage for external request handling.
dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/Sample/06_GroupChat_Workflow.cs Updates streaming execution call to RunStreamingAsync.
dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/Sample/05_Simple_Workflow_Checkpointing.cs Updates checkpointing sample to new streaming/resume APIs and SessionId.
dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/Sample/04_Simple_Workflow_ExternalRequest.cs Updates streaming execution call to RunStreamingAsync.
dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/Sample/03_Simple_Workflow_Loop.cs Updates streaming execution call to RunStreamingAsync.
dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/Sample/02_Simple_Workflow_Condition.cs Updates streaming execution call to RunStreamingAsync.
dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/Sample/01_Simple_Workflow_Sequential.cs Updates streaming execution call to RunStreamingAsync and removes outdated TODO.
dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/RepresentationTests.cs Updates executor binding factory argument to sessionId.
dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/InMemoryJsonStore.cs Updates checkpoint store test helper types/parameters to Session*.
dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/CheckpointParentTests.cs Updates checkpoint-parent tests to RunStreamingAsync/ResumeStreamingAsync and SessionId.
dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/AgentWorkflowBuilderTests.cs Updates workflow execution to RunStreamingAsync.
dotnet/tests/Microsoft.Agents.AI.CosmosNoSql.UnitTests/CosmosCheckpointStoreTests.cs Updates Cosmos checkpoint tests to sessionId and /sessionId partition key.
dotnet/src/Shared/Workflows/Execution/WorkflowRunner.cs Switches external request extraction to TryGetDataAs.
dotnet/src/Microsoft.Agents.AI.Workflows/WorkflowSession.cs Renames session identifier to SessionId and updates streaming/resume calls.
dotnet/src/Microsoft.Agents.AI.Workflows/WorkflowHostAgent.cs Renames assigned ID tracking to session terminology.
dotnet/src/Microsoft.Agents.AI.Workflows/WorkflowBuilder.cs Introduces AddFanInBarrierEdge and updates fan-in API naming.
dotnet/src/Microsoft.Agents.AI.Workflows/SwitchBuilder.cs Renames fan-out selector local function for clarity.
dotnet/src/Microsoft.Agents.AI.Workflows/SubworkflowBinding.cs Updates executor factory parameter name to sessionId.
dotnet/src/Microsoft.Agents.AI.Workflows/StreamingRun.cs Exposes SessionId on StreamingRun.
dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/WorkflowHostExecutor.cs Updates internal state and checkpoint interactions to use sessionId.
dotnet/src/Microsoft.Agents.AI.Workflows/Run.cs Exposes SessionId on Run.
dotnet/src/Microsoft.Agents.AI.Workflows/RouteBuilder.cs Updates typed-response extraction to TryGetDataAs.
dotnet/src/Microsoft.Agents.AI.Workflows/PortableValue.cs Clarifies docs around default values vs nullable value types.
dotnet/src/Microsoft.Agents.AI.Workflows/Observability/Tags.cs Renames telemetry tag constant to SessionId (key currently unchanged).
dotnet/src/Microsoft.Agents.AI.Workflows/InProcessExecution.cs Updates helper APIs to call new streaming methods and accept sessionId.
dotnet/src/Microsoft.Agents.AI.Workflows/InProc/InProcessRunnerContext.cs Updates runner context to pass and report sessionId.
dotnet/src/Microsoft.Agents.AI.Workflows/InProc/InProcessRunner.cs Renames runner identifier to SessionId and updates checkpointing calls.
dotnet/src/Microsoft.Agents.AI.Workflows/InProc/InProcessExecutionEnvironment.cs Renames/implements streaming APIs and propagates sessionId.
dotnet/src/Microsoft.Agents.AI.Workflows/IWorkflowExecutionEnvironment.cs Renames streaming API surface and runId parameter to sessionId.
dotnet/src/Microsoft.Agents.AI.Workflows/GroupChatWorkflowBuilder.cs Updates group chat host factory parameter name to sessionId.
dotnet/src/Microsoft.Agents.AI.Workflows/ExternalResponse.cs Replaces DataIs/DataAs patterns with TryGetDataAs and keeps DataIs<T>().
dotnet/src/Microsoft.Agents.AI.Workflows/ExternalRequest.cs Replaces DataIs(out ...) with TryGetDataAs and adds TryGetDataAs(Type, ...).
dotnet/src/Microsoft.Agents.AI.Workflows/ExecutorBindingExtensions.cs Updates executor factory delegate parameter naming to sessionId.
dotnet/src/Microsoft.Agents.AI.Workflows/ExecutorBinding.cs Updates factory invocation parameter naming to sessionId.
dotnet/src/Microsoft.Agents.AI.Workflows/Execution/StreamingRunEventStream.cs Updates telemetry tagging to use SessionId.
dotnet/src/Microsoft.Agents.AI.Workflows/Execution/LockstepRunEventStream.cs Updates telemetry tagging to use SessionId.
dotnet/src/Microsoft.Agents.AI.Workflows/Execution/ISuperStepRunner.cs Renames runner identifier contract to SessionId.
dotnet/src/Microsoft.Agents.AI.Workflows/Execution/AsyncRunHandle.cs Renames exposed identifier to SessionId.
dotnet/src/Microsoft.Agents.AI.Workflows/Configured.cs Updates configured factory delegate parameter naming to sessionId.
dotnet/src/Microsoft.Agents.AI.Workflows/ConfigurationExtensions.cs Updates configuration adapter delegate parameter naming to sessionId.
dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/SessionCheckpointCache.cs Renames checkpoint cache type to SessionCheckpointCache.
dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/JsonCheckpointStore.cs Updates abstract store methods to accept sessionId.
dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/InMemoryCheckpointManager.cs Updates in-memory checkpoint manager to Session* naming.
dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/ICheckpointStore.cs Updates checkpoint store interface parameter/docs to sessionId.
dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/ICheckpointManager.cs Updates checkpoint manager interface parameter/docs to sessionId.
dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/FileSystemJsonCheckpointStore.cs Updates filesystem store APIs and filenames to use sessionId.
dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/CheckpointManagerImpl.cs Updates checkpoint manager impl to pass sessionId.
dotnet/src/Microsoft.Agents.AI.Workflows/Checkpointing/CheckpointInfoConverter.cs Updates converter regex/grouping and stringification to SessionId.
dotnet/src/Microsoft.Agents.AI.Workflows/CheckpointManager.cs Updates adapter to forward sessionId.
dotnet/src/Microsoft.Agents.AI.Workflows/CheckpointInfo.cs Renames checkpoint identifier from RunId to SessionId.
dotnet/src/Microsoft.Agents.AI.Workflows/AgentWorkflowBuilder.cs Updates workflow construction to use AddFanInBarrierEdge.
dotnet/src/Microsoft.Agents.AI.CosmosNoSql/CosmosCheckpointStore.cs Updates Cosmos checkpoint storage schema/API to sessionId.
dotnet/samples/GettingStarted/Workflows/SharedStates/Program.cs Updates sample workflow fan-in to AddFanInBarrierEdge.
dotnet/samples/GettingStarted/Workflows/Observability/WorkflowAsAnAgent/WorkflowHelper.cs Updates sample workflow fan-in to AddFanInBarrierEdge.
dotnet/samples/GettingStarted/Workflows/HumanInTheLoop/HumanInTheLoopBasic/Program.cs Updates sample to use PortableValue.As<T>() directly where needed.
dotnet/samples/GettingStarted/Workflows/Concurrent/MapReduce/Program.cs Updates sample fan-in to AddFanInBarrierEdge.
dotnet/samples/GettingStarted/Workflows/Concurrent/Concurrent/Program.cs Updates sample fan-in to AddFanInBarrierEdge.
dotnet/samples/GettingStarted/Workflows/Checkpoint/CheckpointWithHumanInTheLoop/Program.cs Updates sample request handling to TryGetDataAs.
dotnet/samples/GettingStarted/Workflows/Agents/WorkflowAsAnAgent/WorkflowFactory.cs Updates sample fan-in to AddFanInBarrierEdge.
dotnet/samples/GettingStarted/Workflows/Agents/GroupChatToolApproval/Program.cs Updates streaming execution to RunStreamingAsync and request extraction to TryGetDataAs.

@lokitoth lokitoth force-pushed the dev/dotnet_workflow/api_review_naming_changes branch from 3c0f570 to c40cd5a Compare February 19, 2026 19:40
@lokitoth lokitoth enabled auto-merge February 19, 2026 19:55
@lokitoth lokitoth added this pull request to the merge queue Feb 19, 2026
github-merge-queue bot pushed a commit that referenced this pull request Feb 19, 2026
@lokitoth
.NET: [BREAKING] Workflows API Review Naming Changes (Part 1?) (#4090)
55b3c25 
* refactor: Normalize Run/RunStreaming with AIAgent

* refactor: Clarify Session vs. Run -level concepts

* Rename RunId to SessionId to better match Run/Session terminology in AIAgent
* [BREAKING]: Will break existing checkpointed sessions in CosmosDb due to field rename

* refactor: Rename and simplify interface around getting typed data out of ExternalRequest/Response

* Also adds hints around using value types in PortableValue

* refactor: Rename AddFanInEdge to AddFanInBarrierEdge

This will prevent a breaking change later when we introduce a programmable FanIn edge, analogous to the FanOut edge's EdgeSelector.

The goal, in the long run is to support a number of different FanIn scenarios, with naive FanIn (no barrier) by default, similar to FanOut.

* refactor: AsAgent(this Workflow, ...) => AsAIAgent(...)

* misc - part1: SwitchBuilder internal
@lokitoth lokitoth removed this pull request from the merge queue due to a manual request Feb 19, 2026
@lokitoth lokitoth added this pull request to the merge queue Feb 19, 2026
@github-merge-queue github-merge-queue bot removed this pull request from the merge queue due to failed status checks Feb 19, 2026
@lokitoth lokitoth added this pull request to the merge queue Feb 19, 2026
@lokitoth lokitoth removed this pull request from the merge queue due to a manual request Feb 19, 2026
@lokitoth lokitoth added this pull request to the merge queue Feb 19, 2026
@github-merge-queue github-merge-queue bot removed this pull request from the merge queue due to failed status checks Feb 19, 2026
@lokitoth lokitoth added this pull request to the merge queue Feb 19, 2026
@github-merge-queue github-merge-queue bot removed this pull request from the merge queue due to failed status checks Feb 19, 2026
@lokitoth lokitoth added this pull request to the merge queue Feb 19, 2026
@github-merge-queue github-merge-queue bot removed this pull request from the merge queue due to failed status checks Feb 20, 2026
@lokitoth lokitoth added this pull request to the merge queue Feb 20, 2026
@dmytrostruk dmytrostruk removed this pull request from the merge queue due to a manual request Feb 20, 2026
@dmytrostruk dmytrostruk added this pull request to the merge queue Feb 20, 2026
Merged via the queue into main with commit 0086d38 Feb 20, 2026
14 checks passed
@github-project-automation github-project-automation bot moved this from In Review to Done in Agent Framework Feb 20, 2026
This was referenced Feb 23, 2026
Open
Open
Open
Closed
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@alliscode alliscode alliscode approved these changes

@SergeyMenshykh SergeyMenshykh SergeyMenshykh approved these changes

Assignees

No one assigned

Labels

breaking change Introduces changes that are not backward compatible and may require updates to dependent code. .NET workflows Related to Workflows in agent-framework

Projects

Agent Framework
Status: Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@lokitoth @alliscode @SergeyMenshykh @dmytrostruk