Clean up handoff orchestration creation (#235)

- Remove Dictionary-derived types
- Add an optional name to orchestrations
- Make Handoffs based purely on AIAgent instances rather than separately provided names

Author: stephentoub

dotnet/samples/GettingStarted/Orchestration/HandoffOrchestration_Intro.cs

@@ -56,11 +56,12 @@ public async Task RunOrchestrationAsync(bool streamedResponse)
         responses.Enqueue("Order ID 321");
         responses.Enqueue("Broken item");
         responses.Enqueue("No, bye");
+
         // Define the orchestration
         HandoffOrchestration orchestration =
-            new(OrchestrationHandoffs
+            new(Handoffs
                     .StartWith(triageAgent)
-                    .Add(triageAgent, statusAgent, returnAgent, refundAgent)
+                    .Add(triageAgent, [statusAgent, returnAgent, refundAgent])
                     .Add(statusAgent, triageAgent, "Transfer to this agent if the issue is not status related")
                     .Add(returnAgent, triageAgent, "Transfer to this agent if the issue is not return related")
                     .Add(refundAgent, triageAgent, "Transfer to this agent if the issue is not refund related"))

dotnet/samples/GettingStarted/Orchestration/HandoffOrchestration_With_StructuredInput.cs

@@ -46,9 +46,9 @@ public async Task RunOrchestrationAsync()
 
         // Define the orchestration
         HandoffOrchestration orchestration =
-            new(OrchestrationHandoffs
+            new(Handoffs
                     .StartWith(triageAgent)
-                    .Add(triageAgent, dotnetAgent, pythonAgent))
+                    .Add(triageAgent, [dotnetAgent, pythonAgent]))
             {
                 LoggerFactory = this.LoggerFactory,
                 ResponseCallback = monitor.ResponseCallback,

dotnet/samples/HelloHttpApi/HelloHttpApi.ApiService/HostApplicationBuilderAgentExtensions.cs

@@ -20,10 +20,11 @@ public static IHostApplicationBuilder AddAIAgent(this IHostApplicationBuilder bu
             ChatClientAgent target = new(chatClient, instructions, $"{name}_targetAgent");
             ChatClientAgent customerService = new(chatClient, "You are a customer service agent. You will handle rude, angry, or upset customer inquiries, asking them to be more calm and polite.", $"{name}_customerServiceAgent");
 
-            return new HandoffOrchestration(OrchestrationHandoffs
+            return Handoffs
                 .StartWith(triage)
                 .Add(triage, target, "Hand off to the target agent for handling normal customer requests.")
-                .Add(triage, customerService, "Hand off to the customer service agent for handling rude customer inquiries."));
+                .Add(triage, customerService, "Hand off to the customer service agent for handling rude customer inquiries.")
+                .Build("PirateWorkflow");
         });
         var actorBuilder = builder.AddActorRuntime();
 

dotnet/src/Microsoft.Agents.Orchestration/ConcurrentOrchestration.cs

@@ -19,7 +19,14 @@ public partial class ConcurrentOrchestration : OrchestratingAgent
 
     /// <summary>Initializes a new instance of the <see cref="ConcurrentOrchestration"/> class.</summary>
     /// <param name="subagents">The agents participating in the orchestration.</param>
-    public ConcurrentOrchestration(params AIAgent[] subagents) : base(subagents)
+    public ConcurrentOrchestration(params AIAgent[] subagents) : this(subagents, name: null)
+    {
+    }
+
+    /// <summary>Initializes a new instance of the <see cref="ConcurrentOrchestration"/> class.</summary>
+    /// <param name="subagents">The agents participating in the orchestration.</param>
+    /// <param name="name">An optional name for this orchestrating agent.</param>
+    public ConcurrentOrchestration(AIAgent[] subagents, string? name) : base(subagents, name)
     {
     }
 

dotnet/src/Microsoft.Agents.Orchestration/GroupChat/GroupChatManager.cs

@@ -86,11 +86,9 @@ protected GroupChatManager() { }
     /// <returns>A <see cref="GroupChatManagerResult{TValue}"/> indicating whether the chat should be terminated.</returns>
     protected internal virtual ValueTask<GroupChatManagerResult<bool>> ShouldTerminate(IReadOnlyCollection<ChatMessage> history, CancellationToken cancellationToken = default)
     {
-        Interlocked.Increment(ref this._invocationCount);
-
         bool resultValue = false;
         string reason = "Maximum number of invocations has not been reached.";
-        if (this.InvocationCount > this.MaximumInvocationCount)
+        if (Interlocked.Increment(ref this._invocationCount) > this.MaximumInvocationCount)
         {
             resultValue = true;
             reason = "Maximum number of invocations reached.";

dotnet/src/Microsoft.Agents.Orchestration/GroupChat/GroupChatOrchestration.cs

@@ -24,7 +24,17 @@ public sealed partial class GroupChatOrchestration : OrchestratingAgent
     /// </summary>
     /// <param name="manager">The manager that controls the flow of the group-chat.</param>
     /// <param name="agents">The agents participating in the orchestration.</param>
-    public GroupChatOrchestration(GroupChatManager manager, params AIAgent[] agents) : base(agents)
+    public GroupChatOrchestration(GroupChatManager manager, params AIAgent[] agents) : this(manager, agents, name: null)
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="GroupChatOrchestration"/> class.
+    /// </summary>
+    /// <param name="manager">The manager that controls the flow of the group-chat.</param>
+    /// <param name="agents">The agents participating in the orchestration.</param>
+    /// <param name="name">An optional name for this orchestrating agent.</param>
+    public GroupChatOrchestration(GroupChatManager manager, AIAgent[] agents, string? name) : base(agents, name)
     {
         this._manager = Throw.IfNull(manager);
     }

dotnet/src/Microsoft.Agents.Orchestration/GroupChat/RoundRobinGroupChatManager.cs

@@ -19,14 +19,16 @@ public class RoundRobinGroupChatManager : GroupChatManager
     private int _currentAgentIndex;
 
     /// <inheritdoc/>
-    protected internal override ValueTask<GroupChatManagerResult<string>> FilterResults(IReadOnlyCollection<ChatMessage> history, CancellationToken cancellationToken = default)
+    protected internal override ValueTask<GroupChatManagerResult<string>> FilterResults(
+        IReadOnlyCollection<ChatMessage> history, CancellationToken cancellationToken = default)
     {
         GroupChatManagerResult<string> result = new(history.LastOrDefault()?.Text ?? string.Empty) { Reason = "Default result filter provides the final chat message." };
         return new ValueTask<GroupChatManagerResult<string>>(result);
     }
 
     /// <inheritdoc/>
-    protected internal override ValueTask<GroupChatManagerResult<string>> SelectNextAgent(IReadOnlyCollection<ChatMessage> history, GroupChatTeam team, CancellationToken cancellationToken = default)
+    protected internal override ValueTask<GroupChatManagerResult<string>> SelectNextAgent(
+        IReadOnlyCollection<ChatMessage> history, GroupChatTeam team, CancellationToken cancellationToken = default)
     {
         string nextAgent = team.Skip(this._currentAgentIndex).First().Key;
         this._currentAgentIndex = (this._currentAgentIndex + 1) % team.Count;
@@ -35,7 +37,8 @@ protected internal override ValueTask<GroupChatManagerResult<string>> SelectNext
     }
 
     /// <inheritdoc/>
-    protected internal override ValueTask<GroupChatManagerResult<bool>> ShouldRequestUserInput(IReadOnlyCollection<ChatMessage> history, CancellationToken cancellationToken = default)
+    protected internal override ValueTask<GroupChatManagerResult<bool>> ShouldRequestUserInput(
+        IReadOnlyCollection<ChatMessage> history, CancellationToken cancellationToken = default)
     {
         GroupChatManagerResult<bool> result = new(false) { Reason = "The default round-robin group chat manager does not request user input." };
         return new ValueTask<GroupChatManagerResult<bool>>(result);

dotnet/src/Microsoft.Agents.Orchestration/Handoffs/HandoffOrchestration.cs

@@ -20,29 +20,23 @@ namespace Microsoft.Agents.Orchestration;
 /// </summary>
 public sealed partial class HandoffOrchestration : OrchestratingAgent
 {
-    private readonly OrchestrationHandoffs _handoffs;
+    private readonly Handoffs _handoffs;
 
     /// <summary>
     /// Initializes a new instance of the <see cref="HandoffOrchestration"/> class.
     /// </summary>
     /// <param name="handoffs">Defines the handoff connections for each agent.</param>
-    /// <param name="agents">Additional agents participating in the orchestration that weren't passed to <paramref name="handoffs"/>.</param>
-    public HandoffOrchestration(OrchestrationHandoffs handoffs, params AIAgent[] agents) : base(
-            agents is { Length: 0 } ? [.. handoffs.Agents] :
-            handoffs.Agents is { Count: 0 } ? agents :
-            [.. handoffs.Agents.Concat(agents).Distinct()])
+    public HandoffOrchestration(Handoffs handoffs) : this(handoffs, name: null)
     {
-        // Create list of distinct agent names
-        HashSet<string> agentNames = [.. base.Agents.Select(a => a.DisplayName), handoffs.FirstAgentName];
-
-        // Extract names from handoffs that don't align with a member agent.
-        // Fail fast if invalid names are present.
-        string[] badNames = [.. handoffs.Keys.Concat(handoffs.Values.SelectMany(h => h.Keys)).Where(name => !agentNames.Contains(name))];
-        if (badNames.Length > 0)
-        {
-            Throw.ArgumentException(nameof(handoffs), $"The following agents are not defined in the orchestration: {string.Join(", ", badNames)}");
-        }
+    }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="HandoffOrchestration"/> class.
+    /// </summary>
+    /// <param name="handoffs">Defines the handoff connections for each agent.</param>
+    /// <param name="name">An optional name for this orchestrating agent.</param>
+    public HandoffOrchestration(Handoffs handoffs, string? name) : base(handoffs.Agents.ToArray(), name)
+    {
         this._handoffs = handoffs;
     }
 
@@ -54,39 +48,51 @@ protected override Task<AgentRunResponse> RunCoreAsync(IReadOnlyCollection<ChatM
     {
         List<ChatMessage> allMessages = [.. messages];
         int originalMessageCount = allMessages.Count;
-        return this.ResumeAsync(this._handoffs.FirstAgentName, allMessages, originalMessageCount, context, cancellationToken);
+        return this.ResumeAsync(this._handoffs.InitialAgent, allMessages, originalMessageCount, context, cancellationToken);
     }
 
     /// <inheritdoc />
     protected override Task<AgentRunResponse> ResumeCoreAsync(JsonElement checkpointState, OrchestratingAgentContext context, CancellationToken cancellationToken)
     {
         var state = checkpointState.Deserialize(OrchestrationJsonContext.Default.HandoffState) ?? throw new InvalidOperationException("The checkpoint state is invalid.");
-        return this.ResumeAsync(state.NextAgent, state.AllMessages, state.OriginalMessageCount, context, cancellationToken);
+
+        AIAgent? nextAgent = null;
+        foreach (var agent in this.Agents)
+        {
+            if (agent.Id == state.NextAgent)
+            {
+                nextAgent = agent;
+                break;
+            }
+        }
+
+        if (nextAgent is null)
+        {
+            Throw.InvalidOperationException($"The next agent '{state.NextAgent}' is not defined in the orchestration.");
+        }
+
+        return this.ResumeAsync(nextAgent, state.AllMessages, state.OriginalMessageCount, context, cancellationToken);
     }
 
     /// <inheritdoc />
     private async Task<AgentRunResponse> ResumeAsync(
-        string? nextAgent, List<ChatMessage> allMessages, int originalMessageCount, OrchestratingAgentContext context, CancellationToken cancellationToken)
+        AIAgent? agent, List<ChatMessage> allMessages, int originalMessageCount, OrchestratingAgentContext context, CancellationToken cancellationToken)
     {
-        Debug.Assert(nextAgent is not null);
+        Debug.Assert(agent is not null);
         AgentRunResponse? response = null;
 
-        while (nextAgent is not null)
+        while (agent is not null)
         {
-            AIAgent? agent =
-                this.Agents.FirstOrDefault(a => a.Name == nextAgent || a.Id == nextAgent) ??
-                throw new InvalidOperationException($"The agent '{nextAgent}' is not defined in the orchestration.");
-
             this.LogOrchestrationSubagentRunning(context, agent);
 
-            if (!this._handoffs.TryGetValue(agent.DisplayName, out AgentHandoffs? handoffs) || handoffs.Count == 0)
+            if (!this._handoffs.Targets.TryGetValue(agent, out var handoffs) || handoffs.Count == 0)
             {
                 // If no handoff is available, we can run the agent directly and return its response.
                 response = await RunAsync(agent, context, allMessages, context.Options, cancellationToken).ConfigureAwait(false);
+                this.LogOrchestrationSubagentCompleted(context, agent);
                 allMessages.AddRange(response.Messages);
-                nextAgent = null;
+                agent = null;
                 await CheckpointAsync().ConfigureAwait(false);
-                this.LogOrchestrationSubagentCompleted(context, agent);
                 break;
             }
 
@@ -107,8 +113,9 @@ private async Task<AgentRunResponse> ResumeAsync(
 
             // Invoke the next agent with all of the messages collected so far.
             response = await RunAsync(agent, context, allMessages, options, cancellationToken).ConfigureAwait(false);
+            this.LogOrchestrationSubagentCompleted(context, agent);
             allMessages.AddRange(response.Messages);
-            nextAgent = handoffCtx.TargetedAgent;
+            agent = handoffCtx.TargetedAgent;
             RemoveHandoffFunctionCalls(response, handoffTools);
 
             if (this.InteractiveCallback is not null)
@@ -118,12 +125,10 @@ private async Task<AgentRunResponse> ResumeAsync(
                     break;
                 }
 
-                nextAgent = agent.DisplayName;
                 allMessages.Add(await this.InteractiveCallback().ConfigureAwait(false));
             }
 
             await CheckpointAsync().ConfigureAwait(false);
-            this.LogOrchestrationSubagentCompleted(context, agent);
         }
 
         allMessages.RemoveRange(0, originalMessageCount);
@@ -132,7 +137,7 @@ private async Task<AgentRunResponse> ResumeAsync(
         return response;
 
         Task CheckpointAsync() => context.Runtime is not null ?
-            base.WriteCheckpointAsync(JsonSerializer.SerializeToElement(new(nextAgent, allMessages, originalMessageCount), OrchestrationJsonContext.Default.HandoffState), context, cancellationToken) :
+            base.WriteCheckpointAsync(JsonSerializer.SerializeToElement(new(agent?.Id, allMessages, originalMessageCount), OrchestrationJsonContext.Default.HandoffState), context, cancellationToken) :
             Task.CompletedTask;
     }
 
@@ -173,9 +178,9 @@ private static void RemoveHandoffFunctionCalls(AgentRunResponse response, List<A
         }
     }
 
-    private sealed class HandoffContext(AgentHandoffs handoffs)
+    private sealed class HandoffContext(HashSet<Handoffs.HandoffTarget> handoffs)
     {
-        public string? TargetedAgent { get; set; }
+        public AIAgent? TargetedAgent { get; set; }
         public bool EndTaskInvoked { get; set; }
 
         public List<AITool> CreateHandoffFunctions(bool needsEndTask)
@@ -194,16 +199,16 @@ public List<AITool> CreateHandoffFunctions(bool needsEndTask)
                     description: "Invoke this function when all work is completed and no further interactions are required."));
             }
 
-            foreach (KeyValuePair<string, string> handoff in handoffs)
+            foreach (Handoffs.HandoffTarget handoff in handoffs)
             {
                 functions.Add(AIFunctionFactory.Create(
                     () =>
                     {
-                        this.TargetedAgent = handoff.Key;
+                        this.TargetedAgent = handoff.Target;
                         Terminate();
                     },
-                    name: $"handoff_to_{InvalidNameCharsRegex().Replace(handoff.Key, "_")}",
-                    description: handoff.Value));
+                    name: $"handoff_to_{InvalidNameCharsRegex().Replace(handoff.Target.DisplayName, "_")}",
+                    description: handoff.Reason));
             }
 
             return functions;