[BREAKING] Python: Move orchestrations to dedicated package

[moonbox3]

Motivation and Context

• Moves orchestration builders (Sequential, Concurrent, Handoff, GroupChat, Magentic) from core to new agent-framework-orchestrations package
• Adds lazy-loading via agent_framework.orchestrations for backwards-compatible imports
• Updates samples to use from agent_framework.orchestrations import ...
• Moves orchestration tests to the new package

Description

• Closes Python: Move orchestrations to new agent-framework-orchestrations package #3536

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/orchestrations/agent_framework_orchestrations
_concurrent.py	193	30	84%	51, 60–61, 69–70, 89–90, 95, 122, 127, 132–133, 139, 161, 171, 178, 346, 349, 377, 433, 445, 484, 486–487, 489, 501–502, 507, 529, 533
_group_chat.py	291	39	86%	171, 332, 339, 366, 377–378, 384, 389, 405, 432–437, 439, 472–475, 477, 482–486, 650, 655, 669, 750, 756, 802, 822, 897–898, 932, 951, 970, 980
_handoff.py	382	57	85%	109–110, 112, 141–142, 162–172, 174, 176, 178, 183, 283, 337, 362, 390, 398–399, 413, 462–463, 495, 542–544, 731, 738, 743, 830, 833, 842–845, 855, 860, 867, 873–876, 911, 916, 1113, 1116, 1124, 1142, 1149, 1224
_magentic.py	620	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, 1460, 1469, 1472, 1477, 1873, 1928, 1943, 1972
_sequential.py	114	14	87%	73, 166, 184, 195, 201, 238, 240–241, 243, 255–256, 261, 283, 287
TOTAL	16362	1922	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
3989	221 💤	0 ❌	0 🔥	1m 7s ⏱️

[Copilot]

Pull request overview

This PR moves orchestration builders (SequentialBuilder, ConcurrentBuilder, HandoffBuilder, GroupChatBuilder, MagenticBuilder) from the core package to a new dedicated agent-framework-orchestrations package. This change improves modularity and clarifies that orchestrations are patterns users can build themselves with the core workflow APIs.

Changes:

• Created new agent-framework-orchestrations package with orchestration builders
• Added lazy-loading via agent_framework.orchestrations for backwards compatibility
• Updated all orchestration samples to use from agent_framework.orchestrations import ...
• Moved orchestration tests from core to the orchestrations package
• Removed orchestration exports from agent_framework._workflows.__init__.py

Reviewed changes

Copilot reviewed 41 out of 43 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
python/packages/orchestrations/pyproject.toml	New package configuration with dependencies on agent-framework-core
python/packages/orchestrations/agent_framework_orchestrations/init.py	Exports for all orchestration builders and related types
python/packages/orchestrations/agent_framework_orchestrations/_*.py	Moved orchestration implementation files with updated imports to reference core via agent_framework._workflows
python/packages/orchestrations/tests/test_*.py	Moved and updated orchestration tests with imports from agent_framework.orchestrations
python/packages/orchestrations/README.md	Package-level documentation with installation and usage examples
python/packages/orchestrations/LICENSE	MIT license file
python/packages/core/agent_framework/orchestrations/init.py	Lazy-loading module with helpful error messages
python/packages/core/agent_framework/orchestrations/init.pyi	Type stubs for IDE support
python/packages/core/agent_framework/_workflows/init.py	Removed orchestration exports, added SharedState export
python/packages/core/pyproject.toml	Added agent-framework-orchestrations to "all" extras
python/samples/getting_started/orchestrations/*.py	Updated all samples to import from agent_framework.orchestrations
python/samples/getting_started/orchestrations/README.md	New README for orchestration samples directory
python/samples/getting_started/workflows/README.md	Updated to reference new orchestrations directory
python/packages/core/tests/workflow/test_workflow_kwargs.py	Deleted - test coverage removed
python/packages/core/tests/workflow/test_*.py	Updated to import orchestrations from agent_framework.orchestrations
python/pyproject.toml	Added orchestrations package and coverage configuration

Comments suppressed due to low confidence (1)

python/packages/core/tests/workflow/test_workflow_kwargs.py:1

• The test file test_workflow_kwargs.py was deleted but the test coverage it provided for kwargs propagation through workflows (Sequential, Concurrent, GroupChat, Handoff, Magentic) was not migrated to the orchestrations package tests. This removes test coverage for an important feature without replacement. Consider either:

1. Moving these tests to python/packages/orchestrations/tests/test_kwargs_propagation.py, or
2. Documenting why this test coverage is no longer needed.

The deleted tests covered:

• Kwargs flow through Sequential/Concurrent/GroupChat/Handoff/Magentic workflows
• Kwargs stored in SharedState with WORKFLOW_RUN_KWARGS_KEY
• Kwargs propagation to agents via workflow.as_agent()
• Kwargs propagation through nested subworkflows