[BREAKING] Python: Add factory pattern to GroupChat and Magentic (#3224)

* group chat

* magentic

* Fix tests

* AI comments

* Unifiy error message and add warning

* misc

* Add overload

* Collapse orchestrator params

python/samples/autogen-migration/orchestrations/02_selector_group_chat.py

@@ -86,12 +86,11 @@ async def run_agent_framework() -> None:
     workflow = (
         GroupChatBuilder()
         .participants([python_expert, javascript_expert, database_expert])
-        .set_manager(
-            manager=client.as_agent(
+        .with_orchestrator(
+            agent=client.as_agent(
                 name="selector_manager",
                 instructions="Based on the conversation, select the most appropriate expert to respond next.",
             ),
-            display_name="SelectorManager",
         )
         .with_max_rounds(1)
         .build()

python/samples/autogen-migration/orchestrations/04_magentic_one.py

@@ -6,6 +6,16 @@ managing specialized agents for complex tasks.
 """
 
 import asyncio
+import json
+from typing import cast
+
+from agent_framework import (
+    AgentRunUpdateEvent,
+    ChatMessage,
+    MagenticOrchestratorEvent,
+    MagenticProgressLedger,
+    WorkflowOutputEvent,
+)
 
 
 async def run_autogen() -> None:
@@ -57,14 +67,7 @@ async def run_autogen() -> None:
 
 async def run_agent_framework() -> None:
     """Agent Framework's MagenticBuilder for orchestrated collaboration."""
-    from agent_framework import (
-        MagenticAgentDeltaEvent,
-        MagenticAgentMessageEvent,
-        MagenticBuilder,
-        MagenticFinalResultEvent,
-        MagenticOrchestratorMessageEvent,
-        tool,
-    )
+    from agent_framework import MagenticBuilder
     from agent_framework.openai import OpenAIChatClient
 
     client = OpenAIChatClient(model_id="gpt-4.1-mini")
@@ -91,9 +94,13 @@ async def run_agent_framework() -> None:
     # Create Magentic workflow
     workflow = (
         MagenticBuilder()
-        .participants(researcher=researcher, coder=coder, reviewer=reviewer)
-        .with_standard_manager(
-            chat_client=client,
+        .participants([researcher, coder, reviewer])
+        .with_manager(
+            agent=client.as_agent(
+                name="magentic_manager",
+                instructions="You coordinate a team to complete complex tasks efficiently.",
+                description="Orchestrator for team coordination",
+            ),
             max_round_count=20,
             max_stall_count=3,
             max_reset_count=1,
@@ -102,41 +109,46 @@ async def run_agent_framework() -> None:
     )
 
     # Run complex task
+    last_message_id: str | None = None
+    output_event: WorkflowOutputEvent | None = None
     print("[Agent Framework] Magentic conversation:")
-    last_stream_agent_id: str | None = None
-    stream_line_open: bool = False
-
     async for event in workflow.run_stream("Research Python async patterns and write a simple example"):
-        if isinstance(event, MagenticOrchestratorMessageEvent):
-            if stream_line_open:
-                print()
-                stream_line_open = False
-            print(f"---------- Orchestrator:{event.kind} ----------")
-            print(getattr(event.message, "text", ""))
-        elif isinstance(event, MagenticAgentDeltaEvent):
-            if last_stream_agent_id != event.agent_id or not stream_line_open:
-                if stream_line_open:
-                    print()
-                print(f"---------- {event.agent_id} ----------")
-                last_stream_agent_id = event.agent_id
-                stream_line_open = True
-            if event.text:
-                print(event.text, end="", flush=True)
-        elif isinstance(event, MagenticAgentMessageEvent):
-            if stream_line_open:
-                print()
-                stream_line_open = False
-        elif isinstance(event, MagenticFinalResultEvent):
-            if stream_line_open:
-                print()
-                stream_line_open = False
-            print("---------- Final Result ----------")
-            if event.message is not None:
-                print(event.message.text)
+        if isinstance(event, AgentRunUpdateEvent):
+            message_id = event.data.message_id
+            if message_id != last_message_id:
+                if last_message_id is not None:
+                    print("\n")
+                print(f"- {event.executor_id}:", end=" ", flush=True)
+                last_message_id = message_id
+            print(event.data, end="", flush=True)
 
-    if stream_line_open:
-        print()
-    print()  # Final newline after conversation
+        elif isinstance(event, MagenticOrchestratorEvent):
+            print(f"\n[Magentic Orchestrator Event] Type: {event.event_type.name}")
+            if isinstance(event.data, ChatMessage):
+                print(f"Please review the plan:\n{event.data.text}")
+            elif isinstance(event.data, MagenticProgressLedger):
+                print(f"Please review progress ledger:\n{json.dumps(event.data.to_dict(), indent=2)}")
+            else:
+                print(f"Unknown data type in MagenticOrchestratorEvent: {type(event.data)}")
+
+            # Block to allow user to read the plan/progress before continuing
+            # Note: this is for demonstration only and is not the recommended way to handle human interaction.
+            # Please refer to `with_plan_review` for proper human interaction during planning phases.
+            await asyncio.get_event_loop().run_in_executor(None, input, "Press Enter to continue...")
+
+        elif isinstance(event, WorkflowOutputEvent):
+            output_event = event
+
+    if not output_event:
+        raise RuntimeError("Workflow did not produce a final output event.")
+    print("\n\nWorkflow completed!")
+    print("Final Output:")
+    # The output of the Magentic workflow is a list of ChatMessages with only one final message
+    # generated by the orchestrator.
+    output_messages = cast(list[ChatMessage], output_event.data)
+    if output_messages:
+        output = output_messages[-1].text
+        print(output)
 
 
 async def main() -> None:

python/samples/getting_started/workflows/README.md

@@ -115,7 +115,7 @@ For additional observability samples in Agent Framework, see the [observability
 | 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_agent_orchestrator()` to select next speaker |
+| 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 |

python/samples/getting_started/workflows/agents/group_chat_workflow_as_agent.py

@@ -34,8 +34,8 @@ async def main() -> None:
 
     workflow = (
         GroupChatBuilder()
-        .with_agent_orchestrator(
-            OpenAIChatClient().as_agent(
+        .with_orchestrator(
+            agent=OpenAIChatClient().as_agent(
                 name="Orchestrator",
                 instructions="You coordinate a team conversation to solve the user's task.",
             )

python/samples/getting_started/workflows/agents/magentic_workflow_as_agent.py

@@ -56,7 +56,7 @@ async def main() -> None:
     workflow = (
         MagenticBuilder()
         .participants([researcher_agent, coder_agent])
-        .with_standard_manager(
+        .with_manager(
             agent=manager_agent,
             max_round_count=10,
             max_stall_count=3,

python/samples/getting_started/workflows/human-in-the-loop/group_chat_request_info.py

@@ -90,7 +90,7 @@ async def main() -> None:
     # Using agents= filter to only pause before pragmatist speaks (not every turn)
     workflow = (
         GroupChatBuilder()
-        .with_agent_orchestrator(orchestrator)
+        .with_orchestrator(agent=orchestrator)
         .participants([optimist, pragmatist, creative])
         .with_max_rounds(6)
         .with_request_info(agents=[pragmatist])  # Only pause before pragmatist speaks

python/samples/getting_started/workflows/orchestration/group_chat_agent_manager.py

@@ -69,7 +69,7 @@ async def main() -> None:
     # Build the group chat workflow
     workflow = (
         GroupChatBuilder()
-        .with_agent_orchestrator(orchestrator_agent)
+        .with_orchestrator(agent=orchestrator_agent)
         .participants([researcher, writer])
         # Set a hard termination condition: stop after 4 assistant messages
         # The agent orchestrator will intelligently decide when to end before this limit but just in case

python/samples/getting_started/workflows/orchestration/group_chat_philosophical_debate.py

@@ -212,7 +212,7 @@ Share your perspective authentically. Feel free to:
 
     workflow = (
         GroupChatBuilder()
-        .with_agent_orchestrator(moderator)
+        .with_orchestrator(agent=moderator)
         .participants([farmer, developer, teacher, activist, spiritual_leader, artist, immigrant, doctor])
         .with_termination_condition(lambda messages: sum(1 for msg in messages if msg.role == Role.ASSISTANT) >= 10)
         .build()

python/samples/getting_started/workflows/orchestration/group_chat_simple_selector.py

@@ -18,7 +18,7 @@ from azure.identity import AzureCliCredential
 Sample: Group Chat with a round-robin speaker selector
 
 What it does:
-- Demonstrates the with_select_speaker_func() API for GroupChat orchestration
+- Demonstrates the with_orchestrator() API for GroupChat orchestration
 - Uses a pure Python function to control speaker selection based on conversation state
 
 Prerequisites:
@@ -85,7 +85,7 @@ async def main() -> None:
     workflow = (
         GroupChatBuilder()
         .participants([expert, verifier, clarifier, skeptic])
-        .with_select_speaker_func(round_robin_selector)
+        .with_orchestrator(selection_func=round_robin_selector)
         # Set a hard termination condition: stop after 6 messages (user task + one full rounds + 1)
         # One round is expert -> verifier -> clarifier -> skeptic, after which the expert gets to respond again.
         # This will end the conversation after the expert has spoken 2 times (one iteration loop)

python/samples/getting_started/workflows/orchestration/magentic.py

@@ -81,7 +81,7 @@ async def main() -> None:
     workflow = (
         MagenticBuilder()
         .participants([researcher_agent, coder_agent])
-        .with_standard_manager(
+        .with_manager(
             agent=manager_agent,
             max_round_count=10,
             max_stall_count=3,

python/samples/getting_started/workflows/orchestration/magentic_checkpoint.py

@@ -84,7 +84,7 @@ def build_workflow(checkpoint_storage: FileCheckpointStorage):
         MagenticBuilder()
         .participants([researcher, writer])
         .with_plan_review()
-        .with_standard_manager(
+        .with_manager(
             agent=manager_agent,
             max_round_count=10,
             max_stall_count=3,

python/samples/getting_started/workflows/orchestration/magentic_human_plan_review.py

@@ -64,7 +64,7 @@ async def main() -> None:
     workflow = (
         MagenticBuilder()
         .participants([researcher_agent, analyst_agent])
-        .with_standard_manager(
+        .with_manager(
             agent=manager_agent,
             max_round_count=10,
             max_stall_count=1,

python/samples/getting_started/workflows/tool-approval/group_chat_builder_tool_approval.py

@@ -119,8 +119,7 @@ async def main() -> None:
     # 4. Build a group chat workflow with the selector function
     workflow = (
         GroupChatBuilder()
-        # Optionally, use `.set_manager(...)` to customize the group chat manager
-        .with_select_speaker_func(select_next_speaker)
+        .with_orchestrator(selection_func=select_next_speaker)
         .participants([qa_engineer, devops_engineer])
         # Set a hard limit to 4 rounds
         # First round: QAEngineer speaks

python/samples/semantic-kernel-migration/orchestrations/group_chat.py

@@ -233,11 +233,8 @@ async def run_agent_framework_example(task: str) -> str:
 
     workflow = (
         GroupChatBuilder()
-        .set_manager(
-            manager=AzureOpenAIChatClient(credential=credential).as_agent(),
-            display_name="Coordinator",
-        )
-        .participants(researcher=researcher, planner=planner)
+        .with_orchestrator(agent=AzureOpenAIChatClient(credential=credential).as_agent())
+        .participants([researcher, planner])
         .build()
     )
 

python/samples/semantic-kernel-migration/orchestrations/magentic.py

@@ -144,12 +144,7 @@ async def run_agent_framework_example(prompt: str) -> str | None:
         chat_client=OpenAIChatClient(),
     )
 
-    workflow = (
-        MagenticBuilder()
-        .participants(researcher=researcher, coder=coder)
-        .with_standard_manager(agent=manager_agent)
-        .build()
-    )
+    workflow = MagenticBuilder().participants([researcher, coder]).with_manager(agent=manager_agent).build()
 
     final_text: str | None = None
     async for event in workflow.run_stream(prompt):