[BREAKING] Python: Refactor orchestrations

[TaoChenOSU]

Motivation and Context

Required by #429

Description

This PR extensively refactors and simplifies the orchestrations in Agent Framework Workflows. Details are as follows.

Note: Since this PR refactors group chat, and handoff and magentic depend on group chat, this PR results in large changes.

Group Chat

1. Split the group chat orchestrator executor into dedicated agent-based and function-based, allowing for better maintainability and extensibility. See BaseGroupChatOrchestrator, GroupChatOrchestrator and AgentBasedGroupChatOrchestrator.
2. Consolidate group chat contract while maintaining support for agents and custom executors in the same group. See GroupChatRequestMessage and GroupChatParticipantMessage.
3. Simplify group chat workflow to a star topology, making it easier to maintain and moving responsibilities to executors.
4. Simplify group chat request info mechanism to rely to sub workflows. See AgentApprovalExecutor and AgentRequestInfoExecutor. HIL happens after an agent responds and the agent-HIL loop stops until instructed.
5. Move group chat to a broadcasting model where the orchestrator will broadcast participant responds to other participants to make sure all of them stay synchronized.

Handoff

1. Remove single tier. We should recommend users to explore replacing single tier handoff with group chat.
2. Remove coordinator. Handoff is a decentralized model thus it doesn't require a central node to coordinate communication.
3. Remove support for custom executor. We are not sure how well we support custom executors now. We may add support back in the future.
4. Move handoff handling to executors.
5. Introduce HandoffAgentExecutor which derives from AgentExecutor. This executor handles handoff.
6. Move handoff to a broadcasting model where each agent will broadcast its responds to other agents when they finish.

Magentic

1. Refactors are driven by changes in group chat.

Sequential & Concurrent

1. Simplify request info mechanism to rely to sub workflows. See AgentApprovalExecutor and AgentRequestInfoExecutor. HIL happens after an agent responds and the agent-HIL loop stops until instructed.

Sub-workflow (WorkflowExecutor)

1. Requests can now also propagate to parent as the original event without the need to wrap it in a specialized message. This is needed for GroupChat HIL.

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 refactors Python orchestrations in the Agent Framework, introducing breaking changes to group chat, handoff, magentic, and other orchestration patterns. The refactoring aims to improve maintainability, simplify workflows, and move to a broadcasting model for better participant synchronization.

Key Changes:

• Refactored group chat to split agent-based and function-based orchestrators with a star topology
• Simplified handoff by removing single-tier and coordinator concepts, moving to a decentralized broadcasting model
• Updated magentic orchestration with new event types and progress tracking
• Simplified request info mechanisms across sequential and concurrent workflows
• Enhanced sub-workflow request propagation capabilities

Reviewed changes

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

Show a summary per file

