Skip to content

Commit 56b8307

Browse files
authored
Fix multi-step handoff message ordering in non-streaming RunAsync
HandoffAgentExecutor synthesizes a 'Transferred.' tool-result update for each handoff function call. That update was created without setting ResponseId, so MessageMerger routed it to the global dangling bucket and flushed all such tool results at the very end of the merged AgentResponse, breaking per-step grouping for multi-step handoffs (see #4544). Streaming output already preserved order because updates are yielded directly without going through the merger. Fix: stamp the synthesized update with the same ResponseId as the preceding agent stream updates so it groups with the agent's other messages in MessageMerger. Also adds a regression test that drives the real workflow through WorkflowHostAgent.RunAsync over a 3-agent handoff chain and asserts the per-step message ordering of the merged response.
1 parent 4e7a46b commit 56b8307

2 files changed

Lines changed: 98 additions & 0 deletions

File tree

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

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -433,6 +433,18 @@ bool CollectHandoffRequestsFilter(FunctionCallContent candidateHandoffRequest)
433433
FunctionCallContent handoffRequest = candidateRequests[candidateRequests.Count - 1];
434434
requestedHandoff = handoffRequest.Name;
435435

436+
// Stamp the synthetic "Transferred." tool-result update with the same
437+
// ResponseId as the agent's preceding updates so it groups with the
438+
// rest of this agent's step in MessageMerger (and therefore in
439+
// RunAsync's merged AgentResponse and in chat history). Without this,
440+
// the synthetic update goes to MessageMerger's null-ResponseId
441+
// "dangling" bucket and surfaces after every keyed response, which
442+
// re-orders multi-step handoff transcripts versus streaming output
443+
// (issue #4544).
444+
string? syntheticResponseId = updates
445+
.Select(u => u.ResponseId)
446+
.LastOrDefault(id => id is not null);
447+
436448
await AddUpdateAsync(
437449
new AgentResponseUpdate
438450
{
@@ -441,6 +453,7 @@ await AddUpdateAsync(
441453
Contents = [CreateHandoffResult(handoffRequest.CallId)],
442454
CreatedAt = DateTimeOffset.UtcNow,
443455
MessageId = Guid.NewGuid().ToString("N"),
456+
ResponseId = syntheticResponseId,
444457
Role = ChatRole.Tool,
445458
},
446459
cancellationToken

‎dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/HandoffOrchestrationTests.cs‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -304,6 +304,91 @@ public async Task Handoffs_TwoTransfers_HandoffTargetsDoNotReceiveHandoffFunctio
304304
Assert.DoesNotContain(capturedThirdAgentMessages, m => m.Role == ChatRole.Tool && m.Contents.Any(c => c is FunctionResultContent));
305305
}
306306

307+
[Fact]
308+
public async Task Handoffs_MultipleTransfers_MergedMessagesPreserveStepOrderAsync()
309+
{
310+
// Regression test for https://github.com/microsoft/agent-framework/issues/4544
311+
//
312+
// Scenario: a multi-step handoff (A -> B -> C) is run through a workflow
313+
// exposed as an AIAgent. When invoked via the non-streaming RunAsync
314+
// entry-point, the merged AgentResponse.Messages must keep each step's
315+
// messages contiguous — in particular, the "Transferred." tool result
316+
// synthesized for a handoff function call must appear immediately after
317+
// the function call that triggered it, before any messages from later
318+
// steps. Streaming output already preserves this order; the bug
319+
// manifested only after merging, where the synthesized tool results were
320+
// bunched at the end of the response, far from their originating function
321+
// calls (and consequently corrupted ChatHistory order).
322+
//
323+
// Each underlying agent response sets a real ResponseId — that is what
324+
// causes MessageMerger to group its updates under that key. If the
325+
// synthesized Tool update is emitted without that ResponseId, the merger
326+
// routes it to the global "dangling" bucket and flushes it last,
327+
// breaking per-step grouping.
328+
329+
var initialAgent = new ChatClientAgent(new MockChatClient((messages, options) =>
330+
{
331+
string? transferFuncName = options?.Tools?.FirstOrDefault(t => t.Name.StartsWith("handoff_to_", StringComparison.Ordinal))?.Name;
332+
Assert.NotNull(transferFuncName);
333+
return new(new ChatMessage(ChatRole.Assistant, [new TextContent("Routing to second agent"), new FunctionCallContent("call1", transferFuncName)]) { MessageId = "msg-initial" }) { ResponseId = "resp-initial" };
334+
}), name: "initialAgent");
335+
336+
var secondAgent = new ChatClientAgent(new MockChatClient((messages, options) =>
337+
{
338+
string? transferFuncName = options?.Tools?.FirstOrDefault(t => t.Name.StartsWith("handoff_to_", StringComparison.Ordinal))?.Name;
339+
Assert.NotNull(transferFuncName);
340+
return new(new ChatMessage(ChatRole.Assistant, [new TextContent("Routing to third agent"), new FunctionCallContent("call2", transferFuncName)]) { MessageId = "msg-second" }) { ResponseId = "resp-second" };
341+
}), name: "secondAgent", description: "The second agent");
342+
343+
var thirdAgent = new ChatClientAgent(new MockChatClient((messages, options) =>
344+
new(new ChatMessage(ChatRole.Assistant, "Hello from agent3") { MessageId = "msg-third" }) { ResponseId = "resp-third" }),
345+
name: "thirdAgent",
346+
description: "The third / final agent");
347+
348+
var workflow =
349+
AgentWorkflowBuilder.CreateHandoffBuilderWith(initialAgent)
350+
.WithHandoff(initialAgent, secondAgent)
351+
.WithHandoff(secondAgent, thirdAgent)
352+
.Build();
353+
354+
AIAgent hostAgent = workflow.AsAIAgent(name: "HandoffWorkflow");
355+
356+
AgentResponse response = await hostAgent.RunAsync("abc");
357+
358+
List<ChatMessage> result = response.Messages.ToList();
359+
360+
// Expected merged sequence keeps each step contiguous:
361+
// [0] Assistant (initialAgent): text + FunctionCall(call1)
362+
// [1] Tool (initialAgent): FunctionResult(call1, "Transferred.")
363+
// [2] Assistant (secondAgent): text + FunctionCall(call2)
364+
// [3] Tool (secondAgent): FunctionResult(call2, "Transferred.")
365+
// [4] Assistant (thirdAgent): "Hello from agent3"
366+
//
367+
// The bug surfaced as the two Tool messages being moved to the end of the
368+
// list — after thirdAgent's reply — which broke chat-history ordering.
369+
Assert.Equal(5, result.Count);
370+
371+
Assert.Equal(ChatRole.Assistant, result[0].Role);
372+
Assert.Contains("initialAgent", result[0].AuthorName);
373+
Assert.Contains(result[0].Contents, c => c is FunctionCallContent fcc && fcc.CallId == "call1");
374+
375+
Assert.Equal(ChatRole.Tool, result[1].Role);
376+
Assert.Contains("initialAgent", result[1].AuthorName);
377+
Assert.Contains(result[1].Contents, c => c is FunctionResultContent frc && frc.CallId == "call1");
378+
379+
Assert.Equal(ChatRole.Assistant, result[2].Role);
380+
Assert.Contains("secondAgent", result[2].AuthorName);
381+
Assert.Contains(result[2].Contents, c => c is FunctionCallContent fcc && fcc.CallId == "call2");
382+
383+
Assert.Equal(ChatRole.Tool, result[3].Role);
384+
Assert.Contains("secondAgent", result[3].AuthorName);
385+
Assert.Contains(result[3].Contents, c => c is FunctionResultContent frc && frc.CallId == "call2");
386+
387+
Assert.Equal(ChatRole.Assistant, result[4].Role);
388+
Assert.Contains("thirdAgent", result[4].AuthorName);
389+
Assert.Equal("Hello from agent3", result[4].Text);
390+
}
391+
307392
[Fact]
308393
public async Task Handoffs_FilteringNone_HandoffTargetReceivesAllMessagesIncludingToolCallsAsync()
309394
{

0 commit comments

Comments
 (0)