feat: tag-aware defaults and designation API on orchestration builders

Aligns the .NET orchestration builders with Python's output / intermediate-output
distinction. Each builder either applies a Python-aligned default designation set or
replays the user's explicit `WithOutputFrom` / `WithIntermediateOutputFrom` calls,
never both.

Static `AgentWorkflowBuilder.BuildSequential` / `BuildConcurrent` apply defaults
unconditionally (no user-facing fluent surface to take control through):

- Sequential: terminal `end` + every agent designated intermediate.
- Concurrent: terminal `end` + every agent and per-agent accumulator designated
  intermediate.

The three fluent instance builders memoize agent-typed designation calls in a
`Dictionary<AIAgent, HashSet<OutputTag>>` (empty set = terminal-only, non-empty =
intermediate tag(s)) so repeated calls dedupe naturally. They replay the entries
at `Build()` time, suppressing defaults when any call has been made:

- `HandoffWorkflowBuilder` / `HandoffWorkflowBuilderCore<TBuilder>` (also picked up
  by the obsolete `HandoffsWorkflowBuilder` via inheritance).
  Default: terminal `HandoffEnd` + every handoff agent intermediate.
  (Bug fix: legacy code relied on `WithOutputFrom(end)` to bind `HandoffEnd`. The
  new explicit-designation path bypasses that, so `Build()` now calls
  `BindExecutor(end)` unconditionally to keep validation happy.)
- `GroupChatWorkflowBuilder` — default: terminal host + every participant intermediate.
- `MagenticWorkflowBuilder` — default: terminal orchestrator + every team member
  intermediate.

Designating a non-participant agent throws `InvalidOperationException`.

The bare `WorkflowBuilder` default is unchanged — only the orchestration-style
builders gain implicit defaults, matching the plan's non-goal.

Tests
-----
- `AgentWorkflowBuilder.SequentialTests` / `.ConcurrentTests`: one default-spec
  assertion each.
- `GroupChatWorkflowBuilderTests`: defaults-match-spec, explicit-replaces-defaults,
  non-participant throws.
- `HandoffWorkflowBuilderTests` (new file): same three.
- `MagenticWorkflowBuilderTests` (new file): same three.

593/593 unit tests pass on net10.0 (582 baseline + 11 new).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/AgentWorkflowBuilder.ConcurrentTests.cs

@@ -2,9 +2,11 @@
 
 using System;
 using System.Collections.Generic;
+using System.Linq;
 using System.Runtime.CompilerServices;
 using System.Text.RegularExpressions;
 using System.Threading.Tasks;
+using FluentAssertions;
 using Microsoft.Extensions.AI;
 
 #pragma warning disable SYSLIB1045 // Use GeneratedRegex
@@ -51,5 +53,25 @@ public static partial class AgentWorkflowBuilderTests
                 Assert.Equal(2, result.Count);
             }
         }
+
+        [Fact]
+        public void Test_BuildConcurrent_DefaultDesignationsMatchSpec()
+        {
+            Workflow workflow = AgentWorkflowBuilder.BuildConcurrent(
+                [new DoubleEchoAgent("agent1"), new DoubleEchoAgent("agent2"), new DoubleEchoAgent("agent3")]);
+
+            Dictionary<string, HashSet<OutputTag>> designations = workflow.OutputExecutors;
+
+            List<KeyValuePair<string, HashSet<OutputTag>>> terminals = designations
+                .Where(kvp => kvp.Value.Count == 0)
+                .ToList();
+            terminals.Should().ContainSingle("Concurrent has exactly one terminal output executor (ConcurrentEndExecutor)");
+
+            List<KeyValuePair<string, HashSet<OutputTag>>> intermediates = designations
+                .Where(kvp => kvp.Value.Contains(OutputTag.Intermediate))
+                .ToList();
+            intermediates.Should().HaveCount(6,
+                "every concurrent agent (3) and its per-agent accumulator (3) are designated intermediate");
+        }
     }
 }

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/AgentWorkflowBuilder.SequentialTests.cs

@@ -4,6 +4,7 @@ using System;
 using System.Collections.Generic;
 using System.Linq;
 using System.Threading.Tasks;
