[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
2026-06-16 21:04:09 +08:00 · 2026-01-28 09:00:20 -08:00
parent a7d924a7d2
commit 739edc7307
24 changed files with 1488 additions and 365 deletions
@@ -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 |
@@ -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.",
            )
@@ -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,
@@ -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
@@ -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
@@ -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()
@@ -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)
@@ -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,
@@ -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,
@@ -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,
@@ -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