Python: Fix underlying tool choice bug and all for return to previous Handoff subagent

[moonbox3]

Motivation and Context

This PR fixes a bug in the HandoffBuilder where specialist-to-specialist handoffs were failing due to tool_choice="auto" defaults overriding agent-level configuration. The root cause was that BaseChatClient.get_response(), get_streaming_response(), and _merge_chat_options() all defaulted tool_choice to "auto", which prevented agents from respecting their configured tool choice settings. When agents returned finish_reason="stop" instead of invoking required handoff tools, control flow broke and caused "dropped target mismatch" errors.

The fix changes these defaults from "auto" to None, allowing agent-level configuration to persist through the merge logic. This preserves backward compatibility while enabling proper handoff tool enforcement.

Additionally, this PR introduces a new enable_return_to_previous() method on HandoffBuilder that allows specialists to maintain control across multiple user turns without routing back through the coordinator. When enabled, user input routes directly back to whichever agent most recently responded, which enables more efficient multi-turn interactions with specialists. The PR also adds logging at key handoff routing decision points to improve observability, and includes test coverage verifying both tool_choice preservation and the new return-to-previous routing behavior.

Description

• Closes Python: Handoff Builder (specialist-to-specialist) — Agent loses control on finish_reason="stop" leading to dropped target mismatch messages #1972

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

[Copilot]

Pull Request Overview

This PR introduces a "return-to-previous" routing feature for handoff workflows. This feature allows user input to route directly back to the current specialist handling the conversation, rather than always going through the coordinator for re-evaluation. This is useful when a specialist needs multiple turns with the user to gather information or resolve issues.

Key changes:

• Added enable_return_to_previous() method to HandoffBuilder API
• Modified handoff coordinator to track the current agent and route accordingly
• Added comprehensive test coverage for the new feature
• Created an interactive sample demonstrating the feature

Reviewed Changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
python/samples/getting_started/workflows/orchestration/handoff_return_to_previous.py	New sample demonstrating return-to-previous routing with interactive user input
python/samples/getting_started/workflows/README.md	Added entry for the new handoff return-to-previous sample
python/samples/README.md	Added entry for the new sample in the main samples index
python/packages/core/tests/workflow/test_handoff.py	Added comprehensive tests for return-to-previous feature and tool_choice preservation
python/packages/core/agent_framework/_workflows/_handoff.py	Core implementation of return-to-previous routing with state tracking and serialization
python/packages/core/agent_framework/_clients.py	Changed tool_choice default from "auto" to None in _merge_chat_options

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework
_clients.py	106	14	86%	266, 381, 427–430, 474, 666, 670, 673–674, 713, 801, 803
_tools.py	597	71	88%	225, 271, 322, 324, 487, 519–520, 620, 622, 639, 645, 650, 652, 659, 689, 738–740, 778, 801, 803–812, 816–817, 822–823, 827, 855, 897, 906, 908, 911, 917, 1284–1288, 1388, 1457, 1558, 1564, 1605–1606, 1720, 1722–1725, 1733, 1738, 1740, 1777–1778, 1806–1808, 1812, 1850, 1907–1908, 1915–1916
packages/core/agent_framework/_workflows
_handoff.py	489	141	71%	61–63, 70–71, 73, 75, 149, 157–162, 165–166, 180, 189, 208–211, 220–222, 233, 236, 246–257, 259, 265, 271, 301, 315–317, 355, 367–369, 426, 435–440, 442–443, 454, 471, 511, 513–515, 527, 555, 567–569, 575, 599–601, 604–607, 609–611, 845, 851, 855, 861, 865, 877, 925, 928, 1016, 1021, 1031, 1037–1040, 1048–1049, 1053–1055, 1057–1067, 1069–1070, 1072, 1074, 1089–1090, 1093–1094, 1097, 1117–1123, 1125, 1131, 1165–1166, 1219–1220, 1402, 1410, 1478, 1491, 1495, 1500–1501
TOTAL	13066	1929	85%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
1745	107 💤	0 ❌	0 🔥	34.785s ⏱️

[droideronline]

This is great, the fix makes sense and the new enable_return_to_previous() behavior looks solid.

That said, I’m wondering if this is the optimal approach for handling handoffs. Right now, when an agent calls the handoff tool, nothing actually happens immediately — the tool call just gets added to the conversation history. Then, after the agent finishes and returns finish_reason="stop", we parse the response and detect handoff intent using regex.

Would it make more sense to trigger the handoff flow as soon as the handoff tool is invoked, rather than waiting until after the agent’s full response cycle? In my case, I’ve noticed the agent keeps calling the handoff tool repeatedly because it thinks the call isn’t being executed. I can work around this by instructing it to “call handoff only once and then stop,” but that feels like a fragile workaround.

Overall, I’m not a huge fan of this delayed-execution pattern — I think direct control transfer at tool invocation time might simplify both agent logic and coordination.

[moonbox3]

This is great, the fix makes sense and the new enable_return_to_previous() behavior looks solid.

That said, I’m wondering if this is the optimal approach for handling handoffs. Right now, when an agent calls the handoff tool, nothing actually happens immediately — the tool call just gets added to the conversation history. Then, after the agent finishes and returns finish_reason="stop", we parse the response and detect handoff intent using regex.

