Merge branch 'main' into dev/dotnet_workflow/state_manager_object_check

dotnet/src/Microsoft.Agents.AI.Workflows/HandoffsWorkflowBuilder.cs

@@ -13,10 +13,18 @@ namespace Microsoft.Agents.AI.Workflows;
 /// </summary>
 public sealed class HandoffsWorkflowBuilder
 {
-    internal const string FunctionPrefix = "handoff_to_";
+    /// <summary>
+    /// The prefix for function calls that trigger handoffs to other agents; the full name is then `{FunctionPrefix}&lt;agent_id&gt;`,
+    /// where `&lt;agent_id&gt;` is the ID of the target agent to hand off to.
+    /// </summary>
+    public const string FunctionPrefix = "handoff_to_";
+
     private readonly AIAgent _initialAgent;
     private readonly Dictionary<AIAgent, HashSet<HandoffTarget>> _targets = [];
     private readonly HashSet<AIAgent> _allAgents = new(AIAgentIDEqualityComparer.Instance);
+
+    private bool _emitAgentResponseEvents;
+    private bool _emitAgentResponseUpdateEvents;
     private HandoffToolCallFilteringBehavior _toolCallFilteringBehavior = HandoffToolCallFilteringBehavior.HandoffOnly;
 
     /// <summary>
@@ -47,9 +55,13 @@ public sealed class HandoffsWorkflowBuilder
               """;
 
     /// <summary>
-    /// Sets additional instructions to provide to an agent that has handoffs about how and when to
-    /// perform them.
+    /// Sets instructions to provide to each agent that has handoffs about how and when to perform them.
     /// </summary>
+    /// <remarks>
+    /// In the vast majority of cases, the <see cref="DefaultHandoffInstructions"/> will be sufficient, and there will be no need to customize.
+    /// If you do provide alternate instructions, remember to explain the mechanics of the handoff function tool call, using see
+    /// <see cref="FunctionPrefix"/> constant.
+    /// </remarks>
     /// <param name="instructions">The instructions to provide, or <see langword="null"/> to restore the default instructions.</param>
     public HandoffsWorkflowBuilder WithHandoffInstructions(string? instructions)
     {
@@ -57,6 +69,29 @@ public sealed class HandoffsWorkflowBuilder
         return this;
     }
 
+    /// <summary>
+    /// Sets a value indicating whether agent streaming update events should be emitted during execution.
+    /// If <see langword="null"/>, the value will be taken from the <see cref="TurnToken"/>
+    /// </summary>
+    /// <param name="emitAgentResponseUpdateEvents"></param>
+    /// <returns></returns>
+    public HandoffsWorkflowBuilder EmitAgentResponseUpdateEvents(bool emitAgentResponseUpdateEvents = true)
+    {
+        this._emitAgentResponseUpdateEvents = emitAgentResponseUpdateEvents;
+        return this;
+    }
+
+    /// <summary>
+    /// Sets a value indicating whether aggregated agent response events should be emitted during execution.
+    /// </summary>
+    /// <param name="emitAgentResponseEvents"></param>
+    /// <returns></returns>
+    public HandoffsWorkflowBuilder EmitAgentResponseEvents(bool emitAgentResponseEvents = true)
+    {
+        this._emitAgentResponseEvents = emitAgentResponseEvents;
+        return this;
+    }
+
     /// <summary>
     /// Sets the behavior for filtering <see cref="FunctionCallContent"/> and <see cref="ChatRole.Tool"/> contents from
     /// <see cref="ChatMessage"/>s flowing through the handoff workflow. Defaults to <see cref="HandoffToolCallFilteringBehavior.HandoffOnly"/>.
@@ -175,7 +210,10 @@ public sealed class HandoffsWorkflowBuilder
         HandoffsEndExecutor end = new();
         WorkflowBuilder builder = new(start);
 
-        HandoffAgentExecutorOptions options = new(this.HandoffInstructions, this._toolCallFilteringBehavior);
+        HandoffAgentExecutorOptions options = new(this.HandoffInstructions,
+                                                  this._emitAgentResponseEvents,
+                                                  this._emitAgentResponseUpdateEvents,
+                                                  this._toolCallFilteringBehavior);
 
         // Create an AgentExecutor for each again.
         Dictionary<string, HandoffAgentExecutor> executors = this._allAgents.ToDictionary(a => a.Id, a => new HandoffAgentExecutor(a, options));

dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/AIAgentHostExecutor.cs

@@ -12,6 +12,15 @@ namespace Microsoft.Agents.AI.Workflows.Specialized;
 
 internal record AIAgentHostState(JsonElement? ThreadState, bool? CurrentTurnEmitEvents);
 
+internal static class TurnExtensions
+{
+    public static bool ShouldEmitStreamingEvents(this TurnToken token, bool? agentSetting)
+        => token.EmitEvents ?? agentSetting ?? false;
+
+    public static bool ShouldEmitStreamingEvents(bool? turnTokenSetting, bool? agentSetting)
+        => turnTokenSetting ?? agentSetting ?? false;
+}
+
 internal sealed class AIAgentHostExecutor : ChatProtocolExecutor
 {
     private readonly AIAgent _agent;
@@ -104,9 +113,6 @@ internal sealed class AIAgentHostExecutor : ChatProtocolExecutor
         }, context, cancellationToken);
     }
 
-    public bool ShouldEmitStreamingEvents(bool? emitEvents)
-        => emitEvents ?? this._options.EmitAgentUpdateEvents ?? false;
-
     private async ValueTask<AgentSession> EnsureSessionAsync(IWorkflowContext context, CancellationToken cancellationToken) =>
         this._session ??= await this._agent.CreateSessionAsync(cancellationToken).ConfigureAwait(false);
 
@@ -175,7 +181,10 @@ internal sealed class AIAgentHostExecutor : ChatProtocolExecutor
     }
 
     protected override ValueTask TakeTurnAsync(List<ChatMessage> messages, IWorkflowContext context, bool? emitEvents, CancellationToken cancellationToken = default)
-        => this.ContinueTurnAsync(messages, context, this.ShouldEmitStreamingEvents(emitEvents), cancellationToken);
+        => this.ContinueTurnAsync(messages,
+                                  context,
+                                  TurnExtensions.ShouldEmitStreamingEvents(turnTokenSetting: emitEvents, this._options.EmitAgentUpdateEvents),
+                                  cancellationToken);
 
     private async ValueTask<AgentResponse> InvokeAgentAsync(IEnumerable<ChatMessage> messages, IWorkflowContext context, bool emitEvents, CancellationToken cancellationToken = default)
     {

dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/HandoffAgentExecutor.cs

@@ -14,14 +14,20 @@ namespace Microsoft.Agents.AI.Workflows.Specialized;
 
 internal sealed class HandoffAgentExecutorOptions
 {
-    public HandoffAgentExecutorOptions(string? handoffInstructions, HandoffToolCallFilteringBehavior toolCallFilteringBehavior)
+    public HandoffAgentExecutorOptions(string? handoffInstructions, bool emitAgentResponseEvents, bool? emitAgentResponseUpdateEvents, HandoffToolCallFilteringBehavior toolCallFilteringBehavior)
     {
         this.HandoffInstructions = handoffInstructions;
+        this.EmitAgentResponseEvents = emitAgentResponseEvents;
+        this.EmitAgentResponseUpdateEvents = emitAgentResponseUpdateEvents;
         this.ToolCallFilteringBehavior = toolCallFilteringBehavior;
     }
 
     public string? HandoffInstructions { get; set; }
 
+    public bool EmitAgentResponseEvents { get; set; }
+
+    public bool? EmitAgentResponseUpdateEvents { get; set; }
+
     public HandoffToolCallFilteringBehavior ToolCallFilteringBehavior { get; set; } = HandoffToolCallFilteringBehavior.HandoffOnly;
 }
 
@@ -250,7 +256,14 @@ internal sealed class HandoffAgentExecutor(
             }
         }
 
-        allMessages.AddRange(updates.ToAgentResponse().Messages);
+        AgentResponse agentResponse = updates.ToAgentResponse();
+
+        if (options.EmitAgentResponseEvents)
+        {
+            await context.YieldOutputAsync(agentResponse, cancellationToken).ConfigureAwait(false);
+        }
+
+        allMessages.AddRange(agentResponse.Messages);
 
         roleChanges.ResetUserToAssistantForChangedRoles();
 
@@ -259,7 +272,7 @@ internal sealed class HandoffAgentExecutor(
         async Task AddUpdateAsync(AgentResponseUpdate update, CancellationToken cancellationToken)
         {
             updates.Add(update);
-            if (message.TurnToken.EmitEvents is true)
+            if (message.TurnToken.ShouldEmitStreamingEvents(options.EmitAgentResponseUpdateEvents))
             {
                 await context.YieldOutputAsync(update, cancellationToken).ConfigureAwait(false);
             }

dotnet/src/Microsoft.Agents.AI.Workflows/WorkflowChatHistoryProvider.cs

@@ -43,7 +43,7 @@ internal sealed class WorkflowChatHistoryProvider : ChatHistoryProvider
         => this._sessionState.GetOrInitializeState(session).Messages.AddRange(messages);
 
     protected override ValueTask<IEnumerable<ChatMessage>> ProvideChatHistoryAsync(InvokingContext context, CancellationToken cancellationToken = default)
-        => new(this._sessionState.GetOrInitializeState(context.Session).Messages);
+        => new(this._sessionState.GetOrInitializeState(context.Session).Messages.AsReadOnly());
 
     protected override ValueTask StoreChatHistoryAsync(InvokedContext context, CancellationToken cancellationToken = default)
     {
@@ -62,6 +62,12 @@ internal sealed class WorkflowChatHistoryProvider : ChatHistoryProvider
         }
     }
 
+    public IEnumerable<ChatMessage> GetAllMessages(AgentSession session)
+    {
+        var state = this._sessionState.GetOrInitializeState(session);
+        return state.Messages.AsReadOnly();
+    }
+
     public void UpdateBookmark(AgentSession session)
     {
         var state = this._sessionState.GetOrInitializeState(session);

dotnet/src/Microsoft.Agents.AI.Workflows/WorkflowHostAgent.cs

@@ -119,13 +119,17 @@ internal sealed class WorkflowHostAgent : AIAgent
         MessageMerger merger = new();
 
         await foreach (AgentResponseUpdate update in workflowSession.InvokeStageAsync(cancellationToken)
-                                                                      .ConfigureAwait(false)
-                                                                      .WithCancellation(cancellationToken))
+                                                                     .ConfigureAwait(false)
+                                                                     .WithCancellation(cancellationToken))
         {
             merger.AddUpdate(update);
         }
 
-        return merger.ComputeMerged(workflowSession.LastResponseId!, this.Id, this.Name);
+        AgentResponse response = merger.ComputeMerged(workflowSession.LastResponseId!, this.Id, this.Name);
+        workflowSession.ChatHistoryProvider.AddMessages(workflowSession, response.Messages);
+        workflowSession.ChatHistoryProvider.UpdateBookmark(workflowSession);
+
+        return response;
     }
 
     protected override async
@@ -138,11 +142,18 @@ internal sealed class WorkflowHostAgent : AIAgent
         await this.ValidateWorkflowAsync().ConfigureAwait(false);
 
         WorkflowSession workflowSession = await this.UpdateSessionAsync(messages, session, cancellationToken).ConfigureAwait(false);
+        MessageMerger merger = new();
+
         await foreach (AgentResponseUpdate update in workflowSession.InvokeStageAsync(cancellationToken)
                                                                       .ConfigureAwait(false)
                                                                       .WithCancellation(cancellationToken))
         {
+            merger.AddUpdate(update);
             yield return update;
         }
+
+        AgentResponse response = merger.ComputeMerged(workflowSession.LastResponseId!, this.Id, this.Name);
+        workflowSession.ChatHistoryProvider.AddMessages(workflowSession, response.Messages);
+        workflowSession.ChatHistoryProvider.UpdateBookmark(workflowSession);
     }
 }

dotnet/src/Microsoft.Agents.AI.Workflows/WorkflowSession.cs

@@ -131,7 +131,7 @@ internal sealed class WorkflowSession : AgentSession
     {
         Throw.IfNullOrEmpty(parts);
 
-        AgentResponseUpdate update = new(ChatRole.Assistant, parts)
+        return new(ChatRole.Assistant, parts)
         {
             CreatedAt = DateTimeOffset.UtcNow,
             MessageId = Guid.NewGuid().ToString("N"),
@@ -139,27 +139,19 @@ internal sealed class WorkflowSession : AgentSession
             ResponseId = responseId,
             RawRepresentation = raw
         };
-
-        this.ChatHistoryProvider.AddMessages(this, update.ToChatMessage());
-
-        return update;
     }
 
     public AgentResponseUpdate CreateUpdate(string responseId, object raw, ChatMessage message)
     {
         Throw.IfNull(message);
 
-        AgentResponseUpdate update = new(message.Role, message.Contents)
+        return new(message.Role, message.Contents)
         {
             CreatedAt = message.CreatedAt ?? DateTimeOffset.UtcNow,
             MessageId = message.MessageId ?? Guid.NewGuid().ToString("N"),
             ResponseId = responseId,
             RawRepresentation = raw
         };
-
-        this.ChatHistoryProvider.AddMessages(this, update.ToChatMessage());
-
-        return update;
     }
 
     private async ValueTask<ResumeRunResult> CreateOrResumeRunAsync(List<ChatMessage> messages, CancellationToken cancellationToken = default)
@@ -328,111 +320,104 @@ internal sealed class WorkflowSession : AgentSession
     IAsyncEnumerable<AgentResponseUpdate> InvokeStageAsync(
         [EnumeratorCancellation] CancellationToken cancellationToken = default)
     {
-        try
-        {
-            this.LastResponseId = Guid.NewGuid().ToString("N");
-            List<ChatMessage> messages = this.ChatHistoryProvider.GetFromBookmark(this).ToList();
+        this.LastResponseId = Guid.NewGuid().ToString("N");
+        List<ChatMessage> messages = this.ChatHistoryProvider.GetFromBookmark(this).ToList();
+
+        ResumeRunResult resumeResult =
+            await this.CreateOrResumeRunAsync(messages, cancellationToken).ConfigureAwait(false);
 
-            ResumeRunResult resumeResult =
-                await this.CreateOrResumeRunAsync(messages, cancellationToken).ConfigureAwait(false);
 #pragma warning disable CA2007 // Analyzer misfiring.
-            await using StreamingRun run = resumeResult.Run;
+        await using StreamingRun run = resumeResult.Run;
 #pragma warning restore CA2007
 
-            ResumeDispatchInfo dispatchInfo = resumeResult.DispatchInfo;
+        ResumeDispatchInfo dispatchInfo = resumeResult.DispatchInfo;
 
-            // Send a TurnToken to the start executor unless the only activity is an external
-            // response directed at the start executor itself (which self-emits a TurnToken via
-            // ContinueTurnAsync). Non-start executors (e.g., RequestInfoExecutor) do not emit
-            // TurnTokens after processing responses, so the session must always provide one.
-            bool shouldSendTurnToken =
-                !dispatchInfo.HasMatchedExternalResponses
-                || !dispatchInfo.HasMatchedResponseForStartExecutor;
-            if (shouldSendTurnToken)
-            {
-                await run.TrySendMessageAsync(new TurnToken(emitEvents: true)).ConfigureAwait(false);
-            }
-            await foreach (WorkflowEvent evt in run.WatchStreamAsync(blockOnPendingRequest: false, cancellationToken)
+        // Send a TurnToken to the start executor unless the only activity is an external
+        // response directed at the start executor itself (which self-emits a TurnToken via
+        // ContinueTurnAsync). Non-start executors (e.g., RequestInfoExecutor) do not emit
+        // TurnTokens after processing responses, so the session must always provide one.
+        bool shouldSendTurnToken =
+            !dispatchInfo.HasMatchedExternalResponses
+            || !dispatchInfo.HasMatchedResponseForStartExecutor;
+        if (shouldSendTurnToken)
+        {
+            await run.TrySendMessageAsync(new TurnToken(emitEvents: true)).ConfigureAwait(false);
+        }
+        await foreach (WorkflowEvent evt in run.WatchStreamAsync(blockOnPendingRequest: false, cancellationToken)
                                                .ConfigureAwait(false)
                                                .WithCancellation(cancellationToken))
-            {
-                switch (evt)
-                {
-                    case AgentResponseUpdateEvent agentUpdate:
-                        yield return agentUpdate.Update;
-                        break;
-
-                    case RequestInfoEvent requestInfo:
-                        AIContent requestContent = CreateRequestContentForDelivery(requestInfo.Request);
-
-                        // Track the pending request so we can convert incoming responses back to ExternalResponse.
-                        // External callers respond using the workflow-facing request ID, which is always RequestId.
-                        this.AddPendingRequest(requestInfo.Request.RequestId, requestInfo.Request);
-
-                        AgentResponseUpdate update = this.CreateUpdate(this.LastResponseId, evt, requestContent);
-                        yield return update;
-                        break;
-
-                    case WorkflowErrorEvent workflowError:
-                        Exception? exception = workflowError.Exception;
-                        if (exception is TargetInvocationException tie && tie.InnerException != null)
-                        {
-                            exception = tie.InnerException;
-                        }
-
-                        if (exception != null)
-                        {
-                            string message = this._includeExceptionDetails
-                                           ? exception.Message
-                                           : "An error occurred while executing the workflow.";
-
-                            ErrorContent errorContent = new(message);
-                            yield return this.CreateUpdate(this.LastResponseId, evt, errorContent);
-                        }
-
-                        break;
-
-                    case SuperStepCompletedEvent stepCompleted:
-                        this.LastCheckpoint = stepCompleted.CompletionInfo?.Checkpoint;
-                        goto default;
-
-                    case WorkflowOutputEvent output:
-                        IEnumerable<ChatMessage>? updateMessages = output.Data switch
-                        {
-                            IEnumerable<ChatMessage> chatMessages => chatMessages,
-                            ChatMessage chatMessage => [chatMessage],
-                            _ => null
-                        };
-
-                        if (!this._includeWorkflowOutputsInResponse || updateMessages == null)
-                        {
-                            goto default;
-                        }
-
-                        foreach (ChatMessage message in updateMessages)
-                        {
-                            yield return this.CreateUpdate(this.LastResponseId, evt, message);
-                        }
-                        break;
-
-                    default:
-                        // Emit all other workflow events for observability (DevUI, logging, etc.)
-                        yield return new AgentResponseUpdate(ChatRole.Assistant, [])
-                        {
-                            CreatedAt = DateTimeOffset.UtcNow,
-                            MessageId = Guid.NewGuid().ToString("N"),
-                            Role = ChatRole.Assistant,
-                            ResponseId = this.LastResponseId,
-                            RawRepresentation = evt
-                        };
-                        break;
-                }
-            }
-        }
-        finally
         {
-            // Do we want to try to undo the step, and not update the bookmark?
-            this.ChatHistoryProvider.UpdateBookmark(this);
+            switch (evt)
+            {
+                case AgentResponseUpdateEvent agentUpdate:
+                    yield return agentUpdate.Update;
+                    break;
+
+                case RequestInfoEvent requestInfo:
+                    AIContent requestContent = CreateRequestContentForDelivery(requestInfo.Request);
+
+                    // Track the pending request so we can convert incoming responses back to ExternalResponse.
+                    // External callers respond using the workflow-facing request ID, which is always RequestId.
+                    this.AddPendingRequest(requestInfo.Request.RequestId, requestInfo.Request);
+
+                    AgentResponseUpdate update = this.CreateUpdate(this.LastResponseId, evt, requestContent);
+                    yield return update;
+                    break;
+
+                case WorkflowErrorEvent workflowError:
+                    Exception? exception = workflowError.Exception;
+                    if (exception is TargetInvocationException tie && tie.InnerException != null)
+                    {
+                        exception = tie.InnerException;
+                    }
+
+                    if (exception != null)
+                    {
+                        string message = this._includeExceptionDetails
+                                       ? exception.Message
+                                       : "An error occurred while executing the workflow.";
+
+                        ErrorContent errorContent = new(message);
+                        yield return this.CreateUpdate(this.LastResponseId, evt, errorContent);
+                    }
+
+                    break;
+
+                case SuperStepCompletedEvent stepCompleted:
+                    this.LastCheckpoint = stepCompleted.CompletionInfo?.Checkpoint;
+                    goto default;
+
+                case WorkflowOutputEvent output:
+                    IEnumerable<ChatMessage>? updateMessages = output.Data switch
+                    {
+                        IEnumerable<ChatMessage> chatMessages => chatMessages,
+                        ChatMessage chatMessage => [chatMessage],
+                        _ => null
+                    };
+
+                    if (!this._includeWorkflowOutputsInResponse || updateMessages == null)
+                    {
+                        goto default;
+                    }
+
+                    foreach (ChatMessage message in updateMessages)
+                    {
+                        yield return this.CreateUpdate(this.LastResponseId, evt, message);
+                    }
+                    break;
+
+                default:
+                    // Emit all other workflow events for observability (DevUI, logging, etc.)
+                    yield return new AgentResponseUpdate(ChatRole.Assistant, [])
+                    {
+                        CreatedAt = DateTimeOffset.UtcNow,
+                        MessageId = Guid.NewGuid().ToString("N"),
+                        Role = ChatRole.Assistant,
+                        ResponseId = this.LastResponseId,
+                        RawRepresentation = evt
+                    };
+                    break;
+            }
         }
     }
 

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

@@ -10,20 +10,8 @@ using Microsoft.Extensions.AI;
 
 namespace Microsoft.Agents.AI.Workflows.UnitTests;
 
-public class AIAgentHostExecutorTests
+public class AIAgentHostExecutorTests : AIAgentHostingExecutorTestsBase
 {
-    private const string TestAgentId = nameof(TestAgentId);
-    private const string TestAgentName = nameof(TestAgentName);
-
-    private static readonly string[] s_messageStrings = [
-        "",
-        "Hello world!",
-        "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
-        "Quisque dignissim ante odio, at facilisis orci porta a. Duis mi augue, fringilla eu egestas a, pellentesque sed lacus."
-    ];
-
-    private static List<ChatMessage> TestMessages => TestReplayAgent.ToChatMessages(s_messageStrings);
-
     [Theory]
     [InlineData(null, null)]
     [InlineData(null, true)]
@@ -50,30 +38,7 @@ public class AIAgentHostExecutorTests
         bool expectingEvents = turnSetting ?? executorSetting ?? false;
 
         AgentResponseUpdateEvent[] updates = testContext.Events.OfType<AgentResponseUpdateEvent>().ToArray();
-        if (expectingEvents)
-        {
-            // The way TestReplayAgent is set up, it will emit one update per non-empty AIContent
-            List<AIContent> expectedUpdateContents = TestMessages.SelectMany(message => message.Contents).ToList();
-
-            updates.Should().HaveCount(expectedUpdateContents.Count);
-            for (int i = 0; i < updates.Length; i++)
-            {
-                AgentResponseUpdateEvent updateEvent = updates[i];
-                AIContent expectedUpdateContent = expectedUpdateContents[i];
-
-                updateEvent.ExecutorId.Should().Be(agent.GetDescriptiveId());
-
-                AgentResponseUpdate update = updateEvent.Update;
-                update.AuthorName.Should().Be(TestAgentName);
-                update.AgentId.Should().Be(TestAgentId);
-                update.Contents.Should().HaveCount(1);
-                update.Contents[0].Should().BeEquivalentTo(expectedUpdateContent);
-            }
-        }
-        else
-        {
-            updates.Should().BeEmpty();
-        }
+        CheckResponseUpdateEventsAgainstTestMessages(updates, expectingEvents, agent.GetDescriptiveId());
     }
 
     [Theory]
@@ -92,30 +57,7 @@ public class AIAgentHostExecutorTests
 
         // Assert
         AgentResponseEvent[] updates = testContext.Events.OfType<AgentResponseEvent>().ToArray();
-        if (executorSetting)
-        {
-            updates.Should().HaveCount(1);
-
-            AgentResponseEvent responseEvent = updates[0];
-            responseEvent.ExecutorId.Should().Be(agent.GetDescriptiveId());
-
-            AgentResponse response = responseEvent.Response;
-            response.AgentId.Should().Be(TestAgentId);
-            response.Messages.Should().HaveCount(TestMessages.Count - 1);
-
-            for (int i = 0; i < response.Messages.Count; i++)
-            {
-                ChatMessage responseMessage = response.Messages[i];
-                ChatMessage expectedMessage = TestMessages[i + 1]; // Skip the first empty message
-
-                responseMessage.AuthorName.Should().Be(TestAgentName);
-                responseMessage.Text.Should().Be(expectedMessage.Text);
-            }
-        }
-        else
-        {
-            updates.Should().BeEmpty();
-        }
+        CheckResponseEventsAgainstTestMessages(updates, expectingResponse: executorSetting, agent.GetDescriptiveId());
     }
 
     private static ChatMessage UserMessage => new(ChatRole.User, "Hello from User!") { AuthorName = "User" };

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

@@ -0,0 +1,79 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Linq;
+using FluentAssertions;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI.Workflows.UnitTests;
+
+public abstract class AIAgentHostingExecutorTestsBase
+{
+    protected const string TestAgentId = nameof(TestAgentId);
+    protected const string TestAgentName = nameof(TestAgentName);
+
+    private static readonly string[] s_messageStrings = [
+        "",
+        "Hello world!",
+        "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
+        "Quisque dignissim ante odio, at facilisis orci porta a. Duis mi augue, fringilla eu egestas a, pellentesque sed lacus."
+    ];
+
+    protected static List<ChatMessage> TestMessages => TestReplayAgent.ToChatMessages(s_messageStrings);
+
+    protected static void CheckResponseUpdateEventsAgainstTestMessages(AgentResponseUpdateEvent[] updates, bool expectingEvents, string expectedExecutorId)
+    {
+        if (expectingEvents)
+        {
+            // The way TestReplayAgent is set up, it will emit one update per non-empty AIContent
+            List<AIContent> expectedUpdateContents = TestMessages.SelectMany(message => message.Contents).ToList();
+
+            updates.Should().HaveCount(expectedUpdateContents.Count);
+            for (int i = 0; i < updates.Length; i++)
+            {
+                AgentResponseUpdateEvent updateEvent = updates[i];
+                AIContent expectedUpdateContent = expectedUpdateContents[i];
+
+                updateEvent.ExecutorId.Should().Be(expectedExecutorId);
+
+                AgentResponseUpdate update = updateEvent.Update;
+                update.AuthorName.Should().Be(TestAgentName);
+                update.AgentId.Should().Be(TestAgentId);
+                update.Contents.Should().HaveCount(1);
+                update.Contents[0].Should().BeEquivalentTo(expectedUpdateContent);
+            }
+        }
+        else
+        {
+            updates.Should().BeEmpty();
+        }
+    }
+
+    protected static void CheckResponseEventsAgainstTestMessages(AgentResponseEvent[] updates, bool expectingResponse, string expectedExecutorId)
+    {
+        if (expectingResponse)
+        {
+            updates.Should().HaveCount(1);
+
+            AgentResponseEvent responseEvent = updates[0];
+            responseEvent.ExecutorId.Should().Be(expectedExecutorId);
+
+            AgentResponse response = responseEvent.Response;
+            response.AgentId.Should().Be(TestAgentId);
+            response.Messages.Should().HaveCount(TestMessages.Count - 1);
+
+            for (int i = 0; i < response.Messages.Count; i++)
+            {
+                ChatMessage responseMessage = response.Messages[i];
+                ChatMessage expectedMessage = TestMessages[i + 1]; // Skip the first empty message
+
+                responseMessage.AuthorName.Should().Be(TestAgentName);
+                responseMessage.Text.Should().Be(expectedMessage.Text);
+            }
+        }
+        else
+        {
+            updates.Should().BeEmpty();
+        }
+    }
+}

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

@@ -0,0 +1,71 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Linq;
+using System.Threading.Tasks;
+using Microsoft.Agents.AI.Workflows.Specialized;
+
+namespace Microsoft.Agents.AI.Workflows.UnitTests;
+
+public class HandoffAgentExecutorTests : AIAgentHostingExecutorTestsBase
+{
+    [Theory]
+    [InlineData(null, null)]
+    [InlineData(null, true)]
+    [InlineData(null, false)]
+    [InlineData(true, null)]
+    [InlineData(true, true)]
+    [InlineData(true, false)]
+    [InlineData(false, null)]
+    [InlineData(false, true)]
+    [InlineData(false, false)]
+    public async Task Test_HandoffAgentExecutor_EmitsStreamingUpdatesIFFConfiguredAsync(bool? executorSetting, bool? turnSetting)
+    {
+        // Arrange
+        TestRunContext testContext = new();
+        TestReplayAgent agent = new(TestMessages, TestAgentId, TestAgentName);
+
+        HandoffAgentExecutorOptions options = new("",
+                                                  emitAgentResponseEvents: false,
+                                                  emitAgentResponseUpdateEvents: executorSetting,
+                                                  HandoffToolCallFilteringBehavior.None);
+
+        HandoffAgentExecutor executor = new(agent, options);
+        testContext.ConfigureExecutor(executor);
+
+        // Act
+        HandoffState message = new(new(turnSetting), null, []);
+        await executor.HandleAsync(message, testContext.BindWorkflowContext(executor.Id));
+
+        // Assert
+        bool expectingStreamingUpdates = turnSetting ?? executorSetting ?? false;
+
+        AgentResponseUpdateEvent[] updates = testContext.Events.OfType<AgentResponseUpdateEvent>().ToArray();
+        CheckResponseUpdateEventsAgainstTestMessages(updates, expectingStreamingUpdates, agent.GetDescriptiveId());
+    }
+
+    [Theory]
+    [InlineData(true)]
+    [InlineData(false)]
+    public async Task Test_HandoffAgentExecutor_EmitsResponseIFFConfiguredAsync(bool executorSetting)
+    {
+        // Arrange
+        TestRunContext testContext = new();
+        TestReplayAgent agent = new(TestMessages, TestAgentId, TestAgentName);
+
+        HandoffAgentExecutorOptions options = new("",
+                                                  emitAgentResponseEvents: executorSetting,
+                                                  emitAgentResponseUpdateEvents: false,
+                                                  HandoffToolCallFilteringBehavior.None);
+
+        HandoffAgentExecutor executor = new(agent, options);
+        testContext.ConfigureExecutor(executor);
+
+        // Act
+        HandoffState message = new(new(false), null, []);
+        await executor.HandleAsync(message, testContext.BindWorkflowContext(executor.Id));
+
+        // Assert
+        AgentResponseEvent[] updates = testContext.Events.OfType<AgentResponseEvent>().ToArray();
+        CheckResponseEventsAgainstTestMessages(updates, expectingResponse: executorSetting, agent.GetDescriptiveId());
+    }
+}

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

@@ -206,7 +206,7 @@ internal sealed class TurnTrackingStartExecutor : ChatProtocolExecutor
     }
 }
 
-public class WorkflowHostSmokeTests
+public class WorkflowHostSmokeTests : AIAgentHostingExecutorTestsBase
 {
     private sealed class AlwaysFailsAIAgent(bool failByThrowing) : AIAgent
     {
@@ -731,4 +731,70 @@ public class WorkflowHostSmokeTests
             .Should()
             .BeEmpty();
     }
+
+    private async Task Run_AsAgent_OutgoingMessagesInHistoryAsync(Workflow workflow, bool runAsync)
+    {
+        // Arrange
+        AIAgent workflowAgent = workflow.AsAIAgent();
+
+        // Act
+        AgentSession session = await workflowAgent.CreateSessionAsync();
+        AgentResponse response;
+        if (runAsync)
+        {
+            List<AgentResponseUpdate> updates = [];
+            await foreach (AgentResponseUpdate update in workflowAgent.RunStreamingAsync(session))
+            {
+                // Skip WorkflowEvent updates, which do not get persisted in ChatHistory; we cannot skip
+                // them after because of a deleterious interaction with .ToAgentResponse() due to the
+                // empty initial message (which is created without a MessageId). When running through the
+                // message merger, it does the right thing internally.
+                if (!string.IsNullOrEmpty(update.Text))
+                {
+                    updates.Add(update);
+                }
+            }
+
+            response = updates.ToAgentResponse();
+        }
+        else
+        {
+            response = await workflowAgent.RunAsync(session);
+        }
+
+        // Assert
+        WorkflowSession workflowSession = session.Should().BeOfType<WorkflowSession>().Subject;
+
+        ChatMessage[] responseMessages = response.Messages.Where(message => message.Contents.Any())
+                                                          .ToArray();
+
+        ChatMessage[] sessionMessages = workflowSession.ChatHistoryProvider.GetAllMessages(workflowSession)
+                                                                           .ToArray();
+
+        // Since we never sent an incoming message, the expectation is that there should be nothing in the session
+        // except the response
+        responseMessages.Should().BeEquivalentTo(sessionMessages, options => options.WithStrictOrdering());
+    }
+
+    [Theory]
+    [InlineData(false)]
+    [InlineData(true)]
+    public Task Test_SingleAgent_AsAgent_OutgoingMessagesInHistoryAsync(bool runAsync)
+    {
+        // Arrange
+        TestReplayAgent agent = new(TestMessages, TestAgentId, TestAgentName);
+        Workflow singleAgentWorkflow = new WorkflowBuilder(agent).Build();
+        return this.Run_AsAgent_OutgoingMessagesInHistoryAsync(singleAgentWorkflow, runAsync);
+    }
+
+    [Theory]
+    [InlineData(false)]
+    [InlineData(true)]
+    public Task Test_Handoffs_AsAgent_OutgoingMessagesInHistoryAsync(bool runAsync)
+    {
+        // Arrange
+        TestReplayAgent agent = new(TestMessages, TestAgentId, TestAgentName);
+        Workflow handoffWorkflow = new HandoffsWorkflowBuilder(agent).Build();
+        return this.Run_AsAgent_OutgoingMessagesInHistoryAsync(handoffWorkflow, runAsync);
+    }
 }