[BREAKING] Python: Fix workflow as agent streaming output (#3649)

* WIP: with_output_from

* Add with_output_from to other modules; next: workflow as agent

* WIP: remove agent run events

* orchestrations

* WIP: update samples; next start at guessing_game_With_human_input.py

* Update all samples

* WIP: consolidate workflow as agent streaming vs non-streaming

* Consolidate workflow as agent streaming vs non-streaming

* Move request info event processing to a share method

* Final pass on the samples

* Fix mypy

* Fix mypy

* Comments

---------

Co-authored-by: Evan Mattson <35585003+moonbox3@users.noreply.github.com>

python/samples/autogen-migration/orchestrations/01_round_robin_group_chat.py

@@ -7,6 +7,8 @@ the task in a round-robin fashion.
 
 import asyncio
 
+from agent_framework import AgentResponseUpdate, WorkflowOutputEvent
+
 
 async def run_autogen() -> None:
     """AutoGen's RoundRobinGroupChat for sequential agent orchestration."""
@@ -53,7 +55,7 @@ async def run_autogen() -> None:
 
 async def run_agent_framework() -> None:
     """Agent Framework's SequentialBuilder for sequential agent orchestration."""
-    from agent_framework import AgentRunUpdateEvent, SequentialBuilder
+    from agent_framework import SequentialBuilder
     from agent_framework.openai import OpenAIChatClient
 
     client = OpenAIChatClient(model_id="gpt-4.1-mini")
@@ -81,14 +83,14 @@ async def run_agent_framework() -> None:
     print("[Agent Framework] Sequential conversation:")
     current_executor = None
     async for event in workflow.run_stream("Create a brief summary about electric vehicles"):
-        if isinstance(event, AgentRunUpdateEvent):
+        if isinstance(event, WorkflowOutputEvent):
             # Print executor name header when switching to a new agent
             if current_executor != event.executor_id:
                 if current_executor is not None:
                     print()  # Newline after previous agent's message
                 print(f"---------- {event.executor_id} ----------")
                 current_executor = event.executor_id
-            if event.data:
+            if isinstance(event.data, AgentResponseUpdate):
                 print(event.data.text, end="", flush=True)
     print()  # Final newline after conversation
 
@@ -98,7 +100,6 @@ async def run_agent_framework_with_cycle() -> None:
     from agent_framework import (
         AgentExecutorRequest,
         AgentExecutorResponse,
-        AgentRunUpdateEvent,
         WorkflowBuilder,
         WorkflowContext,
         WorkflowOutputEvent,
@@ -153,10 +154,7 @@ async def run_agent_framework_with_cycle() -> None:
     print("[Agent Framework with Cycle] Cyclic conversation:")
     current_executor = None
     async for event in workflow.run_stream("Create a brief summary about electric vehicles"):
-        if isinstance(event, WorkflowOutputEvent):
-            print("\n---------- Workflow Output ----------")
-            print(event.data)
-        elif isinstance(event, AgentRunUpdateEvent):
+        if isinstance(event, WorkflowOutputEvent) and isinstance(event.data, AgentResponseUpdate):
             # Print executor name header when switching to a new agent
             if current_executor != event.executor_id:
                 if current_executor is not None:

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

@@ -7,6 +7,8 @@ which agent should speak next based on the conversation context.
 
 import asyncio
 
+from agent_framework import AgentResponseUpdate, WorkflowOutputEvent
+
 
 async def run_autogen() -> None:
     """AutoGen's SelectorGroupChat with LLM-based speaker selection."""
@@ -59,7 +61,7 @@ async def run_autogen() -> None:
 
 async def run_agent_framework() -> None:
     """Agent Framework's GroupChatBuilder with LLM-based speaker selection."""
-    from agent_framework import AgentRunUpdateEvent, GroupChatBuilder
+    from agent_framework import GroupChatBuilder
     from agent_framework.openai import OpenAIChatClient
 
     client = OpenAIChatClient(model_id="gpt-4.1-mini")
@@ -100,7 +102,7 @@ async def run_agent_framework() -> None:
     print("[Agent Framework] Group chat conversation:")
     current_executor = None
     async for event in workflow.run_stream("How do I connect to a PostgreSQL database using Python?"):
-        if isinstance(event, AgentRunUpdateEvent):
+        if isinstance(event, WorkflowOutputEvent) and isinstance(event.data, AgentResponseUpdate):
             # Print executor name header when switching to a new agent
             if current_executor != event.executor_id:
                 if current_executor is not None:

python/samples/autogen-migration/orchestrations/03_swarm.py

@@ -7,6 +7,8 @@ to other specialized agents based on the task requirements.
 
 import asyncio
 
+from agent_framework import AgentResponseUpdate, HandoffAgentUserRequest, WorkflowOutputEvent
+
 
 async def run_autogen() -> None:
     """AutoGen's Swarm pattern with human-in-the-loop handoffs."""
@@ -96,9 +98,7 @@ async def run_autogen() -> None:
 async def run_agent_framework() -> None:
     """Agent Framework's HandoffBuilder for agent coordination."""
     from agent_framework import (
-        AgentRunUpdateEvent,
         HandoffBuilder,
-        HandoffUserInputRequest,
         RequestInfoEvent,
         WorkflowRunState,
         WorkflowStatusEvent,
@@ -139,7 +139,7 @@ async def run_agent_framework() -> None:
             name="support_handoff",
             participants=[triage_agent, billing_agent, tech_support],
         )
-        .set_coordinator(triage_agent)
+        .with_start_agent(triage_agent)
         .add_handoff(triage_agent, [billing_agent, tech_support])
         .with_termination_condition(lambda conv: sum(1 for msg in conv if msg.role == "user") > 3)
         .build()
@@ -162,7 +162,7 @@ async def run_agent_framework() -> None:
     pending_requests: list[RequestInfoEvent] = []
 
     async for event in workflow.run_stream(scripted_responses[0]):
-        if isinstance(event, AgentRunUpdateEvent):
+        if isinstance(event, WorkflowOutputEvent) and isinstance(event.data, AgentResponseUpdate):
             # Print executor name header when switching to a new agent
             if current_executor != event.executor_id:
                 if stream_line_open:
@@ -174,7 +174,7 @@ async def run_agent_framework() -> None:
             if event.data:
                 print(event.data.text, end="", flush=True)
         elif isinstance(event, RequestInfoEvent):
-            if isinstance(event.data, HandoffUserInputRequest):
+            if isinstance(event.data, HandoffAgentUserRequest):
                 pending_requests.append(event)
         elif isinstance(event, WorkflowStatusEvent):
             if event.state in {WorkflowRunState.IDLE_WITH_PENDING_REQUESTS} and stream_line_open:
@@ -194,7 +194,7 @@ async def run_agent_framework() -> None:
         stream_line_open = False
 
         async for event in workflow.send_responses_streaming(responses):
-            if isinstance(event, AgentRunUpdateEvent):
+            if isinstance(event, WorkflowOutputEvent) and isinstance(event.data, AgentResponseUpdate):
                 # Print executor name header when switching to a new agent
                 if current_executor != event.executor_id:
                     if stream_line_open:
@@ -206,7 +206,7 @@ async def run_agent_framework() -> None:
                 if event.data:
                     print(event.data.text, end="", flush=True)
             elif isinstance(event, RequestInfoEvent):
-                if isinstance(event.data, HandoffUserInputRequest):
+                if isinstance(event.data, HandoffAgentUserRequest):
                     pending_requests.append(event)
             elif isinstance(event, WorkflowStatusEvent):
                 if (

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

@@ -10,7 +10,7 @@ import json
 from typing import cast
 
 from agent_framework import (
-    AgentRunUpdateEvent,
+    AgentResponseUpdate,
     ChatMessage,
     MagenticOrchestratorEvent,
     MagenticProgressLedger,
@@ -113,7 +113,7 @@ async def run_agent_framework() -> None:
     output_event: WorkflowOutputEvent | None = None
     print("[Agent Framework] Magentic conversation:")
     async for event in workflow.run_stream("Research Python async patterns and write a simple example"):
-        if isinstance(event, AgentRunUpdateEvent):
+        if isinstance(event, WorkflowOutputEvent) and isinstance(event.data, AgentResponseUpdate):
             message_id = event.data.message_id
             if message_id != last_message_id:
                 if last_message_id is not None:

python/samples/getting_started/workflows/_start-here/step2_agents_in_a_workflow.py

@@ -1,26 +1,26 @@
 # Copyright (c) Microsoft. All rights reserved.
 
 import asyncio
+from typing import cast
 
-from agent_framework import AgentRunEvent, WorkflowBuilder
+from agent_framework import AgentResponse, WorkflowBuilder
 from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
 
 """
 Step 2: Agents in a Workflow non-streaming
 
-This sample uses two custom executors. A Writer agent creates or edits content,
-then hands the conversation to a Reviewer agent which evaluates and finalizes the result.
+This sample creates two agents: a Writer agent creates or edits content, and a Reviewer agent which
+evaluates and provides feedback.
 
 Purpose:
-Show how to wrap chat agents created by AzureOpenAIChatClient inside workflow executors. Demonstrate how agents
-automatically yield outputs when they complete, removing the need for explicit completion events.
-The workflow completes when it becomes idle.
+Show how to create agents from AzureOpenAIChatClient and use them directly in a workflow. Demonstrate
+how agents can be used in a workflow.
 
 Prerequisites:
 - Azure OpenAI configured for AzureOpenAIChatClient with required environment variables.
 - Authentication via azure-identity. Use AzureCliCredential and run az login before executing the sample.
-- Basic familiarity with WorkflowBuilder, executors, edges, events, and streaming or non streaming runs.
+- Basic familiarity with WorkflowBuilder, edges, events, and streaming or non-streaming runs.
 """
 
 
@@ -51,34 +51,26 @@ async def main():
     # Run the workflow with the user's initial message.
     # For foundational clarity, use run (non streaming) and print the terminal event.
     events = await workflow.run("Create a slogan for a new electric SUV that is affordable and fun to drive.")
-    # Print agent run events and final outputs
-    for event in events:
-        if isinstance(event, AgentRunEvent):
-            print(f"{event.executor_id}: {event.data}")
 
-    print(f"{'=' * 60}\nWorkflow Outputs: {events.get_outputs()}")
+    outputs = events.get_outputs()
+    # The outputs of the workflow are whatever the agents produce. So the outputs are expected to be a list
+    # of `AgentResponse` from the agents in the workflow.
+    outputs = cast(list[AgentResponse], outputs)
+    for output in outputs:
+        # TODO: author_name should be available in AgentResponse
+        print(f"{output.messages[0].author_name}: {output.text}\n")
+
     # Summarize the final run state (e.g., COMPLETED)
     print("Final state:", events.get_final_state())
 
     """
-    Sample Output:
+    writer: "Charge Ahead: Affordable Adventure Awaits!"
 
-    writer: "Charge Up Your Adventure—Affordable Fun, Electrified!"
-    reviewer: Slogan: "Plug Into Fun—Affordable Adventure, Electrified."
+    reviewer: - Consider emphasizing both affordability and fun in a more dynamic way. 
+    - Try using a catchy phrase that includes a play on words, like “Electrify Your Drive: Fun Meets Affordability!”
+    - Ensure the slogan is succinct while capturing the essence of the car's unique selling proposition.
 
-    **Feedback:**
-    - Clear focus on affordability and enjoyment.
-    - "Plug into fun" connects emotionally and highlights electric nature.
-    - Consider specifying "SUV" for clarity in some uses.
-    - Strong, upbeat tone suitable for marketing.
-    ============================================================
-    Workflow Outputs: ['Slogan: "Plug Into Fun—Affordable Adventure, Electrified."
-
-    **Feedback:**
-    - Clear focus on affordability and enjoyment.
-    - "Plug into fun" connects emotionally and highlights electric nature.
-    - Consider specifying "SUV" for clarity in some uses.
-    - Strong, upbeat tone suitable for marketing.']
+    Final state: WorkflowRunState.IDLE
     """
 
 

python/samples/getting_started/workflows/_start-here/step3_streaming.py

@@ -2,36 +2,20 @@
 
 import asyncio
 
-from agent_framework import (
-    ChatAgent,
-    ChatMessage,
-    Executor,
-    ExecutorFailedEvent,
-    WorkflowBuilder,
-    WorkflowContext,
-    WorkflowFailedEvent,
-    WorkflowRunState,
-    WorkflowStatusEvent,
-    handler,
-)
+from agent_framework import AgentResponseUpdate, ChatMessage, WorkflowBuilder
 from agent_framework._workflows._events import WorkflowOutputEvent
 from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
-from typing_extensions import Never
 
 """
 Step 3: Agents in a workflow with streaming
 
-A Writer agent generates content,
-then passes the conversation to a Reviewer agent that finalizes the result.
-The workflow is invoked with run_stream so you can observe events as they occur.
+This sample creates two agents: a Writer agent creates or edits content, and a Reviewer agent which
+evaluates and provides feedback.
 
 Purpose:
-Show how to wrap chat agents created by AzureOpenAIChatClient inside workflow executors, wire them with WorkflowBuilder,
-and consume streaming events from the workflow. Demonstrate the @handler pattern with typed inputs and typed
-WorkflowContext[T_Out, T_W_Out] outputs. Agents automatically yield outputs when they complete.
-The streaming loop also surfaces WorkflowEvent.origin so you can distinguish runner-generated lifecycle events
-from executor-generated data-plane events.
+Show how to create agents from AzureOpenAIChatClient and use them directly in a workflow. Demonstrate
+how agents can be used in a workflow.
 
 Prerequisites:
 - Azure OpenAI configured for AzureOpenAIChatClient with required environment variables.
@@ -40,125 +24,59 @@ Prerequisites:
 """
 
 
-class Writer(Executor):
-    """Custom executor that owns a domain specific agent for content generation.
-
-    This class demonstrates:
-    - Attaching a ChatAgent to an Executor so it participates as a node in a workflow.
-    - Using a @handler method to accept a typed input and forward a typed output via ctx.send_message.
-    """
-
-    agent: ChatAgent
-
-    def __init__(self, chat_client: AzureOpenAIChatClient, id: str = "writer"):
-        # Create a domain specific agent using your configured AzureOpenAIChatClient.
-        self.agent = chat_client.as_agent(
-            instructions=(
-                "You are an excellent content writer. You create new content and edit contents based on the feedback."
-            ),
-        )
-        # Associate this agent with the executor node. The base Executor stores it on self.agent.
-        super().__init__(id=id)
-
-    @handler
-    async def handle(self, message: ChatMessage, ctx: WorkflowContext[list[ChatMessage]]) -> None:
-        """Generate content and forward the updated conversation.
-
-        Contract for this handler:
-        - message is the inbound user ChatMessage.
-        - ctx is a WorkflowContext that expects a list[ChatMessage] to be sent downstream.
-
-        Pattern shown here:
-        1) Seed the conversation with the inbound message.
-        2) Run the attached agent to produce assistant messages.
-        3) Forward the cumulative messages to the next executor with ctx.send_message.
-        """
-        # Start the conversation with the incoming user message.
-        messages: list[ChatMessage] = [message]
-        # Run the agent and extend the conversation with the agent's messages.
-        response = await self.agent.run(messages)
-        messages.extend(response.messages)
-        # Forward the accumulated messages to the next executor in the workflow.
-        await ctx.send_message(messages)
-
-
-class Reviewer(Executor):
-    """Custom executor that owns a review agent and completes the workflow."""
-
-    agent: ChatAgent
-
-    def __init__(self, chat_client: AzureOpenAIChatClient, id: str = "reviewer"):
-        # Create a domain specific agent that evaluates and refines content.
-        self.agent = chat_client.as_agent(
-            instructions=(
-                "You are an excellent content reviewer. You review the content and provide feedback to the writer."
-            ),
-        )
-        super().__init__(id=id)
-
-    @handler
-    async def handle(self, messages: list[ChatMessage], ctx: WorkflowContext[Never, str]) -> None:
-        """Review the full conversation transcript and yield the final output.
-
-        This node consumes all messages so far. It uses its agent to produce the final text,
-        then yields the output. The workflow completes when it becomes idle.
-        """
-        response = await self.agent.run(messages)
-        await ctx.yield_output(response.text)
-
-
 async def main():
     """Build the two node workflow and run it with streaming to observe events."""
     # Create the Azure chat client. AzureCliCredential uses your current az login.
     chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
-    # Instantiate the two agent backed executors.
-    writer = Writer(chat_client)
-    reviewer = Reviewer(chat_client)
+    writer_agent = chat_client.as_agent(
+        instructions=(
+            "You are an excellent content writer. You create new content and edit contents based on the feedback."
+        ),
+        name="writer",
+    )
+
+    reviewer_agent = chat_client.as_agent(
+        instructions=(
+            "You are an excellent content reviewer."
+            "Provide actionable feedback to the writer about the provided content."
+            "Provide the feedback in the most concise manner possible."
+        ),
+        name="reviewer",
+    )
 
     # 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().set_start_executor(writer_agent).add_edge(writer_agent, reviewer_agent).build()
+
+    # Track the last author to format streaming output.
+    last_author: str | None = None
 
     # Run the workflow with the user's initial message and stream events as they occur.
-    # This surfaces executor events, workflow outputs, run-state changes, and errors.
     async for event in workflow.run_stream(
         ChatMessage("user", ["Create a slogan for a new electric SUV that is affordable and fun to drive."])
     ):
-        if isinstance(event, WorkflowStatusEvent):
-            prefix = f"State ({event.origin.value}): "
-            if event.state == WorkflowRunState.IN_PROGRESS:
-                print(prefix + "IN_PROGRESS")
-            elif event.state == WorkflowRunState.IN_PROGRESS_PENDING_REQUESTS:
-                print(prefix + "IN_PROGRESS_PENDING_REQUESTS (requests in flight)")
-            elif event.state == WorkflowRunState.IDLE:
-                print(prefix + "IDLE (no active work)")
-            elif event.state == WorkflowRunState.IDLE_WITH_PENDING_REQUESTS:
-                print(prefix + "IDLE_WITH_PENDING_REQUESTS (prompt user or UI now)")
+        # The outputs of the workflow are whatever the agents produce. So the events are expected to
+        # contain `AgentResponseUpdate` from the agents in the workflow.
+        if isinstance(event, WorkflowOutputEvent) and isinstance(event.data, AgentResponseUpdate):
+            update = event.data
+            author = update.author_name
+            if author != last_author:
+                if last_author is not None:
+                    print()  # Newline between different authors
+                print(f"{author}: {update.text}", end="", flush=True)
+                last_author = author
             else:
-                print(prefix + str(event.state))
-        elif isinstance(event, WorkflowOutputEvent):
-            print(f"Workflow output ({event.origin.value}): {event.data}")
-        elif isinstance(event, ExecutorFailedEvent):
-            print(
-                f"Executor failed ({event.origin.value}): "
-                f"{event.executor_id} {event.details.error_type}: {event.details.message}"
-            )
-        elif isinstance(event, WorkflowFailedEvent):
-            details = event.details
-            print(f"Workflow failed ({event.origin.value}): {details.error_type}: {details.message}")
-        else:
-            print(f"{event.__class__.__name__} ({event.origin.value}): {event}")
+                print(update.text, end="", flush=True)
 
     """
-    Sample Output:
+    writer: "Electrify Your Journey: Affordable Fun Awaits!"
+    reviewer: Feedback:
 
-    State (RUNNER): IN_PROGRESS
-    ExecutorInvokeEvent (RUNNER): ExecutorInvokeEvent(executor_id=writer)
-    ExecutorCompletedEvent (RUNNER): ExecutorCompletedEvent(executor_id=writer)
-    ExecutorInvokeEvent (RUNNER): ExecutorInvokeEvent(executor_id=reviewer)
-    Workflow output (EXECUTOR): Drive the Future. Affordable Adventure, Electrified.
-    ExecutorCompletedEvent (RUNNER): ExecutorCompletedEvent(executor_id=reviewer)
-    State (RUNNER): IDLE
+    1. **Clarity**: Consider simplifying the message. "Affordable Fun" could be more direct.
+    2. **Emotional Appeal**: Emphasize the thrill of driving more. Try using words that evoke excitement.
+    3. **Unique Selling Proposition**: Highlight the electric aspect more boldly.
+
+    Example revision: "Charge Your Adventure: Affordable SUVs for Fun-Loving Drivers!"
     """
 
 

python/samples/getting_started/workflows/_start-here/step4_using_factories.py

@@ -3,7 +3,7 @@
 import asyncio
 
 from agent_framework import (
-    AgentResponse,
+    AgentResponseUpdate,
     ChatAgent,
     Executor,
     WorkflowBuilder,
@@ -77,26 +77,28 @@ async def main():
         WorkflowBuilder()
         .register_executor(lambda: UpperCase(id="upper_case_executor"), name="UpperCase")
         .register_executor(lambda: reverse_text, name="ReverseText")
-        .register_agent(create_agent, name="DecoderAgent", output_response=True)
+        .register_agent(create_agent, name="DecoderAgent")
         .add_chain(["UpperCase", "ReverseText", "DecoderAgent"])
         .set_start_executor("UpperCase")
         .build()
     )
 
-    output: AgentResponse | None = None
+    first_update = True
     async for event in workflow.run_stream("hello world"):
-        if isinstance(event, WorkflowOutputEvent) and isinstance(event.data, AgentResponse):
-            output = event.data
-
-    if output:
-        print(f"Decoded output: {output.text}")
-    else:
-        print("No output received.")
+        # The outputs of the workflow are whatever the agents produce. So the events are expected to
+        # contain `AgentResponseUpdate` from the agents in the workflow.
+        if isinstance(event, WorkflowOutputEvent) and isinstance(event.data, AgentResponseUpdate):
+            update = event.data
+            if first_update:
+                print(f"{update.author_name}: {update.text}", end="", flush=True)
+                first_update = False
+            else:
+                print(update.text, end="", flush=True)
 
     """
     Sample Output:
 
-    HELLO WORLD
+    decoder: HELLO WORLD
     """
 
 

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

@@ -2,22 +2,14 @@
 
 import asyncio
 
-from agent_framework import AgentRunUpdateEvent, ChatAgent, WorkflowBuilder, WorkflowOutputEvent
+from agent_framework import AgentResponseUpdate, WorkflowBuilder, WorkflowOutputEvent
 from agent_framework.azure import AzureAIAgentClient
 from azure.identity.aio import AzureCliCredential
 
 """
-Sample: Agents in a workflow with streaming
+Sample: Azure AI Agents in a Workflow with Streaming
 
-A Writer agent generates content, then a Reviewer agent critiques it.
-The workflow uses streaming so you can observe incremental AgentRunUpdateEvent chunks as each agent produces tokens.
-
-Purpose:
-Show how to wire chat agents into a WorkflowBuilder pipeline by adding agents directly as edges.
-
-Demonstrate:
-- Automatic streaming of agent deltas via AgentRunUpdateEvent when using run_stream().
-- Agents adapt to workflow mode: run_stream() emits incremental updates, run() emits complete responses.
+This sample shows how to create Azure AI Agents and use them in a workflow with streaming.
 
 Prerequisites:
 - Azure AI Agent Service configured, along with the required environment variables.
@@ -26,54 +18,46 @@ Prerequisites:
 """
 
 
-def create_writer_agent(client: AzureAIAgentClient) -> ChatAgent:
-    return client.as_agent(
-        name="Writer",
-        instructions=(
-            "You are an excellent content writer. You create new content and edit contents based on the feedback."
-        ),
-    )
-
-
-def create_reviewer_agent(client: AzureAIAgentClient) -> ChatAgent:
-    return client.as_agent(
-        name="Reviewer",
-        instructions=(
-            "You are an excellent content reviewer. "
-            "Provide actionable feedback to the writer about the provided content. "
-            "Provide the feedback in the most concise manner possible."
-        ),
-    )
-
-
 async def main() -> None:
-    async with AzureCliCredential() as cred, AzureAIAgentClient(async_credential=cred) as client:
-        # Build the workflow by adding agents directly as edges.
-        # Agents adapt to workflow mode: run_stream() for incremental updates, run() for complete responses.
-        workflow = (
-            WorkflowBuilder()
-            .register_agent(lambda: create_writer_agent(client), name="writer")
-            .register_agent(lambda: create_reviewer_agent(client), name="reviewer", output_response=True)
-            .set_start_executor("writer")
-            .add_edge("writer", "reviewer")
-            .build()
+    async with AzureCliCredential() as cred, AzureAIAgentClient(credential=cred) as client:
+        # Create two agents: a Writer and a Reviewer.
+        writer_agent = client.as_agent(
+            name="Writer",
+            instructions=(
+                "You are an excellent content writer. You create new content and edit contents based on the feedback."
+            ),
         )
 
-        last_executor_id: str | None = None
+        reviewer_agent = client.as_agent(
+            name="Reviewer",
+            instructions=(
+                "You are an excellent content reviewer. "
+                "Provide actionable feedback to the writer about the provided content. "
+                "Provide the feedback in the most concise manner possible."
+            ),
+        )
+
+        # Build the workflow by adding agents directly as edges.
+        # Agents adapt to workflow mode: run_stream() for incremental updates, run() for complete responses.
+        workflow = WorkflowBuilder().set_start_executor(writer_agent).add_edge(writer_agent, reviewer_agent).build()
+
+        # Track the last author to format streaming output.
+        last_author: str | None = None
 
         events = workflow.run_stream("Create a slogan for a new electric SUV that is affordable and fun to drive.")
         async for event in events:
-            if isinstance(event, AgentRunUpdateEvent):
-                eid = event.executor_id
-                if eid != last_executor_id:
-                    if last_executor_id is not None:
-                        print()
-                    print(f"{eid}:", end=" ", flush=True)
-                    last_executor_id = eid
-                print(event.data, end="", flush=True)
-            elif isinstance(event, WorkflowOutputEvent):
-                print("\n===== Final output =====")
-                print(event.data)
+            # The outputs of the workflow are whatever the agents produce. So the events are expected to
+            # contain `AgentResponseUpdate` from the agents in the workflow.
+            if isinstance(event, WorkflowOutputEvent) and isinstance(event.data, AgentResponseUpdate):
+                update = event.data
+                author = update.author_name
+                if author != last_author:
+                    if last_author is not None:
+                        print()  # Newline between different authors
+                    print(f"{author}: {update.text}", end="", flush=True)
+                    last_author = author
+                else:
+                    print(update.text, end="", flush=True)
 
 
 if __name__ == "__main__":

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

@@ -6,8 +6,7 @@ from typing import Final
 from agent_framework import (
     AgentExecutorRequest,
     AgentExecutorResponse,
-    AgentResponse,
-    AgentRunUpdateEvent,
+    AgentResponseUpdate,
     ChatMessage,
     WorkflowBuilder,
     WorkflowContext,
@@ -18,7 +17,7 @@ from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
 
 """
-Sample: Two agents connected by a function executor bridge
+Sample: AzureOpenAI Chat Agents and an Executor in a Workflow with Streaming
 
 Pipeline layout:
 research_agent -> enrich_with_references (@executor) -> final_editor_agent
@@ -30,7 +29,6 @@ The final agent incorporates the new note and produces the polished output.
 Demonstrates:
 - Using the @executor decorator to create a function-style Workflow node.
 - Consuming an AgentExecutorResponse and forwarding an AgentExecutorRequest for the next agent.
-- Streaming AgentRunUpdateEvent events across agent + function + agent chain.
 
 Prerequisites:
 - Azure OpenAI configured for AzureOpenAIChatClient with required environment variables.
@@ -68,7 +66,14 @@ async def enrich_with_references(
     draft: AgentExecutorResponse,
     ctx: WorkflowContext[AgentExecutorRequest],
 ) -> None:
-    """Inject a follow-up user instruction that adds an external note for the next agent."""
+    """Inject a follow-up user instruction that adds an external note for the next agent.
+
+    Args:
+        draft: The response from the research_agent containing the initial draft. This is
+               a `AgentExecutorResponse` because agents in workflows send their full response
+               wrapped in this type to connected executors.
+        ctx: The workflow context to send the next request.
+    """
     conversation = list(draft.full_conversation or draft.agent_response.messages)
     original_prompt = next((message.text for message in conversation if message.role == "user"), "")
     external_note = _lookup_external_note(original_prompt) or (
@@ -82,20 +87,22 @@ async def enrich_with_references(
     )
     conversation.append(ChatMessage("user", [follow_up]))
 
+    # Output a new AgentExecutorRequest for the next agent in the workflow.
+    # Agents in workflows handle this type and will generate a response based on the request.
     await ctx.send_message(AgentExecutorRequest(messages=conversation))
 
 
-def create_research_agent():
-    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+async def main() -> None:
+    """Run the workflow and stream combined updates from both agents."""
+    # Create the agents
+    research_agent = AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
         name="research_agent",
         instructions=(
             "Produce a short, bullet-style briefing with two actionable ideas. Label the section as 'Initial Draft'."
         ),
     )
 
-
-def create_final_editor_agent():
-    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+    final_editor_agent = AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
         name="final_editor_agent",
         instructions=(
             "Use all conversation context (including external notes) to produce the final answer. "
@@ -103,17 +110,11 @@ def create_final_editor_agent():
         ),
     )
 
-
-async def main() -> None:
-    """Run the workflow and stream combined updates from both agents."""
     workflow = (
         WorkflowBuilder()
-        .register_agent(create_research_agent, name="research_agent")
-        .register_agent(create_final_editor_agent, name="final_editor_agent")
-        .register_executor(lambda: enrich_with_references, name="enrich_with_references")
-        .set_start_executor("research_agent")
-        .add_edge("research_agent", "enrich_with_references")
-        .add_edge("enrich_with_references", "final_editor_agent")
+        .set_start_executor(research_agent)
+        .add_edge(research_agent, enrich_with_references)
+        .add_edge(enrich_with_references, final_editor_agent)
         .build()
     )
 
@@ -121,22 +122,22 @@ async def main() -> None:
         "Create quick workspace wellness tips for a remote analyst working across two monitors."
     )
 
-    last_executor: str | None = None
+    # Track the last author to format streaming output.
+    last_author: str | None = None
+
     async for event in events:
-        if isinstance(event, AgentRunUpdateEvent):
-            if event.executor_id != last_executor:
-                if last_executor is not None:
-                    print()
-                print(f"{event.executor_id}:", end=" ", flush=True)
-                last_executor = event.executor_id
-            print(event.data, end="", flush=True)
-        elif isinstance(event, WorkflowOutputEvent):
-            print("\n\n===== Final Output =====")
-            response = event.data
-            if isinstance(response, AgentResponse):
-                print(response.text or "(empty response)")
+        # The outputs of the workflow are whatever the agents produce. So the events are expected to
+        # contain `AgentResponseUpdate` from the agents in the workflow.
+        if isinstance(event, WorkflowOutputEvent) and isinstance(event.data, AgentResponseUpdate):
+            update = event.data
+            author = update.author_name
+            if author != last_author:
+                if last_author is not None:
+                    print("\n")  # Newline between different authors
+                print(f"{author}: {update.text}", end="", flush=True)
+                last_author = author
             else:
-                print(response if response is not None else "No response generated.")
+                print(update.text, end="", flush=True)
 
 
 if __name__ == "__main__":

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

@@ -2,22 +2,14 @@
 
 import asyncio
 
-from agent_framework import AgentRunUpdateEvent, WorkflowBuilder, WorkflowOutputEvent
+from agent_framework import AgentResponseUpdate, WorkflowBuilder, WorkflowOutputEvent
 from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
 
 """
-Sample: Agents in a workflow with streaming
+Sample: AzureOpenAI Chat Agents in a Workflow with Streaming
 
-A Writer agent generates content, then a Reviewer agent critiques it.
-The workflow uses streaming so you can observe incremental AgentRunUpdateEvent chunks as each agent produces tokens.
-
-Purpose:
-Show how to wire chat agents into a WorkflowBuilder pipeline by adding agents directly as edges.
-
-Demonstrate:
-- Automatic streaming of agent deltas via AgentRunUpdateEvent when using run_stream().
-- Agents adapt to workflow mode: run_stream() emits incremental updates, run() emits complete responses.
+This sample shows how to create AzureOpenAI Chat Agents and use them in a workflow with streaming.
 
 Prerequisites:
 - Azure OpenAI configured for AzureOpenAIChatClient with required environment variables.
@@ -26,17 +18,17 @@ Prerequisites:
 """
 
 
-def create_writer_agent():
-    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+async def main():
+    """Build and run a simple two node agent workflow: Writer then Reviewer."""
+    # Create the agents
+    writer_agent = AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
         instructions=(
             "You are an excellent content writer. You create new content and edit contents based on the feedback."
         ),
         name="writer",
     )
 
-
-def create_reviewer_agent():
-    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+    reviewer_agent = AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
         instructions=(
             "You are an excellent content reviewer."
             "Provide actionable feedback to the writer about the provided content."
@@ -45,50 +37,28 @@ def create_reviewer_agent():
         name="reviewer",
     )
 
-
-async def main():
-    """Build and run a simple two node agent workflow: Writer then Reviewer."""
     # 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() for incremental updates, run() for complete responses.
-    workflow = (
-        WorkflowBuilder()
-        .register_agent(create_writer_agent, name="writer")
-        .register_agent(create_reviewer_agent, name="reviewer", output_response=True)
-        .set_start_executor("writer")
-        .add_edge("writer", "reviewer")
-        .build()
-    )
+    workflow = WorkflowBuilder().set_start_executor(writer_agent).add_edge(writer_agent, reviewer_agent).build()
 
-    # Stream events from the workflow. We aggregate partial token updates per executor for readable output.
-    last_executor_id: str | None = None
+    # Track the last author to format streaming output.
+    last_author: str | None = None
 
     events = workflow.run_stream("Create a slogan for a new electric SUV that is affordable and fun to drive.")
     async for event in events:
-        if isinstance(event, AgentRunUpdateEvent):
-            # AgentRunUpdateEvent contains incremental text deltas from the underlying agent.
-            # Print a prefix when the executor changes, then append updates on the same line.
-            eid = event.executor_id
-            if eid != last_executor_id:
-                if last_executor_id is not None:
-                    print()
-                print(f"{eid}:", end=" ", flush=True)
-                last_executor_id = eid
-            print(event.data, end="", flush=True)
-        elif isinstance(event, WorkflowOutputEvent):
-            print("\n===== Final output =====")
-            print(event.data)
-
-    """
-    Sample Output:
-
-    writer_agent: Charge Up Your Journey. Fun, Affordable, Electric.
-    reviewer_agent: Clear message, but consider highlighting SUV specific benefits (space, versatility) for stronger
-        impact. Try more vivid language to evoke excitement. Example: "Big on Space. Big on Fun. Electric for Everyone."
-    ===== Final Output =====
-    Clear message, but consider highlighting SUV specific benefits (space, versatility) for stronger impact. Try more
-        vivid language to evoke excitement. Example: "Big on Space. Big on Fun. Electric for Everyone."
-    """
+        # The outputs of the workflow are whatever the agents produce. So the events are expected to
+        # contain `AgentResponseUpdate` from the agents in the workflow.
+        if isinstance(event, WorkflowOutputEvent) and isinstance(event.data, AgentResponseUpdate):
+            update = event.data
+            author = update.author_name
+            if author != last_author:
+                if last_author is not None:
+                    print()  # Newline between different authors
+                print(f"{author}: {update.text}", end="", flush=True)
+                last_author = author
+            else:
+                print(update.text, end="", flush=True)
 
 
 if __name__ == "__main__":

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

@@ -1,324 +0,0 @@
-# Copyright (c) Microsoft. All rights reserved.
-
-import asyncio
-import json
-from dataclasses import dataclass, field
-from typing import Annotated
-
-from agent_framework import (
-    AgentExecutorRequest,
-    AgentExecutorResponse,
-    AgentResponse,
-    AgentRunUpdateEvent,
-    ChatAgent,
-    ChatMessage,
-    Executor,
-    FunctionCallContent,
-    FunctionResultContent,
-    RequestInfoEvent,
-    WorkflowBuilder,
-    WorkflowContext,
-    WorkflowOutputEvent,
-    handler,
-    response_handler,
-    tool,
-)
-from agent_framework.azure import AzureOpenAIChatClient
-from azure.identity import AzureCliCredential
-from pydantic import Field
-from typing_extensions import Never
-
-"""
-Sample: Tool-enabled agents with human feedback
-
-Pipeline layout:
-writer_agent (uses Azure OpenAI tools) -> Coordinator -> writer_agent
--> Coordinator -> final_editor_agent -> Coordinator -> output
-
-The writer agent calls tools to gather product facts before drafting copy. A custom executor
-packages the draft and emits a RequestInfoEvent so a human can comment, then replays the human
-guidance back into the conversation before the final editor agent produces the polished output.
-
-Demonstrates:
-- Attaching Python function tools to an agent inside a workflow.
-- Capturing the writer's output for human review.
-- Streaming AgentRunUpdateEvent updates alongside human-in-the-loop pauses.
-
-Prerequisites:
-- Azure OpenAI configured for AzureOpenAIChatClient with required environment variables.
-- Authentication via azure-identity. Run `az login` before executing.
-"""
-
-
-# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
-@tool(approval_mode="never_require")
-def fetch_product_brief(
-    product_name: Annotated[str, Field(description="Product name to look up.")],
-) -> str:
-    """Return a marketing brief for a product."""
-    briefs = {
-        "lumenx desk lamp": (
-            "Product: LumenX Desk Lamp\n"
-            "- Three-point adjustable arm with 270° rotation.\n"
-            "- Custom warm-to-neutral LED spectrum (2700K-4000K).\n"
-            "- USB-C charging pad integrated in the base.\n"
-            "- Designed for home offices and late-night study sessions."
-        )
-    }
-    return briefs.get(product_name.lower(), f"No stored brief for '{product_name}'.")
-
-
-@tool(approval_mode="never_require")
-def get_brand_voice_profile(
-    voice_name: Annotated[str, Field(description="Brand or campaign voice to emulate.")],
-) -> str:
-    """Return guidance for the requested brand voice."""
-    voices = {
-        "lumenx launch": (
-            "Voice guidelines:\n"
-            "- Friendly and modern with concise sentences.\n"
-            "- Highlight practical benefits before aesthetics.\n"
-            "- End with an invitation to imagine the product in daily use."
-        )
-    }
-    return voices.get(voice_name.lower(), f"No stored voice profile for '{voice_name}'.")
-
-
-@dataclass
-class DraftFeedbackRequest:
-    """Payload sent for human review."""
-
-    prompt: str = ""
-    draft_text: str = ""
-    conversation: list[ChatMessage] = field(default_factory=list)  # type: ignore[reportUnknownVariableType]
-
-
-class Coordinator(Executor):
-    """Bridge between the writer agent, human feedback, and final editor."""
-
-    def __init__(self, id: str, writer_id: str, final_editor_id: str) -> None:
-        super().__init__(id)
-        self.writer_id = writer_id
-        self.final_editor_id = final_editor_id
-
-    @handler
-    async def on_writer_response(
-        self,
-        draft: AgentExecutorResponse,
-        ctx: WorkflowContext[Never, AgentResponse],
-    ) -> None:
-        """Handle responses from the other two agents in the workflow."""
-        if draft.executor_id == self.final_editor_id:
-            # Final editor response; yield output directly.
-            await ctx.yield_output(draft.agent_response)
-            return
-
-        # Writer agent response; request human feedback.
-        # Preserve the full conversation so the final editor
-        # can see tool traces and the initial prompt.
-        conversation: list[ChatMessage]
-        if draft.full_conversation is not None:
-            conversation = list(draft.full_conversation)
-        else:
-            conversation = list(draft.agent_response.messages)
-        draft_text = draft.agent_response.text.strip()
-        if not draft_text:
-            draft_text = "No draft text was produced."
-
-        prompt = (
-            "Review the draft from the writer and provide a short directional note "
-            "(tone tweaks, must-have detail, target audience, etc.). "
-            "Keep it under 30 words."
-        )
-        await ctx.request_info(
-            request_data=DraftFeedbackRequest(prompt=prompt, draft_text=draft_text, conversation=conversation),
-            response_type=str,
-        )
-
-    @response_handler
-    async def on_human_feedback(
-        self,
-        original_request: DraftFeedbackRequest,
-        feedback: str,
-        ctx: WorkflowContext[AgentExecutorRequest],
-    ) -> None:
-        note = feedback.strip()
-        if note.lower() == "approve":
-            # Human approved the draft as-is; forward it unchanged.
-            await ctx.send_message(
-                AgentExecutorRequest(
-                    messages=original_request.conversation
-                    + [ChatMessage("user", text="The draft is approved as-is.")],
-                    should_respond=True,
-                ),
-                target_id=self.final_editor_id,
-            )
-            return
-
-        # Human provided feedback; prompt the writer to revise.
-        conversation: list[ChatMessage] = list(original_request.conversation)
-        instruction = (
-            "A human reviewer shared the following guidance:\n"
-            f"{note or 'No specific guidance provided.'}\n\n"
-            "Rewrite the draft from the previous assistant message into a polished final version. "
-            "Keep the response under 120 words and reflect any requested tone adjustments."
-        )
-        conversation.append(ChatMessage("user", text=instruction))
-        await ctx.send_message(
-            AgentExecutorRequest(messages=conversation, should_respond=True), target_id=self.writer_id
-        )
-
-
-def create_writer_agent() -> ChatAgent:
-    """Creates a writer agent with tools."""
-    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
-        name="writer_agent",
-        instructions=(
-            "You are a marketing writer. Call the available tools before drafting copy so you are precise. "
-            "Always call both tools once before drafting. Summarize tool outputs as bullet points, then "
-            "produce a 3-sentence draft."
-        ),
-        tools=[fetch_product_brief, get_brand_voice_profile],
-        tool_choice="required",
-    )
-
-
-def create_final_editor_agent() -> ChatAgent:
-    """Creates a final editor agent."""
-    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
-        name="final_editor_agent",
-        instructions=(
-            "You are an editor who polishes marketing copy after human approval. "
-            "Correct any legal or factual issues. Return the final version even if no changes are made. "
-        ),
-    )
-
-
-def display_agent_run_update(event: AgentRunUpdateEvent, last_executor: str | None) -> None:
-    """Display an AgentRunUpdateEvent in a readable format."""
-    printed_tool_calls: set[str] = set()
-    printed_tool_results: set[str] = set()
-    executor_id = event.executor_id
-    update = event.data
-    # Extract and print any new tool calls or results from the update.
-    function_calls = [c for c in update.contents if isinstance(c, FunctionCallContent)]  # type: ignore[union-attr]
-    function_results = [c for c in update.contents if isinstance(c, FunctionResultContent)]  # type: ignore[union-attr]
-    if executor_id != last_executor:
-        if last_executor is not None:
-            print()
-        print(f"{executor_id}:", end=" ", flush=True)
-        last_executor = executor_id
-    # Print any new tool calls before the text update.
-    for call in function_calls:
-        if call.call_id in printed_tool_calls:
-            continue
-        printed_tool_calls.add(call.call_id)
-        args = call.arguments
-        args_preview = json.dumps(args, ensure_ascii=False) if isinstance(args, dict) else (args or "").strip()
-        print(
-            f"\n{executor_id} [tool-call] {call.name}({args_preview})",
-            flush=True,
-        )
-        print(f"{executor_id}:", end=" ", flush=True)
-    # Print any new tool results before the text update.
-    for result in function_results:
-        if result.call_id in printed_tool_results:
-            continue
-        printed_tool_results.add(result.call_id)
-        result_text = result.result
-        if not isinstance(result_text, str):
-            result_text = json.dumps(result_text, ensure_ascii=False)
-        print(
-            f"\n{executor_id} [tool-result] {result.call_id}: {result_text}",
-            flush=True,
-        )
-        print(f"{executor_id}:", end=" ", flush=True)
-    # Finally, print the text update.
-    print(update, end="", flush=True)
-
-
-async def main() -> None:
-    """Run the workflow and bridge human feedback between two agents."""
-
-    # Build the workflow.
-    workflow = (
-        WorkflowBuilder()
-        .register_agent(create_writer_agent, name="writer_agent")
-        .register_agent(create_final_editor_agent, name="final_editor_agent")
-        .register_executor(
-            lambda: Coordinator(
-                id="coordinator",
-                writer_id="writer_agent",
-                final_editor_id="final_editor_agent",
-            ),
-            name="coordinator",
-        )
-        .set_start_executor("writer_agent")
-        .add_edge("writer_agent", "coordinator")
-        .add_edge("coordinator", "writer_agent")
-        .add_edge("final_editor_agent", "coordinator")
-        .add_edge("coordinator", "final_editor_agent")
-        .build()
-    )
-
-    # Switch to turn on agent run update display.
-    # By default this is off to reduce clutter during human input.
-    display_agent_run_update_switch = False
-
-    print(
-        "Interactive mode. When prompted, provide a short feedback note for the editor.",
-        flush=True,
-    )
-
-    pending_responses: dict[str, str] | None = None
-    completed = False
-    initial_run = True
-
-    while not completed:
-        last_executor: str | None = None
-        if initial_run:
-            stream = workflow.run_stream(
-                "Create a short launch blurb for the LumenX desk lamp. Emphasize adjustability and warm lighting."
-            )
-            initial_run = False
-        elif pending_responses is not None:
-            stream = workflow.send_responses_streaming(pending_responses)
-            pending_responses = None
-        else:
-            break
-
-        requests: list[tuple[str, DraftFeedbackRequest]] = []
-
-        async for event in stream:
-            if isinstance(event, AgentRunUpdateEvent) and display_agent_run_update_switch:
-                display_agent_run_update(event, last_executor)
-            if isinstance(event, RequestInfoEvent) and isinstance(event.data, DraftFeedbackRequest):
-                # Stash the request so we can prompt the human after the stream completes.
-                requests.append((event.request_id, event.data))
-                last_executor = None
-            elif isinstance(event, WorkflowOutputEvent):
-                last_executor = None
-                response = event.data
-                print("\n===== Final output =====")
-                final_text = getattr(response, "text", str(response))
-                print(final_text.strip())
-                completed = True
-
-        if requests and not completed:
-            responses: dict[str, str] = {}
-            for request_id, request in requests:
-                print("\n----- Writer draft -----")
-                print(request.draft_text.strip())
-                print("\nProvide guidance for the editor (or 'approve' to accept the draft).")
-                answer = input("Human feedback: ").strip()  # noqa: ASYNC250
-                if answer.lower() == "exit":
-                    print("Exiting...")
-                    return
-                responses[request_id] = answer
-            pending_responses = responses
-
-    print("Workflow complete.")
-
-
-if __name__ == "__main__":
-    asyncio.run(main())

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

@@ -20,10 +20,22 @@ Demonstrates:
 
 Prerequisites:
 - Azure OpenAI access configured for AzureOpenAIChatClient (use az login + env vars)
-- Familiarity with Workflow events (AgentRunEvent, WorkflowOutputEvent)
+- Familiarity with Workflow events (WorkflowOutputEvent)
 """
 
 
+def clear_and_redraw(buffers: dict[str, str], agent_order: list[str]) -> None:
+    """Clear terminal and redraw all agent outputs grouped together."""
+    # ANSI escape: clear screen and move cursor to top-left
+    print("\033[2J\033[H", end="")
+    print("===== Concurrent Agent Streaming (Live) =====\n")
+    for name in agent_order:
+        print(f"--- {name} ---")
+        print(buffers.get(name, ""))
+        print()
+    print("", end="", flush=True)
+
+
 async def main() -> None:
     # 1) Create three domain agents using AzureOpenAIChatClient
     chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
@@ -58,68 +70,13 @@ async def main() -> None:
     # 3) Expose the concurrent workflow as an agent for easy reuse
     agent = workflow.as_agent(name="ConcurrentWorkflowAgent")
     prompt = "We are launching a new budget-friendly electric bike for urban commuters."
+
     agent_response = await agent.run(prompt)
-
-    if agent_response.messages:
-        print("\n===== Aggregated Messages =====")
-        for i, msg in enumerate(agent_response.messages, start=1):
-            role = getattr(msg.role, "value", msg.role)
-            name = msg.author_name if msg.author_name else role
-            print(f"{'-' * 60}\n\n{i:02d} [{name}]:\n{msg.text}")
-
-    """
-    Sample Output:
-
-    ===== Aggregated Messages =====
-    ------------------------------------------------------------
-
-    01 [user]:
-    We are launching a new budget-friendly electric bike for urban commuters.
-    ------------------------------------------------------------
-
-    02 [researcher]:
-    **Insights:**
-
-    - **Target Demographic:** Urban commuters seeking affordable, eco-friendly transport;
-        likely to include students, young professionals, and price-sensitive urban residents.
-    - **Market Trends:** E-bike sales are growing globally, with increasing urbanization,
-        higher fuel costs, and sustainability concerns driving adoption.
-    - **Competitive Landscape:** Key competitors include brands like Rad Power Bikes, Aventon,
-        Lectric, and domestic budget-focused manufacturers in North America, Europe, and Asia.
-    - **Feature Expectations:** Customers expect reliability, ease-of-use, theft protection,
-        lightweight design, sufficient battery range for daily city commutes (typically 25-40 miles),
-        and low-maintenance components.
-
-    **Opportunities:**
-
-    - **First-time Buyers:** Capture newcomers to e-biking by emphasizing affordability, ease of
-        operation, and cost savings vs. public transit/car ownership.
-    ...
-    ------------------------------------------------------------
-
-    03 [marketer]:
-    **Value Proposition:**
-    "Empowering your city commute: Our new electric bike combines affordability, reliability, and
-        sustainable design—helping you conquer urban journeys without breaking the bank."
-
-    **Target Messaging:**
-
-    *For Young Professionals:*
-    ...
-    ------------------------------------------------------------
-
-    04 [legal]:
-    **Constraints, Disclaimers, & Policy Concerns for Launching a Budget-Friendly Electric Bike for Urban Commuters:**
-
-    **1. Regulatory Compliance**
-    - Verify that the electric bike meets all applicable federal, state, and local regulations
-        regarding e-bike classification, speed limits, power output, and safety features.
-    - Ensure necessary certifications (e.g., UL certification for batteries, CE markings if sold internationally) are obtained.
-
-    **2. Product Safety**
-    - Include consumer safety warnings regarding use, battery handling, charging protocols, and age restrictions.
-    ...
-    """  # noqa: E501
+    print("===== Final Aggregated Response =====\n")
+    for message in agent_response.messages:
+        # The agent_response contains messages from all participants concatenated
+        # into a single message.
+        print(f"{message.author_name}: {message.text}\n")
 
 
 if __name__ == "__main__":

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

@@ -14,15 +14,17 @@ from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
 
 """
-Step 2: Agents in a Workflow non-streaming
+Sample: Custom Agent Executors in a Workflow
 
 This sample uses two custom executors. A Writer agent creates or edits content,
 then hands the conversation to a Reviewer agent which evaluates and finalizes the result.
 
 Purpose:
-Show how to wrap chat agents created by AzureOpenAIChatClient inside workflow executors. Demonstrate the @handler pattern
-with typed inputs and typed WorkflowContext[T] outputs, connect executors with the fluent WorkflowBuilder, and finish
-by yielding outputs from the terminal node.
+Show how to wrap chat agents created by AzureOpenAIChatClient inside workflow executors. Demonstrate the @handler
+pattern with typed inputs and typed WorkflowContext[T] outputs, connect executors with the fluent WorkflowBuilder,
+and finish by yielding outputs from the terminal node.
+
+Note: When an agent is passed to a workflow, the workflow essenatially wrap the agent in a more sophisticated executor.
 
 Prerequisites:
 - Azure OpenAI configured for AzureOpenAIChatClient with required environment variables.
@@ -105,17 +107,13 @@ class Reviewer(Executor):
 
 async def main():
     """Build and run a simple two node agent workflow: Writer then Reviewer."""
+    # Create the executors
+    writer = Writer()
+    reviewer = Reviewer()
 
     # Build the workflow using the fluent builder.
     # Set the start node and connect an edge from writer to reviewer.
-    workflow = (
-        WorkflowBuilder()
-        .register_executor(Writer, name="writer")
-        .register_executor(Reviewer, name="reviewer")
-        .set_start_executor("writer")
-        .add_edge("writer", "reviewer")
-        .build()
-    )
+    workflow = WorkflowBuilder().set_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

@@ -41,6 +41,9 @@ async def main() -> None:
             )
         )
         .participants([researcher, writer])
+        # Enable intermediate outputs to observe the conversation as it unfolds
+        # Intermediate outputs will be emitted as WorkflowOutputEvent events
+        .with_intermediate_outputs()
         .build()
     )
 
@@ -54,6 +57,8 @@ async def main() -> None:
         agent_result = await workflow_agent.run(task)
 
         if agent_result.messages:
+            # The output should contain a message from the researcher, a message from the writer,
+            # and a final synthesized answer from the orchestrator.
             print("\n===== as_agent() Transcript =====")
             for i, msg in enumerate(agent_result.messages, start=1):
                 role_value = getattr(msg.role, "value", msg.role)

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

@@ -7,8 +7,7 @@ from agent_framework import (
     AgentResponse,
     ChatAgent,
     ChatMessage,
-    FunctionCallContent,
-    FunctionResultContent,
+    Content,
     HandoffAgentUserRequest,
     HandoffBuilder,
     WorkflowAgent,
@@ -37,7 +36,10 @@ Key Concepts:
 """
 
 
-# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
+# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
+# See:
+# samples/getting_started/tools/function_tool_with_approval.py
+# samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def process_refund(order_number: Annotated[str, "Order number to process refund for"]) -> str:
     """Simulated function to process a refund for a given order number."""
@@ -119,7 +121,7 @@ def handle_response_and_requests(response: AgentResponse) -> dict[str, HandoffAg
         if message.text:
             print(f"- {message.author_name or message.role}: {message.text}")
         for content in message.contents:
-            if isinstance(content, FunctionCallContent):
+            if content.type == "function_call":
                 if isinstance(content.arguments, dict):
                     request = WorkflowAgent.RequestInfoFunctionArgs.from_dict(content.arguments)
                 elif isinstance(content.arguments, str):
@@ -128,6 +130,7 @@ def handle_response_and_requests(response: AgentResponse) -> dict[str, HandoffAg
                     raise ValueError("Invalid arguments type. Expecting a request info structure for this sample.")
                 if isinstance(request.data, HandoffAgentUserRequest):
                     pending_requests[request.request_id] = request.data
+
     return pending_requests
 
 
@@ -196,11 +199,6 @@ async def main() -> None:
     # 1. The termination condition is met, OR
     # 2. We run out of scripted responses
     while pending_requests:
-        for request in pending_requests.values():
-            for message in request.agent_response.messages:
-                if message.text:
-                    print(f"- {message.author_name or message.role}: {message.text}")
-
         if not scripted_responses:
             # No more scripted responses; terminate the workflow
             responses = {req_id: HandoffAgentUserRequest.terminate() for req_id in pending_requests}
@@ -214,7 +212,7 @@ async def main() -> None:
             responses = {req_id: HandoffAgentUserRequest.create_response(user_response) for req_id in pending_requests}
 
         function_results = [
-            FunctionResultContent(call_id=req_id, result=response) for req_id, response in responses.items()
+            Content.from_function_result(call_id=req_id, result=response) for req_id, response in responses.items()
         ]
         response = await agent.run(ChatMessage("tool", function_results))
         pending_requests = handle_response_and_requests(response)

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

@@ -61,6 +61,9 @@ async def main() -> None:
             max_stall_count=3,
             max_reset_count=2,
         )
+        # Enable intermediate outputs to observe the conversation as it unfolds
+        # Intermediate outputs will be emitted as WorkflowOutputEvent events
+        .with_intermediate_outputs()
         .build()
     )
 
@@ -80,9 +83,17 @@ async def main() -> None:
         # Wrap the workflow as an agent for composition scenarios
         print("\nWrapping workflow as an agent and running...")
         workflow_agent = workflow.as_agent(name="MagenticWorkflowAgent")
-        async for response in workflow_agent.run_stream(task):
+
+        last_response_id: str | None = None
+        async for update in workflow_agent.run_stream(task):
             # Fallback for any other events with text
-            print(response.text, end="", flush=True)
+            if last_response_id != update.response_id:
+                if last_response_id is not None:
+                    print()  # Newline between different responses
+                print(f"{update.author_name}: ", end="", flush=True)
+                last_response_id = update.response_id
+            else:
+                print(update.text, end="", flush=True)
 
     except Exception as e:
         print(f"Workflow execution failed: {e}")

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

@@ -1,122 +0,0 @@
-# Copyright (c) Microsoft. All rights reserved.
-
-import asyncio
-from typing import Never
-
-from agent_framework import (
-    AgentExecutorResponse,
-    ChatAgent,
-    Executor,
-    HostedCodeInterpreterTool,
-    WorkflowBuilder,
-    WorkflowContext,
-    handler,
-)
-from agent_framework.azure import AzureAIAgentClient
-from azure.identity.aio import AzureCliCredential
-
-"""
-This sample demonstrates how to create a workflow that combines an AI agent executor
-with a custom executor.
-
-The workflow consists of two stages:
-1. An AI agent with code interpreter capabilities that generates and executes Python code
-2. An evaluator executor that reviews the agent's output and provides a final assessment
-
-Key concepts demonstrated:
-- Creating an AI agent with tool capabilities (HostedCodeInterpreterTool)
-- Building workflows using WorkflowBuilder with an agent and a custom executor
-- Using the @handler decorator in the executor to process AgentExecutorResponse from the agent
-- Connecting workflow executors with edges to create a processing pipeline
-- Yielding final outputs from terminal executors
-- Non-streaming workflow execution and result collection
-
-Prerequisites:
-- Azure AI services configured with required environment variables
-- Azure CLI authentication (run 'az login' before executing)
-- Basic understanding of async Python and workflow concepts
-"""
-
-
-class Evaluator(Executor):
-    """Custom executor that evaluates the output from an AI agent.
-
-    This executor demonstrates how to:
-    - Create a custom workflow executor that processes agent responses
-    - Use the @handler decorator to define the processing logic
-    - Access agent execution details including response text and usage metrics
-    - Yield final results to complete the workflow execution
-
-    The evaluator checks if the agent successfully generated the Fibonacci sequence
-    and provides feedback on correctness along with resource consumption details.
-    """
-
-    @handler
-    async def handle(self, message: AgentExecutorResponse, ctx: WorkflowContext[Never, str]) -> None:
-        """Evaluate the agent's response and complete the workflow with a final assessment.
-
-        This handler:
-        1. Receives the AgentExecutorResponse containing the agent's complete interaction
-        2. Checks if the expected Fibonacci sequence appears in the response text
-        3. Extracts usage details (token consumption, execution time, etc.)
-        4. Yields a final evaluation string to complete the workflow
-
-        Args:
-            message: The response from the Azure AI agent containing text and metadata
-            ctx: Workflow context for yielding the final output string
-        """
-        target_text = "1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89"
-        correctness = target_text in message.agent_response.text
-        consumption = message.agent_response.usage_details
-        await ctx.yield_output(f"Correctness: {correctness}, Consumption: {consumption}")
-
-
-def create_coding_agent(client: AzureAIAgentClient) -> ChatAgent:
-    """Create an AI agent with code interpretation capabilities.
-
-    This agent can generate and execute Python code to solve problems.
-
-    Args:
-        client: The AzureAIAgentClient used to create the agent
-
-    Returns:
-        A ChatAgent configured with coding instructions and tools
-    """
-    return client.as_agent(
-        name="CodingAgent",
-        instructions=("You are a helpful assistant that can write and execute Python code to solve problems."),
-        tools=HostedCodeInterpreterTool(),
-    )
-
-
-async def main():
-    async with (
-        AzureCliCredential() as credential,
-        AzureAIAgentClient(credential=credential) as chat_client,
-    ):
-        # Build a workflow: Agent generates code -> Evaluator assesses results
-        # The agent will be wrapped in a special agent executor which produces AgentExecutorResponse
-        workflow = (
-            WorkflowBuilder()
-            .register_agent(lambda: create_coding_agent(chat_client), name="coding_agent")
-            .register_executor(lambda: Evaluator(id="evaluator"), name="evaluator")
-            .set_start_executor("coding_agent")
-            .add_edge("coding_agent", "evaluator")
-            .build()
-        )
-
-        # Execute the workflow with a specific coding task
-        results = await workflow.run(
-            "Generate the fibonacci numbers to 100 using python code, show the code and execute it."
-        )
-
-        # Extract and display the final evaluation
-        outputs = results.get_outputs()
-        if isinstance(outputs, list) and len(outputs) == 1:
-            print("Workflow results:", outputs[0])
-        else:
-            raise ValueError("Unexpected workflow outputs:", outputs)
-
-
-if __name__ == "__main__":
-    asyncio.run(main())

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

@@ -50,9 +50,7 @@ async def main() -> None:
     if agent_response.messages:
         print("\n===== Conversation =====")
         for i, msg in enumerate(agent_response.messages, start=1):
-            role_value = getattr(msg.role, "value", msg.role)
-            normalized_role = str(role_value).lower() if role_value is not None else "assistant"
-            name = msg.author_name or ("assistant" if normalized_role == "assistant".value else "user")
+            name = msg.author_name or msg.role
             print(f"{'-' * 60}\n{i:02d} [{name}]\n{msg.text}")
 
     """

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

@@ -17,9 +17,8 @@ if str(_SAMPLES_ROOT) not in sys.path:
 
 from agent_framework import (  # noqa: E402
     ChatMessage,
+    Content,
     Executor,
-    FunctionCallContent,
-    FunctionResultContent,
     WorkflowAgent,
     WorkflowBuilder,
     WorkflowContext,
@@ -129,10 +128,10 @@ async def main() -> None:
     )
 
     # Locate the human review function call in the response messages.
-    human_review_function_call: FunctionCallContent | None = None
+    human_review_function_call: Content | None = None
     for message in response.messages:
         for content in message.contents:
-            if isinstance(content, FunctionCallContent) and content.name == WorkflowAgent.REQUEST_INFO_FUNCTION_NAME:
+            if content.name == WorkflowAgent.REQUEST_INFO_FUNCTION_NAME:
                 human_review_function_call = content
 
     # Handle the human review if required.
@@ -161,8 +160,8 @@ async def main() -> None:
         human_response = ReviewResponse(request_id=request_id, feedback="Approved", approved=True)
 
         # Create the function call result object to send back to the agent.
-        human_review_function_result = FunctionResultContent(
-            call_id=human_review_function_call.call_id,
+        human_review_function_result = Content.from_function_result(
+            call_id=human_review_function_call.call_id,  # type: ignore
             result=human_response,
         )
         # Send the human review result back to the agent.

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

@@ -5,11 +5,9 @@ from dataclasses import dataclass
 from uuid import uuid4
 
 from agent_framework import (
-    AgentResponseUpdate,
-    AgentRunUpdateEvent,
+    AgentResponse,
     ChatClientProtocol,
     ChatMessage,
-    Content,
     Executor,
     WorkflowBuilder,
     WorkflowContext,
@@ -31,7 +29,6 @@ approved responses are emitted to the external consumer. The workflow completes
 Key Concepts Demonstrated:
 - WorkflowAgent: Wraps a workflow to behave like a regular agent.
 - Cyclic workflow design (Worker ↔ Reviewer) for iterative improvement.
-- AgentRunUpdateEvent: Mechanism for emitting approved responses externally.
 - Structured output parsing for review feedback using Pydantic.
 - State management for pending requests and retry logic.
 
@@ -144,7 +141,9 @@ class Worker(Executor):
         self._pending_requests[request.request_id] = (request, messages)
 
     @handler
-    async def handle_review_response(self, review: ReviewResponse, ctx: WorkflowContext[ReviewRequest]) -> None:
+    async def handle_review_response(
+        self, review: ReviewResponse, ctx: WorkflowContext[ReviewRequest, AgentResponse]
+    ) -> None:
         print(f"Worker: Received review for request {review.request_id[:8]} - Approved: {review.approved}")
 
         if review.request_id not in self._pending_requests:
@@ -154,14 +153,8 @@ class Worker(Executor):
 
         if review.approved:
             print("Worker: Response approved. Emitting to external consumer...")
-            contents: list[Content] = []
-            for message in request.agent_messages:
-                contents.extend(message.contents)
-
-            # Emit approved result to external consumer via AgentRunUpdateEvent.
-            await ctx.add_event(
-                AgentRunUpdateEvent(self.id, data=AgentResponseUpdate(contents=contents, role="assistant"))
-            )
+            # Emit approved result to external consumer
+            await ctx.yield_output(AgentResponse(messages=request.agent_messages))
             return
 
         print(f"Worker: Response not approved. Feedback: {review.feedback}")
@@ -169,9 +162,7 @@ class Worker(Executor):
 
         # Incorporate review feedback.
         messages.append(ChatMessage("system", [review.feedback]))
-        messages.append(
-            ChatMessage("system", ["Please incorporate the feedback and regenerate the response."])
-        )
+        messages.append(ChatMessage("system", ["Please incorporate the feedback and regenerate the response."]))
         messages.extend(request.user_messages)
 
         # Retry with updated prompt.
@@ -217,13 +208,13 @@ async def main() -> None:
     print("-" * 50)
 
     # Run agent in streaming mode to observe incremental updates.
-    async for event in agent.run_stream(
+    response = await agent.run(
         "Write code for parallel reading 1 million files on disk and write to a sorted output file."
-    ):
-        print(f"Agent Response: {event}")
+    )
 
-    print("=" * 50)
-    print("Workflow completed!")
+    print("-" * 50)
+    print("Final Approved Response:")
+    print(f"{response.agent_id}: {response.text}")
 
 
 if __name__ == "__main__":

python/samples/getting_started/workflows/checkpoint/handoff_with_tool_approval_checkpoint_resume.py

@@ -7,6 +7,7 @@ from pathlib import Path
 from typing import cast
 
 from agent_framework import (
+    AgentResponse,
     ChatAgent,
     ChatMessage,
     Content,
@@ -26,7 +27,7 @@ from azure.identity import AzureCliCredential
 Sample: Handoff Workflow with Tool Approvals + Checkpoint Resume
 
 Demonstrates the two-step pattern for resuming a handoff workflow from a checkpoint
-while handling both HandoffUserInputRequest prompts and function approval request Content
+while handling both HandoffAgentUserRequest prompts and function approval request Content
 for tool calls (e.g., submit_refund).
 
 Scenario:
@@ -124,7 +125,7 @@ def _print_handoff_agent_user_request(response: AgentResponse) -> None:
     for message in response.messages:
         if not message.text:
             continue
-        speaker = message.author_name or message.role.value
+        speaker = message.author_name or message.role
         print(f"  {speaker}: {message.text}")
 
 
@@ -133,6 +134,7 @@ def _print_handoff_request(request: HandoffAgentUserRequest, request_id: str) ->
     print(f"\n{'=' * 60}")
     print("WORKFLOW PAUSED - User input needed")
     print(f"Request ID: {request_id}")
+    print(f"Awaiting agent: {request.agent_response.agent_id}")
 
     _print_handoff_agent_user_request(request.agent_response)
 
@@ -141,11 +143,11 @@ def _print_handoff_request(request: HandoffAgentUserRequest, request_id: str) ->
 
 def _print_function_approval_request(request: Content, request_id: str) -> None:
     """Log pending tool approval details for debugging."""
-    args = request.function_call.parse_arguments() or {}
+    args = request.function_call.parse_arguments() or {}  # type: ignore
     print(f"\n{'=' * 60}")
     print("WORKFLOW PAUSED - Tool approval required")
     print(f"Request ID: {request_id}")
-    print(f"Function: {request.function_call.name}")
+    print(f"Function: {request.function_call.name}")  # type: ignore
     print(f"Arguments:\n{json.dumps(args, indent=2)}")
     print(f"{'=' * 60}\n")
 
@@ -161,7 +163,7 @@ def _build_responses_for_requests(
     for request in pending_requests:
         if isinstance(request.data, HandoffAgentUserRequest):
             if user_response is None:
-                raise ValueError("User response is required for HandoffUserInputRequest")
+                raise ValueError("User response is required for HandoffAgentUserRequest")
             responses[request.request_id] = user_response
         elif isinstance(request.data, Content) and request.data.type == "function_approval_request":
             if approve_tools is None:
@@ -281,9 +283,9 @@ async def resume_with_responses(
 
         elif isinstance(event, WorkflowOutputEvent):
             print("\n[Workflow Output Event - Conversation Update]")
-            if event.data and isinstance(event.data, list) and all(isinstance(msg, ChatMessage) for msg in event.data):
+            if event.data and isinstance(event.data, list) and all(isinstance(msg, ChatMessage) for msg in event.data):  # type: ignore
                 # Now safe to cast event.data to list[ChatMessage]
-                conversation = cast(list[ChatMessage], event.data)
+                conversation = cast(list[ChatMessage], event.data)  # type: ignore
                 for msg in conversation[-3:]:  # Show last 3 messages
                     author = msg.author_name or msg.role
                     text = msg.text[:100] + "..." if len(msg.text) > 100 else msg.text

python/samples/getting_started/workflows/control-flow/edge_condition.py

@@ -12,7 +12,7 @@ from agent_framework import (  # Core chat primitives used to build requests
     WorkflowBuilder,  # Fluent builder for wiring executors and edges
     WorkflowContext,  # Per-run context and event bus
     executor,  # Decorator to declare a Python function as a workflow executor
-    )
+)
 from agent_framework.azure import AzureOpenAIChatClient  # Thin client wrapper for Azure OpenAI chat models
 from azure.identity import AzureCliCredential  # Uses your az CLI login for credentials
 from pydantic import BaseModel  # Structured outputs for safer parsing

python/samples/getting_started/workflows/control-flow/switch_case_edge_group.py

@@ -16,7 +16,7 @@ from agent_framework import (  # Core chat primitives used to form LLM requests
     WorkflowBuilder,  # Fluent builder for assembling the graph
     WorkflowContext,  # Per-run context and event bus
     executor,  # Decorator to turn a function into a workflow executor
-    )
+)
 from agent_framework.azure import AzureOpenAIChatClient  # Thin client for Azure OpenAI chat models
 from azure.identity import AzureCliCredential  # Uses your az CLI login for credentials
 from pydantic import BaseModel  # Structured outputs with validation

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

@@ -0,0 +1,222 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from collections.abc import AsyncIterable
+from dataclasses import dataclass, field
+
+from agent_framework import (
+    AgentExecutorRequest,
+    AgentExecutorResponse,
+    AgentResponse,
+    AgentResponseUpdate,
+    ChatMessage,
+    Executor,
+    RequestInfoEvent,
+    Role,
+    WorkflowBuilder,
+    WorkflowContext,
+    WorkflowEvent,
+    WorkflowOutputEvent,
+    handler,
+    response_handler,
+)
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+from typing_extensions import Never
+
+"""
+Sample: AzureOpenAI Chat Agents in workflow with human feedback
+
+Pipeline layout:
+writer_agent -> Coordinator -> writer_agent -> Coordinator -> final_editor_agent -> Coordinator -> output
+
+The writer agent drafts marketing copy. A custom executor emits a RequestInfoEvent so a human can comment,
+then relays the human guidance back into the conversation before the final editor agent produces the polished
+output.
+
+Demonstrates:
+- Capturing agent responses in a custom executor.
+- Emitting RequestInfoEvent to request human input.
+- Handling human feedback and routing it to the appropriate agents.
+
+Prerequisites:
+- Azure OpenAI configured for AzureOpenAIChatClient with required environment variables.
+- Authentication via azure-identity. Run `az login` before executing.
+"""
+
+
+@dataclass
+class DraftFeedbackRequest:
+    """Payload sent for human review."""
+
+    prompt: str = ""
+    conversation: list[ChatMessage] = field(default_factory=lambda: [])
+
+
+class Coordinator(Executor):
+    """Bridge between the writer agent, human feedback, and final editor."""
+
+    def __init__(self, id: str, writer_name: str, final_editor_name: str) -> None:
+        super().__init__(id)
+        self.writer_name = writer_name
+        self.final_editor_name = final_editor_name
+
+    @handler
+    async def on_writer_response(
+        self,
+        draft: AgentExecutorResponse,
+        ctx: WorkflowContext[Never, AgentResponse],
+    ) -> None:
+        """Handle responses from the writer and final editor agents."""
+        if draft.executor_id == self.final_editor_name:
+            # No further processing is needed when the final editor has responded.
+            return
+
+        # Writer agent response; request human feedback.
+        # Preserve the full conversation so that the final editor has context.
+        conversation: list[ChatMessage]
+        if draft.full_conversation is not None:
+            conversation = list(draft.full_conversation)
+        else:
+            conversation = list(draft.agent_response.messages)
+
+        prompt = (
+            "Review the draft from the writer and provide a short directional note "
+            "(tone tweaks, must-have detail, target audience, etc.). "
+            "Keep it under 30 words."
+        )
+        await ctx.request_info(
+            request_data=DraftFeedbackRequest(prompt=prompt, conversation=conversation),
+            response_type=str,
+        )
+
+    @response_handler
+    async def on_human_feedback(
+        self,
+        original_request: DraftFeedbackRequest,
+        feedback: str,
+        ctx: WorkflowContext[AgentExecutorRequest],
+    ) -> None:
+        """Process human feedback and forward to the appropriate agent."""
+        note = feedback.strip()
+        if note.lower() == "approve":
+            # Human approved the draft as-is; forward it unchanged.
+            await ctx.send_message(
+                AgentExecutorRequest(
+                    messages=original_request.conversation
+                    + [ChatMessage(Role.USER, text="The draft is approved as-is.")],
+                    should_respond=True,
+                ),
+                target_id=self.final_editor_name,
+            )
+            return
+
+        # Human provided feedback; prompt the writer to revise.
+        conversation: list[ChatMessage] = list(original_request.conversation)
+        instruction = (
+            "A human reviewer shared the following guidance:\n"
+            f"{note or 'No specific guidance provided.'}\n\n"
+            "Rewrite the draft from the previous assistant message into a polished final version. "
+            "Keep the response under 120 words and reflect any requested tone adjustments."
+        )
+        conversation.append(ChatMessage(Role.USER, text=instruction))
+        await ctx.send_message(
+            AgentExecutorRequest(messages=conversation, should_respond=True), target_id=self.writer_name
+        )
+
+
+async def process_event_stream(stream: AsyncIterable[WorkflowEvent]) -> dict[str, str] | None:
+    """Process events from the workflow stream to capture human feedback requests."""
+    # Track the last author to format streaming output.
+    last_author: str | None = None
+
+    requests: list[tuple[str, DraftFeedbackRequest]] = []
+    async for event in stream:
+        if isinstance(event, RequestInfoEvent) and isinstance(event.data, DraftFeedbackRequest):
+            requests.append((event.request_id, event.data))
+        elif isinstance(event, WorkflowOutputEvent) and isinstance(event.data, AgentResponseUpdate):
+            # This workflow should only produce AgentResponseUpdate as outputs.
+            # Streaming updates from an agent will be consecutive, because no two agents run simultaneously
+            # in this workflow. So we can use last_author to format output nicely.
+            update = event.data
+            author = update.author_name
+            if author != last_author:
+                if last_author is not None:
+                    print()  # Newline between different authors
+                print(f"{author}: {update.text}", end="", flush=True)
+                last_author = author
+            else:
+                print(update.text, end="", flush=True)
+
+    # Handle any pending human feedback requests.
+    if requests:
+        responses: dict[str, str] = {}
+        for request_id, _ in requests:
+            print("\nProvide guidance for the editor (or 'approve' to accept the draft).")
+            answer = input("Human feedback: ").strip()  # noqa: ASYNC250
+            if answer.lower() == "exit":
+                print("Exiting...")
+                return None
+            responses[request_id] = answer
+        return responses
+    return None
+
+
+async def main() -> None:
+    """Run the workflow and bridge human feedback between two agents."""
+    # Create the agents
+    writer_agent = AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+        name="writer_agent",
+        instructions=("You are a marketing writer."),
+        tool_choice="required",
+    )
+
+    final_editor_agent = AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+        name="final_editor_agent",
+        instructions=(
+            "You are an editor who polishes marketing copy after human approval. "
+            "Correct any legal or factual issues. Return the final version even if no changes are made. "
+        ),
+    )
+
+    # Create the executor
+    coordinator = Coordinator(
+        id="coordinator",
+        writer_name=writer_agent.name,  # type: ignore
+        final_editor_name=final_editor_agent.name,  # type: ignore
+    )
+
+    # Build the workflow.
+    workflow = (
+        WorkflowBuilder()
+        .set_start_executor(writer_agent)
+        .add_edge(writer_agent, coordinator)
+        .add_edge(coordinator, writer_agent)
+        .add_edge(final_editor_agent, coordinator)
+        .add_edge(coordinator, final_editor_agent)
+        .build()
+    )
+
+    print(
+        "Interactive mode. When prompted, provide a short feedback note for the editor.",
+        flush=True,
+    )
+
+    # Initiate the first run of the workflow.
+    # Runs are not isolated; state is preserved across multiple calls to run or send_responses_streaming.
+    stream = workflow.run_stream(
+        "Create a short launch blurb for the LumenX desk lamp. Emphasize adjustability and warm lighting."
+    )
+
+    pending_responses = await process_event_stream(stream)
+    while pending_responses is not None:
+        # Run the workflow until there is no more human feedback to provide,
+        # in which case this workflow completes.
+        stream = workflow.send_responses_streaming(pending_responses)
+        pending_responses = await process_event_stream(stream)
+
+    print("\nWorkflow complete.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -7,8 +7,6 @@ from typing import Annotated, Never
 
 from agent_framework import (
     AgentExecutorResponse,
-    ChatAgent,
-    ChatMessage,
     Content,
     Executor,
     WorkflowBuilder,
@@ -52,7 +50,10 @@ Prerequisites:
 """
 
 
-# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
+# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
+# See:
+# samples/getting_started/tools/function_tool_with_approval.py
+# samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_current_date() -> str:
     """Get the current date in YYYY-MM-DD format."""
@@ -211,10 +212,10 @@ async def conclude_workflow(
     await ctx.yield_output(email_response.agent_response.text)
 
 
-def create_email_writer_agent() -> ChatAgent:
-    """Create the Email Writer agent with tools that require approval."""
-    return OpenAIChatClient().as_agent(
-        name="Email Writer",
+async def main() -> None:
+    # Create agent
+    email_writer_agent = OpenAIChatClient().as_agent(
+        name="EmailWriter",
         instructions=("You are an excellent email assistant. You respond to incoming emails."),
         # tools with `approval_mode="always_require"` will trigger approval requests
         tools=[
@@ -226,20 +227,16 @@ def create_email_writer_agent() -> ChatAgent:
         ],
     )
 
+    # Create executor
+    email_processor = EmailPreprocessor(special_email_addresses={"mike@contoso.com"})
 
-async def main() -> None:
     # Build the workflow
     workflow = (
         WorkflowBuilder()
-        .register_agent(create_email_writer_agent, name="email_writer")
-        .register_executor(
-            lambda: EmailPreprocessor(special_email_addresses={"mike@contoso.com"}),
-            name="email_preprocessor",
-        )
-        .register_executor(lambda: conclude_workflow, name="conclude_workflow")
-        .set_start_executor("email_preprocessor")
-        .add_edge("email_preprocessor", "email_writer")
-        .add_edge("email_writer", "conclude_workflow")
+        .set_start_executor(email_processor)
+        .add_edge(email_processor, email_writer_agent)
+        .add_edge(email_writer_agent, conclude_workflow)
+        .with_output_from([conclude_workflow])
         .build()
     )
 
@@ -250,46 +247,40 @@ async def main() -> None:
         body="Please provide your team's status update on the project since last week.",
     )
 
-    responses: dict[str, Content] = {}
-    output: list[ChatMessage] | None = None
-    while True:
-        if responses:
-            events = await workflow.send_responses(responses)
-            responses.clear()
-        else:
-            events = await workflow.run(incoming_email)
+    # Initiate the first run of the workflow.
+    # Runs are not isolated; state is preserved across multiple calls to run or send_responses_streaming.
+    events = await workflow.run(incoming_email)
+    request_info_events = events.get_request_info_events()
 
-        request_info_events = events.get_request_info_events()
+    # Run until there are no more approval requests
+    while request_info_events:
+        responses: dict[str, Content] = {}
         for request_info_event in request_info_events:
-            # We should only expect function_approval_request Content in this sample
-            if not isinstance(request_info_event.data, Content) or request_info_event.data.type != "function_approval_request":
-                raise ValueError(f"Unexpected request info content type: {type(request_info_event.data)}")
+            # We should only expect FunctionApprovalRequestContent in this sample
+            data = request_info_event.data
+            if not isinstance(data, Content) or data.type != "function_approval_request":
+                raise ValueError(f"Unexpected request info content type: {type(data)}")
+
+            # To make the type checker happy, we make sure function_call is not None
+            if data.function_call is None:
+                raise ValueError("Function call information is missing in the approval request.")
 
             # Pretty print the function call details
-            arguments = json.dumps(request_info_event.data.function_call.parse_arguments(), indent=2)
-            print(
-                f"Received approval request for function: {request_info_event.data.function_call.name} "
-                f"with args:\n{arguments}"
-            )
+            arguments = json.dumps(data.function_call.parse_arguments(), indent=2)
+            print(f"Received approval request for function: {data.function_call.name} with args:\n{arguments}")
 
             # For demo purposes, we automatically approve the request
             # The expected response type of the request is `function_approval_response Content`,
             # which can be created via `to_function_approval_response` method on the request content
             print("Performing automatic approval for demo purposes...")
-            responses[request_info_event.request_id] = request_info_event.data.to_function_approval_response(approved=True)
+            responses[request_info_event.request_id] = data.to_function_approval_response(approved=True)
 
-        # Once we get an output event, we can conclude the workflow
-        # Outputs can only be produced by the conclude_workflow_executor in this sample
-        if outputs := events.get_outputs():
-            # We expect only one output from the conclude_workflow_executor
-            output = outputs[0]
-            break
-
-    if not output:
-        raise RuntimeError("Workflow did not produce any output event.")
+        events = await workflow.send_responses(responses)
+        request_info_events = events.get_request_info_events()
 
+    # The output should only come from conclude_workflow executor and it's a single string
     print("Final email response conversation:")
-    print(output)
+    print(events.get_outputs()[0])
 
     """
     Sample Output:

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

@@ -22,6 +22,7 @@ Prerequisites:
 """
 
 import asyncio
+from collections.abc import AsyncIterable
 from typing import Any
 
 from agent_framework import (
@@ -29,9 +30,8 @@ from agent_framework import (
     ChatMessage,
     ConcurrentBuilder,
     RequestInfoEvent,
+    WorkflowEvent,
     WorkflowOutputEvent,
-    WorkflowRunState,
-    WorkflowStatusEvent,
 )
 from agent_framework._workflows._agent_executor import AgentExecutorResponse
 from agent_framework.azure import AzureOpenAIChatClient
@@ -93,6 +93,57 @@ async def aggregate_with_synthesis(results: list[AgentExecutorResponse]) -> Any:
     return response.messages[-1].text if response.messages else ""
 
 
+async def process_event_stream(stream: AsyncIterable[WorkflowEvent]) -> dict[str, AgentRequestInfoResponse] | None:
+    """Process events from the workflow stream to capture human feedback requests."""
+
+    requests: dict[str, AgentExecutorResponse] = {}
+    async for event in stream:
+        if isinstance(event, RequestInfoEvent) and isinstance(event.data, AgentExecutorResponse):
+            # Display agent output for review and potential modification
+            requests[event.request_id] = event.data
+
+        if isinstance(event, WorkflowOutputEvent):
+            # The output of the workflow comes from the aggregator and it's a single string
+            print("\n" + "=" * 60)
+            print("ANALYSIS COMPLETE")
+            print("=" * 60)
+            print("Final synthesized analysis:")
+            print(event.data)
+
+    # Process any requests for human feedback
+    responses: dict[str, AgentRequestInfoResponse] = {}
+    if requests:
+        for request_id, request in requests.items():
+            print("\n" + "-" * 40)
+            print("INPUT REQUESTED")
+            print(
+                f"Agent {request.executor_id} just responded with: '{request.agent_response.text}'. "
+                "Please provide your feedback."
+            )
+            print("-" * 40)
+            if request.full_conversation:
+                print("Conversation context:")
+                recent = (
+                    request.full_conversation[-2:] if len(request.full_conversation) > 2 else request.full_conversation
+                )
+                for msg in recent:
+                    name = msg.author_name or msg.role
+                    text = (msg.text or "")[:150]
+                    print(f"  [{name}]: {text}...")
+                print("-" * 40)
+
+            # Get human input to steer this agent's contribution
+            user_input = input("Your guidance for the analysts (or 'skip' to approve): ")  # noqa: ASYNC250
+            if user_input.lower() == "skip":
+                user_input = AgentRequestInfoResponse.approve()
+            else:
+                user_input = AgentRequestInfoResponse.from_strings([user_input])
+
+            responses[request_id] = user_input
+
+    return responses if responses else None
+
+
 async def main() -> None:
     global _chat_client
     _chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
@@ -135,70 +186,16 @@ async def main() -> None:
         .build()
     )
 
-    # Run the workflow with human-in-the-loop
-    pending_responses: dict[str, AgentRequestInfoResponse] | None = None
-    workflow_complete = False
+    # Initiate the first run of the workflow.
+    # Runs are not isolated; state is preserved across multiple calls to run or send_responses_streaming.
+    stream = workflow.run_stream("Analyze the impact of large language models on software development.")
 
-    print("Starting multi-perspective analysis workflow...")
-    print("=" * 60)
-
-    while not workflow_complete:
-        # Run or continue the workflow
-        stream = (
-            workflow.send_responses_streaming(pending_responses)
-            if pending_responses
-            else workflow.run_stream("Analyze the impact of large language models on software development.")
-        )
-
-        pending_responses = None
-
-        # Process events
-        async for event in stream:
-            if isinstance(event, RequestInfoEvent):
-                if isinstance(event.data, AgentExecutorResponse):
-                    # Display agent output for review and potential modification
-                    print("\n" + "-" * 40)
-                    print("INPUT REQUESTED")
-                    print(
-                        f"Agent {event.source_executor_id} just responded with: '{event.data.agent_response.text}'. "
-                        "Please provide your feedback."
-                    )
-                    print("-" * 40)
-                    if event.data.full_conversation:
-                        print("Conversation context:")
-                        recent = (
-                            event.data.full_conversation[-2:]
-                            if len(event.data.full_conversation) > 2
-                            else event.data.full_conversation
-                        )
-                        for msg in recent:
-                            name = msg.author_name or msg.role
-                            text = (msg.text or "")[:150]
-                            print(f"  [{name}]: {text}...")
-                        print("-" * 40)
-
-                    # Get human input to steer this agent's contribution
-                    user_input = input("Your guidance for the analysts (or 'skip' to approve): ")  # noqa: ASYNC250
-                    if user_input.lower() == "skip":
-                        user_input = AgentRequestInfoResponse.approve()
-                    else:
-                        user_input = AgentRequestInfoResponse.from_strings([user_input])
-
-                    pending_responses = {event.request_id: user_input}
-                    print("(Resuming workflow...)")
-
-            elif isinstance(event, WorkflowOutputEvent):
-                print("\n" + "=" * 60)
-                print("WORKFLOW COMPLETE")
-                print("=" * 60)
-                print("Aggregated output:")
-                # Custom aggregator returns a string
-                if event.data:
-                    print(event.data)
-                workflow_complete = True
-
-            elif isinstance(event, WorkflowStatusEvent) and event.state == WorkflowRunState.IDLE:
-                workflow_complete = True
+    pending_responses = await process_event_stream(stream)
+    while pending_responses is not None:
+        # Run the workflow until there is no more human feedback to provide,
+        # in which case this workflow completes.
+        stream = workflow.send_responses_streaming(pending_responses)
+        pending_responses = await process_event_stream(stream)
 
 
 if __name__ == "__main__":

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

@@ -23,23 +23,76 @@ Prerequisites:
 """
 
 import asyncio
+from collections.abc import AsyncIterable
+from typing import cast
 
 from agent_framework import (
     AgentExecutorResponse,
     AgentRequestInfoResponse,
-    AgentResponse,
-    AgentRunUpdateEvent,
     ChatMessage,
     GroupChatBuilder,
     RequestInfoEvent,
+    WorkflowEvent,
     WorkflowOutputEvent,
-    WorkflowRunState,
-    WorkflowStatusEvent,
 )
 from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
 
 
+async def process_event_stream(stream: AsyncIterable[WorkflowEvent]) -> dict[str, AgentRequestInfoResponse] | None:
+    """Process events from the workflow stream to capture human feedback requests."""
+
+    requests: dict[str, AgentExecutorResponse] = {}
+    async for event in stream:
+        if isinstance(event, RequestInfoEvent) and isinstance(event.data, AgentExecutorResponse):
+            requests[event.request_id] = event.data
+
+        if isinstance(event, WorkflowOutputEvent):
+            # The output of the workflow comes from the orchestrator and it's a list of messages
+            print("\n" + "=" * 60)
+            print("DISCUSSION COMPLETE")
+            print("=" * 60)
+            print("Final discussion summary:")
+            # To make the type checker happy, we cast event.data to the expected type
+            outputs = cast(list[ChatMessage], event.data)
+            for msg in outputs:
+                speaker = msg.author_name or msg.role
+                print(f"[{speaker}]: {msg.text}")
+
+    responses: dict[str, AgentRequestInfoResponse] = {}
+    if requests:
+        for request_id, request in requests.items():
+            # Display pre-agent context for human input
+            print("\n" + "-" * 40)
+            print("INPUT REQUESTED")
+            print(
+                f"Agent {request.executor_id} just responded with: '{request.agent_response.text}'. "
+                "Please provide your feedback."
+            )
+            print("-" * 40)
+            if request.full_conversation:
+                print("Conversation context:")
+                recent = (
+                    request.full_conversation[-2:] if len(request.full_conversation) > 2 else request.full_conversation
+                )
+                for msg in recent:
+                    name = msg.author_name or msg.role
+                    text = (msg.text or "")[:150]
+                    print(f"  [{name}]: {text}...")
+                print("-" * 40)
+
+            # Get human input to steer the agent
+            user_input = input(f"Feedback for {request.executor_id} (or 'skip' to approve): ")  # noqa: ASYNC250
+            if user_input.lower() == "skip":
+                user_input = AgentRequestInfoResponse.approve()
+            else:
+                user_input = AgentRequestInfoResponse.from_strings([user_input])
+
+            responses[request_id] = user_input
+
+    return responses if responses else None
+
+
 async def main() -> None:
     chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
 
@@ -96,81 +149,19 @@ async def main() -> None:
         .build()
     )
 
-    # Run the workflow with human-in-the-loop
-    pending_responses: dict[str, AgentRequestInfoResponse] | None = None
-    workflow_complete = False
-    current_agent: str | None = None  # Track current streaming agent
+    # Initiate the first run of the workflow.
+    # Runs are not isolated; state is preserved across multiple calls to run or send_responses_streaming.
+    stream = workflow.run_stream(
+        "Discuss how our team should approach adopting AI tools for productivity. "
+        "Consider benefits, risks, and implementation strategies."
+    )
 
-    print("Starting group discussion workflow...")
-    print("=" * 60)
-
-    while not workflow_complete:
-        # Run or continue the workflow
-        stream = (
-            workflow.send_responses_streaming(pending_responses)
-            if pending_responses
-            else workflow.run_stream(
-                "Discuss how our team should approach adopting AI tools for productivity. "
-                "Consider benefits, risks, and implementation strategies."
-            )
-        )
-
-        pending_responses = None
-
-        # Process events
-        async for event in stream:
-            if isinstance(event, AgentRunUpdateEvent):
-                # Show all agent responses as they stream
-                if event.data and event.data.text:
-                    agent_name = event.data.author_name or "unknown"
-                    # Print agent name header only when agent changes
-                    if agent_name != current_agent:
-                        current_agent = agent_name
-                        print(f"\n[{agent_name}]: ", end="", flush=True)
-                    print(event.data.text, end="", flush=True)
-
-            elif isinstance(event, RequestInfoEvent):
-                current_agent = None  # Reset for next agent
-                if isinstance(event.data, AgentExecutorResponse):
-                    # Display pre-agent context for human input
-                    print("\n" + "-" * 40)
-                    print("INPUT REQUESTED")
-                    print(f"About to call agent: {event.source_executor_id}")
-                    print("-" * 40)
-                    print("Conversation context:")
-                    agent_response: AgentResponse = event.data.agent_response
-                    messages: list[ChatMessage] = agent_response.messages
-                    recent: list[ChatMessage] = messages[-3:] if len(messages) > 3 else messages  # type: ignore
-                    for msg in recent:
-                        name = msg.author_name or "unknown"
-                        text = (msg.text or "")[:100]
-                        print(f"  [{name}]: {text}...")
-                    print("-" * 40)
-
-                    # Get human input to steer the agent
-                    user_input = input(f"Feedback for {event.source_executor_id} (or 'skip' to approve): ")  # noqa: ASYNC250
-                    if user_input.lower() == "skip":
-                        pending_responses = {event.request_id: AgentRequestInfoResponse.approve()}
-                    else:
-                        pending_responses = {event.request_id: AgentRequestInfoResponse.from_strings([user_input])}
-                    print("(Resuming discussion...)")
-
-            elif isinstance(event, WorkflowOutputEvent):
-                print("\n" + "=" * 60)
-                print("DISCUSSION COMPLETE")
-                print("=" * 60)
-                print("Final conversation:")
-                if event.data:
-                    messages: list[ChatMessage] = event.data
-                    for msg in messages:
-                        role = msg.role.capitalize()
-                        name = msg.author_name or "unknown"
-                        text = (msg.text or "")[:200]
-                        print(f"[{role}][{name}]: {text}...")
-                workflow_complete = True
-
-            elif isinstance(event, WorkflowStatusEvent) and event.state == WorkflowRunState.IDLE:
-                workflow_complete = True
+    pending_responses = await process_event_stream(stream)
+    while pending_responses is not None:
+        # Run the workflow until there is no more human feedback to provide,
+        # in which case this workflow completes.
+        stream = workflow.send_responses_streaming(pending_responses)
+        pending_responses = await process_event_stream(stream)
 
 
 if __name__ == "__main__":

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

@@ -1,23 +1,23 @@
 # Copyright (c) Microsoft. All rights reserved.
 
 import asyncio
+from collections.abc import AsyncIterable
 from dataclasses import dataclass
 
 from agent_framework import (
-    AgentExecutorRequest,  # Message bundle sent to an AgentExecutor
+    AgentExecutorRequest,
     AgentExecutorResponse,
-    ChatAgent,  # Result returned by an AgentExecutor
-    ChatMessage,  # Chat message structure
-    Executor,  # Base class for workflow executors
-    RequestInfoEvent,  # Event emitted when human input is requested
-    WorkflowBuilder,  # Fluent builder for assembling the graph
-    WorkflowContext,  # Per run context and event bus
-    WorkflowOutputEvent,  # Event emitted when workflow yields output
-    WorkflowRunState,  # Enum of workflow run states
-    WorkflowStatusEvent,  # Event emitted on run state changes
+    AgentResponseUpdate,
+    ChatMessage,
+    Executor,
+    RequestInfoEvent,
+    WorkflowBuilder,
+    WorkflowContext,
+    WorkflowEvent,
+    WorkflowOutputEvent,
     handler,
-    response_handler,  # Decorator to expose an Executor method as a step
-    )
+    response_handler,
+)
 from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
 from pydantic import BaseModel
@@ -125,8 +125,6 @@ class TurnManager(Executor):
         ctx: WorkflowContext[AgentExecutorRequest, str],
     ) -> None:
         """Continue the game or finish based on human feedback."""
-        print(f"Feedback for prompt '{original_request.prompt}' received: {feedback}")
-
         reply = feedback.strip().lower()
 
         if reply == "correct":
@@ -142,9 +140,50 @@ class TurnManager(Executor):
         await ctx.send_message(AgentExecutorRequest(messages=[user_msg], should_respond=True))
 
 
-def create_guessing_agent() -> ChatAgent:
-    """Create the guessing agent with instructions to guess a number between 1 and 10."""
-    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+async def process_event_stream(stream: AsyncIterable[WorkflowEvent]) -> dict[str, str] | None:
+    """Process events from the workflow stream to capture human feedback requests."""
+    # Track the last author to format streaming output.
+    last_response_id: str | None = None
+
+    requests: list[tuple[str, HumanFeedbackRequest]] = []
+    async for event in stream:
+        if isinstance(event, RequestInfoEvent) and isinstance(event.data, HumanFeedbackRequest):
+            requests.append((event.request_id, event.data))
+        elif isinstance(event, WorkflowOutputEvent):
+            if isinstance(event.data, AgentResponseUpdate):
+                update = event.data
+                response_id = update.response_id
+                if response_id != last_response_id:
+                    if last_response_id is not None:
+                        print()  # Newline between different responses
+                    print(f"{update.author_name}: {update.text}", end="", flush=True)
+                    last_response_id = response_id
+                else:
+                    print(update.text, end="", flush=True)
+            else:
+                print(f"\n{event.executor_id}: {event.data}")
+
+    # Handle any pending human feedback requests.
+    if requests:
+        responses: dict[str, str] = {}
+        for request_id, request in requests:
+            print(f"\nHITL: {request.prompt}")
+            # Instructional print already appears above. The input line below is the user entry point.
+            # If desired, you can add more guidance here, but keep it concise.
+            answer = input("Enter higher/lower/correct/exit: ").lower()  # noqa: ASYNC250
+            if answer == "exit":
+                print("Exiting...")
+                return None
+            responses[request_id] = answer
+        return responses
+
+    return None
+
+
+async def main() -> None:
+    """Run the human-in-the-loop guessing game workflow."""
+    # Create agent and executor
+    guessing_agent = AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
         name="GuessingAgent",
         instructions=(
             "You guess a number between 1 and 10. "
@@ -155,88 +194,27 @@ def create_guessing_agent() -> ChatAgent:
         # response_format enforces that the model produces JSON compatible with GuessOutput.
         default_options={"response_format": GuessOutput},
     )
-
-
-async def main() -> None:
-    """Run the human-in-the-loop guessing game workflow."""
+    turn_manager = TurnManager(id="turn_manager")
 
     # Build a simple loop: TurnManager <-> AgentExecutor.
     workflow = (
         WorkflowBuilder()
-        .register_agent(create_guessing_agent, name="guessing_agent")
-        .register_executor(lambda: TurnManager(id="turn_manager"), name="turn_manager")
-        .set_start_executor("turn_manager")
-        .add_edge("turn_manager", "guessing_agent")  # Ask agent to make/adjust a guess
-        .add_edge("guessing_agent", "turn_manager")  # Agent's response comes back to coordinator
+        .set_start_executor(turn_manager)
+        .add_edge(turn_manager, guessing_agent)  # Ask agent to make/adjust a guess
+        .add_edge(guessing_agent, turn_manager)  # Agent's response comes back to coordinator
     ).build()
 
-    # Human in the loop run: alternate between invoking the workflow and supplying collected responses.
-    pending_responses: dict[str, str] | None = None
-    workflow_output: str | None = None
+    # Initiate the first run of the workflow.
+    # Runs are not isolated; state is preserved across multiple calls to run or send_responses_streaming.
+    stream = workflow.run_stream("start")
 
-    # User guidance printing:
-    # If you want to instruct users up front, print a short banner before the loop.
-    # Example:
-    # print(
-    #     "Interactive mode. When prompted, type one of: higher, lower, correct, or exit. "
-    #     "The agent will keep guessing until you reply correct.",
-    #     flush=True,
-    # )
+    pending_responses = await process_event_stream(stream)
+    while pending_responses is not None:
+        # Run the workflow until there is no more human feedback to provide,
+        # in which case this workflow completes.
+        stream = workflow.send_responses_streaming(pending_responses)
+        pending_responses = await process_event_stream(stream)
 
-    while workflow_output is None:
-        # First iteration uses run_stream("start").
-        # Subsequent iterations use send_responses_streaming with pending_responses from the console.
-        stream = (
-            workflow.send_responses_streaming(pending_responses) if pending_responses else workflow.run_stream("start")
-        )
-        # Collect events for this turn. Among these you may see WorkflowStatusEvent
-        # with state IDLE_WITH_PENDING_REQUESTS when the workflow pauses for
-        # human input, preceded by IN_PROGRESS_PENDING_REQUESTS as requests are
-        # emitted.
-        events = [event async for event in stream]
-        pending_responses = None
-
-        # Collect human requests, workflow outputs, and check for completion.
-        requests: list[tuple[str, str]] = []  # (request_id, prompt)
-        for event in events:
-            if isinstance(event, RequestInfoEvent) and isinstance(event.data, HumanFeedbackRequest):
-                # RequestInfoEvent for our HumanFeedbackRequest.
-                requests.append((event.request_id, event.data.prompt))
-            elif isinstance(event, WorkflowOutputEvent):
-                # Capture workflow output as they're yielded
-                workflow_output = str(event.data)
-
-        # Detect run state transitions for a better developer experience.
-        pending_status = any(
-            isinstance(e, WorkflowStatusEvent) and e.state == WorkflowRunState.IN_PROGRESS_PENDING_REQUESTS
-            for e in events
-        )
-        idle_with_requests = any(
-            isinstance(e, WorkflowStatusEvent) and e.state == WorkflowRunState.IDLE_WITH_PENDING_REQUESTS
-            for e in events
-        )
-        if pending_status:
-            print("State: IN_PROGRESS_PENDING_REQUESTS (requests outstanding)")
-        if idle_with_requests:
-            print("State: IDLE_WITH_PENDING_REQUESTS (awaiting human input)")
-
-        # If we have any human requests, prompt the user and prepare responses.
-        if requests:
-            responses: dict[str, str] = {}
-            for req_id, prompt in requests:
-                # Simple console prompt for the sample.
-                print(f"HITL> {prompt}")
-                # Instructional print already appears above. The input line below is the user entry point.
-                # If desired, you can add more guidance here, but keep it concise.
-                answer = input("Enter higher/lower/correct/exit: ").lower()  # noqa: ASYNC250
-                if answer == "exit":
-                    print("Exiting...")
-                    return
-                responses[req_id] = answer
-            pending_responses = responses
-
-    # Show final result from workflow output captured during streaming.
-    print(f"Workflow output: {workflow_output}")
     """
     Sample Output:
 

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

@@ -22,6 +22,8 @@ Prerequisites:
 """
 
 import asyncio
+from collections.abc import AsyncIterable
+from typing import cast
 
 from agent_framework import (
     AgentExecutorResponse,
@@ -29,14 +31,65 @@ from agent_framework import (
     ChatMessage,
     RequestInfoEvent,
     SequentialBuilder,
+    WorkflowEvent,
     WorkflowOutputEvent,
-    WorkflowRunState,
-    WorkflowStatusEvent,
 )
 from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
 
 
+async def process_event_stream(stream: AsyncIterable[WorkflowEvent]) -> dict[str, AgentRequestInfoResponse] | None:
+    """Process events from the workflow stream to capture human feedback requests."""
+
+    requests: dict[str, AgentExecutorResponse] = {}
+    async for event in stream:
+        if isinstance(event, RequestInfoEvent) and isinstance(event.data, AgentExecutorResponse):
+            requests[event.request_id] = event.data
+
+        elif isinstance(event, WorkflowOutputEvent):
+            # The output of the sequential workflow is a list of ChatMessages
+            print("\n" + "=" * 60)
+            print("WORKFLOW COMPLETE")
+            print("=" * 60)
+            print("Final output:")
+            outputs = cast(list[ChatMessage], event.data)
+            for message in outputs:
+                print(f"[{message.author_name or message.role}]: {message.text}")
+
+    responses: dict[str, AgentRequestInfoResponse] = {}
+    if requests:
+        for request_id, request in requests.items():
+            # Display agent response and conversation context for review
+            print("\n" + "-" * 40)
+            print("REQUEST INFO: INPUT REQUESTED")
+            print(
+                f"Agent {request.executor_id} just responded with: '{request.agent_response.text}'. "
+                "Please provide your feedback."
+            )
+            print("-" * 40)
+            if request.full_conversation:
+                print("Conversation context:")
+                recent = (
+                    request.full_conversation[-2:] if len(request.full_conversation) > 2 else request.full_conversation
+                )
+                for msg in recent:
+                    name = msg.author_name or msg.role
+                    text = (msg.text or "")[:150]
+                    print(f"  [{name}]: {text}...")
+                print("-" * 40)
+
+            # Get feedback on the agent's response (approve or request iteration)
+            user_input = input("Your guidance (or 'skip' to approve): ")  # noqa: ASYNC250
+            if user_input.lower() == "skip":
+                user_input = AgentRequestInfoResponse.approve()
+            else:
+                user_input = AgentRequestInfoResponse.from_strings([user_input])
+
+            responses[request_id] = user_input
+
+    return responses if responses else None
+
+
 async def main() -> None:
     chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
 
@@ -71,72 +124,16 @@ async def main() -> None:
         .build()
     )
 
-    # Run the workflow with request info handling
-    pending_responses: dict[str, AgentRequestInfoResponse] | None = None
-    workflow_complete = False
+    # Initiate the first run of the workflow.
+    # Runs are not isolated; state is preserved across multiple calls to run or send_responses_streaming.
+    stream = workflow.run_stream("Write a brief introduction to artificial intelligence.")
 
-    print("Starting document review workflow...")
-    print("=" * 60)
-
-    while not workflow_complete:
-        # Run or continue the workflow
-        stream = (
-            workflow.send_responses_streaming(pending_responses)
-            if pending_responses
-            else workflow.run_stream("Write a brief introduction to artificial intelligence.")
-        )
-
-        pending_responses = None
-
-        # Process events
-        async for event in stream:
-            if isinstance(event, RequestInfoEvent):
-                if isinstance(event.data, AgentExecutorResponse):
-                    # Display agent response and conversation context for review
-                    print("\n" + "-" * 40)
-                    print("REQUEST INFO: INPUT REQUESTED")
-                    print(
-                        f"Agent {event.source_executor_id} just responded with: '{event.data.agent_response.text}'. "
-                        "Please provide your feedback."
-                    )
-                    print("-" * 40)
-                    if event.data.full_conversation:
-                        print("Conversation context:")
-                        recent = (
-                            event.data.full_conversation[-2:]
-                            if len(event.data.full_conversation) > 2
-                            else event.data.full_conversation
-                        )
-                        for msg in recent:
-                            name = msg.author_name or msg.role
-                            text = (msg.text or "")[:150]
-                            print(f"  [{name}]: {text}...")
-                        print("-" * 40)
-
-                    # Get feedback on the agent's response (approve or request iteration)
-                    user_input = input("Your guidance (or 'skip' to approve): ")  # noqa: ASYNC250
-                    if user_input.lower() == "skip":
-                        user_input = AgentRequestInfoResponse.approve()
-                    else:
-                        user_input = AgentRequestInfoResponse.from_strings([user_input])
-
-                    pending_responses = {event.request_id: user_input}
-                    print("(Resuming workflow...)")
-
-            elif isinstance(event, WorkflowOutputEvent):
-                print("\n" + "=" * 60)
-                print("WORKFLOW COMPLETE")
-                print("=" * 60)
-                print("Final output:")
-                if event.data:
-                    messages: list[ChatMessage] = event.data[-3:]
-                    for msg in messages:
-                        role = msg.role if msg.role else "unknown"
-                        print(f"[{role}]: {msg.text}")
-                workflow_complete = True
-
-            elif isinstance(event, WorkflowStatusEvent) and event.state == WorkflowRunState.IDLE:
-                workflow_complete = True
+    pending_responses = await process_event_stream(stream)
+    while pending_responses is not None:
+        # Run the workflow until there is no more human feedback to provide,
+        # in which case this workflow completes.
+        stream = workflow.send_responses_streaming(pending_responses)
+        pending_responses = await process_event_stream(stream)
 
 
 if __name__ == "__main__":

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

@@ -22,7 +22,7 @@ Demonstrates:
 
 Prerequisites:
 - Azure OpenAI access configured for AzureOpenAIChatClient (use az login + env vars)
-- Familiarity with Workflow events (AgentRunEvent, WorkflowOutputEvent)
+- Familiarity with Workflow events (WorkflowOutputEvent)
 """
 
 

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

@@ -1,9 +1,10 @@
 # Copyright (c) Microsoft. All rights reserved.
 
 import asyncio
+from typing import cast
 
 from agent_framework import (
-    AgentRunUpdateEvent,
+    AgentResponseUpdate,
     ChatAgent,
     ChatMessage,
     GroupChatBuilder,
@@ -72,6 +73,9 @@ async def main() -> None:
         # 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
         .with_termination_condition(lambda messages: sum(1 for msg in messages if msg.role == "assistant") >= 4)
+        # Enable intermediate outputs to observe the conversation as it unfolds
+        # Intermediate outputs will be emitted as WorkflowOutputEvent events
+        .with_intermediate_outputs()
         .build()
     )
 
@@ -81,35 +85,26 @@ async def main() -> None:
     print(f"TASK: {task}\n")
     print("=" * 80)
 
-    # Keep track of the last executor to format output nicely in streaming mode
-    last_executor_id: str | None = None
-    output_event: WorkflowOutputEvent | None = None
+    # Keep track of the last response to format output nicely in streaming mode
+    last_response_id: str | None = None
     async for event in workflow.run_stream(task):
-        if isinstance(event, AgentRunUpdateEvent):
-            eid = event.executor_id
-            if eid != last_executor_id:
-                if last_executor_id is not None:
-                    print("\n")
-                print(f"{eid}:", end=" ", flush=True)
-                last_executor_id = eid
-            print(event.data, end="", flush=True)
-        elif isinstance(event, WorkflowOutputEvent):
-            output_event = event
-
-    # The output of the workflow is the full list of messages exchanged
-    if output_event:
-        if not isinstance(output_event.data, list) or not all(
-            isinstance(msg, ChatMessage)
-            for msg in output_event.data  # type: ignore
-        ):
-            raise RuntimeError("Unexpected output event data format.")
-        print("\n" + "=" * 80)
-        print("\nFINAL OUTPUT (The conversation history)\n")
-        for msg in output_event.data:  # type: ignore
-            assert isinstance(msg, ChatMessage)
-            print(f"{msg.author_name or msg.role}: {msg.text}\n")
-    else:
-        raise RuntimeError("Workflow did not produce a final output event.")
+        if isinstance(event, WorkflowOutputEvent):
+            data = event.data
+            if isinstance(data, AgentResponseUpdate):
+                rid = data.response_id
+                if rid != last_response_id:
+                    if last_response_id is not None:
+                        print("\n")
+                    print(f"{data.author_name}:", end=" ", flush=True)
+                    last_response_id = rid
+                print(data.text, end="", flush=True)
+            else:
+                # The output of the group chat workflow is a collection of chat messages from all participants
+                outputs = cast(list[ChatMessage], event.data)
+                print("\n" + "=" * 80)
+                print("\nFinal Conversation Transcript:\n")
+                for message in outputs:
+                    print(f"{message.author_name or message.role}: {message.text}\n")
 
 
 if __name__ == "__main__":

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

@@ -4,13 +4,7 @@ import asyncio
 import logging
 from typing import cast
 
-from agent_framework import (
-    AgentRunUpdateEvent,
-    ChatAgent,
-    ChatMessage,
-    GroupChatBuilder,
-    WorkflowOutputEvent,
-)
+from agent_framework import AgentResponseUpdate, ChatAgent, ChatMessage, GroupChatBuilder, WorkflowOutputEvent
 from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
 
@@ -213,6 +207,9 @@ Share your perspective authentically. Feel free to:
         .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 == "assistant") >= 10)
+        # Enable intermediate outputs to observe the conversation as it unfolds
+        # Intermediate outputs will be emitted as WorkflowOutputEvent events
+        .with_intermediate_outputs()
         .build()
     )
 
@@ -235,30 +232,26 @@ Share your perspective authentically. Feel free to:
     print("DISCUSSION BEGINS")
     print("=" * 80 + "\n")
 
-    final_conversation: list[ChatMessage] = []
-    current_speaker: str | None = None
-
+    # Keep track of the last response to format output nicely in streaming mode
+    last_response_id: str | None = None
     async for event in workflow.run_stream(f"Please begin the discussion on: {topic}"):
-        if isinstance(event, AgentRunUpdateEvent):
-            if event.executor_id != current_speaker:
-                if current_speaker is not None:
-                    print("\n")
-                print(f"[{event.executor_id}]", flush=True)
-                current_speaker = event.executor_id
-
-            print(event.data, end="", flush=True)
-
-        elif isinstance(event, WorkflowOutputEvent):
-            final_conversation = cast(list[ChatMessage], event.data)
-
-    print("\n\n" + "=" * 80)
-    print("DISCUSSION SUMMARY")
-    print("=" * 80)
-
-    if final_conversation and isinstance(final_conversation, list) and final_conversation:
-        final_msg = final_conversation[-1]
-        if hasattr(final_msg, "author_name") and final_msg.author_name == "Moderator":
-            print(f"\n{final_msg.text}")
+        if isinstance(event, WorkflowOutputEvent):
+            data = event.data
+            if isinstance(data, AgentResponseUpdate):
+                rid = data.response_id
+                if rid != last_response_id:
+                    if last_response_id is not None:
+                        print("\n")
+                    print(f"{data.author_name}:", end=" ", flush=True)
+                    last_response_id = rid
+                print(data.text, end="", flush=True)
+            else:
+                # The output of the group chat workflow is a collection of chat messages from all participants
+                outputs = cast(list[ChatMessage], event.data)
+                print("\n" + "=" * 80)
+                print("\nFinal Conversation Transcript:\n")
+                for message in outputs:
+                    print(f"{message.author_name or message.role}: {message.text}\n")
 
     """
     Sample Output:

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

@@ -1,9 +1,10 @@
 # Copyright (c) Microsoft. All rights reserved.
 
 import asyncio
+from typing import cast
 
 from agent_framework import (
-    AgentRunUpdateEvent,
+    AgentResponseUpdate,
     ChatAgent,
     ChatMessage,
     GroupChatBuilder,
@@ -91,6 +92,9 @@ async def main() -> None:
         # Note: it's possible that the expert gets it right the first time and the other participants
         # have nothing to add, but for demo purposes we want to see at least one full round of interaction.
         .with_termination_condition(lambda conversation: len(conversation) >= 6)
+        # Enable intermediate outputs to observe the conversation as it unfolds
+        # Intermediate outputs will be emitted as WorkflowOutputEvent events
+        .with_intermediate_outputs()
         .build()
     )
 
@@ -100,35 +104,26 @@ async def main() -> None:
     print(f"TASK: {task}\n")
     print("=" * 80)
 
-    # Keep track of the last executor to format output nicely in streaming mode
-    last_executor_id: str | None = None
-    output_event: WorkflowOutputEvent | None = None
+    # Keep track of the last response to format output nicely in streaming mode
+    last_response_id: str | None = None
     async for event in workflow.run_stream(task):
-        if isinstance(event, AgentRunUpdateEvent):
-            eid = event.executor_id
-            if eid != last_executor_id:
-                if last_executor_id is not None:
-                    print("\n")
-                print(f"{eid}:", end=" ", flush=True)
-                last_executor_id = eid
-            print(event.data, end="", flush=True)
-        elif isinstance(event, WorkflowOutputEvent):
-            output_event = event
-
-    # The output of the workflow is the full list of messages exchanged
-    if output_event:
-        if not isinstance(output_event.data, list) or not all(
-            isinstance(msg, ChatMessage)
-            for msg in output_event.data  # type: ignore
-        ):
-            raise RuntimeError("Unexpected output event data format.")
-        print("\n" + "=" * 80)
-        print("\nFINAL OUTPUT (The conversation history)\n")
-        for msg in output_event.data:  # type: ignore
-            assert isinstance(msg, ChatMessage)
-            print(f"{msg.author_name or msg.role}: {msg.text}\n")
-    else:
-        raise RuntimeError("Workflow did not produce a final output event.")
+        if isinstance(event, WorkflowOutputEvent):
+            data = event.data
+            if isinstance(data, AgentResponseUpdate):
+                rid = data.response_id
+                if rid != last_response_id:
+                    if last_response_id is not None:
+                        print("\n")
+                    print(f"{data.author_name}:", end=" ", flush=True)
+                    last_response_id = rid
+                print(data.text, end="", flush=True)
+            else:
+                # The output of the group chat workflow is a collection of chat messages from all participants
+                outputs = cast(list[ChatMessage], event.data)
+                print("\n" + "=" * 80)
+                print("\nFinal Conversation Transcript:\n")
+                for message in outputs:
+                    print(f"{message.author_name or message.role}: {message.text}\n")
 
 
 if __name__ == "__main__":

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

@@ -6,12 +6,11 @@ from typing import cast
 
 from agent_framework import (
     AgentResponseUpdate,
-    AgentRunUpdateEvent,
     ChatAgent,
     ChatMessage,
     HandoffBuilder,
+    HandoffSentEvent,
     HostedWebSearchTool,
-    WorkflowEvent,
     WorkflowOutputEvent,
     resolve_agent_id,
 )
@@ -76,31 +75,6 @@ def create_agents(
     return coordinator, research_agent, summary_agent
 
 
-last_response_id: str | None = None
-
-
-def _display_event(event: WorkflowEvent) -> None:
-    """Print the final conversation snapshot from workflow output events."""
-    if isinstance(event, AgentRunUpdateEvent) and event.data:
-        update: AgentResponseUpdate = event.data
-        if not update.text:
-            return
-        global last_response_id
-        if update.response_id != last_response_id:
-            last_response_id = update.response_id
-            print(f"\n- {update.author_name}: ", flush=True, end="")
-        print(event.data, flush=True, end="")
-    elif isinstance(event, WorkflowOutputEvent):
-        conversation = cast(list[ChatMessage], event.data)
-        print("\n=== Final Conversation (Autonomous with Iteration) ===")
-        for message in conversation:
-            speaker = message.author_name or message.role
-            text_preview = message.text[:200] + "..." if len(message.text) > 200 else message.text
-            print(f"- {speaker}: {text_preview}")
-        print(f"\nTotal messages: {len(conversation)}")
-        print("=====================================================")
-
-
 async def main() -> None:
     """Run an autonomous handoff workflow with specialist iteration enabled."""
     chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
@@ -130,16 +104,39 @@ async def main() -> None:
         )
         .with_termination_condition(
             # Terminate after coordinator provides 5 assistant responses
-            lambda conv: sum(1 for msg in conv if msg.author_name == "coordinator" and msg.role == "assistant")
-            >= 5
+            lambda conv: sum(1 for msg in conv if msg.author_name == "coordinator" and msg.role == "assistant") >= 5
         )
         .build()
     )
 
     request = "Perform a comprehensive research on Microsoft Agent Framework."
     print("Request:", request)
+
+    last_response_id: str | None = None
     async for event in workflow.run_stream(request):
-        _display_event(event)
+        if isinstance(event, HandoffSentEvent):
+            print(f"\nHandoff Event: from {event.source} to {event.target}\n")
+        elif isinstance(event, WorkflowOutputEvent):
+            data = event.data
+            if isinstance(data, AgentResponseUpdate):
+                if not data.text:
+                    # Skip updates that don't have text content
+                    # These can be tool calls or other non-text events
+                    continue
+                rid = data.response_id
+                if rid != last_response_id:
+                    if last_response_id is not None:
+                        print("\n")
+                    print(f"{data.author_name}:", end=" ", flush=True)
+                    last_response_id = rid
+                print(data.text, end="", flush=True)
+            else:
+                # The output of the group chat workflow is a collection of chat messages from all participants
+                outputs = cast(list[ChatMessage], event.data)
+                print("\n" + "=" * 80)
+                print("\nFinal Conversation Transcript:\n")
+                for message in outputs:
+                    print(f"{message.author_name or message.role}: {message.text}\n")
 
     """
     Expected behavior:

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

@@ -6,7 +6,6 @@ from typing import Annotated, cast
 
 from agent_framework import (
     AgentResponse,
-    AgentRunEvent,
     ChatAgent,
     ChatMessage,
     HandoffAgentUserRequest,
@@ -47,7 +46,10 @@ Key Concepts:
 """
 
 
-# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
+# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
+# See:
+# samples/getting_started/tools/function_tool_with_approval.py
+# samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def process_refund(order_number: Annotated[str, "Order number to process refund for"]) -> str:
     """Simulated function to process a refund for a given order number."""
@@ -125,38 +127,36 @@ def _handle_events(events: list[WorkflowEvent]) -> list[RequestInfoEvent]:
     requests: list[RequestInfoEvent] = []
 
     for event in events:
-        # AgentRunEvent: Contains messages generated by agents during their turn
-        if isinstance(event, AgentRunEvent):
-            for message in event.data.messages:
-                if not message.text:
-                    # Skip messages without text (e.g., tool calls)
-                    continue
-                speaker = message.author_name or message.role
-                print(f"- {speaker}: {message.text}")
-
-        # HandoffSentEvent: Indicates a handoff has been initiated
         if isinstance(event, HandoffSentEvent):
+            # HandoffSentEvent: Indicates a handoff has been initiated
             print(f"\n[Handoff from {event.source} to {event.target} initiated.]")
-
-        # WorkflowStatusEvent: Indicates workflow state changes
-        if isinstance(event, WorkflowStatusEvent) and event.state in {
+        elif isinstance(event, WorkflowStatusEvent) and event.state in {
             WorkflowRunState.IDLE,
             WorkflowRunState.IDLE_WITH_PENDING_REQUESTS,
         }:
+            # WorkflowStatusEvent: Indicates workflow state changes
             print(f"\n[Workflow Status] {event.state.name}")
-
-        # WorkflowOutputEvent: Contains the final conversation when workflow terminates
         elif isinstance(event, WorkflowOutputEvent):
-            conversation = cast(list[ChatMessage], event.data)
-            if isinstance(conversation, list):
-                print("\n=== Final Conversation Snapshot ===")
-                for message in conversation:
+            # WorkflowOutputEvent: Contains contents generated by the workflow
+            data = event.data
+            if isinstance(data, AgentResponse):
+                for message in data.messages:
+                    if not message.text:
+                        # Skip messages without text (e.g., tool calls)
+                        continue
                     speaker = message.author_name or message.role
-                    print(f"- {speaker}: {message.text or [content.type for content in message.contents]}")
-                print("===================================")
-
-        # RequestInfoEvent: Workflow is requesting user input
+                    print(f"- {speaker}: {message.text}")
+            else:
+                # The output of the handoff workflow is a collection of chat messages from all participants
+                conversation = cast(list[ChatMessage], event.data)
+                if isinstance(conversation, list):
+                    print("\n=== Final Conversation Snapshot ===")
+                    for message in conversation:
+                        speaker = message.author_name or message.role
+                        print(f"- {speaker}: {message.text or [content.type for content in message.contents]}")
+                    print("===================================")
         elif isinstance(event, RequestInfoEvent):
+            # RequestInfoEvent: Workflow is requesting user input
             if isinstance(event.data, HandoffAgentUserRequest):
                 _print_handoff_agent_user_request(event.data.agent_response)
             requests.append(event)
@@ -237,9 +237,11 @@ async def main() -> None:
             # Custom termination: Check if the triage agent has provided a closing message.
             # This looks for the last message being from triage_agent and containing "welcome",
             # which indicates the conversation has concluded naturally.
-            lambda conversation: len(conversation) > 0
-            and conversation[-1].author_name == "triage_agent"
-            and "welcome" in conversation[-1].text.lower()
+            lambda conversation: (
+                len(conversation) > 0
+                and conversation[-1].author_name == "triage_agent"
+                and "welcome" in conversation[-1].text.lower()
+            )
         )
     )
 

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

@@ -5,7 +5,6 @@ from typing import Annotated, cast
 
 from agent_framework import (
     AgentResponse,
-    AgentRunEvent,
     ChatAgent,
     ChatMessage,
     HandoffAgentUserRequest,
@@ -38,7 +37,10 @@ Key Concepts:
 """
 
 
-# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
+# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
+# See:
+# samples/getting_started/tools/function_tool_with_approval.py
+# samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def process_refund(order_number: Annotated[str, "Order number to process refund for"]) -> str:
     """Simulated function to process a refund for a given order number."""
@@ -120,38 +122,36 @@ def _handle_events(events: list[WorkflowEvent]) -> list[RequestInfoEvent]:
     requests: list[RequestInfoEvent] = []
 
     for event in events:
-        # AgentRunEvent: Contains messages generated by agents during their turn
-        if isinstance(event, AgentRunEvent):
-            for message in event.data.messages:
-                if not message.text:
-                    # Skip messages without text (e.g., tool calls)
-                    continue
-                speaker = message.author_name or message.role
-                print(f"- {speaker}: {message.text}")
-
-        # HandoffSentEvent: Indicates a handoff has been initiated
         if isinstance(event, HandoffSentEvent):
+            # HandoffSentEvent: Indicates a handoff has been initiated
             print(f"\n[Handoff from {event.source} to {event.target} initiated.]")
-
-        # WorkflowStatusEvent: Indicates workflow state changes
-        if isinstance(event, WorkflowStatusEvent) and event.state in {
+        elif isinstance(event, WorkflowStatusEvent) and event.state in {
             WorkflowRunState.IDLE,
             WorkflowRunState.IDLE_WITH_PENDING_REQUESTS,
         }:
+            # WorkflowStatusEvent: Indicates workflow state changes
             print(f"\n[Workflow Status] {event.state.name}")
-
-        # WorkflowOutputEvent: Contains the final conversation when workflow terminates
         elif isinstance(event, WorkflowOutputEvent):
-            conversation = cast(list[ChatMessage], event.data)
-            if isinstance(conversation, list):
-                print("\n=== Final Conversation Snapshot ===")
-                for message in conversation:
+            # WorkflowOutputEvent: Contains contents generated by the workflow
+            data = event.data
+            if isinstance(data, AgentResponse):
+                for message in data.messages:
+                    if not message.text:
+                        # Skip messages without text (e.g., tool calls)
+                        continue
                     speaker = message.author_name or message.role
-                    print(f"- {speaker}: {message.text or [content.type for content in message.contents]}")
-                print("===================================")
-
-        # RequestInfoEvent: Workflow is requesting user input
+                    print(f"- {speaker}: {message.text}")
+            else:
+                # The output of the handoff workflow is a collection of chat messages from all participants
+                conversation = cast(list[ChatMessage], event.data)
+                if isinstance(conversation, list):
+                    print("\n=== Final Conversation Snapshot ===")
+                    for message in conversation:
+                        speaker = message.author_name or message.role
+                        print(f"- {speaker}: {message.text or [content.type for content in message.contents]}")
+                    print("===================================")
         elif isinstance(event, RequestInfoEvent):
+            # RequestInfoEvent: Workflow is requesting user input
             if isinstance(event.data, HandoffAgentUserRequest):
                 _print_handoff_agent_user_request(event.data.agent_response)
             requests.append(event)

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

@@ -6,7 +6,7 @@ Handoff Workflow with Code Interpreter File Generation Sample
 This sample demonstrates retrieving file IDs from code interpreter output
 in a handoff workflow context. A triage agent routes to a code specialist
 that generates a text file, and we verify the file_id is captured correctly
-from the streaming AgentRunUpdateEvent events.
+from the streaming WorkflowOutputEvent events.
 
 Verifies GitHub issue #2718: files generated by code interpreter in
 HandoffBuilder workflows can be properly retrieved.
@@ -28,17 +28,19 @@ Prerequisites:
 import asyncio
 from collections.abc import AsyncIterable, AsyncIterator
 from contextlib import asynccontextmanager
+from typing import cast
 
 from agent_framework import (
-    AgentRunUpdateEvent,
+    AgentResponseUpdate,
     ChatAgent,
-    Content,
+    ChatMessage,
     HandoffAgentUserRequest,
     HandoffBuilder,
+    HandoffSentEvent,
     HostedCodeInterpreterTool,
-    HostedFileContent,
     RequestInfoEvent,
     WorkflowEvent,
+    WorkflowOutputEvent,
     WorkflowRunState,
     WorkflowStatusEvent,
 )
@@ -63,24 +65,42 @@ def _handle_events(events: list[WorkflowEvent]) -> tuple[list[RequestInfoEvent],
     file_ids: list[str] = []
 
     for event in events:
-        if isinstance(event, WorkflowStatusEvent):
-            if event.state in {WorkflowRunState.IDLE, WorkflowRunState.IDLE_WITH_PENDING_REQUESTS}:
-                print(f"[status] {event.state.name}")
-
+        if isinstance(event, HandoffSentEvent):
+            # HandoffSentEvent: Indicates a handoff has been initiated
+            print(f"\n[Handoff from {event.source} to {event.target} initiated.]")
+        elif isinstance(event, WorkflowStatusEvent) and event.state in {
+            WorkflowRunState.IDLE,
+            WorkflowRunState.IDLE_WITH_PENDING_REQUESTS,
+        }:
+            # WorkflowStatusEvent: Indicates workflow state changes
+            print(f"\n[Workflow Status] {event.state.name}")
+        elif isinstance(event, WorkflowOutputEvent):
+            # WorkflowOutputEvent: Contains contents generated by the workflow
+            data = event.data
+            if isinstance(data, AgentResponseUpdate):
+                # AgentResponseUpdate: Intermediate output from an agent
+                for content in data.contents:
+                    if content.type == "hosted_file":
+                        file_ids.append(content.file_id)  # type: ignore
+                        print(f"[Found HostedFileContent: file_id={content.file_id}]")
+                    elif content.type == "text" and content.annotations:
+                        for annotation in content.annotations:
+                            file_id = annotation["file_id"]  # type: ignore
+                            file_ids.append(file_id)
+                            print(f"[Found file annotation: file_id={file_id}]")
+            else:
+                # The output of the handoff workflow is a collection of chat messages from all participants
+                conversation = cast(list[ChatMessage], event.data)
+                if isinstance(conversation, list):
+                    print("\n=== Final Conversation Snapshot ===")
+                    for message in conversation:
+                        speaker = message.author_name or message.role
+                        print(f"- {speaker}: {message.text or [content.type for content in message.contents]}")
+                    print("===================================")
         elif isinstance(event, RequestInfoEvent):
+            # RequestInfoEvent: Workflow is requesting user input
             requests.append(event)
 
-        elif isinstance(event, AgentRunUpdateEvent):
-            for content in event.data.contents:
-                if isinstance(content, HostedFileContent):
-                    file_ids.append(content.file_id)
-                    print(f"[Found HostedFileContent: file_id={content.file_id}]")
-                elif content.type == "text" and content.annotations:
-                    for annotation in content.annotations:
-                        if hasattr(annotation, "file_id") and annotation.file_id:
-                            file_ids.append(annotation.file_id)
-                            print(f"[Found file annotation: file_id={annotation.file_id}]")
-
     return requests, file_ids
 
 
@@ -108,7 +128,7 @@ async def create_agents_v1(credential: AzureCliCredential) -> AsyncIterator[tupl
             tools=[HostedCodeInterpreterTool()],
         )
 
-        yield triage, code_specialist
+        yield triage, code_specialist  # type: ignore
 
 
 @asynccontextmanager

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

@@ -6,7 +6,7 @@ import logging
 from typing import cast
 
 from agent_framework import (
-    AgentRunUpdateEvent,
+    AgentResponseUpdate,
     ChatAgent,
     ChatMessage,
     GroupChatRequestSentEvent,
@@ -86,6 +86,9 @@ async def main() -> None:
             max_stall_count=3,
             max_reset_count=2,
         )
+        # Enable intermediate outputs to observe the conversation as it unfolds
+        # Intermediate outputs will be emitted as WorkflowOutputEvent events
+        .with_intermediate_outputs()
         .build()
     )
 
@@ -102,19 +105,9 @@ async def main() -> None:
     print("\nStarting workflow execution...")
 
     # Keep track of the last executor to format output nicely in streaming mode
-    last_message_id: str | None = None
-    output_event: WorkflowOutputEvent | None = None
+    last_response_id: str | None = None
     async for event in workflow.run_stream(task):
-        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)
-
-        elif isinstance(event, MagenticOrchestratorEvent):
+        if 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}")
@@ -132,18 +125,22 @@ async def main() -> None:
             print(f"\n[REQUEST SENT ({event.round_index})] to agent: {event.participant_name}")
 
         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)
+            data = event.data
+            if isinstance(data, AgentResponseUpdate):
+                response_id = data.response_id
+                if response_id != last_response_id:
+                    if last_response_id is not None:
+                        print("\n")
+                    print(f"- {event.executor_id}:", end=" ", flush=True)
+                    last_response_id = response_id
+                print(event.data, end="", flush=True)
+            else:
+                # The output of the magentic workflow is a collection of chat messages from all participants
+                outputs = cast(list[ChatMessage], event.data)
+                print("\n" + "=" * 80)
+                print("\nFinal Conversation Transcript:\n")
+                for message in outputs:
+                    print(f"{message.author_name or message.role}: {message.text}\n")
 
 
 if __name__ == "__main__":

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

@@ -2,15 +2,18 @@
 
 import asyncio
 import json
+from collections.abc import AsyncIterable
 from typing import cast
 
 from agent_framework import (
-    AgentRunUpdateEvent,
+    AgentResponseUpdate,
     ChatAgent,
     ChatMessage,
     MagenticBuilder,
     MagenticPlanReviewRequest,
+    MagenticPlanReviewResponse,
     RequestInfoEvent,
+    WorkflowEvent,
     WorkflowOutputEvent,
 )
 from agent_framework.openai import OpenAIChatClient
@@ -35,6 +38,62 @@ Prerequisites:
 - OpenAI credentials configured for `OpenAIChatClient`.
 """
 
+# Keep track of the last response to format output nicely in streaming mode
+last_response_id: str | None = None
+
+
+async def process_event_stream(stream: AsyncIterable[WorkflowEvent]) -> dict[str, MagenticPlanReviewResponse] | None:
+    """Process events from the workflow stream to capture human feedback requests."""
+    global last_response_id
+
+    requests: dict[str, MagenticPlanReviewRequest] = {}
+    async for event in stream:
+        if isinstance(event, RequestInfoEvent) and event.request_type is MagenticPlanReviewRequest:
+            requests[event.request_id] = cast(MagenticPlanReviewRequest, event.data)
+
+        if isinstance(event, WorkflowOutputEvent):
+            data = event.data
+            if isinstance(data, AgentResponseUpdate):
+                rid = data.response_id
+                if rid != last_response_id:
+                    if last_response_id is not None:
+                        print("\n")
+                    print(f"{data.author_name}:", end=" ", flush=True)
+                    last_response_id = rid
+                print(data.text, end="", flush=True)
+            else:
+                # The output of the workflow comes from the orchestrator and it's a list of messages
+                print("\n" + "=" * 60)
+                print("DISCUSSION COMPLETE")
+                print("=" * 60)
+                print("Final discussion summary:")
+                # To make the type checker happy, we cast event.data to the expected type
+                outputs = cast(list[ChatMessage], event.data)
+                for msg in outputs:
+                    speaker = msg.author_name or msg.role.value
+                    print(f"[{speaker}]: {msg.text}")
+
+    responses: dict[str, MagenticPlanReviewResponse] = {}
+    if requests:
+        for request_id, request in requests.items():
+            print("\n\n[Magentic Plan Review Request]")
+            if request.current_progress is not None:
+                print("Current Progress Ledger:")
+                print(json.dumps(request.current_progress.to_dict(), indent=2))
+                print()
+            print(f"Proposed Plan:\n{request.plan.text}\n")
+            print("Please provide your feedback (press Enter to approve):")
+
+            reply = input("> ")  # noqa: ASYNC250
+            if reply.strip() == "":
+                print("Plan approved.\n")
+                responses[request_id] = request.approve()
+            else:
+                print("Plan revised by human.\n")
+                responses[request_id] = request.revise(reply)
+
+    return responses if responses else None
+
 
 async def main() -> None:
     researcher_agent = ChatAgent(
@@ -69,7 +128,11 @@ async def main() -> None:
             max_stall_count=1,
             max_reset_count=2,
         )
-        .with_plan_review()  # Request human input for plan review
+        # Request human input for plan review
+        .with_plan_review()
+        # Enable intermediate outputs to observe the conversation as it unfolds
+        # Intermediate outputs will be emitted as WorkflowOutputEvent events
+        .with_intermediate_outputs()
         .build()
     )
 
@@ -79,66 +142,16 @@ async def main() -> None:
     print("\nStarting workflow execution...")
     print("=" * 60)
 
-    pending_request: RequestInfoEvent | None = None
-    pending_responses: dict[str, object] | None = None
-    output_event: WorkflowOutputEvent | None = None
+    # Initiate the first run of the workflow.
+    # Runs are not isolated; state is preserved across multiple calls to run or send_responses_streaming.
+    stream = workflow.run_stream(task)
 
-    while not output_event:
-        if pending_responses is not None:
-            stream = workflow.send_responses_streaming(pending_responses)
-        else:
-            stream = workflow.run_stream(task)
-
-        last_message_id: str | None = None
-        async for event in stream:
-            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)
-
-            elif isinstance(event, RequestInfoEvent) and event.request_type is MagenticPlanReviewRequest:
-                pending_request = event
-
-            elif isinstance(event, WorkflowOutputEvent):
-                output_event = event
-
-        pending_responses = None
-
-        # Handle plan review request if any
-        if pending_request is not None:
-            event_data = cast(MagenticPlanReviewRequest, pending_request.data)
-
-            print("\n\n[Magentic Plan Review Request]")
-            if event_data.current_progress is not None:
-                print("Current Progress Ledger:")
-                print(json.dumps(event_data.current_progress.to_dict(), indent=2))
-                print()
-            print(f"Proposed Plan:\n{event_data.plan.text}\n")
-            print("Please provide your feedback (press Enter to approve):")
-
-            reply = await asyncio.get_event_loop().run_in_executor(None, input, "> ")
-            if reply.strip() == "":
-                print("Plan approved.\n")
-                pending_responses = {pending_request.request_id: event_data.approve()}
-            else:
-                print("Plan revised by human.\n")
-                pending_responses = {pending_request.request_id: event_data.revise(reply)}
-            pending_request = None
-
-    print("\n" + "=" * 60)
-    print("WORKFLOW COMPLETED")
-    print("=" * 60)
-    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)
+    pending_responses = await process_event_stream(stream)
+    while pending_responses is not None:
+        # Run the workflow until there is no more human feedback to provide,
+        # in which case this workflow completes.
+        stream = workflow.send_responses_streaming(pending_responses)
+        pending_responses = await process_event_stream(stream)
 
 
 if __name__ == "__main__":

python/samples/getting_started/workflows/parallelism/aggregate_results_of_different_types.py

@@ -13,7 +13,6 @@ Purpose:
 Show how to construct a parallel branch pattern in workflows. Demonstrate:
 - Fan out by targeting multiple executors from one dispatcher.
 - Fan in by collecting a list of results from the executors.
-- Simple tracing using AgentRunEvent to observe execution order and progress.
 
 Prerequisites:
 - Familiarity with WorkflowBuilder, executors, edges, events, and streaming runs.

python/samples/getting_started/workflows/parallelism/fan_out_fan_in_edges.py

@@ -15,7 +15,7 @@ from agent_framework import (  # Core chat primitives to build LLM requests
     WorkflowContext,  # Per run context and event bus
     WorkflowOutputEvent,  # Event emitted when workflow yields output
     handler,  # Decorator to mark an Executor method as invokable
-    )
+)
 from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential  # Uses your az CLI login for credentials
 from typing_extensions import Never
@@ -30,7 +30,6 @@ Purpose:
 Show how to construct a parallel branch pattern in workflows. Demonstrate:
 - Fan out by targeting multiple AgentExecutor nodes from one dispatcher.
 - Fan in by collecting a list of AgentExecutorResponse objects and reducing them to a single result.
-- Simple tracing using AgentRunEvent to observe execution order and progress.
 
 Prerequisites:
 - Familiarity with WorkflowBuilder, executors, edges, events, and streaming runs.

python/samples/getting_started/workflows/parallelism/map_reduce_and_visualization.py

@@ -14,7 +14,7 @@ from agent_framework import (
     WorkflowOutputEvent,  # Event emitted when workflow yields output
     WorkflowViz,  # Utility to visualize a workflow graph
     handler,  # Decorator to expose an Executor method as a step
-    )
+)
 from typing_extensions import Never
 
 """
@@ -286,7 +286,8 @@ async def main():
 
     # Step 2: Build the workflow graph using fan out and fan in edges.
     workflow = (
-        workflow_builder.set_start_executor("split_data_executor")
+        workflow_builder
+        .set_start_executor("split_data_executor")
         .add_fan_out_edges(
             "split_data_executor",
             ["map_executor_0", "map_executor_1", "map_executor_2"],

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

@@ -1,6 +1,7 @@
 # Copyright (c) Microsoft. All rights reserved.
 
 import asyncio
+from collections.abc import AsyncIterable
 from typing import Annotated
 
 from agent_framework import (
@@ -8,6 +9,7 @@ from agent_framework import (
     ConcurrentBuilder,
     Content,
     RequestInfoEvent,
+    WorkflowEvent,
     WorkflowOutputEvent,
     tool,
 )
@@ -44,7 +46,10 @@ Prerequisites:
 
 
 # 1. Define market data tools (no approval required)
-# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
+# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
+# See:
+# samples/getting_started/tools/function_tool_with_approval.py
+# samples/getting_started/tools/function_tool_with_approval_and_threads.py.
 @tool(approval_mode="never_require")
 def get_stock_price(symbol: Annotated[str, "The stock ticker symbol"]) -> str:
     """Get the current stock price for a given symbol."""
@@ -100,6 +105,27 @@ def _print_output(event: WorkflowOutputEvent) -> None:
             print(f"- {msg.author_name or msg.role}: {msg.text}")
 
 
+async def process_event_stream(stream: AsyncIterable[WorkflowEvent]) -> dict[str, Content] | None:
+    """Process events from the workflow stream to capture human feedback requests."""
+    requests: dict[str, Content] = {}
+    async for event in stream:
+        if isinstance(event, RequestInfoEvent) and isinstance(event.data, Content):
+            # We are only expecting tool approval requests in this sample
+            requests[event.request_id] = event.data
+        elif isinstance(event, WorkflowOutputEvent):
+            _print_output(event)
+
+    responses: dict[str, Content] = {}
+    if requests:
+        for request_id, request in requests.items():
+            if request.type == "function_approval_request":
+                print(f"\nSimulating human approval for: {request.function_call.name}")  # type: ignore
+                # Create approval response
+                responses[request_id] = request.to_function_approval_response(approved=True)
+
+    return responses if responses else None
+
+
 async def main() -> None:
     # 3. Create two agents focused on different stocks but with the same tool sets
     chat_client = OpenAIChatClient()
@@ -130,37 +156,19 @@ async def main() -> None:
     print("Starting concurrent workflow with tool approval...")
     print("-" * 60)
 
-    # Phase 1: Run workflow and collect request info events
-    request_info_events: list[RequestInfoEvent] = []
-    async for event in workflow.run_stream(
+    # Initiate the first run of the workflow.
+    # Runs are not isolated; state is preserved across multiple calls to run or send_responses_streaming.
+    stream = workflow.run_stream(
         "Manage my portfolio. Use a max of 5000 dollars to adjust my position using "
         "your best judgment based on market sentiment. No need to confirm trades with me."
-    ):
-        if isinstance(event, RequestInfoEvent):
-            request_info_events.append(event)
-            if isinstance(event.data, Content) and event.data.type == "function_approval_request":
-                print(f"\nApproval requested for tool: {event.data.function_call.name}")
-                print(f"  Arguments: {event.data.function_call.arguments}")
-        elif isinstance(event, WorkflowOutputEvent):
-            _print_output(event)
+    )
 
-    # 6. Handle approval requests (if any)
-    if request_info_events:
-        responses: dict[str, Content] = {}
-        for request_event in request_info_events:
-            if isinstance(request_event.data, Content) and request_event.data.type == "function_approval_request":
-                print(f"\nSimulating human approval for: {request_event.data.function_call.name}")
-                # Create approval response
-                responses[request_event.request_id] = request_event.data.to_function_approval_response(approved=True)
-
-        if responses:
-            # Phase 2: Send all approvals and continue workflow
-            async for event in workflow.send_responses_streaming(responses):
-                if isinstance(event, WorkflowOutputEvent):
-                    _print_output(event)
-    else:
-        print("\nWorkflow completed without requiring approvals.")
-        print("(The agents may have only checked data without executing trades)")
+    pending_responses = await process_event_stream(stream)
+    while pending_responses is not None:
+        # Run the workflow until there is no more human feedback to provide,
+        # in which case this workflow completes.
+        stream = workflow.send_responses_streaming(pending_responses)
+        pending_responses = await process_event_stream(stream)
 
     """
     Sample Output:

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

@@ -1,15 +1,17 @@
 # Copyright (c) Microsoft. All rights reserved.
 
 import asyncio
-from typing import Annotated
+from collections.abc import AsyncIterable
+from typing import Annotated, cast
 
 from agent_framework import (
-    AgentRunUpdateEvent,
+    ChatMessage,
     Content,
     GroupChatBuilder,
-    GroupChatRequestSentEvent,
     GroupChatState,
     RequestInfoEvent,
+    WorkflowEvent,
+    WorkflowOutputEvent,
     tool,
 )
 from agent_framework.openai import OpenAIChatClient
@@ -93,6 +95,36 @@ def select_next_speaker(state: GroupChatState) -> str:
     return "DevOpsEngineer"  # Subsequent speakers
 
 
+async def process_event_stream(stream: AsyncIterable[WorkflowEvent]) -> dict[str, Content] | None:
+    """Process events from the workflow stream to capture human feedback requests."""
+    requests: dict[str, Content] = {}
+    async for event in stream:
+        if isinstance(event, RequestInfoEvent) and isinstance(event.data, Content):
+            # We are only expecting tool approval requests in this sample
+            requests[event.request_id] = event.data
+        elif isinstance(event, WorkflowOutputEvent):
+            # The output of the workflow comes from the orchestrator and it's a list of messages
+            print("\n" + "=" * 60)
+            print("Workflow summary:")
+            outputs = cast(list[ChatMessage], event.data)
+            for msg in outputs:
+                speaker = msg.author_name or msg.role.value
+                print(f"[{speaker}]: {msg.text}")
+
+    responses: dict[str, Content] = {}
+    if requests:
+        for request_id, request in requests.items():
+            if request.type == "function_approval_request":
+                print("\n[APPROVAL REQUIRED]")
+                print(f"  Tool: {request.function_call.name}")  # type: ignore
+                print(f"  Arguments: {request.function_call.arguments}")  # type: ignore
+                print(f"Simulating human approval for: {request.function_call.name}")  # type: ignore
+                # Create approval response
+                responses[request_id] = request.to_function_approval_response(approved=True)
+
+    return responses if responses else None
+
+
 async def main() -> None:
     # 3. Create specialized agents
     chat_client = OpenAIChatClient()
@@ -135,67 +167,16 @@ async def main() -> None:
     print(f"Agents: {[qa_engineer.name, devops_engineer.name]}")
     print("-" * 60)
 
-    # Phase 1: Run workflow and collect all events (stream ends at IDLE or IDLE_WITH_PENDING_REQUESTS)
-    request_info_events: list[RequestInfoEvent] = []
-    # Keep track of the last response to format output nicely in streaming mode
-    last_response_id: str | None = None
-    async for event in workflow.run_stream(
-        "We need to deploy version 2.4.0 to production. Please coordinate the deployment."
-    ):
-        if isinstance(event, RequestInfoEvent):
-            request_info_events.append(event)
-            if isinstance(event.data, Content) and event.data.type == "function_approval_request":
-                print("\n[APPROVAL REQUIRED] From agent:", event.source_executor_id)
-                print(f"  Tool: {event.data.function_call.name}")
-                print(f"  Arguments: {event.data.function_call.arguments}")
-        elif isinstance(event, AgentRunUpdateEvent):
-            if not event.data.text:
-                continue  # Skip empty updates
-            response_id = event.data.response_id
-            if response_id != last_response_id:
-                if last_response_id is not None:
-                    print("\n")
-                print(f"- {event.executor_id}:", end=" ", flush=True)
-                last_response_id = response_id
-            print(event.data, end="", flush=True)
-        elif isinstance(event, GroupChatRequestSentEvent):
-            print(f"\n[REQUEST SENT ({event.round_index})] to agent: {event.participant_name}")
+    # Initiate the first run of the workflow.
+    # Runs are not isolated; state is preserved across multiple calls to run or send_responses_streaming.
+    stream = workflow.run_stream("We need to deploy version 2.4.0 to production. Please coordinate the deployment.")
 
-    # 6. Handle approval requests
-    if request_info_events:
-        for request_event in request_info_events:
-            if isinstance(request_event.data, Content) and request_event.data.type == "function_approval_request":
-                print("\n" + "=" * 60)
-                print("Human review required for production deployment!")
-                print("In a real scenario, you would review the deployment details here.")
-                print("Simulating approval for demo purposes...")
-                print("=" * 60)
-
-                # Create approval response
-                approval_response = request_event.data.to_function_approval_response(approved=True)
-
-                # Phase 2: Send approval and continue workflow
-                # Keep track of the response to format output nicely in streaming mode
-                last_response_id: str | None = None
-                async for event in workflow.send_responses_streaming({request_event.request_id: approval_response}):
-                    if isinstance(event, AgentRunUpdateEvent):
-                        if not event.data.text:
-                            continue  # Skip empty updates
-                        response_id = event.data.response_id
-                        if response_id != last_response_id:
-                            if last_response_id is not None:
-                                print("\n")
-                            print(f"- {event.executor_id}:", end=" ", flush=True)
-                            last_response_id = response_id
-                        print(event.data, end="", flush=True)
-                    elif isinstance(event, GroupChatRequestSentEvent):
-                        print(f"\n[REQUEST SENT ({event.round_index})] To agent: {event.participant_name}")
-
-                print("\n" + "-" * 60)
-                print("Deployment workflow completed successfully!")
-                print("All agents have finished their tasks.")
-    else:
-        print("\nWorkflow completed without requiring production deployment approval.")
+    pending_responses = await process_event_stream(stream)
+    while pending_responses is not None:
+        # Run the workflow until there is no more human feedback to provide,
+        # in which case this workflow completes.
+        stream = workflow.send_responses_streaming(pending_responses)
+        pending_responses = await process_event_stream(stream)
 
     """
     Sample Output:

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

@@ -1,13 +1,15 @@
 # Copyright (c) Microsoft. All rights reserved.
 
 import asyncio
-from typing import Annotated
+from collections.abc import AsyncIterable
+from typing import Annotated, cast
 
 from agent_framework import (
     ChatMessage,
     Content,
     RequestInfoEvent,
     SequentialBuilder,
+    WorkflowEvent,
     WorkflowOutputEvent,
     tool,
 )
@@ -65,6 +67,36 @@ def get_database_schema() -> str:
     """
 
 
+async def process_event_stream(stream: AsyncIterable[WorkflowEvent]) -> dict[str, Content] | None:
+    """Process events from the workflow stream to capture human feedback requests."""
+    requests: dict[str, Content] = {}
+    async for event in stream:
+        if isinstance(event, RequestInfoEvent) and isinstance(event.data, Content):
+            # We are only expecting tool approval requests in this sample
+            requests[event.request_id] = event.data
+        elif isinstance(event, WorkflowOutputEvent):
+            # The output of the workflow comes from the orchestrator and it's a list of messages
+            print("\n" + "=" * 60)
+            print("Workflow summary:")
+            outputs = cast(list[ChatMessage], event.data)
+            for msg in outputs:
+                speaker = msg.author_name or msg.role
+                print(f"[{speaker}]: {msg.text}")
+
+    responses: dict[str, Content] = {}
+    if requests:
+        for request_id, request in requests.items():
+            if request.type == "function_approval_request":
+                print("\n[APPROVAL REQUIRED]")
+                print(f"  Tool: {request.function_call.name}")  # type: ignore
+                print(f"  Arguments: {request.function_call.arguments}")  # type: ignore
+                print(f"Simulating human approval for: {request.function_call.name}")  # type: ignore
+                # Create approval response
+                responses[request_id] = request.to_function_approval_response(approved=True)
+
+    return responses if responses else None
+
+
 async def main() -> None:
     # 2. Create the agent with tools (approval mode is set per-tool via decorator)
     chat_client = OpenAIChatClient()
@@ -85,42 +117,16 @@ async def main() -> None:
     print("Starting sequential workflow with tool approval...")
     print("-" * 60)
 
-    # Phase 1: Run workflow and collect all events (stream ends at IDLE or IDLE_WITH_PENDING_REQUESTS)
-    request_info_events: list[RequestInfoEvent] = []
-    async for event in workflow.run_stream(
-        "Check the schema and then update all orders with status 'pending' to 'processing'"
-    ):
-        if isinstance(event, RequestInfoEvent):
-            request_info_events.append(event)
-            if isinstance(event.data, Content) and event.data.type == "function_approval_request":
-                print(f"\nApproval requested for tool: {event.data.function_call.name}")
-                print(f"  Arguments: {event.data.function_call.arguments}")
+    # Initiate the first run of the workflow.
+    # Runs are not isolated; state is preserved across multiple calls to run or send_responses_streaming.
+    stream = workflow.run_stream("Check the schema and then update all orders with status 'pending' to 'processing'")
 
-    # 5. Handle approval requests
-    if request_info_events:
-        for request_event in request_info_events:
-            if isinstance(request_event.data, Content) and request_event.data.type == "function_approval_request":
-                # In a real application, you would prompt the user here
-                print("\nSimulating human approval (auto-approving for demo)...")
-
-                # Create approval response
-                approval_response = request_event.data.to_function_approval_response(approved=True)
-
-                # Phase 2: Send approval and continue workflow
-                output: list[ChatMessage] | None = None
-                async for event in workflow.send_responses_streaming({request_event.request_id: approval_response}):
-                    if isinstance(event, WorkflowOutputEvent):
-                        output = event.data
-
-                if output:
-                    print("\n" + "-" * 60)
-                    print("Workflow completed. Final conversation:")
-                    for msg in output:
-                        role = msg.role if hasattr(msg.role, "value") else msg.role
-                        text = msg.text[:200] + "..." if len(msg.text) > 200 else msg.text
-                        print(f"  [{role}]: {text}")
-    else:
-        print("No approval requests were generated (schema check may have been sufficient).")
+    pending_responses = await process_event_stream(stream)
+    while pending_responses is not None:
+        # Run the workflow until there is no more human feedback to provide,
+        # in which case this workflow completes.
+        stream = workflow.send_responses_streaming(pending_responses)
+        pending_responses = await process_event_stream(stream)
 
     """
     Sample Output: