[BREAKING] Python: Move single-config fluent methods to constructor parameters (#3693)

* Move single-config fluent methods to constructor parameters

* Updates

* Adjust magentic and group chat

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

@@ -38,8 +38,8 @@ async def main() -> None:
         )
 
         # Build the workflow by adding agents directly as edges.
-        # Agents adapt to workflow mode: run(stream=True) for complete responses, run() for incremental updates.
-        workflow = WorkflowBuilder().set_start_executor(writer_agent).add_edge(writer_agent, reviewer_agent).build()
+        # Agents adapt to workflow mode: run(stream=True) for incremental updates, run() for complete responses.
+        workflow = WorkflowBuilder(start_executor=writer_agent).add_edge(writer_agent, reviewer_agent).build()
 
         # Track the last author to format streaming output.
         last_author: str | None = None

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

@@ -71,7 +71,7 @@ async def main() -> None:
         shared_thread.message_store = ChatMessageStore()
 
         workflow = (
-            WorkflowBuilder()
+            WorkflowBuilder(start_executor="writer")
             .register_agent(factory_func=lambda: writer, name="writer", agent_thread=shared_thread)
             .register_agent(factory_func=lambda: reviewer, name="reviewer", agent_thread=shared_thread)
             .register_executor(
@@ -79,7 +79,6 @@ async def main() -> None:
                 name="intercept_agent_response",
             )
             .add_chain(["writer", "intercept_agent_response", "reviewer"])
-            .set_start_executor("writer")
             .build()
         )
 

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

@@ -110,8 +110,7 @@ async def main() -> None:
     )
 
     workflow = (
-        WorkflowBuilder()
-        .set_start_executor(research_agent)
+        WorkflowBuilder(start_executor=research_agent)
         .add_edge(research_agent, enrich_with_references)
         .add_edge(enrich_with_references, final_editor_agent)
         .build()

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

@@ -40,7 +40,7 @@ async def main():
     # Build the workflow using the fluent builder.
     # Set the start node and connect an edge from writer to reviewer.
     # Agents adapt to workflow mode: run(stream=True) for incremental updates, run() for complete responses.
-    workflow = WorkflowBuilder().set_start_executor(writer_agent).add_edge(writer_agent, reviewer_agent).build()
+    workflow = WorkflowBuilder(start_executor=writer_agent).add_edge(writer_agent, reviewer_agent).build()
 
     # Track the last author to format streaming output.
     last_author: str | None = None

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

@@ -240,7 +240,7 @@ async def main() -> None:
 
     # Build the workflow.
     workflow = (
-        WorkflowBuilder()
+        WorkflowBuilder(start_executor="writer_agent")
         .register_agent(create_writer_agent, name="writer_agent")
         .register_agent(create_final_editor_agent, name="final_editor_agent")
         .register_executor(
@@ -251,7 +251,6 @@ async def main() -> None:
             ),
             name="coordinator",
         )
-        .set_start_executor("writer_agent")
         .add_edge("writer_agent", "coordinator")
         .add_edge("coordinator", "writer_agent")
         .add_edge("final_editor_agent", "coordinator")

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

@@ -65,7 +65,7 @@ async def main() -> None:
     )
 
     # 2) Build a concurrent workflow
-    workflow = ConcurrentBuilder().participants([researcher, marketer, legal]).build()
+    workflow = ConcurrentBuilder(participants=[researcher, marketer, legal]).build()
 
     # 3) Expose the concurrent workflow as an agent for easy reuse
     agent = workflow.as_agent(name="ConcurrentWorkflowAgent")

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

@@ -113,7 +113,7 @@ async def main():
 
     # Build the workflow using the fluent builder.
     # Set the start node and connect an edge from writer to reviewer.
-    workflow = WorkflowBuilder().set_start_executor(writer).add_edge(writer, reviewer).build()
+    workflow = WorkflowBuilder(start_executor=writer).add_edge(writer, reviewer).build()
 
     # Run the workflow with the user's initial message.
     # For foundational clarity, use run (non streaming) and print the workflow output.

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

@@ -33,20 +33,16 @@ async def main() -> None:
         chat_client=OpenAIResponsesClient(),
     )
 
-    workflow = (
-        GroupChatBuilder()
-        .with_orchestrator(
-            agent=OpenAIChatClient().as_agent(
-                name="Orchestrator",
-                instructions="You coordinate a team conversation to solve the user's task.",
-            )
-        )
-        .participants([researcher, writer])
-        # Enable intermediate outputs to observe the conversation as it unfolds
-        # Intermediate outputs will be emitted as WorkflowEvent with type "output" events
-        .with_intermediate_outputs()
-        .build()
-    )
+    # intermediate_outputs=True: Enable intermediate outputs to observe the conversation as it unfolds
+    # (Intermediate outputs will be emitted as WorkflowOutputEvent events)
+    workflow = GroupChatBuilder(
+        participants=[researcher, writer],
+        intermediate_outputs=True,
+        orchestrator_agent=OpenAIChatClient().as_agent(
+            name="Orchestrator",
+            instructions="You coordinate a team conversation to solve the user's task.",
+        ),
+    ).build()
 
     task = "Outline the core considerations for planning a community hackathon, and finish with a concise action plan."
 

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

@@ -156,7 +156,7 @@ async def main() -> None:
     # - participants: All agents that can participate in the workflow
     # - with_start_agent: The triage agent is designated as the start agent, which means
     #   it receives all user input first and orchestrates handoffs to specialists