File	Description
group_chat_builder_tool_approval.py	Updated to use new group chat API with with_select_speaker_func, GroupChatState, and new event types
concurrent_builder_tool_approval.py	Updated tool approval sample with modified request info handling and agent setup
sequential_custom_executors.py	Updated custom executor to handle AgentExecutorResponse instead of raw conversation
magentic_human_replan.py	Deleted - functionality moved to other samples
magentic_human_plan_update.py	Deleted - replaced by magentic_human_plan_review.py
magentic_human_plan_review.py	New sample demonstrating plan review with simplified API
magentic_checkpoint.py	Updated for new magentic API with MagenticPlanReviewRequest
magentic_agent_clarification.py	Deleted - functionality consolidated
magentic.py	Significantly updated with new event types and simplified orchestrator handling
handoff_with_code_interpreter_file.py	Updated handoff API from set_coordinator to with_start_agent
handoff_specialist_to_specialist.py	Deleted - functionality replaced by simpler handoff model
handoff_simple.py	Major refactor with new API (with_start_agent, HandoffAgentUserRequest)
handoff_return_to_previous.py	Deleted - return-to-previous pattern removed
handoff_participant_factory.py	Updated to use new handoff API
handoff_autonomous.py	Updated autonomous mode API with per-agent turn limits
group_chat_simple_selector.py	Completely rewritten with new selector function signature
group_chat_philosophical_debate.py	Updated to use with_agent_orchestrator instead of set_manager
group_chat_agent_manager.py	Updated orchestrator agent setup and API
sequential_request_info.py	Updated request info to work after agent execution instead of before
group_chat_request_info.py	Updated for new request info API with AgentExecutorResponse
concurrent_request_info.py	Updated request info handling for concurrent workflows
sub_workflow_basics.py	Minor whitespace fix
magentic_workflow_as_agent.py	Simplified event handling, removed specific event type processing
handoff_workflow_as_agent.py	Major refactor with new handoff API and request handling
group_chat_workflow_as_agent.py	Updated to use with_agent_orchestrator
test_workflow_kwargs.py	Updated tests for new APIs with breaking changes marked as xfail where needed
test_sequential.py	Updated test to handle AgentExecutorResponse in custom executors
test_orchestration_request_info.py	Extensive test updates for new request info architecture
test_magentic.py	Major test refactoring for new magentic implementation
test_handoff.py	Extensive test refactoring for simplified handoff model
test_executor.py	Added comprehensive tests for executor output type introspection
test_agent_run_event_typing.py	Removed tests for nullable event data
_workflow_context.py	Added request_id parameter support for request info tracking
_workflow.py	Updated response type validation with utility function
_runner_context.py	Changed request tracking to use RequestInfoEvent instead of raw data

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework/_workflows
_agent_executor.py	172	24	86%	27, 94, 116, 150, 166–167, 218–219, 221–222, 254–256, 264–266, 276–278, 280, 284, 288, 292–293
_agent_utils.py	3	0	100%
_base_group_chat_orchestrator.py	172	13	92%	25, 135, 301, 316, 350–352, 356, 375, 436, 480–482
_concurrent.py	190	29	84%	53, 62–63, 71–72, 91–92, 97, 102, 127, 132, 137–138, 144, 166, 176, 183, 354, 357, 385, 441, 453, 492, 494–495, 497, 520, 524, 553
_events.py	130	14	89%	59–60, 78, 86, 90, 180–181, 232, 257, 294, 312, 337, 378, 392
_executor.py	151	9	94%	209, 338, 353, 355, 368, 371, 479, 484, 494
_group_chat.py	261	56	78%	55, 172, 333, 340, 366–367, 369–370, 374, 378–379, 385, 390, 406, 433–438, 440, 461, 464–466, 473–476, 478, 483–487, 563–566, 570–571, 576–577, 595, 599, 604, 659, 664, 702, 711, 717, 762, 850, 853, 885, 895
_handoff.py	382	59	84%	58, 110–111, 113, 142–143, 163–173, 175, 177, 179, 184, 283, 331, 356, 382, 390–391, 405, 454–455, 485, 532–534, 722, 729, 734, 821, 824, 833–836, 846, 851, 858, 864–867, 902, 907, 1097, 1110, 1115, 1123, 1141, 1148, 1223
_magentic.py	571	111	80%	43, 48, 70–79, 84, 88–99, 264, 275, 279, 299, 360, 369, 371, 413, 430, 439–440, 442–444, 446, 457, 597–601, 603, 641, 689, 725–727, 729, 737–740, 744–747, 790, 817–820, 911, 917, 923, 962, 1000, 1029, 1046, 1057, 1072–1075, 1111–1112, 1116–1118, 1142, 1163–1164, 1177, 1193, 1215, 1263–1264, 1302–1303, 1342–1343, 1345–1346, 1348, 1416, 1419, 1428, 1431, 1436, 1671–1672, 1674, 1688, 1697, 1714, 1723, 1726
_orchestration_request_info.py	54	0	100%
_orchestration_state.py	28	5	82%	20, 28, 68, 85–86
_orchestrator_helpers.py	22	2	90%	92–93
_runner_context.py	166	9	94%	77–78, 80–81, 83, 377, 397, 494, 498
_sequential.py	110	13	88%	74, 168, 188, 199, 205, 242, 244–245, 247, 270, 274, 291, 298
_workflow.py	249	18	92%	88, 258–260, 262–263, 281, 307, 309, 410, 690, 724, 729, 732, 751–753, 818
_workflow_context.py	177	25	85%	61–62, 70, 74, 88, 164, 189, 307, 426, 440, 469–471, 473, 475–476, 478–479, 488–490, 492–494, 496
_workflow_executor.py	174	44	74%	29, 95, 444, 455, 467–470, 473–475, 478–479, 481, 484–486, 489–493, 497–498, 507, 512, 546, 572–577, 580, 583, 591, 596, 607, 617, 621, 627, 631, 641, 645
TOTAL	16589	2519	84%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
2576	155 💤	0 ❌	0 🔥	59.629s ⏱️

[moonbox3]

After another look, some questions for you.

[moonbox3]

Do we need this elif isinstance(event, GroupChatRequestSentEvent) in this sample? As a dev, I need to know that the GroupChatRequestSentEvent type is applicable to the magentic pattern?

[TaoChenOSU]

We can get rid of it in the sample. But this event is generic to group chat.

[moonbox3]

It feels weird to me that I need to understand that the magentic pattern will produce GroupChat*Events.

[TaoChenOSU]

Magentic is essentially a group chat with a special manager. We need to let users understand that too.

[moonbox3]

This is going to break DevUI - we previously moved away from custom magentic events (we had these in the past) to purely raising AgentRunUpdateEvent which was used throughout workflows.

[TaoChenOSU]

It may not be accurate to create an AgentRunUpdateEvent because the manager is not necessarily an agent.

What is the reason that DevUI can't support custom events?

[moonbox3]

because the manager is not necessarily an agent.

What do you mean it's not an agent? In a different comment below you mentioned we only support agents?

[TaoChenOSU]

That was the handoff orchestration

[moonbox3]

As I was reading through the docs, I was thinking: why can't this public API and the with_agent_orchestrator be the same? For example, some name that either says "give me some func to choose the next speaker" or "give me an agent to choose the next speaker." That way there aren't multiple APIs doing similar things - only one API to worry about.