Would it make more sense to trigger the handoff flow as soon as the handoff tool is invoked, rather than waiting until after the agent’s full response cycle? In my case, I’ve noticed the agent keeps calling the handoff tool repeatedly because it thinks the call isn’t being executed. I can work around this by instructing it to “call handoff only once and then stop,” but that feels like a fragile workaround.

Overall, I’m not a huge fan of this delayed-execution pattern — I think direct control transfer at tool invocation time might simplify both agent logic and coordination.

Valid feedback, thanks @droideronline. I'm going to move this PR to a draft so I can test out a few improvements. Will updated as soon as possible.

[moonbox3]

@droideronline I've been trying to repo some issues that you brought up, and I am having a hard time doing so. What model are you using?

I am seeing something like this:

1. Agent generates response with handoff tool call
2. Stream completes
3. We process tool calls from completed response
4. Middleware intercepts: "Handoff tool detected: handoff_to_technical_support" (as an example)
5. Middleware sets context.terminate = True
6. Coordinator finds FunctionCallContent in message
7. Conversation is cleaned (tool calls removed)
8. Cleaned conversation passed to next agent

I'm not sure how to repro the issues you're seeing. Any tips will help, thank you.

[markwallace-microsoft]

@moonbox3 If this is a change in behaviour and code break Ignite demoes and samples we should consider holding until after Ignite.

[droideronline]

@droideronline I've been trying to repo some issues that you brought up, and I am having a hard time doing so. What model are you using?

I am seeing something like this:

1. Agent generates response with handoff tool call
2. Stream completes
3. We process tool calls from completed response
4. Middleware intercepts: "Handoff tool detected: handoff_to_technical_support" (as an example)
5. Middleware sets context.terminate = True
6. Coordinator finds FunctionCallContent in message
7. Conversation is cleaned (tool calls removed)
8. Cleaned conversation passed to next agent

I'm not sure how to repro the issues you're seeing. Any tips will help, thank you.

Deterministically, this behavior can be reproduced by setting tool_choice="required", which ensures the finish_reason will always be "tool_calls" instead of "stop". In that setup, the agent will consistently attempt to invoke the handoff tool, making the delayed-execution behavior easy to observe.

Non-deterministically, though, this can still occur even without tool_choice="required", especially with more capable models (like the GPT-5 family) that expect the tool call to be acknowledged with an actual tool response. If the response isn’t provided, the model may retry the tool invocation because it assumes the call wasn’t executed. I’ve noticed this happens occasionally — likely influenced by the way the prompt is written.

[moonbox3]

@droideronline thanks for the additional feedback. As I mentioned: after investigation with diagnostic logging, I can confirm that the current implementation doesn't exhibit the redundant tool call behavior you've described. The key is that middleware intercepts tool execution after the model has completed its response and streaming has finished -- not during generation. At that point, the middleware sets context.terminate = True to prevent execution, and then clean_conversation_for_handoff() intentionally removes all FunctionCallContent before passing the conversation to the next agent. Since models are stateless and only see the cleaned conversation (without any tool calls), there's no mechanism for them to "retry" or generate redundant calls -- they have no knowledge that a tool call ever occurred. Even with tool_choice="required", the model generates the tool call once, middleware intercepts it once, and the handoff completes cleanly. Our diagnostics across multiple scenarios consistently show exactly one middleware invocation per handoff with zero tool calls appearing in subsequent turns. The delayed-execution timing is by design and working correctly, it doesn't create the problem you've anticipated because the cleaning step breaks any potential feedback loop before the next agent sees the conversation.

[droideronline]

@droideronline thanks for the additional feedback. As I mentioned: after investigation with diagnostic logging, I can confirm that the current implementation doesn't exhibit the redundant tool call behavior you've described. The key is that middleware intercepts tool execution after the model has completed its response and streaming has finished -- not during generation. At that point, the middleware sets context.terminate = True to prevent execution, and then clean_conversation_for_handoff() intentionally removes all FunctionCallContent before passing the conversation to the next agent. Since models are stateless and only see the cleaned conversation (without any tool calls), there's no mechanism for them to "retry" or generate redundant calls -- they have no knowledge that a tool call ever occurred. Even with tool_choice="required", the model generates the tool call once, middleware intercepts it once, and the handoff completes cleanly. Our diagnostics across multiple scenarios consistently show exactly one middleware invocation per handoff with zero tool calls appearing in subsequent turns. The delayed-execution timing is by design and working correctly, it doesn't create the problem you've anticipated because the cleaning step breaks any potential feedback loop before the next agent sees the conversation.

Perfect, thanks for the clarification.

[moonbox3]

@moonbox3 If this is a change in behaviour and code break Ignite demoes and samples we should consider holding until after Ignite.

@markwallace-microsoft

• For agents without explicit tool_choice config, the behavior remains the same. When tools are present and tool_choice is None, the function invocation wrapper now sets it to auto. That preserves the same behavior as before the change.
• For agents with explicit tool_choice config, this is the bug fix. Previous to the fix, even if an agent specified tool_choice="required', the merge functions would override it back to auto. Now, with this fix, the config is respected.
• In our Handoff pattern, where we require tool_choice="required" to force the agent to invoke a handoff, the current code (no bug fix) is silently breaking this by resetting the tool_choice="auto" which is causing the agent to sometimes finish the call instead of invoking the tool.