+using FluentAssertions;
 using Microsoft.Extensions.AI;
 
 namespace Microsoft.Agents.AI.Workflows.UnitTests;
@@ -62,5 +63,28 @@ public static partial class AgentWorkflowBuilderTests
                 static string Double(string s) => s + s;
             }
         }
+
+        [Fact]
+        public void Test_BuildSequential_DefaultDesignationsMatchSpec()
+        {
+            Workflow workflow = AgentWorkflowBuilder.BuildSequential(
+                new DoubleEchoAgent("agent1"),
+                new DoubleEchoAgent("agent2"),
+                new DoubleEchoAgent("agent3"));
+
+            // Defaults: every agent executor is intermediate; exactly one terminal entry (the OutputMessagesExecutor).
+            Dictionary<string, HashSet<OutputTag>> designations = workflow.OutputExecutors;
+            designations.Should().NotBeEmpty();
+
+            List<KeyValuePair<string, HashSet<OutputTag>>> terminals = designations
+                .Where(kvp => kvp.Value.Count == 0)
+                .ToList();
+            terminals.Should().ContainSingle("Sequential has exactly one terminal output executor (OutputMessagesExecutor)");
+
+            List<KeyValuePair<string, HashSet<OutputTag>>> intermediates = designations
+                .Where(kvp => kvp.Value.Contains(OutputTag.Intermediate))
+                .ToList();
+            intermediates.Should().HaveCount(3, "every agent in the pipeline is designated intermediate");
+        }
     }
 }

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/GroupChatWorkflowBuilderTests.cs

@@ -7,6 +7,7 @@ using System.Runtime.CompilerServices;
 using System.Text.Json;
 using System.Threading;
 using System.Threading.Tasks;
+using FluentAssertions;
 using Microsoft.Agents.AI.Workflows.InProc;
 using Microsoft.Extensions.AI;
 
@@ -162,6 +163,65 @@ public class GroupChatWorkflowBuilderTests
         }
     }
 
