[BREAKING] Python: Move orchestrations to dedicated package (#3685)

* Move orchestrations to dedicated package * Merge main * Fix markdown links * Fix links
2026-06-16 21:04:09 +08:00 · 2026-02-05 12:05:13 +09:00
parent 10afb86213
commit 0daa7700c6
47 changed files with 1197 additions and 712 deletions
@@ -0,0 +1,70 @@
+# Orchestration Getting Started Samples
+
+## Installation
+
+The orchestrations package is included when you install `agent-framework` (which pulls in all optional packages):
+
+```bash
+pip install agent-framework
+```
+
+Or install the orchestrations package directly:
+
+```bash
+pip install agent-framework-orchestrations
+```
+
+Orchestration builders are available via the `agent_framework.orchestrations` submodule:
+
+```python
+from agent_framework.orchestrations import (
+    SequentialBuilder,
+    ConcurrentBuilder,
+    HandoffBuilder,
+    GroupChatBuilder,
+    MagenticBuilder,
+)
+```
+
+## Samples Overview
+
+| Sample                                            | File                                                                                 | Concepts                                                                                                         |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| Concurrent Orchestration (Default Aggregator)     | [concurrent_agents.py](./concurrent_agents.py)                                       | Fan-out to multiple agents; fan-in with default aggregator returning combined ChatMessages                       |
+| Concurrent Orchestration (Custom Aggregator)      | [concurrent_custom_aggregator.py](./concurrent_custom_aggregator.py)                 | Override aggregator via callback; summarize results with an LLM                                                  |
+| Concurrent Orchestration (Custom Agent Executors) | [concurrent_custom_agent_executors.py](./concurrent_custom_agent_executors.py)       | Child executors own ChatAgents; concurrent fan-out/fan-in via ConcurrentBuilder                                  |
+| Concurrent Orchestration (Participant Factory)    | [concurrent_participant_factory.py](./concurrent_participant_factory.py)             | Use participant factories for state isolation between workflow instances                                         |
+| Group Chat with Agent Manager                     | [group_chat_agent_manager.py](./group_chat_agent_manager.py)                         | Agent-based manager using `with_orchestrator(agent=)` to select next speaker                                     |
+| Group Chat Philosophical Debate                   | [group_chat_philosophical_debate.py](./group_chat_philosophical_debate.py)           | Agent manager moderates long-form, multi-round debate across diverse participants                                |
+| Group Chat with Simple Function Selector          | [group_chat_simple_selector.py](./group_chat_simple_selector.py)                     | Group chat with a simple function selector for next speaker                                                      |
+| Handoff (Simple)                                  | [handoff_simple.py](./handoff_simple.py)                                             | Single-tier routing: triage agent routes to specialists, control returns to user after each specialist response  |
+| Handoff (Autonomous)                              | [handoff_autonomous.py](./handoff_autonomous.py)                                     | Autonomous mode: specialists iterate independently until invoking a handoff tool using `.with_autonomous_mode()` |
+| Handoff (Participant Factory)                     | [handoff_participant_factory.py](./handoff_participant_factory.py)                   | Use participant factories for state isolation between workflow instances                                         |
+| Handoff with Code Interpreter                     | [handoff_with_code_interpreter_file.py](./handoff_with_code_interpreter_file.py)     | Retrieve file IDs from code interpreter output in handoff workflow                                               |
+| Magentic Workflow (Multi-Agent)                   | [magentic.py](./magentic.py)                                                         | Orchestrate multiple agents with Magentic manager and streaming                                                  |
+| Magentic + Human Plan Review                      | [magentic_human_plan_review.py](./magentic_human_plan_review.py)                     | Human reviews/updates the plan before execution                                                                  |
+| Magentic + Checkpoint Resume                      | [magentic_checkpoint.py](./magentic_checkpoint.py)                                   | Resume Magentic orchestration from saved checkpoints                                                             |
+| Sequential Orchestration (Agents)                 | [sequential_agents.py](./sequential_agents.py)                                       | Chain agents sequentially with shared conversation context                                                       |
+| Sequential Orchestration (Custom Executor)        | [sequential_custom_executors.py](./sequential_custom_executors.py)                   | Mix agents with a summarizer that appends a compact summary                                                      |
+| Sequential Orchestration (Participant Factories)  | [sequential_participant_factory.py](./sequential_participant_factory.py)             | Use participant factories for state isolation between workflow instances                                         |
+
+## Tips
+
+**Magentic checkpointing tip**: Treat `MagenticBuilder.participants` keys as stable identifiers. When resuming from a checkpoint, the rebuilt workflow must reuse the same participant names; otherwise the checkpoint cannot be applied and the run will fail fast.
+
+**Handoff workflow tip**: Handoff workflows maintain the full conversation history including any `ChatMessage.additional_properties` emitted by your agents. This ensures routing metadata remains intact across all agent transitions. For specialist-to-specialist handoffs, use `.add_handoff(source, targets)` to configure which agents can route to which others with a fluent, type-safe API.
+
+**Sequential orchestration note**: Sequential orchestration uses a few small adapter nodes for plumbing:
+- `input-conversation` normalizes input to `list[ChatMessage]`
+- `to-conversation:<participant>` converts agent responses into the shared conversation
+- `complete` publishes the final `WorkflowOutputEvent`
+
+These may appear in event streams (ExecutorInvoke/Completed). They're analogous to concurrent's dispatcher and aggregator and can be ignored if you only care about agent activity.
+
+## Environment Variables
+
+- **AzureOpenAIChatClient**: Set Azure OpenAI environment variables as documented [here](https://github.com/microsoft/agent-framework/blob/main/python/samples/getting_started/chat_client/README.md#environment-variables).
+
+- **OpenAI** (used in some orchestration samples):
+  - [OpenAIChatClient env vars](https://github.com/microsoft/agent-framework/blob/main/python/samples/getting_started/agents/openai_chat_client/README.md)
+  - [OpenAIResponsesClient env vars](https://github.com/microsoft/agent-framework/blob/main/python/samples/getting_started/agents/openai_responses_client/README.md)
@@ -3,8 +3,9 @@
 import asyncio
 from typing import Any

-from agent_framework import ChatMessage, ConcurrentBuilder
+from agent_framework import ChatMessage
 from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.orchestrations import ConcurrentBuilder
 from azure.identity import AzureCliCredential

 """
@@ -8,12 +8,12 @@ from agent_framework import (
    AgentExecutorResponse,
    ChatAgent,
    ChatMessage,
-    ConcurrentBuilder,
    Executor,
    WorkflowContext,
    handler,
 )
 from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.orchestrations import ConcurrentBuilder
 from azure.identity import AzureCliCredential

 """
@@ -3,8 +3,9 @@
 import asyncio
 from typing import Any

-from agent_framework import ChatMessage, ConcurrentBuilder
+from agent_framework import ChatMessage
 from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.orchestrations import ConcurrentBuilder
 from azure.identity import AzureCliCredential

 """
@@ -6,13 +6,13 @@ from typing import Any, Never
 from agent_framework import (
    ChatAgent,
    ChatMessage,
-    ConcurrentBuilder,
    Executor,
    Workflow,
    WorkflowContext,
    handler,
 )
 from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.orchestrations import ConcurrentBuilder
 from azure.identity import AzureCliCredential

 """
@@ -7,10 +7,10 @@ from agent_framework import (
    AgentResponseUpdate,
    ChatAgent,
    ChatMessage,
-    GroupChatBuilder,
    WorkflowOutputEvent,
 )
 from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.orchestrations import GroupChatBuilder
 from azure.identity import AzureCliCredential

 """
@@ -4,8 +4,14 @@ import asyncio
 import logging
 from typing import cast

-from agent_framework import AgentResponseUpdate, ChatAgent, ChatMessage, GroupChatBuilder, WorkflowOutputEvent
+from agent_framework import (
+    AgentResponseUpdate,
+    ChatAgent,
+    ChatMessage,
+    WorkflowOutputEvent,
+)
 from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.orchestrations import GroupChatBuilder
 from azure.identity import AzureCliCredential

 logging.basicConfig(level=logging.WARNING)
@@ -7,11 +7,10 @@ from agent_framework import (
    AgentResponseUpdate,
    ChatAgent,
    ChatMessage,
-    GroupChatBuilder,
-    GroupChatState,
    WorkflowOutputEvent,
 )
 from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.orchestrations import GroupChatBuilder, GroupChatState
 from azure.identity import AzureCliCredential

 """
@@ -8,13 +8,12 @@ from agent_framework import (
    AgentResponseUpdate,
    ChatAgent,
    ChatMessage,
-    HandoffBuilder,
    HandoffSentEvent,
-    HostedWebSearchTool,
    WorkflowOutputEvent,
    resolve_agent_id,
 )
 from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.orchestrations import HandoffBuilder
 from azure.identity import AzureCliCredential

 logging.basicConfig(level=logging.ERROR)
@@ -61,7 +60,6 @@ def create_agents(
            "coordinator. Keep each individual response focused on one aspect."
        ),
        name="research_agent",
-        tools=[HostedWebSearchTool()],
    )

    summary_agent = chat_client.as_agent(
@@ -8,9 +8,6 @@ from agent_framework import (
    AgentResponse,
    ChatAgent,
    ChatMessage,
-    HandoffAgentUserRequest,
-    HandoffBuilder,
-    HandoffSentEvent,
    RequestInfoEvent,
    Workflow,
    WorkflowEvent,
@@ -20,6 +17,7 @@ from agent_framework import (
    tool,
 )
 from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.orchestrations import HandoffAgentUserRequest, HandoffBuilder, HandoffSentEvent
 from azure.identity import AzureCliCredential

 logging.basicConfig(level=logging.ERROR)
@@ -7,9 +7,6 @@ from agent_framework import (
    AgentResponse,
    ChatAgent,
    ChatMessage,
-    HandoffAgentUserRequest,
-    HandoffBuilder,
-    HandoffSentEvent,
    RequestInfoEvent,
    WorkflowEvent,
    WorkflowOutputEvent,
@@ -18,6 +15,7 @@ from agent_framework import (
    tool,
 )
 from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.orchestrations import HandoffAgentUserRequest, HandoffBuilder, HandoffSentEvent
 from azure.identity import AzureCliCredential

 """Sample: Simple handoff workflow.
@@ -34,8 +34,6 @@ from agent_framework import (
    AgentResponseUpdate,
    ChatAgent,
    ChatMessage,
-    HandoffAgentUserRequest,
-    HandoffBuilder,
    HandoffSentEvent,
    HostedCodeInterpreterTool,
    RequestInfoEvent,
@@ -44,6 +42,7 @@ from agent_framework import (
    WorkflowRunState,
    WorkflowStatusEvent,
 )
+from agent_framework.orchestrations import HandoffAgentUserRequest, HandoffBuilder
 from azure.identity.aio import AzureCliCredential

 # Toggle between V1 (AzureAIAgentClient) and V2 (AzureAIClient)
@@ -11,12 +11,10 @@ from agent_framework import (
    ChatMessage,
    GroupChatRequestSentEvent,
    HostedCodeInterpreterTool,
-    MagenticBuilder,
-    MagenticOrchestratorEvent,
-    MagenticProgressLedger,
    WorkflowOutputEvent,
 )
 from agent_framework.openai import OpenAIChatClient, OpenAIResponsesClient
+from agent_framework.orchestrations import MagenticBuilder, MagenticOrchestratorEvent, MagenticProgressLedger

 logging.basicConfig(level=logging.WARNING)
 logger = logging.getLogger(__name__)
@@ -9,8 +9,6 @@ from agent_framework import (
    ChatAgent,
    ChatMessage,
    FileCheckpointStorage,
-    MagenticBuilder,
-    MagenticPlanReviewRequest,
    RequestInfoEvent,
    WorkflowCheckpoint,
    WorkflowOutputEvent,
@@ -18,6 +16,7 @@ from agent_framework import (
    WorkflowStatusEvent,
 )
 from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.orchestrations import MagenticBuilder, MagenticPlanReviewRequest
 from azure.identity._credentials import AzureCliCredential

 """
@@ -9,14 +9,12 @@ from agent_framework import (
    AgentResponseUpdate,
    ChatAgent,
    ChatMessage,
-    MagenticBuilder,
-    MagenticPlanReviewRequest,
-    MagenticPlanReviewResponse,
    RequestInfoEvent,
    WorkflowEvent,
    WorkflowOutputEvent,
 )
 from agent_framework.openai import OpenAIChatClient
+from agent_framework.orchestrations import MagenticBuilder, MagenticPlanReviewRequest, MagenticPlanReviewResponse

 """
 Sample: Magentic Orchestration with Human Plan Review
@@ -3,8 +3,9 @@
 import asyncio
 from typing import cast

-from agent_framework import ChatMessage, SequentialBuilder, WorkflowOutputEvent
+from agent_framework import ChatMessage, WorkflowOutputEvent
 from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.orchestrations import SequentialBuilder
 from azure.identity import AzureCliCredential

 """
@@ -7,11 +7,11 @@ from agent_framework import (
    AgentExecutorResponse,
    ChatMessage,
    Executor,
-    SequentialBuilder,
    WorkflowContext,
    handler,
 )
 from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.orchestrations import SequentialBuilder
 from azure.identity import AzureCliCredential

 """
@@ -6,12 +6,12 @@ from agent_framework import (
    ChatAgent,
    ChatMessage,
    Executor,
-    SequentialBuilder,
    Workflow,
    WorkflowContext,
    handler,
 )
 from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.orchestrations import SequentialBuilder
 from azure.identity import AzureCliCredential

 """
@@ -108,31 +108,7 @@ For additional observability samples in Agent Framework, see the [observability

 ### orchestration

-| Sample                                            | File                                                                                                       | Concepts                                                                                                         |
-| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| Concurrent Orchestration (Default Aggregator)     | [orchestration/concurrent_agents.py](./orchestration/concurrent_agents.py)                                 | Fan-out to multiple agents; fan-in with default aggregator returning combined ChatMessages                       |
-| Concurrent Orchestration (Custom Aggregator)      | [orchestration/concurrent_custom_aggregator.py](./orchestration/concurrent_custom_aggregator.py)           | Override aggregator via callback; summarize results with an LLM                                                  |
-| Concurrent Orchestration (Custom Agent Executors) | [orchestration/concurrent_custom_agent_executors.py](./orchestration/concurrent_custom_agent_executors.py) | Child executors own ChatAgents; concurrent fan-out/fan-in via ConcurrentBuilder                                  |
-| Concurrent Orchestration (Participant Factory)    | [orchestration/concurrent_participant_factory.py](./orchestration/concurrent_participant_factory.py)       | Use participant factories for state isolation between workflow instances                                         |
-| Group Chat with Agent Manager                     | [orchestration/group_chat_agent_manager.py](./orchestration/group_chat_agent_manager.py)                   | Agent-based manager using `with_orchestrator(agent=)` to select next speaker                                     |
-| Group Chat Philosophical Debate                   | [orchestration/group_chat_philosophical_debate.py](./orchestration/group_chat_philosophical_debate.py)     | Agent manager moderates long-form, multi-round debate across diverse participants                                |
-| Group Chat with Simple Function Selector          | [orchestration/group_chat_simple_selector.py](./orchestration/group_chat_simple_selector.py)               | Group chat with a simple function selector for next speaker                                                      |
-| Handoff (Simple)                                  | [orchestration/handoff_simple.py](./orchestration/handoff_simple.py)                                       | Single-tier routing: triage agent routes to specialists, control returns to user after each specialist response  |
-| Handoff (Autonomous)                              | [orchestration/handoff_autonomous.py](./orchestration/handoff_autonomous.py)                               | Autonomous mode: specialists iterate independently until invoking a handoff tool using `.with_autonomous_mode()` |
-| Handoff (Participant Factory)                     | [orchestration/handoff_participant_factory.py](./orchestration/handoff_participant_factory.py)             | Use participant factories for state isolation between workflow instances                                         |
-| Magentic Workflow (Multi-Agent)                   | [orchestration/magentic.py](./orchestration/magentic.py)                                                   | Orchestrate multiple agents with Magentic manager and streaming                                                  |
-| Magentic + Human Plan Review                      | [orchestration/magentic_human_plan_review.py](./orchestration/magentic_human_plan_review.py)               | Human reviews/updates the plan before execution                                                                  |
-| Magentic + Checkpoint Resume                      | [orchestration/magentic_checkpoint.py](./orchestration/magentic_checkpoint.py)                             | Resume Magentic orchestration from saved checkpoints                                                             |
-| Sequential Orchestration (Agents)                 | [orchestration/sequential_agents.py](./orchestration/sequential_agents.py)                                 | Chain agents sequentially with shared conversation context                                                       |
-| Sequential Orchestration (Custom Executor)        | [orchestration/sequential_custom_executors.py](./orchestration/sequential_custom_executors.py)             | Mix agents with a summarizer that appends a compact summary                                                      |
-| Sequential Orchestration (Participant Factories)  | [orchestration/sequential_participant_factory.py](./orchestration/sequential_participant_factory.py)       | Use participant factories for state isolation between workflow instances                                         |
-
-**Magentic checkpointing tip**: Treat `MagenticBuilder.participants` keys as stable identifiers. When resuming from a checkpoint, the rebuilt workflow must reuse the same participant names; otherwise the checkpoint cannot be applied and the run will fail fast.
-
-**Handoff workflow tip**: Handoff workflows maintain the full conversation history including any
-`ChatMessage.additional_properties` emitted by your agents. This ensures routing metadata remains
-intact across all agent transitions. For specialist-to-specialist handoffs, use `.add_handoff(source, targets)`
-to configure which agents can route to which others with a fluent, type-safe API.
+Orchestration samples (Sequential, Concurrent, Handoff, GroupChat, Magentic) have moved to the dedicated [orchestrations samples directory](../orchestrations/README.md).

 ### parallelism