[BREAKING] Python: Standardize orchestration outputs as list of ChatMessage. Allow agent as group chat manager.

[moonbox3]

Motivation and Context

Currently there is a divergence in the types returned from some orchestrations - for example, group chat/magentic return a ChatMessage versus others (sequential, concurrent, handoff) return a list[ChatMessage]. To standardize, also to what an agent can return, we're adjusting the output for group chat/magentic to be a list[ChatMessage].

Additionally, for a group chat, when configuring a manager, allow for the use of an Agent or an Executor. The underlying group chat architecture was refactored to allow for the agent / executor manager to actually be a node in the group chat graph in place of the previous PromptManager class.

Caution

This is a breaking change. Will hold this PR until after Ignite.

Description

Closes: #2272, #2228, #2350

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.

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework/_workflows
_group_chat.py	548	93	83%	112, 144, 155, 379–389, 408, 435–436, 441, 503, 517, 524, 528–530, 533, 592–593, 649–658, 667–668, 671, 709, 723–725, 729, 731–735, 740, 742, 748, 752–754, 757, 772, 795, 804, 969, 985, 989, 1037, 1085, 1102, 1110, 1127, 1132–1134, 1339, 1345, 1496, 1510, 1577–1578, 1580–1581, 1583, 1585, 1587–1588, 1753, 1825–1828, 1838, 1849, 1858–1860
_handoff.py	477	136	71%	55, 68–70, 77–78, 80, 82, 156, 164–169, 172–173, 187, 196, 215–218, 227–229, 240, 243, 253–264, 266, 272, 278, 308, 353, 364–366, 422, 431–436, 438–439, 450, 467, 485, 509, 537, 549–551, 557, 581–583, 586–589, 591–593, 827, 833, 837, 843, 847, 859, 907, 910, 998, 1003, 1013, 1019–1022, 1030–1031, 1035–1037, 1039–1049, 1051–1052, 1054, 1056, 1071–1072, 1075–1076, 1079, 1099–1105, 1107, 1113, 1147–1148, 1201–1202, 1384, 1392, 1461, 1474, 1478, 1483–1484
_magentic.py	899	257	71%	48, 53, 75–84, 89, 93–104, 328, 333, 350, 352, 367, 375–384, 462, 466, 480, 486, 501, 581, 594, 611, 620–621, 623–625, 627, 638, 780–783, 786–790, 792–794, 801, 840, 887, 923–925, 927, 935–938, 942–945, 1009, 1067–1068, 1085, 1087–1088, 1096, 1132, 1141–1143, 1163, 1216, 1236, 1239, 1268, 1271, 1279–1283, 1289, 1317–1319, 1321, 1323, 1331–1334, 1336, 1340–1341, 1344–1347, 1349–1350, 1356–1358, 1361–1362, 1367–1368, 1376, 1384, 1399, 1411, 1423–1426, 1455–1456, 1461–1463, 1494, 1520, 1537, 1553, 1572, 1639, 1646, 1649, 1651–1652, 1655–1656, 1660, 1663, 1684, 1719–1720, 1722, 1726–1728, 1743, 1754, 1764, 1808, 1813–1814, 2140–2141, 2145, 2160, 2165, 2168, 2222, 2233, 2244–2246, 2259–2260, 2265, 2276–2278, 2289–2291, 2303–2310, 2312–2313, 2321, 2329–2330, 2332–2334, 2336–2339, 2343–2351, 2355–2356, 2359–2363, 2365–2366, 2368–2371, 2373–2376, 2378–2380, 2382–2383, 2385–2387, 2402–2405, 2416–2419, 2431–2434, 2438
_orchestrator_helpers.py	50	5	90%	96–97, 127, 129, 195
TOTAL	15607	2383	84%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
2225	130 💤	0 ❌	0 🔥	54.542s ⏱️

[Copilot]

Pull Request Overview

This PR standardizes orchestration outputs in the Python agent framework to consistently return list[ChatMessage] instead of a single ChatMessage. Previously, group chat and magentic orchestrations returned a single message while other orchestrations (sequential, concurrent, handoff) returned lists, creating inconsistency. The PR also adds the ability to configure ChatOptions for the group chat prompt-based manager, allowing fine-tuned control over LLM parameters like temperature and seed for reproducible manager decisions.

Key changes:

• Group chat and magentic orchestrations now yield the full conversation history as list[ChatMessage] instead of just the final message
• Added chat_options parameter to GroupChatBuilder.set_prompt_based_manager() and _PromptBasedGroupChatManager
• Updated all tests and samples to handle the new list output format

Reviewed Changes

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

Show a summary per file

File	Description
python/uv.lock	Version bump for ag-ui package
python/samples/semantic-kernel-migration/orchestrations/group_chat.py	Updated to handle both list and single message outputs for migration compatibility
python/samples/getting_started/workflows/orchestration/group_chat_with_chat_options.py	New sample demonstrating ChatOptions configuration for prompt-based manager
python/samples/getting_started/workflows/orchestration/group_chat_simple_selector.py	Updated to iterate over full conversation list instead of single message
python/samples/getting_started/workflows/orchestration/group_chat_prompt_based_manager.py	Updated to display full conversation history instead of single response
python/samples/getting_started/workflows/README.md	Added entry for new ChatOptions sample
python/packages/core/tests/workflow/test_magentic.py	Updated assertions to expect list output and verify conversation structure
python/packages/core/tests/workflow/test_group_chat.py	Updated test expectations for list outputs and added test for chat_options passthrough
python/packages/core/agent_framework/_workflows/_magentic.py	Changed output type from ChatMessage to list[ChatMessage], yields full conversation with final answer
python/packages/core/agent_framework/_workflows/_group_chat.py	Added chat_options support to prompt manager, changed yield_output to return full conversation list

[eavanvalkenburg]

Approved with one small comment on the add_manager method

[TaoChenOSU]

Is this making an implicit assumption that the agent is configured to output ManagerSelectionResponse? If so, is it possible to make a requirement on the manger that it must output a structured output and the type must be ManagerSelectionResponse?

[TaoChenOSU]

nit: more comments on the differences between the two and when to use which.
question: what happens if both are specified?

[TaoChenOSU]

nit: maybe set_select_speakers_func instead of select_speakers on the builder?

[TaoChenOSU]

nit: is it possible to have

manager: _GroupChatManagerFn | AgentProtocol | Executor

?