[BREAKING] Python: Refactor orchestrations #3023

TaoChenOSU · 2025-12-23T02:13:43Z

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

Split the group chat orchestrator executor into dedicated agent-based and function-based, allowing for better maintainability and extensibility. See BaseGroupChatOrchestrator, GroupChatOrchestrator and AgentBasedGroupChatOrchestrator.
Consolidate group chat contract while maintaining support for agents and custom executors in the same group. See GroupChatRequestMessage and GroupChatParticipantMessage.
Simplify group chat workflow to a star topology, making it easier to maintain and moving responsibilities to executors.
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.
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

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

Magentic

Refactors are driven by changes in group chat.

Sequential & Concurrent

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`)

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.

python/packages/core/agent_framework/_workflows/_group_chat.py

python/packages/core/agent_framework/_workflows/_orchestration_request_info_old.py

python/packages/core/agent_framework/_workflows/__init__.py

python/packages/core/agent_framework/_workflows/_group_chat.py

python/packages/core/agent_framework/_workflows/_handoff.py

python/samples/getting_started/workflows/orchestration/group_chat_philosophical_debate.py

python/samples/getting_started/workflows/orchestration/handoff_return_to_previous.py

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 · 2026-01-07T19:51:56Z

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework/_workflows
_agent_executor.py	171	24	85%	26, 93, 115, 149, 165–166, 217–218, 220–221, 253–255, 263–265, 275–277, 279, 283, 287, 291–292
_base_group_chat_orchestrator.py	172	13	92%	25, 135, 301, 316, 350–352, 356, 375, 436, 480–482
_concurrent.py	189	29	84%	52, 61–62, 70–71, 90–91, 96, 101, 126, 131, 136–137, 143, 165, 175, 182, 353, 356, 384, 440, 452, 491, 493–494, 496, 519, 523, 552
_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	260	56	78%	54, 171, 332, 339, 365–366, 368–369, 373, 377–378, 384, 389, 405, 432–437, 439, 460, 463–465, 472–475, 477, 482–486, 562–565, 569–570, 575–576, 594, 598, 603, 658, 663, 701, 710, 716, 761, 849, 852, 884, 894
_handoff.py	379	59	84%	57, 109–110, 112, 141–142, 162–172, 174, 176, 178, 183, 282, 330, 355, 381, 389–390, 404, 453–454, 484, 531–533, 726, 733, 738, 825, 828, 837–840, 850, 855, 862, 868–871, 905, 910, 1100, 1113, 1118, 1126, 1144, 1151, 1225
_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	53	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	109	13	88%	73, 167, 187, 198, 204, 241, 243–244, 246, 269, 273, 290, 297
_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	15904	2325	85%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
2543	151 💤	0 ❌	0 🔥	56.753s ⏱️

moonbox3

After another look, some questions for you.

moonbox3 · 2026-01-08T03:08:02Z

python/samples/getting_started/workflows/orchestration/handoff_autonomous.py

+        .add_handoff(summary_agent, [coordinator])
+        .with_autonomous_mode(
+            turn_limits={
+                coordinator.display_name: 5,


It's not clear to me what an agent's display_name has to do with the turn limit?

Users can set different turn limits for different agents. I will add a comment. Or we can accept only a single limit.

moonbox3 · 2026-01-08T03:09:17Z

python/samples/getting_started/workflows/orchestration/handoff_autonomous.py

            participants=[coordinator, research_agent, summary_agent],
        )
-        .set_coordinator(coordinator)
+        .with_start_agent(coordinator)


Aren't we planning to allow the use of executors in the future with these patterns (not only agents as we do today)? .with_start_agent kind of locks us into agent-only use, right?

I don' think we should support executors because that makes implicitly requirements on the executor. This is true for other orchestrations too but those are more manageable. Handoff has features like autonomous mode that is difficult to enforce on custom executors.

moonbox3 · 2026-01-08T03:10:51Z

python/samples/getting_started/workflows/orchestration/magentic.py

+            # Please refer to `with_plan_review` for proper human interaction during planning phases.
+            await asyncio.get_event_loop().run_in_executor(None, input, "Press Enter to continue...")
+
+        elif isinstance(event, GroupChatRequestSentEvent):


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?

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

moonbox3 · 2026-01-08T03:11:45Z

python/samples/getting_started/workflows/orchestration/magentic.py

+                last_message_id = message_id
+            print(event.data, end="", flush=True)
+
+        elif isinstance(event, MagenticOrchestratorEvent):


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.

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 · 2026-01-08T03:12:48Z

python/samples/getting_started/workflows/orchestration/magentic.py

+        elif isinstance(event, WorkflowOutputEvent):
+            output_event = event
+
+    if not output_event:


It feels like we should look at somehow always producing a "WorkflowOutputEvent" to avoid the need to have to check if the event is present or not (idle, error, complete, etc).

I think we will always produce a workflow output event (unless there are bugs, which we should fix). The check here is for type checking purposes because the type of output_event is WorkflowOutputEvent | None.

moonbox3 · 2026-01-08T03:13:29Z

python/samples/getting_started/workflows/orchestration/group_chat_agent_manager.py

-        name="Coordinator",
-        description="Coordinates multi-agent collaboration by selecting speakers",
-        instructions="""
+ORCHESTRATOR_AGENT_INSTRUCTIONS = """


These instructions aren't super verbose. Why can't we have them inline below?

I am open to it, but this makes the sample look cleaner.

moonbox3 · 2026-01-08T03:15:58Z

python/samples/getting_started/workflows/orchestration/magentic_human_plan_review.py

+automatically replanning.
+
+Key concepts:
+- with_human_input_on_stall(): Enables human intervention when workflow detects stalls


I don't see us configuring the builder with this with_human_input_on_stall(). It would be good to have this in a sample (which looks to now be deleted).

I will update the comment.

with_human_input_on_stall can be achieved via with_plan_review. They serve the same purpose. When a plan review is requested, it contains a flag indicating if the manager is stalled.

moonbox3 · 2026-01-08T03:21:59Z

python/packages/core/agent_framework/_workflows/_handoff.py

+        self._full_conversation.extend(self._cache)
+
+        # Check termination condition before running the agent
+        if await self._check_terminate_and_yield(cast(WorkflowContext[Never, list[ChatMessage]], ctx)):


Is it intended that termination conditions can short-circuit immediately on initial input? This could cause surprising behavior where a workflow terminates before any agent has spoken if the initial message triggers the condition.

moonbox3 · 2026-01-08T03:23:46Z

python/packages/core/agent_framework/_workflows/_handoff.py

+        new_tools: list[AIFunction[Any, Any]] = []
+        for target in targets:
+            tool = self._create_handoff_tool(target.target_id, target.description)
+            if tool.name in existing_names:


To make sure I understand: if tools are added dynamically at runtime, could there still be conflicts?

TaoChenOSU added 8 commits December 18, 2025 15:08

Group chat refactoring Part 1; Next: HIL and handoff

dbe5ff1

Add agent approval flow; next samples

16ae7fe

WIP: samples

fc0268c

Merge branch 'main' into local-branch-python-group-chat-refactoring

e46ccf9

WIP: HIL samples

3d5b831

Group chat HIL working; next: handoff

5901421

Fix group chat tool approval sample

c9e7286

WIP: refactor handoff; next handoff handling

aa5edbf

TaoChenOSU self-assigned this Dec 23, 2025

TaoChenOSU added this to Agent Framework Dec 23, 2025

TaoChenOSU added python agent orchestration Issues related to agent orchestration workflows Related to Workflows in agent-framework labels Dec 23, 2025

github-actions bot changed the title ~~Refactor orchestrations~~ Python: Refactor orchestrations Dec 23, 2025

TaoChenOSU changed the title ~~Python: Refactor orchestrations~~ [BREAKING] Python: Refactor orchestrations Dec 23, 2025

eavanvalkenburg reviewed Dec 23, 2025

View reviewed changes

python/packages/core/agent_framework/_workflows/_group_chat.py Outdated Show resolved Hide resolved

python/packages/core/agent_framework/_workflows/_group_chat.py Outdated Show resolved Hide resolved

TaoChenOSU added 6 commits December 23, 2025 21:22

Handoff done; next handoff samples and concurrent and sequential

c6e5121

Handoff samples, concurrent, and sequential done; next Magentic

60fd7f0

WIP: magentic; next test with samples + HIL

b555421

Magentic Working; next fix all samples and tests

b808c18

Fix handoff samples; next tests

36d908c

WIP: fixing tests; some orchestration as agent samples are failing

c4e7c66

moonbox3 reviewed Jan 5, 2026

View reviewed changes

TaoChenOSU added 5 commits January 5, 2026 12:20

Group chat unit tests done

d9d371e

Handoff unit tests done

b2d918e

Remove old orchestration_request_info and fix related tests

9b6a273

Magentic unit tests done

a362161

Fix samples

22d56ca

TaoChenOSU marked this pull request as ready for review January 7, 2026 18:58

Copilot AI review requested due to automatic review settings January 7, 2026 18:58

Copilot started reviewing on behalf of TaoChenOSU January 7, 2026 18:59 View session

Copilot AI reviewed Jan 7, 2026

View reviewed changes

TaoChenOSU added 3 commits January 7, 2026 11:03

Merge branch 'main' into local-branch-python-group-chat-refactoring

c003804

Fix test

2d5110c

Fix test 2

8070a6d

TaoChenOSU added 3 commits January 7, 2026 12:20

mypy

4540771

Address comments

b018eab

Update readme

11678e5

markwallace-microsoft added the documentation Improvements or additions to documentation label Jan 7, 2026

moonbox3 reviewed Jan 8, 2026

View reviewed changes

[BREAKING] Python: Refactor orchestrations #3023

Are you sure you want to change the base?

[BREAKING] Python: Refactor orchestrations #3023

Conversation

TaoChenOSU commented Dec 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

Description

Group Chat

Handoff

Magentic

Sequential & Concurrent

Sub-workflow (WorkflowExecutor)

Contribution Checklist

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Key Changes:

Reviewed changes

Uh oh!

markwallace-microsoft commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Python Unit Test Overview

Uh oh!

moonbox3 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

TaoChenOSU commented Dec 23, 2025 •

edited

Loading

Sub-workflow (`WorkflowExecutor`)

markwallace-microsoft commented Jan 7, 2026 •

edited

Loading