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

* 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

---------

Co-authored-by: Dmytro Struk <13853051+dmytrostruk@users.noreply.github.com>

Author: lokitoth

dotnet/samples/AgentWebChat/AgentWebChat.AgentHost/Program.cs

@@ -70,7 +70,7 @@ Once the user has deduced what type (knight or knave) both Alice and Bob are, te
         If the user asks a general question about their surrounding, make something up which is consistent with the scenario.
         """, "Narrator");
 
-    return AgentWorkflowBuilder.BuildConcurrent([knight, knave, narrator]).AsAgent(name: key);
+    return AgentWorkflowBuilder.BuildConcurrent([knight, knave, narrator]).AsAIAgent(name: key);
 });
 
 // Workflow consisting of multiple specialized agents

dotnet/samples/GettingStarted/Workflows/Agents/CustomAgentExecutors/Program.cs

@@ -34,10 +34,7 @@ private static async Task Main()
         // Set up the Azure OpenAI client
         var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
         var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
-        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-        // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-        // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-        var chatClient = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential()).GetChatClient(deploymentName).AsIChatClient();
+        var chatClient = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential()).GetChatClient(deploymentName).AsIChatClient();
 
         // Create the executors
         var sloganWriter = new SloganWriterExecutor("SloganWriter", chatClient);
@@ -51,7 +48,7 @@ private static async Task Main()
             .Build();
 
         // Execute the workflow
-        await using StreamingRun run = await InProcessExecution.StreamAsync(workflow, input: "Create a slogan for a new electric SUV that is affordable and fun to drive.");
+        await using StreamingRun run = await InProcessExecution.RunStreamingAsync(workflow, input: "Create a slogan for a new electric SUV that is affordable and fun to drive.");
         await foreach (WorkflowEvent evt in run.WatchStreamAsync())
         {
             if (evt is SloganGeneratedEvent or FeedbackEvent)

dotnet/samples/GettingStarted/Workflows/Agents/FoundryAgent/Program.cs

@@ -24,10 +24,7 @@ private static async Task Main()
         var endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_ENDPOINT")
             ?? throw new InvalidOperationException("AZURE_FOUNDRY_PROJECT_ENDPOINT is not set.");
         var deploymentName = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
-        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-        // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-        // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-        var persistentAgentsClient = new PersistentAgentsClient(endpoint, new DefaultAzureCredential());
+        var persistentAgentsClient = new PersistentAgentsClient(endpoint, new AzureCliCredential());
 
         // Create agents
         AIAgent frenchAgent = await GetTranslationAgentAsync("French", persistentAgentsClient, deploymentName);
@@ -41,7 +38,7 @@ private static async Task Main()
             .Build();
 
         // Execute the workflow
-        await using StreamingRun run = await InProcessExecution.StreamAsync(workflow, new ChatMessage(ChatRole.User, "Hello World!"));
+        await using StreamingRun run = await InProcessExecution.RunStreamingAsync(workflow, new ChatMessage(ChatRole.User, "Hello World!"));
         // Must send the turn token to trigger the agents.
         // The agents are wrapped as executors. When they receive messages,
         // they will cache the messages and only start processing when they receive a TurnToken.

dotnet/samples/GettingStarted/Workflows/Agents/GroupChatToolApproval/Program.cs

@@ -91,7 +91,7 @@ private static async Task Main()
 
         List<ChatMessage> messages = [new(ChatRole.User, "We need to deploy version 2.4.0 to production. Please coordinate the deployment.")];
 
-        await using StreamingRun run = await InProcessExecution.Lockstep.StreamAsync(workflow, messages);
+        await using StreamingRun run = await InProcessExecution.Lockstep.RunStreamingAsync(workflow, messages);
         await run.TrySendMessageAsync(new TurnToken(emitEvents: true));
 
         string? lastExecutorId = null;
@@ -101,7 +101,7 @@ private static async Task Main()
             {
                 case RequestInfoEvent e:
                 {
-                    if (e.Request.DataIs(out FunctionApprovalRequestContent? approvalRequestContent))
+                    if (e.Request.TryGetDataAs(out FunctionApprovalRequestContent? approvalRequestContent))
                     {
                         Console.WriteLine();
                         Console.WriteLine($"[APPROVAL REQUIRED] From agent: {e.Request.PortInfo.PortId}");

dotnet/samples/GettingStarted/Workflows/Agents/WorkflowAsAnAgent/Program.cs

@@ -32,14 +32,11 @@ private static async Task Main()
         // Set up the Azure OpenAI client
         var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
         var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
-        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-        // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-        // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-        var chatClient = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential()).GetChatClient(deploymentName).AsIChatClient();
+        var chatClient = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential()).GetChatClient(deploymentName).AsIChatClient();
 
         // Create the workflow and turn it into an agent
         var workflow = WorkflowFactory.BuildWorkflow(chatClient);
-        var agent = workflow.AsAgent("workflow-agent", "Workflow Agent");
+        var agent = workflow.AsAIAgent("workflow-agent", "Workflow Agent");
         var session = await agent.CreateSessionAsync();
 
         // Start an interactive loop to interact with the workflow as if it were an agent

dotnet/samples/GettingStarted/Workflows/Agents/WorkflowAsAnAgent/WorkflowFactory.cs

@@ -24,7 +24,7 @@ internal static Workflow BuildWorkflow(IChatClient chatClient)
         // Build the workflow by adding executors and connecting them
         return new WorkflowBuilder(startExecutor)
             .AddFanOutEdge(startExecutor, [frenchAgent, englishAgent])
-            .AddFanInEdge([frenchAgent, englishAgent], aggregationExecutor)
+            .AddFanInBarrierEdge([frenchAgent, englishAgent], aggregationExecutor)
             .WithOutputFrom(aggregationExecutor)
             .Build();
     }

dotnet/samples/GettingStarted/Workflows/Checkpoint/CheckpointAndRehydrate/Program.cs

@@ -33,7 +33,7 @@ private static async Task Main()
 
         // Execute the workflow and save checkpoints
         await using StreamingRun checkpointedRun = await InProcessExecution
-            .StreamAsync(workflow, NumberSignal.Init, checkpointManager);
+            .RunStreamingAsync(workflow, NumberSignal.Init, checkpointManager);
 
         await foreach (WorkflowEvent evt in checkpointedRun.WatchStreamAsync())
         {
@@ -73,7 +73,7 @@ private static async Task Main()
         CheckpointInfo savedCheckpoint = checkpoints[CheckpointIndex];
 
         await using StreamingRun newCheckpointedRun =
-            await InProcessExecution.ResumeStreamAsync(newWorkflow, savedCheckpoint, checkpointManager);
+            await InProcessExecution.ResumeStreamingAsync(newWorkflow, savedCheckpoint, checkpointManager);
 
         await foreach (WorkflowEvent evt in newCheckpointedRun.WatchStreamAsync())
         {

dotnet/samples/GettingStarted/Workflows/Checkpoint/CheckpointAndResume/Program.cs

@@ -31,9 +31,7 @@ private static async Task Main()
         var checkpoints = new List<CheckpointInfo>();
 
         // Execute the workflow and save checkpoints
-        await using StreamingRun checkpointedRun = await InProcessExecution
-            .StreamAsync(workflow, NumberSignal.Init, checkpointManager)
-            ;
+        await using StreamingRun checkpointedRun = await InProcessExecution.RunStreamingAsync(workflow, NumberSignal.Init, checkpointManager);
         await foreach (WorkflowEvent evt in checkpointedRun.WatchStreamAsync())
         {
             if (evt is ExecutorCompletedEvent executorCompletedEvt)

dotnet/samples/GettingStarted/Workflows/Checkpoint/CheckpointWithHumanInTheLoop/Program.cs

@@ -35,7 +35,7 @@ private static async Task Main()
 
         // Execute the workflow and save checkpoints
         await using StreamingRun checkpointedRun = await InProcessExecution
-            .StreamAsync(workflow, new SignalWithNumber(NumberSignal.Init), checkpointManager)
+            .RunStreamingAsync(workflow, new SignalWithNumber(NumberSignal.Init), checkpointManager)
             ;
         await foreach (WorkflowEvent evt in checkpointedRun.WatchStreamAsync())
         {
@@ -98,8 +98,7 @@ private static async Task Main()
 
     private static ExternalResponse HandleExternalRequest(ExternalRequest request)
     {
-        var signal = request.DataAs<SignalWithNumber>();
-        if (signal is not null)
+        if (request.TryGetDataAs<SignalWithNumber>(out var signal))
         {
             switch (signal.Signal)
             {

dotnet/samples/GettingStarted/Workflows/Concurrent/Concurrent/Program.cs

@@ -34,10 +34,7 @@ private static async Task Main()
         // Set up the Azure OpenAI client
         var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
         var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
-        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-        // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-        // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-        var chatClient = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential()).GetChatClient(deploymentName).AsIChatClient();
+        var chatClient = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential()).GetChatClient(deploymentName).AsIChatClient();
 
         // Create the executors
         ChatClientAgent physicist = new(
@@ -56,12 +53,12 @@ private static async Task Main()
         // Build the workflow by adding executors and connecting them
         var workflow = new WorkflowBuilder(startExecutor)
             .AddFanOutEdge(startExecutor, [physicist, chemist])
-            .AddFanInEdge([physicist, chemist], aggregationExecutor)
+            .AddFanInBarrierEdge([physicist, chemist], aggregationExecutor)
             .WithOutputFrom(aggregationExecutor)
             .Build();
 
         // Execute the workflow in streaming mode
-        await using StreamingRun run = await InProcessExecution.StreamAsync(workflow, input: "What is temperature?");
+        await using StreamingRun run = await InProcessExecution.RunStreamingAsync(workflow, input: "What is temperature?");
         await foreach (WorkflowEvent evt in run.WatchStreamAsync())
         {
             if (evt is WorkflowOutputEvent output)