Python: Support an autonomous handoff flow

[moonbox3]

Motivation and Context

Right now the Handoff pattern requires a HITL as it passes back control to a human when no handoff is triggered. Per feedback, we should also support an autonomous mode where a sub-agent is able to iterate until done, and then handoff to the next agent.

Description

Adding ability to support an interaction mode of either "autonomous" or "human_in_the_loop" (this is the default).

• Add a new sample
• Add unit tests for coverage
• Addresses Python: Specialist-to-Specialist Handoff Interrupted by User Input Fallback on stop #2264

Devs can now specify the autonomous mode:

workflow = (
    HandoffBuilder(
        name="autonomous_iteration_handoff",
        participants=[coordinator, research_agent, summary_agent],
    )
    .set_coordinator(coordinator)
    .add_handoff(coordinator, [research_agent, summary_agent])
    .add_handoff(research_agent, coordinator)  # Research can hand back to coordinator
    .add_handoff(summary_agent, coordinator)
    .with_interaction_mode("autonomous", autonomous_turn_limit=15) # Limit total turns to prevent runaway 
    .with_termination_condition(
        # Terminate after coordinator provides 5 assistant responses
        lambda conv: sum(1 for msg in conv if msg.author_name == "coordinator" and msg.role.value == "assistant")
        >= 5
    )
    .build()
)

There are some public API args (like with_autonomous_turn_limit) to act as guards so that we don't have runaway agents

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 adds autonomous interaction mode to the handoff workflow, allowing agents to iterate on tasks without returning to the user after each response. The key change enables specialists to perform long-running work (research, analysis, coding) until they explicitly invoke a handoff tool or reach a configured turn limit.

Key Changes:

• Added with_interaction_mode() builder method to support "autonomous" and "human_in_loop" modes
• Added with_autonomous_turn_limit() to cap iterations and prevent runaway agents (default: 50)
• Modified handoff coordinator to route responses back to the same agent in autonomous mode instead of requesting user input
• Turn counter resets on handoffs and new user input to track continuous autonomous execution

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
python/samples/getting_started/workflows/orchestration/handoff_autonomous.py	New sample demonstrating autonomous mode with research agent that iterates multiple times before handing back to coordinator
python/samples/getting_started/workflows/README.md	Added documentation entry for the new autonomous handoff sample
python/packages/core/tests/workflow/test_handoff.py	Added comprehensive unit tests covering autonomous mode behavior, turn limits, and routing without user input
python/packages/core/agent_framework/_workflows/_handoff.py	Core implementation of autonomous interaction mode in HandoffCoordinator and HandoffBuilder
python/samples/getting_started/workflows/agents/group_chat_workflow_as_agent.py	Unrelated refactoring: updated to use set_manager() instead of deprecated set_prompt_based_manager()
python/samples/autogen-migration/orchestrations/02_selector_group_chat.py	Unrelated refactoring: updated to use set_manager() instead of deprecated set_prompt_based_manager()

---

You can also share your feedback on Copilot code review for a chance to win a $100 gift card. Take the survey.

[MrAssel]

Hi, will this be implemented for C# as well? I have a similar issue using specialized autonomous agents in my project where handoff defaults to user input.

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework/_workflows
_handoff.py	513	135	73%	58, 71–73, 80–81, 83, 85, 159, 167–172, 175–176, 190, 199, 218–221, 230–232, 243, 246, 256–267, 269, 275, 281, 316, 362, 455, 464–469, 471–472, 483, 500, 518, 533, 545, 573, 585–587, 593, 617–619, 622–625, 627–629, 872, 878, 882, 888, 892, 904, 954, 957, 1045, 1050, 1060, 1066–1069, 1077–1078, 1082–1084, 1086–1096, 1098–1099, 1101, 1103, 1118–1119, 1122–1123, 1126, 1146–1152, 1154, 1160, 1194–1195, 1248–1249, 1334, 1495, 1503, 1575, 1587, 1591, 1596–1597
TOTAL	16076	2507	84%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
2303	130 💤	0 ❌	0 🔥	56.376s ⏱️

[moonbox3]

Hi, will this be implemented for C# as well? I have a similar issue using specialized autonomous agents in my project where handoff defaults to user input.

Thanks for the feedback, @MrAssel. I will file an issue to track it for .NET.