-    # - with_termination_condition: Custom logic to stop the request/response loop.
+    # - termination_condition: Custom logic to stop the request/response loop.
     #   Without this, the default behavior continues requesting user input until max_turns
     #   is reached. Here we use a custom condition that checks if the conversation has ended
     #   naturally (when one of the agents says something like "you're welcome").
@@ -164,14 +164,14 @@ async def main() -> None:
         HandoffBuilder(
             name="customer_support_handoff",
             participants=[triage, refund, order, support],
-        )
-        .with_start_agent(triage)
-        .with_termination_condition(
             # Custom termination: Check if one of the agents has provided a closing message.
             # This looks for the last message containing "welcome", which indicates the
             # conversation has concluded naturally.
-            lambda conversation: len(conversation) > 0 and "welcome" in conversation[-1].text.lower()
+            termination_condition=lambda conversation: (
+                len(conversation) > 0 and "welcome" in conversation[-1].text.lower()
+            ),
         )
+        .with_start_agent(triage)
         .build()
         .as_agent()  # Convert workflow to agent interface
     )

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

@@ -50,20 +50,16 @@ async def main() -> None:
 
     print("\nBuilding Magentic Workflow...")
 
-    workflow = (
-        MagenticBuilder()
-        .participants([researcher_agent, coder_agent])
-        .with_manager(
-            agent=manager_agent,
-            max_round_count=10,
-            max_stall_count=3,
-            max_reset_count=2,
-        )
-        # Enable intermediate outputs to observe the conversation as it unfolds
-        # Intermediate outputs will be emitted as WorkflowEvent with type "output" events
-        .with_intermediate_outputs()
-        .build()
-    )
+    # intermediate_outputs=True: Enable intermediate outputs to observe the conversation as it unfolds
+    # (Intermediate outputs will be emitted as WorkflowOutputEvent events)
+    workflow = MagenticBuilder(
+        participants=[researcher_agent, coder_agent],
+        intermediate_outputs=True,
+        manager_agent=manager_agent,
+        max_round_count=10,
+        max_stall_count=3,
+        max_reset_count=2,
+    ).build()
 
     task = (
         "I am preparing a report on the energy efficiency of different machine learning model architectures. "

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

@@ -40,7 +40,7 @@ async def main() -> None:
     )
 
     # 2) Build sequential workflow: writer -> reviewer
-    workflow = SequentialBuilder().participants([writer, reviewer]).build()
+    workflow = SequentialBuilder(participants=[writer, reviewer]).build()
 
     # 3) Treat the workflow itself as an agent for follow-up invocations
     agent = workflow.as_agent(name="SequentialWorkflowAgent")

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

@@ -99,7 +99,7 @@ async def main() -> None:
     # Build a workflow with bidirectional communication between Worker and Reviewer,
     # and escalation paths for human review.
     agent = (
-        WorkflowBuilder()
+        WorkflowBuilder(start_executor="worker")
         .register_executor(
             lambda: Worker(
                 id="sub-worker",
@@ -113,7 +113,6 @@ async def main() -> None:
         )
         .add_edge("worker", "reviewer")  # Worker sends requests to Reviewer
         .add_edge("reviewer", "worker")  # Reviewer sends feedback to Worker
-        .set_start_executor("worker")
         .build()
         .as_agent()  # Convert workflow into an agent interface
     )

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

@@ -94,7 +94,7 @@ async def main() -> None:
     )
 
     # Build a sequential workflow
-    workflow = SequentialBuilder().participants([agent]).build()
+    workflow = SequentialBuilder(participants=[agent]).build()
 
     # Expose the workflow as an agent using .as_agent()
     workflow_agent = workflow.as_agent(name="WorkflowAgent")

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

@@ -187,7 +187,7 @@ async def main() -> None:
 
     print("Building workflow with Worker ↔ Reviewer cycle...")
     agent = (
-        WorkflowBuilder()
+        WorkflowBuilder(start_executor="worker")
         .register_executor(
             lambda: Worker(id="worker", chat_client=OpenAIChatClient(model_id="gpt-4.1-nano")),
             name="worker",
@@ -198,7 +198,6 @@ async def main() -> None:
         )
         .add_edge("worker", "reviewer")  # Worker sends responses to Reviewer
         .add_edge("reviewer", "worker")  # Reviewer provides feedback to Worker
-        .set_start_executor("worker")
         .build()
         .as_agent()  # Wrap workflow as an agent
     )

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

@@ -59,7 +59,7 @@ async def main() -> None:
         )
 
     # Build a sequential workflow: assistant -> summarizer
-    workflow = SequentialBuilder().register_participants([create_assistant, create_summarizer]).build()
+    workflow = SequentialBuilder(participant_factories=[create_assistant, create_summarizer]).build()
 
     # Wrap the workflow as an agent
     agent = workflow.as_agent(name="ConversationalWorkflowAgent")
@@ -130,7 +130,7 @@ async def demonstrate_thread_serialization() -> None:
             instructions="You are a helpful assistant with good memory. Remember details from our conversation.",
         )
 
-    workflow = SequentialBuilder().register_participants([create_assistant]).build()
+    workflow = SequentialBuilder(participant_factories=[create_assistant]).build()
     agent = workflow.as_agent(name="MemoryWorkflowAgent")
 
     # Create initial thread and have a conversation