[BREAKING] Python: Move single-config fluent methods to constructor parameters

[moonbox3]

Motivation and Context

• Migrates fluent methods across 6 builders to constructor parameters
• Removes or internalizes fluent methods to avoid duplicate configuration paths
• Updates all samples and tests to use new constructor syntax

Breaking Changes

An (simple, omitting some config) example of a change:

# Before (no longer works):
workflow = (
    SequentialBuilder()
    .participants([agent_a, agent_b])
    .with_checkpointing(storage)
    .with_intermediate_outputs()
    .build()
)

# After:
workflow = SequentialBuilder(
    participants=[agent_a, agent_b],
    checkpoint_storage=storage,
    intermediate_outputs=True,
).build()

Methods removed (in favor of constructor arguments):

• WorkflowBuilder: set_start_executor(), with_checkpointing(), with_output_from()
• SequentialBuilder: participants(), register_participants(), with_checkpointing(), with_intermediate_outputs()
• ConcurrentBuilder: participants(), register_participants(), with_checkpointing(), with_intermediate_outputs()
• GroupChatBuilder: participants(), register_participants(), with_termination_condition(), with_max_rounds(), with_checkpointing(), with_intermediate_outputs()
• MagenticBuilder: participants(), register_participants(), with_plan_review(), with_checkpointing(), with_intermediate_outputs()
• HandoffBuilder: with_checkpointing(), with_termination_condition()

Validation changes:

• WorkflowBuilder now requires start_executor as a constructor argument (previously set via fluent method)
• SequentialBuilder, ConcurrentBuilder, GroupChatBuilder, and MagenticBuilder now require either participants or participant_factories at construction time — passing neither raises ValueError

Note: HandoffBuilder already accepted participants/participant_factories as constructor parameters and was not changed in this regard.

Description

• Closes Python: Move single-config fluent methods to constructor parameters #3552

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
_workflow.py	262	26	90%	87, 265–267, 269–270, 288, 292, 320, 422, 597, 618, 644, 671, 673–674, 679–680, 686, 692, 697, 717–719, 732, 800
_workflow_builder.py	267	35	86%	257, 527, 625, 632–633, 733, 736, 741, 743, 750, 753–757, 759, 820, 894, 897, 953, 971, 984, 998–1005, 1007, 1010, 1012–1014
packages/orchestrations/agent_framework_orchestrations
_concurrent.py	186	32	82%	52, 61–62, 70–71, 90–91, 96, 123, 128, 133–134, 140, 162, 172, 179, 266, 279, 282, 295, 311, 314, 341, 397, 409, 439, 441–442, 444, 449, 471, 475
_group_chat.py	286	51	82%	173, 336, 343, 372, 383–384, 390, 395, 411, 438–443, 445, 478–481, 483, 488–492, 622, 625, 628, 631, 639, 652, 655, 668, 677, 683, 727–728, 732–733, 747–748, 750–751, 782–783, 849, 868, 876, 890, 900
_handoff.py	380	61	83%	104–105, 107, 136–137, 159–169, 171, 173, 175, 180, 280, 334, 359, 387, 395–396, 410, 461–462, 494, 541–543, 737, 744, 749, 836, 839, 848–851, 861, 866, 873, 879–882, 917, 922, 1003–1004, 1036–1037, 1117, 1120, 1128, 1146, 1153, 1228
_magentic.py	606	98	83%	63–72, 77, 81–92, 257, 268, 272, 292, 353, 362, 364, 406, 423, 432–433, 435–437, 439, 450, 592, 594, 634, 682, 718–720, 722, 730–733, 737–740, 801–804, 895, 901, 907, 949, 987, 1019, 1036, 1047, 1104–1105, 1109–1111, 1135, 1159–1160, 1173, 1189, 1211, 1259–1260, 1298–1299, 1474, 1477, 1490, 1493, 1502, 1505, 1510, 1561–1562, 1603–1604, 1652, 1682, 1740, 1754, 1772
_orchestration_request_info.py	54	0	100%
_sequential.py	107	14	86%	74, 173, 186, 189, 202, 213, 219, 250, 252–253, 255, 260, 282, 286
TOTAL	16545	2057	87%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
3920	225 💤	0 ❌	0 🔥	1m 7s ⏱️

[Copilot]

Pull request overview

This PR implements a breaking change that converts 14 fluent builder methods across 6 orchestration builders into constructor parameters. The change eliminates duplicate configuration paths by removing methods like set_start_executor(), with_checkpointing(), with_max_rounds(), with_termination_condition(), with_intermediate_outputs(), and with_plan_review() in favor of constructor parameters.

Changes:

• Moves single-configuration fluent methods to constructor parameters for WorkflowBuilder, SequentialBuilder, ConcurrentBuilder, GroupChatBuilder, HandoffBuilder, and MagenticBuilder
• Updates all samples (60+ files) and tests (20+ files) to use the new constructor syntax
• Converts set_start_executor() to private _set_start_executor() method and adds start_executor constructor parameter
• Updates error messages and documentation to reflect the new API

Reviewed changes

Copilot reviewed 103 out of 103 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
_workflow_builder.py	Adds constructor parameters (start_executor, checkpoint_storage, output_executors), removes fluent methods, makes set_start_executor private
_sequential.py	Adds checkpoint_storage and intermediate_outputs constructor parameters, removes corresponding fluent methods
_concurrent.py	Adds checkpoint_storage and intermediate_outputs constructor parameters, removes corresponding fluent methods
_group_chat.py	Adds termination_condition, max_rounds, checkpoint_storage, and intermediate_outputs constructor parameters
_handoff.py	Adds checkpoint_storage and termination_condition constructor parameters
_magentic.py	Adds enable_plan_review, checkpoint_storage, and intermediate_outputs constructor parameters
Sample files (60+)	Updates all workflow construction to use new constructor parameter syntax
Test files (20+)	Updates all test code to use new constructor parameter syntax
_declarative_builder.py	Updates to use WorkflowBuilder constructor parameters but calls private _set_start_executor()
_workflow.py, _orchestration_request_info.py	Updates documentation and usage examples