+    [Fact]
+    public void Test_GroupChatWorkflowBuilder_DefaultDesignationsMatchSpec()
+    {
+        AgentWorkflowBuilderTests.DoubleEchoAgent a1 = new("agent1");
+        AgentWorkflowBuilderTests.DoubleEchoAgent a2 = new("agent2");
+        AgentWorkflowBuilderTests.DoubleEchoAgent a3 = new("agent3");
+
+        Workflow workflow = AgentWorkflowBuilder
+            .CreateGroupChatBuilderWith(agents => new RoundRobinGroupChatManager(agents) { MaximumIterationCount = 1 })
+            .AddParticipants(a1, a2, a3)
+            .Build();
+
+        Dictionary<string, HashSet<OutputTag>> designations = workflow.OutputExecutors;
+
+        designations.Where(kvp => kvp.Value.Count == 0)
+            .Should().ContainSingle("group-chat host is the sole terminal output executor by default");
+        designations.Where(kvp => kvp.Value.Contains(OutputTag.Intermediate))
+            .Should().HaveCount(3, "every participant is designated intermediate by default");
+    }
+
+    [Fact]
+    public void Test_GroupChatWorkflowBuilder_ExplicitDesignationsReplaceDefaults()
+    {
+        AgentWorkflowBuilderTests.DoubleEchoAgent a1 = new("agent1");
+        AgentWorkflowBuilderTests.DoubleEchoAgent a2 = new("agent2");
+        AgentWorkflowBuilderTests.DoubleEchoAgent a3 = new("agent3");
+
+        Workflow workflow = AgentWorkflowBuilder
+            .CreateGroupChatBuilderWith(agents => new RoundRobinGroupChatManager(agents) { MaximumIterationCount = 1 })
+            .AddParticipants(a1, a2, a3)
+            .WithOutputFrom(a1)
+            .WithIntermediateOutputFrom([a2])
+            .Build();
+
+        Dictionary<string, HashSet<OutputTag>> designations = workflow.OutputExecutors;
+
+        designations.Should().HaveCount(2,
+            "only the two explicitly-designated agents land on the inner builder; the host default is suppressed");
+        designations.Values.Where(tags => tags.Count == 0)
+            .Should().ContainSingle("agent1 is the only terminal designation");
+        designations.Values.Where(tags => tags.Contains(OutputTag.Intermediate))
+            .Should().ContainSingle("agent2 is the only intermediate designation");
+    }
+
+    [Fact]
+    public void Test_GroupChatWorkflowBuilder_DesignationForNonParticipantThrows()
+    {
+        AgentWorkflowBuilderTests.DoubleEchoAgent participant = new("p1");
+        AgentWorkflowBuilderTests.DoubleEchoAgent stranger = new("stranger");
+
+        GroupChatWorkflowBuilder builder = AgentWorkflowBuilder
+            .CreateGroupChatBuilderWith(agents => new RoundRobinGroupChatManager(agents) { MaximumIterationCount = 1 })
+            .AddParticipants(participant)
+            .WithOutputFrom(stranger);
+
+        Action build = () => builder.Build();
+        build.Should().Throw<InvalidOperationException>().WithMessage("*stranger*");
+    }
+
     private sealed class RecordingAgent(string name) : AIAgent
     {
         public List<List<string>> Invocations { get; } = [];

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/HandoffWorkflowBuilderTests.cs

@@ -0,0 +1,77 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using FluentAssertions;
+
+namespace Microsoft.Agents.AI.Workflows.UnitTests;
+
+/// <summary>
+/// Tests focused on <see cref="HandoffWorkflowBuilder"/>'s output-designation surface —
+/// the Python-aligned defaults applied at <see cref="HandoffWorkflowBuilderCore{TBuilder}.Build"/>
+/// when the user has not made explicit designations, and the memoized
+/// <c>WithOutputFrom</c> / <c>WithIntermediateOutputFrom</c> replay otherwise.
+/// </summary>
+#pragma warning disable MAAIW001 // Experimental: HandoffWorkflowBuilder
+public class HandoffWorkflowBuilderTests
+{
+    [Fact]
+    public void Test_HandoffWorkflowBuilder_DefaultDesignationsMatchSpec()
+    {
+        AgentWorkflowBuilderTests.DoubleEchoAgent coordinator = new("coordinator");
+        AgentWorkflowBuilderTests.DoubleEchoAgent specialist = new("specialist");
+
+        Workflow workflow = AgentWorkflowBuilder
+            .CreateHandoffBuilderWith(coordinator)
+            .WithHandoff(coordinator, specialist)
+            .Build();
+
+        Dictionary<string, HashSet<OutputTag>> designations = workflow.OutputExecutors;
+
+        designations.Where(kvp => kvp.Value.Count == 0)
+            .Should().ContainSingle("the handoff end executor is the sole terminal output by default");
+        designations.Where(kvp => kvp.Value.Contains(OutputTag.Intermediate))
+            .Should().HaveCount(2, "both the coordinator and the specialist are designated intermediate by default");
+    }
+
+    [Fact]
+    public void Test_HandoffWorkflowBuilder_ExplicitDesignationsReplaceDefaults()
+    {
+        AgentWorkflowBuilderTests.DoubleEchoAgent coordinator = new("coordinator");
+        AgentWorkflowBuilderTests.DoubleEchoAgent specialist = new("specialist");
+
+        Workflow workflow = AgentWorkflowBuilder
+            .CreateHandoffBuilderWith(coordinator)
+            .WithHandoff(coordinator, specialist)
+            .WithOutputFrom(coordinator)
+            .WithIntermediateOutputFrom([specialist])
+            .Build();
+
+        Dictionary<string, HashSet<OutputTag>> designations = workflow.OutputExecutors;
+
+        designations.Should().HaveCount(2,
+            "only the user-specified designations land on the inner builder; the handoff-end default is suppressed");
+        designations.Values.Where(tags => tags.Count == 0)
+            .Should().ContainSingle("coordinator is the only terminal designation");
+        designations.Values.Where(tags => tags.Contains(OutputTag.Intermediate))
+            .Should().ContainSingle("specialist is the only intermediate designation");
+    }
+
+    [Fact]
+    public void Test_HandoffWorkflowBuilder_DesignationForNonParticipantThrows()
+    {
+        AgentWorkflowBuilderTests.DoubleEchoAgent coordinator = new("coordinator");
+        AgentWorkflowBuilderTests.DoubleEchoAgent specialist = new("specialist");
+        AgentWorkflowBuilderTests.DoubleEchoAgent stranger = new("stranger");
+
+        HandoffWorkflowBuilder builder = AgentWorkflowBuilder
+            .CreateHandoffBuilderWith(coordinator)
+            .WithHandoff(coordinator, specialist)
+            .WithIntermediateOutputFrom([stranger]);
+
+        Action build = () => builder.Build();
+        build.Should().Throw<InvalidOperationException>().WithMessage("*stranger*");
+    }
+}
+#pragma warning restore MAAIW001

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/MagenticWorkflowBuilderTests.cs

@@ -0,0 +1,79 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using FluentAssertions;
+
+namespace Microsoft.Agents.AI.Workflows.UnitTests;
+
+/// <summary>
+/// Tests focused on <see cref="MagenticWorkflowBuilder"/>'s output-designation surface —
+/// the Python-aligned defaults applied at <see cref="MagenticWorkflowBuilder.Build"/> when
+/// the user has not made explicit designations, and the memoized
+/// <c>WithOutputFrom</c> / <c>WithIntermediateOutputFrom</c> replay otherwise.
+/// </summary>
+#pragma warning disable MAAIW001 // Experimental: MagenticWorkflowBuilder
+public class MagenticWorkflowBuilderTests
+{
+    [Fact]
+    public void Test_MagenticWorkflowBuilder_DefaultDesignationsMatchSpec()
+    {
+        TestReplayAgent manager = new(name: "Manager");
+        TestEchoAgent member1 = new(name: "Worker1");
+        TestEchoAgent member2 = new(name: "Worker2");
+
+        Workflow workflow = new MagenticWorkflowBuilder(manager)
+            .AddParticipants(member1, member2)
+            .RequirePlanSignoff(false)
+            .Build();
+
+        Dictionary<string, HashSet<OutputTag>> designations = workflow.OutputExecutors;
+
+        designations.Where(kvp => kvp.Value.Count == 0)
+            .Should().ContainSingle("the Magentic orchestrator is the sole terminal output by default");
+        designations.Where(kvp => kvp.Value.Contains(OutputTag.Intermediate))
+            .Should().HaveCount(2, "every team member is designated intermediate by default");
+    }
+
+    [Fact]
+    public void Test_MagenticWorkflowBuilder_ExplicitDesignationsReplaceDefaults()
+    {
+        TestReplayAgent manager = new(name: "Manager");
+        TestEchoAgent member1 = new(name: "Worker1");
+        TestEchoAgent member2 = new(name: "Worker2");
+
+        Workflow workflow = new MagenticWorkflowBuilder(manager)
+            .AddParticipants(member1, member2)
+            .RequirePlanSignoff(false)
+            .WithOutputFrom(member1)
+            .WithIntermediateOutputFrom([member2])
+            .Build();
+
+        Dictionary<string, HashSet<OutputTag>> designations = workflow.OutputExecutors;
+
+        designations.Should().HaveCount(2,
+            "only the user-specified designations land on the inner builder; the orchestrator default is suppressed");
+        designations.Values.Where(tags => tags.Count == 0)
+            .Should().ContainSingle("member1 is the only terminal designation");
+        designations.Values.Where(tags => tags.Contains(OutputTag.Intermediate))
+            .Should().ContainSingle("member2 is the only intermediate designation");
+    }
+
+    [Fact]
+    public void Test_MagenticWorkflowBuilder_DesignationForNonParticipantThrows()
+    {
+        TestReplayAgent manager = new(name: "Manager");
+        TestEchoAgent member = new(name: "Worker");
+        TestEchoAgent stranger = new(name: "Stranger");
+
+        MagenticWorkflowBuilder builder = new MagenticWorkflowBuilder(manager)
+            .AddParticipants(member)
+            .RequirePlanSignoff(false)
+            .WithIntermediateOutputFrom([stranger]);
+
+        Action build = () => builder.Build();
+        build.Should().Throw<InvalidOperationException>().WithMessage("*Stranger*");
+    }
+}
+#pragma warning restore MAAIW001