[BREAKING] Python: Move orchestrations to dedicated package

python/README.md

@@ -233,7 +233,7 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-For more advanced orchestration patterns including Sequential, GroupChat, Concurrent, Magentic, and Handoff orchestrations, see the [orchestration samples](samples/getting_started/workflows/orchestration).
+For more advanced orchestration patterns including Sequential, Concurrent, Group Chat, Handoff, and Magentic orchestrations, see the [orchestration samples](samples/getting_started/orchestrations).
 
 ## More Examples & Samples
 

python/packages/core/README.md

@@ -213,10 +213,7 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-**Note**: GroupChat, Sequential, and Concurrent orchestrations are available today. See examples in:
-- [python/samples/getting_started/workflows/orchestration/](https://github.com/microsoft/agent-framework/tree/main/python/samples/getting_started/workflows/orchestration)
-- [group_chat_simple_selector.py](https://github.com/microsoft/agent-framework/blob/main/python/samples/getting_started/workflows/orchestration/group_chat_simple_selector.py)
-- [group_chat_prompt_based_manager.py](https://github.com/microsoft/agent-framework/blob/main/python/samples/getting_started/workflows/orchestration/group_chat_prompt_based_manager.py)
+**Note**: Sequential, Concurrent, Group Chat, Handoff, and Magentic orchestrations are available. See examples in [orchestration samples](../../samples/getting_started/orchestrations).
 
 ## More Examples & Samples
 

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

@@ -20,7 +20,6 @@
     WorkflowCheckpoint,
 )
 from ._checkpoint_summary import WorkflowCheckpointSummary, get_checkpoint_summary
-from ._concurrent import ConcurrentBuilder
 from ._const import (
     DEFAULT_MAX_ITERATIONS,
 )
@@ -66,30 +65,6 @@
     handler,
 )
 from ._function_executor import FunctionExecutor, executor
-from ._group_chat import (
-    AgentBasedGroupChatOrchestrator,
-    GroupChatBuilder,
-    GroupChatState,
-)
-from ._handoff import HandoffAgentUserRequest, HandoffBuilder, HandoffSentEvent
-from ._magentic import (
-    ORCH_MSG_KIND_INSTRUCTION,
-    ORCH_MSG_KIND_NOTICE,
-    ORCH_MSG_KIND_TASK_LEDGER,
-    ORCH_MSG_KIND_USER_TASK,
-    MagenticBuilder,
-    MagenticContext,
-    MagenticManagerBase,
-    MagenticOrchestrator,
-    MagenticOrchestratorEvent,
-    MagenticOrchestratorEventType,
-    MagenticPlanReviewRequest,
-    MagenticPlanReviewResponse,
-    MagenticProgressLedger,
-    MagenticProgressLedgerItem,
-    MagenticResetSignal,
-    StandardMagenticManager,
-)
 from ._orchestration_request_info import AgentRequestInfoResponse
 from ._orchestration_state import OrchestrationState
 from ._request_info_mixin import response_handler
@@ -99,7 +74,6 @@
     Message,
     RunnerContext,
 )
