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

[moonbox3]

Motivation and Context

• Migrates 14 fluent methods across 6 builders to constructor parameters
• Removes fluent methods entirely 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):
builder = SequentialBuilder().with_checkpointing(storage).with_intermediate_outputs().build()

# After:
builder = SequentialBuilder(checkpoint_storage=storage, intermediate_outputs=True).build()

Methods removed (in favor of constructor arguments):

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

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
_orchestration_request_info.py	54	0	100%
_workflow.py	268	19	92%	89, 267–269, 271–272, 290, 294, 322, 424, 705, 747, 752, 755, 774–776, 789, 857
_workflow_builder.py	268	38	85%	250, 258, 528, 626, 633–634, 734, 737, 742, 744, 751, 754–758, 760, 821, 895, 898, 924–925, 972, 985, 999–1006, 1008, 1011, 1013–1015, 1023
packages/orchestrations/agent_framework_orchestrations
_concurrent.py	182	28	84%	51, 60–61, 69–70, 89–90, 95, 122, 127, 132–133, 139, 161, 171, 178, 358, 361, 389, 445, 457, 487, 489–490, 492, 497, 519, 523
_group_chat.py	271	35	87%	171, 332, 339, 366, 377–378, 384, 389, 405, 432–437, 439, 472–475, 477, 482–486, 665, 670, 684, 765, 771, 845, 864, 883, 893
_handoff.py	374	57	84%	109–110, 112, 141–142, 162–172, 174, 176, 178, 183, 283, 337, 362, 390, 398–399, 413, 462–463, 495, 542–544, 738, 745, 750, 837, 840, 849–852, 862, 867, 874, 880–883, 918, 923, 1036, 1039, 1047, 1065, 1072, 1147
_magentic.py	607	91	85%	66–75, 80, 84–95, 260, 271, 275, 295, 356, 365, 367, 409, 426, 435–436, 438–440, 442, 453, 595, 597, 637, 687, 723–725, 727, 735–738, 742–745, 788, 815–818, 909, 915, 921, 960, 998, 1027, 1044, 1055, 1109–1110, 1114–1116, 1140, 1161–1162, 1175, 1191, 1213, 1261–1262, 1300–1301, 1472, 1481, 1484, 1489, 1789, 1831, 1846, 1875
_sequential.py	103	12	88%	73, 177, 195, 206, 212, 244, 246–247, 249, 254, 276, 280
TOTAL	16291	1915	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
3991	221 💤	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

[Copilot]

Direct assignment to private attribute _start_executor bypasses the validation and wrapping logic in _set_start_executor. This could lead to bugs if the start_executor is an Agent or a string reference that needs to be resolved. Consider using builder._set_start_executor(...) instead to ensure proper validation and wrapping.

[Copilot]

Multiple direct assignments to private attribute _start_executor bypass the validation and wrapping logic in _set_start_executor. This pattern appears throughout the test file and could lead to bugs if the start_executor is an Agent or a string reference that needs to be resolved. While acceptable in test code, consider documenting why the private API is being used directly, or preferably use the constructor parameter start_executor consistently.

[Copilot]

The error message should be updated to match the new API. Instead of "using the start_executor constructor parameter", it should say "via the start_executor constructor parameter" to be consistent with Python conventions and clearer.

Suggested change

	"Starting executor must be set using the start_executor constructor parameter before building."
	"Starting executor must be set via the start_executor constructor parameter before building."

[Copilot]

The _set_start_executor method is being made internal (prefixed with underscore) but is being called in user-facing code in the declarative builder. This creates an inconsistency - internal methods should not be called from outside the class. The declarative builder should use the constructor parameter start_executor instead, or this method should remain public.

[Copilot]

Direct assignment to private attribute _start_executor bypasses the validation and wrapping logic in _set_start_executor. This could lead to bugs if the start_executor is an Agent or a string reference that needs to be resolved. Consider using builder._set_start_executor(...) instead to ensure proper validation and wrapping.