From b8a55dccb4c39714571db6cff2c6f14ddce9712c Mon Sep 17 00:00:00 2001
From: Jacob Alber <jaalber@microsoft.com>
Date: Wed, 5 Nov 2025 12:26:46 -0500
Subject: [PATCH] [BREAKING] refactor: Fix unintuitive binding of StreamAsync
 (#1930)

In #1551 we added a mechanism to open a Streaming workflow run without providing any input. This caused unintuitive behaviour when passing a string as input without providing a runId, resulting in the input being misinterpreted as the runId and the workflow not executing.

As well, the name caused confusion about why the Workflow was not running when using the input-less StreamAsync (since the Workflow cannot run without any messages to drive its execution).
---
 .../IWorkflowExecutionEnvironment.cs                        | 5 +++--
 .../InProc/InProcessExecutionEnvironment.cs                 | 2 +-
 .../src/Microsoft.Agents.AI.Workflows/InProcessExecution.cs | 6 +++---
 3 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/dotnet/src/Microsoft.Agents.AI.Workflows/IWorkflowExecutionEnvironment.cs b/dotnet/src/Microsoft.Agents.AI.Workflows/IWorkflowExecutionEnvironment.cs
index d1906e0df2..b8e8b37fa5 100644
--- a/dotnet/src/Microsoft.Agents.AI.Workflows/IWorkflowExecutionEnvironment.cs
+++ b/dotnet/src/Microsoft.Agents.AI.Workflows/IWorkflowExecutionEnvironment.cs
@@ -12,14 +12,15 @@ namespace Microsoft.Agents.AI.Workflows;
 public interface IWorkflowExecutionEnvironment
 {
     /// <summary>
-    /// Initiates a streaming run of the specified workflow without sending any initial input.
+    /// Initiates a streaming run of the specified workflow without sending any initial input. Note that the starting
+    /// <see cref="Executor"/> will not be invoked until an input message is received.
     /// </summary>
     /// <param name="workflow">The workflow to execute. Cannot be null.</param>
     /// <param name="runId">An optional identifier for the run. If null, a new run identifier will be generated.</param>
     /// <param name="cancellationToken">A cancellation token that can be used to cancel the streaming operation.</param>
     /// <returns>A ValueTask that represents the asynchronous operation. The result contains a StreamingRun object for accessing
     /// the streamed workflow output.</returns>
-    ValueTask<StreamingRun> StreamAsync(Workflow workflow, string? runId = null, CancellationToken cancellationToken = default);
+    ValueTask<StreamingRun> OpenStreamAsync(Workflow workflow, string? runId = null, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// Initiates an asynchronous streaming execution using the specified input.
diff --git a/dotnet/src/Microsoft.Agents.AI.Workflows/InProc/InProcessExecutionEnvironment.cs b/dotnet/src/Microsoft.Agents.AI.Workflows/InProc/InProcessExecutionEnvironment.cs
index 1bbed760db..a4d40ff127 100644
--- a/dotnet/src/Microsoft.Agents.AI.Workflows/InProc/InProcessExecutionEnvironment.cs
+++ b/dotnet/src/Microsoft.Agents.AI.Workflows/InProc/InProcessExecutionEnvironment.cs
@@ -37,7 +37,7 @@ public sealed class InProcessExecutionEnvironment : IWorkflowExecutionEnvironmen
     }
 
     /// <inheritdoc/>
-    public async ValueTask<StreamingRun> StreamAsync(
+    public async ValueTask<StreamingRun> OpenStreamAsync(
         Workflow workflow,
         string? runId = null,
         CancellationToken cancellationToken = default)
diff --git a/dotnet/src/Microsoft.Agents.AI.Workflows/InProcessExecution.cs b/dotnet/src/Microsoft.Agents.AI.Workflows/InProcessExecution.cs
index fe88f7ffff..dc110e7570 100644
--- a/dotnet/src/Microsoft.Agents.AI.Workflows/InProcessExecution.cs
+++ b/dotnet/src/Microsoft.Agents.AI.Workflows/InProcessExecution.cs
@@ -41,9 +41,9 @@ public static class InProcessExecution
     /// </summary>
     internal static InProcessExecutionEnvironment Subworkflow { get; } = new(ExecutionMode.Subworkflow);
 
-    /// <inheritdoc cref="IWorkflowExecutionEnvironment.StreamAsync(Workflow, string?, CancellationToken)"/>
-    public static ValueTask<StreamingRun> StreamAsync(Workflow workflow, string? runId = null, CancellationToken cancellationToken = default)
-        => Default.StreamAsync(workflow, runId, cancellationToken);
+    /// <inheritdoc cref="IWorkflowExecutionEnvironment.OpenStreamAsync(Workflow, string?, CancellationToken)"/>
+    public static ValueTask<StreamingRun> OpenStreamAsync(Workflow workflow, string? runId = null, CancellationToken cancellationToken = default)
+        => Default.OpenStreamAsync(workflow, runId, cancellationToken);
 
     /// <inheritdoc cref="IWorkflowExecutionEnvironment.StreamAsync{TInput}(Workflow, TInput, string?, CancellationToken)"/>
     public static ValueTask<StreamingRun> StreamAsync<TInput>(Workflow workflow, TInput input, string? runId = null, CancellationToken cancellationToken = default) where TInput : notnull