-from ._sequential import SequentialBuilder
 from ._validation import (
     EdgeDuplicationError,
     GraphConnectivityError,
@@ -120,19 +94,13 @@
 
 __all__ = [
     "DEFAULT_MAX_ITERATIONS",
-    "ORCH_MSG_KIND_INSTRUCTION",
-    "ORCH_MSG_KIND_NOTICE",
-    "ORCH_MSG_KIND_TASK_LEDGER",
-    "ORCH_MSG_KIND_USER_TASK",
-    "AgentBasedGroupChatOrchestrator",
     "AgentExecutor",
     "AgentExecutorRequest",
     "AgentExecutorResponse",
     "AgentRequestInfoResponse",
     "BaseGroupChatOrchestrator",
     "Case",
     "CheckpointStorage",
-    "ConcurrentBuilder",
     "Default",
     "Edge",
     "EdgeCondition",
@@ -147,35 +115,17 @@
     "FileCheckpointStorage",
     "FunctionExecutor",
     "GraphConnectivityError",
-    "GroupChatBuilder",
     "GroupChatRequestMessage",
     "GroupChatRequestSentEvent",
     "GroupChatResponseReceivedEvent",
-    "GroupChatState",
-    "HandoffAgentUserRequest",
-    "HandoffBuilder",
-    "HandoffSentEvent",
     "InMemoryCheckpointStorage",
     "InProcRunnerContext",
-    "MagenticBuilder",
-    "MagenticContext",
-    "MagenticManagerBase",
-    "MagenticOrchestrator",
-    "MagenticOrchestratorEvent",
-    "MagenticOrchestratorEventType",
-    "MagenticPlanReviewRequest",
-    "MagenticPlanReviewResponse",
-    "MagenticProgressLedger",
-    "MagenticProgressLedgerItem",
-    "MagenticResetSignal",
     "Message",
     "OrchestrationState",
     "RequestInfoEvent",
     "Runner",
     "RunnerContext",
-    "SequentialBuilder",
     "SingleEdgeGroup",
-    "StandardMagenticManager",
     "SubWorkflowRequestMessage",
     "SubWorkflowResponseMessage",
     "SuperStepCompletedEvent",

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

@@ -0,0 +1,61 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import importlib
+from typing import Any
+
+IMPORT_PATH = "agent_framework_orchestrations"
+PACKAGE_NAME = "agent-framework-orchestrations"
+_IMPORTS = [
+    "__version__",
+    # Sequential
+    "SequentialBuilder",
+    # Concurrent
+    "ConcurrentBuilder",
+    # Handoff
+    "HandoffAgentExecutor",
+    "HandoffAgentUserRequest",
+    "HandoffBuilder",
+    "HandoffConfiguration",
+    "HandoffSentEvent",
+    # Group Chat
+    "AgentBasedGroupChatOrchestrator",
+    "AgentOrchestrationOutput",
+    "GroupChatBuilder",
+    "GroupChatOrchestrator",
+    "GroupChatSelectionFunction",
+    "GroupChatState",
+    # Magentic
+    "MAGENTIC_MANAGER_NAME",
+    "ORCH_MSG_KIND_INSTRUCTION",
+    "ORCH_MSG_KIND_NOTICE",
+    "ORCH_MSG_KIND_TASK_LEDGER",
+    "ORCH_MSG_KIND_USER_TASK",
+    "MagenticAgentExecutor",
+    "MagenticBuilder",
+    "MagenticContext",
+    "MagenticManagerBase",
+    "MagenticOrchestrator",
+    "MagenticOrchestratorEvent",
+    "MagenticOrchestratorEventType",
+    "MagenticPlanReviewRequest",
+    "MagenticPlanReviewResponse",
+    "MagenticProgressLedger",
+    "MagenticProgressLedgerItem",
+    "MagenticResetSignal",
+    "StandardMagenticManager",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name in _IMPORTS:
+        try:
+            return getattr(importlib.import_module(IMPORT_PATH), name)
+        except ModuleNotFoundError as exc:
+            raise ModuleNotFoundError(
+                f"The '{PACKAGE_NAME}' package is not installed, please do `pip install {PACKAGE_NAME}`"
+            ) from exc
+    raise AttributeError(f"Module {IMPORT_PATH} has no attribute {name}.")
+
+
+def __dir__() -> list[str]:
+    return _IMPORTS

python/packages/core/agent_framework/orchestrations/__init__.pyi

@@ -0,0 +1,141 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+# Type stubs for lazy-loaded orchestrations module
+# These re-export types from agent_framework_orchestrations
+
+from agent_framework_orchestrations import (
+    # Magentic
+    MAGENTIC_MANAGER_NAME as MAGENTIC_MANAGER_NAME,
+)
+from agent_framework_orchestrations import (
+    ORCH_MSG_KIND_INSTRUCTION as ORCH_MSG_KIND_INSTRUCTION,
+)
+from agent_framework_orchestrations import (
+    ORCH_MSG_KIND_NOTICE as ORCH_MSG_KIND_NOTICE,
+)
+from agent_framework_orchestrations import (
+    ORCH_MSG_KIND_TASK_LEDGER as ORCH_MSG_KIND_TASK_LEDGER,
+)
+from agent_framework_orchestrations import (
+    ORCH_MSG_KIND_USER_TASK as ORCH_MSG_KIND_USER_TASK,
+)
+from agent_framework_orchestrations import (
+    # Group Chat
+    AgentBasedGroupChatOrchestrator as AgentBasedGroupChatOrchestrator,
+)
+from agent_framework_orchestrations import (
+    AgentOrchestrationOutput as AgentOrchestrationOutput,
+)
+from agent_framework_orchestrations import (
+    # Concurrent
+    ConcurrentBuilder as ConcurrentBuilder,
+)
+from agent_framework_orchestrations import (
+    GroupChatBuilder as GroupChatBuilder,
+)
+from agent_framework_orchestrations import (
+    GroupChatOrchestrator as GroupChatOrchestrator,
+)
+from agent_framework_orchestrations import (
+    GroupChatSelectionFunction as GroupChatSelectionFunction,
+)
+from agent_framework_orchestrations import (
+    GroupChatState as GroupChatState,
+)
+from agent_framework_orchestrations import (
+    # Handoff
+    HandoffAgentExecutor as HandoffAgentExecutor,
+)
+from agent_framework_orchestrations import (
+    HandoffAgentUserRequest as HandoffAgentUserRequest,
+)
+from agent_framework_orchestrations import (
+    HandoffBuilder as HandoffBuilder,
+)
+from agent_framework_orchestrations import (
+    HandoffConfiguration as HandoffConfiguration,
+)
+from agent_framework_orchestrations import (
+    HandoffSentEvent as HandoffSentEvent,
+)
+from agent_framework_orchestrations import (
+    MagenticAgentExecutor as MagenticAgentExecutor,
+)
+from agent_framework_orchestrations import (
+    MagenticBuilder as MagenticBuilder,
+)
+from agent_framework_orchestrations import (
+    MagenticContext as MagenticContext,
+)
+from agent_framework_orchestrations import (
+    MagenticManagerBase as MagenticManagerBase,
+)
+from agent_framework_orchestrations import (
+    MagenticOrchestrator as MagenticOrchestrator,
+)
+from agent_framework_orchestrations import (
+    MagenticOrchestratorEvent as MagenticOrchestratorEvent,
+)
+from agent_framework_orchestrations import (
+    MagenticOrchestratorEventType as MagenticOrchestratorEventType,
+)
+from agent_framework_orchestrations import (
+    MagenticPlanReviewRequest as MagenticPlanReviewRequest,
+)
+from agent_framework_orchestrations import (
+    MagenticPlanReviewResponse as MagenticPlanReviewResponse,
+)
+from agent_framework_orchestrations import (
+    MagenticProgressLedger as MagenticProgressLedger,
+)
+from agent_framework_orchestrations import (
+    MagenticProgressLedgerItem as MagenticProgressLedgerItem,
+)
+from agent_framework_orchestrations import (
+    MagenticResetSignal as MagenticResetSignal,
+)
+from agent_framework_orchestrations import (
+    # Sequential
+    SequentialBuilder as SequentialBuilder,
+)
+from agent_framework_orchestrations import (
+    StandardMagenticManager as StandardMagenticManager,
+)
+from agent_framework_orchestrations import (
+    __version__ as __version__,
+)
+
+__all__ = [
+    "MAGENTIC_MANAGER_NAME",
+    "ORCH_MSG_KIND_INSTRUCTION",
+    "ORCH_MSG_KIND_NOTICE",
+    "ORCH_MSG_KIND_TASK_LEDGER",
+    "ORCH_MSG_KIND_USER_TASK",
+    "AgentBasedGroupChatOrchestrator",
+    "AgentOrchestrationOutput",
+    "ConcurrentBuilder",
+    "GroupChatBuilder",
+    "GroupChatOrchestrator",
+    "GroupChatSelectionFunction",
+    "GroupChatState",
+    "HandoffAgentExecutor",
+    "HandoffAgentUserRequest",
+    "HandoffBuilder",
+    "HandoffConfiguration",
+    "HandoffSentEvent",
+    "MagenticAgentExecutor",
+    "MagenticBuilder",
+    "MagenticContext",
+    "MagenticManagerBase",
+    "MagenticOrchestrator",
+    "MagenticOrchestratorEvent",
+    "MagenticOrchestratorEventType",
+    "MagenticPlanReviewRequest",
+    "MagenticPlanReviewResponse",
+    "MagenticProgressLedger",
+    "MagenticProgressLedgerItem",
+    "MagenticResetSignal",
+    "SequentialBuilder",
+    "StandardMagenticManager",
+    "__version__",
+]

python/packages/core/pyproject.toml

@@ -55,6 +55,7 @@ all = [
     "agent-framework-lab",
     "agent-framework-mem0",
     "agent-framework-ollama",
+    "agent-framework-orchestrations",
     "agent-framework-purview",
     "agent-framework-redis",
 ]

python/packages/core/tests/workflow/test_agent_executor.py

@@ -12,13 +12,13 @@
     ChatMessage,
     ChatMessageStore,
     Content,
-    SequentialBuilder,
     WorkflowOutputEvent,
     WorkflowRunState,
     WorkflowStatusEvent,
 )
 from agent_framework._workflows._agent_executor import AgentExecutorResponse
 from agent_framework._workflows._checkpoint import InMemoryCheckpointStorage
+from agent_framework.orchestrations import SequentialBuilder
 
 
 class _CountingAgent(BaseAgent):

python/packages/core/tests/workflow/test_full_conversation.py

@@ -16,13 +16,13 @@
     ChatMessage,
     Content,
     Executor,
-    SequentialBuilder,
     WorkflowBuilder,
     WorkflowContext,
     WorkflowRunState,
     WorkflowStatusEvent,
     handler,
 )
+from agent_framework.orchestrations import SequentialBuilder
 
 
 class _SimpleAgent(BaseAgent):