Python: [BREAKING] Python: Rename workflow to workflows (#1007)

* Rename workflow to workflows

* Update occurence of workflow to new name

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

@@ -0,0 +1,129 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import Any
+
+from agent_framework import ChatMessage, ConcurrentBuilder
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+
+"""
+Sample: Concurrent fan-out/fan-in (agent-only API) with default aggregator
+
+Build a high-level concurrent workflow using ConcurrentBuilder and three domain agents.
+The default dispatcher fans out the same user prompt to all agents in parallel.
+The default aggregator fans in their results and yields output containing
+a list[ChatMessage] representing the concatenated conversations from all agents.
+
+Demonstrates:
+- Minimal wiring with ConcurrentBuilder().participants([...]).build()
+- Fan-out to multiple agents, fan-in aggregation of final ChatMessages
+- Workflow completion when idle with no pending work
+
+Prerequisites:
+- Azure OpenAI access configured for AzureOpenAIChatClient (use az login + env vars)
+- Familiarity with Workflow events (AgentRunEvent, WorkflowOutputEvent)
+"""
+
+
+async def main() -> None:
+    # 1) Create three domain agents using AzureOpenAIChatClient
+    chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
+
+    researcher = chat_client.create_agent(
+        instructions=(
+            "You're an expert market and product researcher. Given a prompt, provide concise, factual insights,"
+            " opportunities, and risks."
+        ),
+        name="researcher",
+    )
+
+    marketer = chat_client.create_agent(
+        instructions=(
+            "You're a creative marketing strategist. Craft compelling value propositions and target messaging"
+            " aligned to the prompt."
+        ),
+        name="marketer",
+    )
+
+    legal = chat_client.create_agent(
+        instructions=(
+            "You're a cautious legal/compliance reviewer. Highlight constraints, disclaimers, and policy concerns"
+            " based on the prompt."
+        ),
+        name="legal",
+    )
+
+    # 2) Build a concurrent workflow
+    # Participants are either Agents (type of AgentProtocol) or Executors
+    workflow = ConcurrentBuilder().participants([researcher, marketer, legal]).build()
+
+    # 3) Run with a single prompt and pretty-print the final combined messages
+    events = await workflow.run("We are launching a new budget-friendly electric bike for urban commuters.")
+    outputs = events.get_outputs()
+
+    if outputs:
+        print("===== Final Aggregated Conversation (messages) =====")
+        for output in outputs:
+            messages: list[ChatMessage] | Any = output
+            for i, msg in enumerate(messages, start=1):
+                name = msg.author_name if msg.author_name else "user"
+                print(f"{'-' * 60}\n\n{i:02d} [{name}]:\n{msg.text}")
+
+    """
+    Sample Output:
+
+    ===== Final Aggregated Conversation (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
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,174 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import Any
+
+from agent_framework import (
+    AgentExecutorRequest,
+    AgentExecutorResponse,
+    ChatAgent,
+    ChatMessage,
+    ConcurrentBuilder,
+    Executor,
+    WorkflowContext,
+    handler,
+)
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+
+"""
+Sample: Concurrent Orchestration with Custom Agent Executors
+
+This sample shows a concurrent fan-out/fan-in pattern using child Executor classes
+that each own their ChatAgent. The executors accept AgentExecutorRequest inputs
+and emit AgentExecutorResponse outputs, which allows reuse of the high-level
+ConcurrentBuilder API and the default aggregator.
+
+Demonstrates:
+- Executors that create their ChatAgent in __init__ (via AzureOpenAIChatClient)
+- A @handler that converts AgentExecutorRequest -> AgentExecutorResponse
+- ConcurrentBuilder().participants([...]) to build fan-out/fan-in
+- Default aggregator returning list[ChatMessage] (one user + one assistant per agent)
+- Workflow completion when all participants become idle
+
+Prerequisites:
+- Azure OpenAI configured for AzureOpenAIChatClient (az login + required env vars)
+"""
+
+
+class ResearcherExec(Executor):
+    agent: ChatAgent
+
+    def __init__(self, chat_client: AzureOpenAIChatClient, id: str = "researcher"):
+        self.agent = chat_client.create_agent(
+            instructions=(
+                "You're an expert market and product researcher. Given a prompt, provide concise, factual insights,"
+                " opportunities, and risks."
+            ),
+            name=id,
+        )
+        super().__init__(id=id)
+
+    @handler
+    async def run(self, request: AgentExecutorRequest, ctx: WorkflowContext[AgentExecutorResponse]) -> None:
+        response = await self.agent.run(request.messages)
+        full_conversation = list(request.messages) + list(response.messages)
+        await ctx.send_message(AgentExecutorResponse(self.id, response, full_conversation=full_conversation))
+
+
+class MarketerExec(Executor):
+    agent: ChatAgent
+
+    def __init__(self, chat_client: AzureOpenAIChatClient, id: str = "marketer"):
+        self.agent = chat_client.create_agent(
+            instructions=(
+                "You're a creative marketing strategist. Craft compelling value propositions and target messaging"
+                " aligned to the prompt."
+            ),
+            name=id,
+        )
+        super().__init__(id=id)
+
+    @handler
+    async def run(self, request: AgentExecutorRequest, ctx: WorkflowContext[AgentExecutorResponse]) -> None:
+        response = await self.agent.run(request.messages)
+        full_conversation = list(request.messages) + list(response.messages)
+        await ctx.send_message(AgentExecutorResponse(self.id, response, full_conversation=full_conversation))
+
+
+class LegalExec(Executor):
+    agent: ChatAgent
+
+    def __init__(self, chat_client: AzureOpenAIChatClient, id: str = "legal"):
+        self.agent = chat_client.create_agent(
+            instructions=(
+                "You're a cautious legal/compliance reviewer. Highlight constraints, disclaimers, and policy concerns"
+                " based on the prompt."
+            ),
+            name=id,
+        )
+        super().__init__(id=id)
+
+    @handler
+    async def run(self, request: AgentExecutorRequest, ctx: WorkflowContext[AgentExecutorResponse]) -> None:
+        response = await self.agent.run(request.messages)
+        full_conversation = list(request.messages) + list(response.messages)
+        await ctx.send_message(AgentExecutorResponse(self.id, response, full_conversation=full_conversation))
+
+
+async def main() -> None:
+    chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
+
+    researcher = ResearcherExec(chat_client)
+    marketer = MarketerExec(chat_client)
+    legal = LegalExec(chat_client)
+
+    workflow = ConcurrentBuilder().participants([researcher, marketer, legal]).build()
+
+    events = await workflow.run("We are launching a new budget-friendly electric bike for urban commuters.")
+    outputs = events.get_outputs()
+
+    if outputs:
+        print("===== Final Aggregated Conversation (messages) =====")
+        messages: list[ChatMessage] | Any = outputs[0]  # Get the first (and typically only) output
+        for i, msg in enumerate(messages, start=1):
+            name = msg.author_name if msg.author_name else "user"
+            print(f"{'-' * 60}\n\n{i:02d} [{name}]:\n{msg.text}")
+
+    """
+    Sample Output:
+
+    ===== Final Aggregated Conversation (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
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,123 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import Any
+
+from agent_framework import ChatMessage, ConcurrentBuilder, Role
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+
+"""
+Sample: Concurrent Orchestration with Custom Aggregator
+
+Build a concurrent workflow with ConcurrentBuilder that fans out one prompt to
+multiple domain agents and fans in their responses. Override the default
+aggregator with a custom async callback that uses AzureOpenAIChatClient.get_response()
+to synthesize a concise, consolidated summary from the experts' outputs.
+The workflow completes when all participants become idle.
+
+Demonstrates:
+- ConcurrentBuilder().participants([...]).with_custom_aggregator(callback)
+- Fan-out to agents and fan-in at an aggregator
+- Aggregation implemented via an LLM call (chat_client.get_response)
+- Workflow output yielded with the synthesized summary string
+
+Prerequisites:
+- Azure OpenAI configured for AzureOpenAIChatClient (az login + required env vars)
+"""
+
+
+async def main() -> None:
+    chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
+
+    researcher = chat_client.create_agent(
+        instructions=(
+            "You're an expert market and product researcher. Given a prompt, provide concise, factual insights,"
+            " opportunities, and risks."
+        ),
+        name="researcher",
+    )
+    marketer = chat_client.create_agent(
+        instructions=(
+            "You're a creative marketing strategist. Craft compelling value propositions and target messaging"
+            " aligned to the prompt."
+        ),
+        name="marketer",
+    )
+    legal = chat_client.create_agent(
+        instructions=(
+            "You're a cautious legal/compliance reviewer. Highlight constraints, disclaimers, and policy concerns"
+            " based on the prompt."
+        ),
+        name="legal",
+    )
+
+    # Define a custom aggregator callback that uses the chat client to summarize
+    async def summarize_results(results: list[Any]) -> str:
+        # Extract one final assistant message per agent
+        expert_sections: list[str] = []
+        for r in results:
+            try:
+                messages = getattr(r.agent_run_response, "messages", [])
+                final_text = messages[-1].text if messages and hasattr(messages[-1], "text") else "(no content)"
+                expert_sections.append(f"{getattr(r, 'executor_id', 'expert')}:\n{final_text}")
+            except Exception as e:
+                expert_sections.append(f"{getattr(r, 'executor_id', 'expert')}: (error: {type(e).__name__}: {e})")
+
+        # Ask the model to synthesize a concise summary of the experts' outputs
+        system_msg = ChatMessage(
+            Role.SYSTEM,
+            text=(
+                "You are a helpful assistant that consolidates multiple domain expert outputs "
+                "into one cohesive, concise summary with clear takeaways. Keep it under 200 words."
+            ),
+        )
+        user_msg = ChatMessage(Role.USER, text="\n\n".join(expert_sections))
+
+        response = await chat_client.get_response([system_msg, user_msg])
+        # Return the model's final assistant text as the completion result
+        return response.messages[-1].text if response.messages else ""
+
+    # Build with a custom aggregator callback function
+    # - participants([...]) accepts AgentProtocol (agents) or Executor instances.
+    #   Each participant becomes a parallel branch (fan-out) from an internal dispatcher.
+    # - with_aggregator(...) overrides the default aggregator:
+    #   • Default aggregator -> returns list[ChatMessage] (one user + one assistant per agent)
+    #   • Custom callback    -> return value becomes workflow output (string here)
+    #   The callback can be sync or async; it receives list[AgentExecutorResponse].
+    workflow = (
+        ConcurrentBuilder().participants([researcher, marketer, legal]).with_aggregator(summarize_results).build()
+    )
+
+    events = await workflow.run("We are launching a new budget-friendly electric bike for urban commuters.")
+    outputs = events.get_outputs()
+
+    if outputs:
+        print("===== Final Consolidated Output =====")
+        print(outputs[0])  # Get the first (and typically only) output
+
+    """
+    Sample Output:
+
+    ===== Final Consolidated Output =====
+    Urban e-bike demand is rising rapidly due to eco-awareness, urban congestion, and high fuel costs,
+    with market growth projected at a ~10% CAGR through 2030. Key customer concerns are affordability,
+    easy maintenance, convenient charging, compact design, and theft protection. Differentiation opportunities
+    include integrating smart features (GPS, app connectivity), offering subscription or leasing options, and
+    developing portable, space-saving designs. Partnering with local governments and bike shops can boost visibility.
+
+    Risks include price wars eroding margins, regulatory hurdles, battery quality concerns, and heightened expectations
+    for after-sales support. Accurate, substantiated product claims and transparent marketing (with range disclaimers)
+    are essential. All e-bikes must comply with local and federal regulations on speed, wattage, safety certification,
+    and labeling. Clear warranty, safety instructions (especially regarding batteries), and inclusive, accessible
+    marketing are required. For connected features, data privacy policies and user consents are mandatory.
+
+    Effective messaging should target young professionals, students, eco-conscious commuters, and first-time buyers,
+    emphasizing affordability, convenience, and sustainability. Slogan suggestion: “Charge Ahead—City Commutes Made
+    Affordable.” Legal review in each target market, compliance vetting, and robust customer support policies are
+    critical before launch.
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,149 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import logging
+
+from agent_framework import (
+    ChatAgent,
+    HostedCodeInterpreterTool,
+    MagenticAgentDeltaEvent,
+    MagenticAgentMessageEvent,
+    MagenticBuilder,
+    MagenticCallbackEvent,
+    MagenticCallbackMode,
+    MagenticFinalResultEvent,
+    MagenticOrchestratorMessageEvent,
+    WorkflowOutputEvent,
+)
+from agent_framework.openai import OpenAIChatClient, OpenAIResponsesClient
+
+logging.basicConfig(level=logging.DEBUG)
+logger = logging.getLogger(__name__)
+
+"""
+Sample: Magentic Orchestration (multi-agent)
+
+What it does:
+- Orchestrates multiple agents using `MagenticBuilder` with streaming callbacks.
+
+- ResearcherAgent (ChatAgent backed by an OpenAI chat client) for
+    finding information.
+- CoderAgent (ChatAgent backed by OpenAI Assistants with the hosted
+    code interpreter tool) for analysis and computation.
+
+The workflow is configured with:
+- A Standard Magentic manager (uses a chat client for planning and progress).
+- Callbacks for final results, per-message agent responses, and streaming
+    token updates.
+
+When run, the script builds the workflow, submits a task about estimating the
+energy efficiency and CO2 emissions of several ML models, streams intermediate
+events, and prints the final answer. The workflow completes when idle.
+
+Prerequisites:
+- OpenAI credentials configured for `OpenAIChatClient` and `OpenAIResponsesClient`.
+"""
+
+
+async def main() -> None:
+    researcher_agent = ChatAgent(
+        name="ResearcherAgent",
+        description="Specialist in research and information gathering",
+        instructions=(
+            "You are a Researcher. You find information without additional computation or quantitative analysis."
+        ),
+        # This agent requires the gpt-4o-search-preview model to perform web searches.
+        # Feel free to explore with other agents that support web search, for example,
+        # the `OpenAIResponseAgent` or `AzureAgentProtocol` with bing grounding.
+        chat_client=OpenAIChatClient(ai_model_id="gpt-4o-search-preview"),
+    )
+
+    coder_agent = ChatAgent(
+        name="CoderAgent",
+        description="A helpful assistant that writes and executes code to process and analyze data.",
+        instructions="You solve questions using code. Please provide detailed analysis and computation process.",
+        chat_client=OpenAIResponsesClient(),
+        tools=HostedCodeInterpreterTool(),
+    )
+
+    # Unified callback
+    async def on_event(event: MagenticCallbackEvent) -> None:
+        """
+        The `on_event` callback processes events emitted by the workflow.
+        Events include: orchestrator messages, agent delta updates, agent messages, and final result events.
+        """
+        nonlocal last_stream_agent_id, stream_line_open
+        if isinstance(event, MagenticOrchestratorMessageEvent):
+            print(f"\n[ORCH:{event.kind}]\n\n{getattr(event.message, 'text', '')}\n{'-' * 26}")
+        elif isinstance(event, MagenticAgentDeltaEvent):
+            if last_stream_agent_id != event.agent_id or not stream_line_open:
+                if stream_line_open:
+                    print()
+                print(f"\n[STREAM:{event.agent_id}]: ", end="", flush=True)
+                last_stream_agent_id = event.agent_id
+                stream_line_open = True
+            print(event.text, end="", flush=True)
+        elif isinstance(event, MagenticAgentMessageEvent):
+            if stream_line_open:
+                print(" (final)")
+                stream_line_open = False
+                print()
+            msg = event.message
+            if msg is not None:
+                response_text = (msg.text or "").replace("\n", " ")
+                print(f"\n[AGENT:{event.agent_id}] {msg.role.value}\n\n{response_text}\n{'-' * 26}")
+        elif isinstance(event, MagenticFinalResultEvent):
+            print("\n" + "=" * 50)
+            print("FINAL RESULT:")
+            print("=" * 50)
+            if event.message is not None:
+                print(event.message.text)
+            print("=" * 50)
+
+    print("\nBuilding Magentic Workflow...")
+
+    # State used by on_agent_stream callback
+    last_stream_agent_id: str | None = None
+    stream_line_open: bool = False
+
+    workflow = (
+        MagenticBuilder()
+        .participants(researcher=researcher_agent, coder=coder_agent)
+        .on_event(on_event, mode=MagenticCallbackMode.STREAMING)
+        .with_standard_manager(
+            chat_client=OpenAIChatClient(),
+            max_round_count=10,
+            max_stall_count=3,
+            max_reset_count=2,
+        )
+        .build()
+    )
+
+    task = (
+        "I am preparing a report on the energy efficiency of different machine learning model architectures. "
+        "Compare the estimated training and inference energy consumption of ResNet-50, BERT-base, and GPT-2 "
+        "on standard datasets (e.g., ImageNet for ResNet, GLUE for BERT, WebText for GPT-2). "
+        "Then, estimate the CO2 emissions associated with each, assuming training on an Azure Standard_NC6s_v3 "
+        "VM for 24 hours. Provide tables for clarity, and recommend the most energy-efficient model "
+        "per task type (image classification, text classification, and text generation)."
+    )
+
+    print(f"\nTask: {task}")
+    print("\nStarting workflow execution...")
+
+    try:
+        output: str | None = None
+        async for event in workflow.run_stream(task):
+            print(event)
+            if isinstance(event, WorkflowOutputEvent):
+                output = str(event.data)
+
+        if output is not None:
+            print(f"Workflow completed with result:\n\n{output}")
+
+    except Exception as e:
+        print(f"Workflow execution failed: {e}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,299 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import json
+from pathlib import Path
+
+from agent_framework import (
+    ChatAgent,
+    FileCheckpointStorage,
+    MagenticBuilder,
+    MagenticPlanReviewDecision,
+    MagenticPlanReviewReply,
+    MagenticPlanReviewRequest,
+    RequestInfoEvent,
+    WorkflowCheckpoint,
+    WorkflowOutputEvent,
+    WorkflowRunState,
+    WorkflowStatusEvent,
+)
+from agent_framework.openai import OpenAIChatClient
+
+"""
+Sample: Magentic Orchestration + Checkpointing
+
+The goal of this sample is to show the exact mechanics needed to pause a Magentic
+workflow that requires human plan review, persist the outstanding request via a
+checkpoint, and later resume the workflow by feeding in the saved response.
+
+Concepts highlighted here:
+1. **Deterministic executor IDs** - the orchestrator and plan-review request executor
+   must keep stable IDs so the checkpoint state aligns when we rebuild the graph.
+2. **Executor snapshotting** - checkpoints capture the `RequestInfoExecutor` state,
+   specifically the pending plan-review request map, at superstep boundaries.
+3. **Resume with responses** - `Workflow.run_stream_from_checkpoint` accepts a
+   `responses` mapping so we can inject the stored human reply during restoration.
+
+Prerequisites:
+- OpenAI environment variables configured for `OpenAIChatClient`.
+"""
+
+TASK = (
+    "Draft a concise internal brief describing how our research and implementation teams should collaborate "
+    "to launch a beta feature for data-driven email summarization. Highlight the key milestones, "
+    "risks, and communication cadence."
+)
+
+# Dedicated folder for captured checkpoints. Keeping it under the sample directory
+# makes it easy to inspect the JSON blobs produced by each run.
+CHECKPOINT_DIR = Path(__file__).parent / "tmp" / "magentic_checkpoints"
+
+
+def build_workflow(checkpoint_storage: FileCheckpointStorage):
+    """Construct the Magentic workflow graph with checkpointing enabled."""
+
+    # Two vanilla ChatAgents act as participants in the orchestration. They do not need
+    # extra state handling because their inputs/outputs are fully described by chat messages.
+    researcher = ChatAgent(
+        name="ResearcherAgent",
+        description="Collects background facts and references for the project.",
+        instructions=("You are the research lead. Gather crisp bullet points the team should know."),
+        chat_client=OpenAIChatClient(),
+    )
+
+    writer = ChatAgent(
+        name="WriterAgent",
+        description="Synthesizes the final brief for stakeholders.",
+        instructions=("You convert the research notes into a structured brief with milestones and risks."),
+        chat_client=OpenAIChatClient(),
+    )
+
+    # The builder wires in the Magentic orchestrator, sets the plan review path, and
+    # stores the checkpoint backend so the runtime knows where to persist snapshots.
+    return (
+        MagenticBuilder()
+        .participants(researcher=researcher, writer=writer)
+        .with_plan_review()
+        .with_standard_manager(
+            chat_client=OpenAIChatClient(),
+            max_round_count=10,
+            max_stall_count=3,
+        )
+        .with_checkpointing(checkpoint_storage)
+        .build()
+    )
+
+
+async def main() -> None:
+    # Stage 0: make sure the checkpoint folder is empty so we inspect only checkpoints
+    # written by this invocation. This prevents stale files from previous runs from
+    # confusing the analysis.
+    CHECKPOINT_DIR.mkdir(parents=True, exist_ok=True)
+    for file in CHECKPOINT_DIR.glob("*.json"):
+        file.unlink()
+
+    checkpoint_storage = FileCheckpointStorage(CHECKPOINT_DIR)
+
+    print("\n=== Stage 1: run until plan review request (checkpointing active) ===")
+    workflow = build_workflow(checkpoint_storage)
+
+    # Run the workflow until the first RequestInfoEvent is surfaced. The event carries the
+    # request_id we must reuse on resume. In a real system this is where the UI would present
+    # the plan for human review.
+    plan_review_request_id: str | None = None
+    async for event in workflow.run_stream(TASK):
+        if isinstance(event, RequestInfoEvent) and event.request_type is MagenticPlanReviewRequest:
+            plan_review_request_id = event.request_id
+            print(f"Captured plan review request: {plan_review_request_id}")
+
+        if isinstance(event, WorkflowStatusEvent) and event.state is WorkflowRunState.IDLE_WITH_PENDING_REQUESTS:
+            break
+
+    if plan_review_request_id is None:
+        print("No plan review request emitted; nothing to resume.")
+        return
+
+    checkpoints = await checkpoint_storage.list_checkpoints(workflow.workflow.id)
+    if not checkpoints:
+        print("No checkpoints persisted.")
+        return
+
+    resume_checkpoint = max(
+        checkpoints,
+        key=lambda cp: (cp.iteration_count, cp.timestamp),
+    )
+    print(f"Using checkpoint {resume_checkpoint.checkpoint_id} at iteration {resume_checkpoint.iteration_count}")
+
+    # Show that the checkpoint JSON indeed contains the pending plan-review request record.
+    checkpoint_path = checkpoint_storage.storage_path / f"{resume_checkpoint.checkpoint_id}.json"
+    if checkpoint_path.exists():
+        with checkpoint_path.open() as f:
+            snapshot = json.load(f)
+        request_map = snapshot.get("executor_states", {}).get("magentic_plan_review", {}).get("request_events", {})
+        print(f"Pending plan-review requests persisted in checkpoint: {list(request_map.keys())}")
+
+    print("\n=== Stage 2: resume from checkpoint and approve plan ===")
+    resumed_workflow = build_workflow(checkpoint_storage)
+
+    approval = MagenticPlanReviewReply(decision=MagenticPlanReviewDecision.APPROVE)
+    # Resume execution and supply the recorded approval in a single call.
+    # `run_stream_from_checkpoint` rebuilds executor state, applies the provided responses,
+    # and then continues the workflow. Because we only captured the initial plan review
+    # checkpoint, the resumed run should complete almost immediately.
+    final_event: WorkflowOutputEvent | None = None
+    async for event in resumed_workflow.workflow.run_stream_from_checkpoint(
+        resume_checkpoint.checkpoint_id,
+        responses={plan_review_request_id: approval},
+    ):
+        if isinstance(event, WorkflowOutputEvent):
+            final_event = event
+
+    if final_event is None:
+        print("Workflow did not complete after resume.")
+        return
+
+    # Final sanity check: display the assistant's answer as proof the orchestration reached
+    # a natural completion after resuming from the checkpoint.
+    result = final_event.data
+    if not result:
+        print("No result data from workflow.")
+        return
+    text = getattr(result, "text", None) or str(result)
+    print("\n=== Final Answer ===")
+    print(text)
+
+    # ------------------------------------------------------------------
+    # Stage 3: demonstrate resuming from a later checkpoint (post-plan)
+    # ------------------------------------------------------------------
+
+    def _pending_message_count(cp: WorkflowCheckpoint) -> int:
+        return sum(len(msg_list) for msg_list in cp.messages.values() if isinstance(msg_list, list))
+
+    all_checkpoints = await checkpoint_storage.list_checkpoints(resume_checkpoint.workflow_id)
+    later_checkpoints_with_messages = [
+        cp
+        for cp in all_checkpoints
+        if cp.iteration_count > resume_checkpoint.iteration_count and _pending_message_count(cp) > 0
+    ]
+
+    if later_checkpoints_with_messages:
+        post_plan_checkpoint = max(
+            later_checkpoints_with_messages,
+            key=lambda cp: (cp.iteration_count, cp.timestamp),
+        )
+    else:
+        later_checkpoints = [cp for cp in all_checkpoints if cp.iteration_count > resume_checkpoint.iteration_count]
+
+        if not later_checkpoints:
+            print("\nNo additional checkpoints recorded beyond plan approval; sample complete.")
+            return
+
+        post_plan_checkpoint = max(
+            later_checkpoints,
+            key=lambda cp: (cp.iteration_count, cp.timestamp),
+        )
+    print("\n=== Stage 3: resume from post-plan checkpoint ===")
+    pending_messages = _pending_message_count(post_plan_checkpoint)
+    print(
+        f"Resuming from checkpoint {post_plan_checkpoint.checkpoint_id} at iteration "
+        f"{post_plan_checkpoint.iteration_count} (pending messages: {pending_messages})"
+    )
+    if pending_messages == 0:
+        print("Checkpoint has no pending messages; no additional work expected on resume.")
+
+    final_event_post: WorkflowOutputEvent | None = None
+    post_emitted_events = False
+    post_plan_workflow = build_workflow(checkpoint_storage)
+    async for event in post_plan_workflow.workflow.run_stream_from_checkpoint(
+        post_plan_checkpoint.checkpoint_id,
+        responses={},
+    ):
+        post_emitted_events = True
+        if isinstance(event, WorkflowOutputEvent):
+            final_event_post = event
+
+    if final_event_post is None:
+        if not post_emitted_events:
+            print("No new events were emitted; checkpoint already captured a completed run.")
+            print("\n=== Final Answer (post-plan resume) ===")
+            print(text)
+            return
+        print("Workflow did not complete after post-plan resume.")
+        return
+
+    post_result = final_event_post.data
+    if not post_result:
+        print("No result data from post-plan resume.")
+        return
+
+    post_text = getattr(post_result, "text", None) or str(post_result)
+    print("\n=== Final Answer (post-plan resume) ===")
+    print(post_text)
+
+    """
+    Sample Output:
+
+    === Stage 1: run until plan review request (checkpointing active) ===
+    Captured plan review request: 3a1a4a09-4ed1-4c90-9cf6-9ac488d452c0
+    Using checkpoint 4c76d77a-6ff8-4d2b-84f6-824771ffac7e at iteration 1
+    Pending plan-review requests persisted in checkpoint: ['3a1a4a09-4ed1-4c90-9cf6-9ac488d452c0']
+
+    === Stage 2: resume from checkpoint and approve plan ===
+
+    === Final Answer ===
+    Certainly! Here's your concise internal brief on how the research and implementation teams should collaborate for
+    the beta launch of the data-driven email summarization feature:
+
+    ---
+
+    **Internal Brief: Collaboration Plan for Data-driven Email Summarization Beta Launch**
+
+    **Collaboration Approach**
+    - **Joint Kickoff:** Research and Implementation teams hold a project kickoff to align on objectives, requirements,
+        and success metrics.
+    - **Ongoing Coordination:** Teams collaborate closely; researchers share model developments and insights, while
+        implementation ensures smooth integration and user experience.
+    - **Real-time Feedback Loop:** Implementation provides early feedback on technical integration and UX, while
+        Research evaluates initial performance and user engagement signals post-integration.
+
+    **Key Milestones**
+    1. **Requirement Finalization & Scoping** - Define MVP feature set and success criteria.
+    2. **Model Prototyping & Evaluation** - Researchers develop and validate summarization models with agreed metrics.
+    3. **Integration & Internal Testing** - Implementation team integrates the model; internal alpha testing and
+        compliance checks.
+    4. **Beta User Onboarding** - Recruit a select cohort of beta users and guide them through onboarding.
+    5. **Beta Launch & Monitoring** - Soft-launch for beta group, with active monitoring of usage, feedback,
+      and performance.
+    6. **Iterative Improvements** - Address issues, refine features, and prepare for possible broader rollout.
+
+    **Top Risks**
+    - **Data Privacy & Compliance:** Strict protocols and compliance reviews to prevent data leakage.
+    - **Model Quality (Bias, Hallucination):** Careful monitoring of summary accuracy; rapid iterations if critical
+        errors occur.
+    - **User Adoption:** Ensuring the beta solves genuine user needs, collecting actionable feedback early.
+    - **Feedback Quality & Quantity:** Proactively schedule user outreach to ensure substantive beta feedback.
+
+    **Communication Cadence**
+    - **Weekly Team Syncs:** Short all-hands progress and blockers meeting.
+    - **Bi-Weekly Stakeholder Check-ins:** Leadership and project leads address escalations and strategic decisions.
+    - **Dedicated Slack Channel:** For real-time queries and updates.
+    - **Documentation Hub:** Up-to-date project docs and FAQs on a shared internal wiki.
+    - **Post-Milestone Retrospectives:** After critical phases (e.g., alpha, beta), reviewing what worked and what needs
+        improvement.
+
+    **Summary**
+    Clear alignment, consistent communication, and iterative feedback are key to a successful beta. All team members are
+        expected to surface issues quickly and keep documentation current as we drive toward launch.
+    ---
+
+    === Stage 3: resume from post-plan checkpoint ===
+    Resuming from checkpoint 9a3b... at iteration 3 (pending messages: 0)
+    No new events were emitted; checkpoint already captured a completed run.
+
+    === Final Answer (post-plan resume) ===
+    (same brief as above)
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,202 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import logging
+from typing import cast
+
+from agent_framework import (
+    ChatAgent,
+    HostedCodeInterpreterTool,
+    MagenticAgentDeltaEvent,
+    MagenticAgentMessageEvent,
+    MagenticBuilder,
+    MagenticCallbackEvent,
+    MagenticCallbackMode,
+    MagenticFinalResultEvent,
+    MagenticOrchestratorMessageEvent,
+    MagenticPlanReviewDecision,
+    MagenticPlanReviewReply,
+    MagenticPlanReviewRequest,
+    RequestInfoEvent,
+    WorkflowOutputEvent,
+)
+from agent_framework.openai import OpenAIChatClient, OpenAIResponsesClient
+
+logging.basicConfig(level=logging.DEBUG)
+logger = logging.getLogger(__name__)
+
+"""
+Sample: Magentic Orchestration + Human Plan Review
+
+What it does:
+- Builds a Magentic workflow with two agents and enables human plan review.
+  A human approves or edits the plan via `RequestInfoEvent` before execution.
+
+- researcher: ChatAgent backed by OpenAIChatClient (web/search-capable model)
+- coder: ChatAgent backed by OpenAIAssistantsClient with the Hosted Code Interpreter tool
+
+Key behaviors demonstrated:
+- with_plan_review(): requests a PlanReviewRequest before coordination begins
+- Event loop that waits for RequestInfoEvent[PlanReviewRequest], prints the plan, then
+    replies with PlanReviewReply (here we auto-approve, but you can edit/collect input)
+- Callbacks: on_agent_stream (incremental chunks), on_agent_response (final messages),
+    on_result (final answer), and on_exception
+- Workflow completion when idle
+
+Prerequisites:
+- OpenAI credentials configured for `OpenAIChatClient` and `OpenAIResponsesClient`.
+"""
+
+
+async def main() -> None:
+    researcher_agent = ChatAgent(
+        name="ResearcherAgent",
+        description="Specialist in research and information gathering",
+        instructions=(
+            "You are a Researcher. You find information without additional computation or quantitative analysis."
+        ),
+        # This agent requires the gpt-4o-search-preview model to perform web searches.
+        # Feel free to explore with other agents that support web search, for example,
+        # the `OpenAIResponseAgent` or `AzureAgentProtocol` with bing grounding.
+        chat_client=OpenAIChatClient(ai_model_id="gpt-4o-search-preview"),
+    )
+
+    coder_agent = ChatAgent(
+        name="CoderAgent",
+        description="A helpful assistant that writes and executes code to process and analyze data.",
+        instructions="You solve questions using code. Please provide detailed analysis and computation process.",
+        chat_client=OpenAIResponsesClient(),
+        tools=HostedCodeInterpreterTool(),
+    )
+
+    # Callbacks
+    def on_exception(exception: Exception) -> None:
+        print(f"Exception occurred: {exception}")
+        logger.exception("Workflow exception", exc_info=exception)
+
+    last_stream_agent_id: str | None = None
+    stream_line_open: bool = False
+
+    # Unified callback
+    async def on_event(event: MagenticCallbackEvent) -> None:
+        nonlocal last_stream_agent_id, stream_line_open
+        if isinstance(event, MagenticOrchestratorMessageEvent):
+            print(f"\n[ORCH:{event.kind}]\n\n{getattr(event.message, 'text', '')}\n{'-' * 26}")
+        elif isinstance(event, MagenticAgentDeltaEvent):
+            if last_stream_agent_id != event.agent_id or not stream_line_open:
+                if stream_line_open:
+                    print()
+                print(f"\n[STREAM:{event.agent_id}]: ", end="", flush=True)
+                last_stream_agent_id = event.agent_id
+                stream_line_open = True
+            print(event.text, end="", flush=True)
+        elif isinstance(event, MagenticAgentMessageEvent):
+            if stream_line_open:
+                print(" (final)")
+                stream_line_open = False
+                print()
+            msg = event.message
+            if msg is not None:
+                response_text = (msg.text or "").replace("\n", " ")
+                print(f"\n[AGENT:{event.agent_id}] {msg.role.value}\n\n{response_text}\n{'-' * 26}")
+        elif isinstance(event, MagenticFinalResultEvent):
+            print("\n" + "=" * 50)
+            print("FINAL RESULT:")
+            print("=" * 50)
+            if event.message is not None:
+                print(event.message.text)
+            print("=" * 50)
+
+    print("\nBuilding Magentic Workflow...")
+
+    workflow = (
+        MagenticBuilder()
+        .participants(researcher=researcher_agent, coder=coder_agent)
+        .on_exception(on_exception)
+        .on_event(on_event, mode=MagenticCallbackMode.STREAMING)
+        .with_standard_manager(
+            chat_client=OpenAIChatClient(),
+            max_round_count=10,
+            max_stall_count=3,
+            max_reset_count=2,
+        )
+        .with_plan_review()
+        .build()
+    )
+
+    task = (
+        "I am preparing a report on the energy efficiency of different machine learning model architectures. "
+        "Compare the estimated training and inference energy consumption of ResNet-50, BERT-base, and GPT-2 "
+        "on standard datasets (e.g., ImageNet for ResNet, GLUE for BERT, WebText for GPT-2). "
+        "Then, estimate the CO2 emissions associated with each, assuming training on an Azure Standard_NC6s_v3 "
+        "VM for 24 hours. Provide tables for clarity, and recommend the most energy-efficient model "
+        "per task type (image classification, text classification, and text generation)."
+    )
+
+    print(f"\nTask: {task}")
+    print("\nStarting workflow execution...")
+
+    try:
+        pending_request: RequestInfoEvent | None = None
+        pending_responses: dict[str, MagenticPlanReviewReply] | None = None
+        completed = False
+        workflow_output: str | None = None
+
+        while not completed:
+            # Use streaming for both initial run and response sending
+            if pending_responses is not None:
+                stream = workflow.send_responses_streaming(pending_responses)
+            else:
+                stream = workflow.run_stream(task)
+
+            # Collect events from the stream
+            events = [event async for event in stream]
+            pending_responses = None
+
+            # Process events to find request info events, outputs, and completion status
+            for event in events:
+                if isinstance(event, RequestInfoEvent) and event.request_type is MagenticPlanReviewRequest:
+                    pending_request = event
+                    review_req = cast(MagenticPlanReviewRequest, event.data)
+                    if review_req.plan_text:
+                        print(f"\n=== PLAN REVIEW REQUEST ===\n{review_req.plan_text}\n")
+                elif isinstance(event, WorkflowOutputEvent):
+                    # Capture workflow output during streaming
+                    workflow_output = str(event.data)
+                    completed = True
+
+            # Handle pending plan review request
+            if pending_request is not None:
+                # Get human input for plan review decision
+                print("Plan review options:")
+                print("1. approve - Approve the plan as-is")
+                print("2. revise - Request revision of the plan")
+                print("3. exit - Exit the workflow")
+
+                while True:
+                    choice = input("Enter your choice (approve/revise/exit): ").strip().lower()  # noqa: ASYNC250
+                    if choice in ["approve", "1"]:
+                        reply = MagenticPlanReviewReply(decision=MagenticPlanReviewDecision.APPROVE)
+                        break
+                    if choice in ["revise", "2"]:
+                        reply = MagenticPlanReviewReply(decision=MagenticPlanReviewDecision.REVISE)
+                        break
+                    if choice in ["exit", "3"]:
+                        print("Exiting workflow...")
+                        return
+                    print("Invalid choice. Please enter 'approve', 'revise', or 'exit'.")
+
+                pending_responses = {pending_request.request_id: reply}
+                pending_request = None
+
+        # Show final result from captured workflow output
+        if workflow_output:
+            print(f"Workflow completed with result:\n\n{workflow_output}")
+
+    except Exception as e:
+        print(f"Workflow execution failed: {e}")
+        on_exception(e)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,78 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import cast
+
+from agent_framework import ChatMessage, Role, SequentialBuilder, WorkflowOutputEvent
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+
+"""
+Sample: Sequential workflow (agent-focused API) with shared conversation context
+
+Build a high-level sequential workflow using SequentialBuilder and two domain agents.
+The shared conversation (list[ChatMessage]) flows through each participant. Each agent
+appends its assistant message to the context. The workflow outputs the final conversation
+list when complete.
+
+Note on internal adapters:
+- Sequential orchestration includes small adapter nodes for input normalization
+  ("input-conversation"), agent-response conversion ("to-conversation:<participant>"),
+  and completion ("complete"). These may appear as ExecutorInvoke/Completed events in
+  the stream—similar to how concurrent orchestration includes a dispatcher/aggregator.
+  You can safely ignore them when focusing on agent progress.
+
+Prerequisites:
+- Azure OpenAI access configured for AzureOpenAIChatClient (use az login + env vars)
+"""
+
+
+async def main() -> None:
+    # 1) Create agents
+    chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
+
+    writer = chat_client.create_agent(
+        instructions=("You are a concise copywriter. Provide a single, punchy marketing sentence based on the prompt."),
+        name="writer",
+    )
+
+    reviewer = chat_client.create_agent(
+        instructions=("You are a thoughtful reviewer. Give brief feedback on the previous assistant message."),
+        name="reviewer",
+    )
+
+    # 2) Build sequential workflow: writer -> reviewer
+    workflow = SequentialBuilder().participants([writer, reviewer]).build()
+
+    # 3) Run and collect outputs
+    outputs: list[list[ChatMessage]] = []
+    async for event in workflow.run_stream("Write a tagline for a budget-friendly eBike."):
+        if isinstance(event, WorkflowOutputEvent):
+            outputs.append(cast(list[ChatMessage], event.data))
+
+    if outputs:
+        print("===== Final Conversation =====")
+        for i, msg in enumerate(outputs[-1], start=1):
+            name = msg.author_name or ("assistant" if msg.role == Role.ASSISTANT else "user")
+            print(f"{'-' * 60}\n{i:02d} [{name}]\n{msg.text}")
+
+    """
+    Sample Output:
+
+    ===== Final Conversation =====
+    ------------------------------------------------------------
+    01 [user]
+    Write a tagline for a budget-friendly eBike.
+    ------------------------------------------------------------
+    02 [writer]
+    Ride farther, spend less—your affordable eBike adventure starts here.
+    ------------------------------------------------------------
+    03 [reviewer]
+    This tagline clearly communicates affordability and the benefit of extended travel, making it
+    appealing to budget-conscious consumers. It has a friendly and motivating tone, though it could
+    be slightly shorter for more punch. Overall, a strong and effective suggestion!
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,97 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import Any
+
+from agent_framework import (
+    ChatMessage,
+    Executor,
+    Role,
+    SequentialBuilder,
+    WorkflowContext,
+    handler,
+)
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+from typing_extensions import Never
+
+"""
+Sample: Sequential workflow mixing agents and a custom summarizer executor
+
+This demonstrates how SequentialBuilder chains participants with a shared
+conversation context (list[ChatMessage]). An agent produces content; a custom
+executor appends a compact summary to the conversation. The workflow completes
+when idle, and the final output contains the complete conversation.
+
+Custom executor contract:
+- Provide at least one @handler accepting list[ChatMessage] and a WorkflowContext[list[ChatMessage]]
+- Emit the updated conversation via ctx.send_message([...])
+
+Note on internal adapters:
+- You may see adapter nodes in the event stream such as "input-conversation",
+  "to-conversation:<participant>", and "complete". These provide consistent typing,
+  conversion of agent responses into the shared conversation, and a single point
+  for completion—similar to concurrent's dispatcher/aggregator.
+
+Prerequisites:
+- Azure OpenAI access configured for AzureOpenAIChatClient (use az login + env vars)
+"""
+
+
+class Summarizer(Executor):
+    """Simple summarizer: consumes full conversation and appends an assistant summary."""
+
+    @handler
+    async def summarize(self, conversation: list[ChatMessage], ctx: WorkflowContext[Never, list[ChatMessage]]) -> None:
+        users = sum(1 for m in conversation if m.role == Role.USER)
+        assistants = sum(1 for m in conversation if m.role == Role.ASSISTANT)
+        summary = ChatMessage(role=Role.ASSISTANT, text=f"Summary -> users:{users} assistants:{assistants}")
+        final_conversation = list(conversation) + [summary]
+        await ctx.yield_output(final_conversation)
+
+
+async def main() -> None:
+    # 1) Create a content agent
+    chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
+    content = chat_client.create_agent(
+        instructions="Produce a concise paragraph answering the user's request.",
+        name="content",
+    )
+
+    # 2) Build sequential workflow: content -> summarizer
+    summarizer = Summarizer(id="summarizer")
+    workflow = SequentialBuilder().participants([content, summarizer]).build()
+
+    # 3) Run and print final conversation
+    events = await workflow.run("Explain the benefits of budget eBikes for commuters.")
+    outputs = events.get_outputs()
+
+    if outputs:
+        print("===== Final Conversation =====")
+        messages: list[ChatMessage] | Any = outputs[0]
+        for i, msg in enumerate(messages, start=1):
+            name = msg.author_name or ("assistant" if msg.role == Role.ASSISTANT else "user")
+            print(f"{'-' * 60}\n{i:02d} [{name}]\n{msg.text}")
+
+    """
+    Sample Output:
+
+    ------------------------------------------------------------
+    01 [user]
+    Explain the benefits of budget eBikes for commuters.
+    ------------------------------------------------------------
+    02 [content]
+    Budget eBikes offer commuters an affordable, eco-friendly alternative to cars and public transport.
+    Their electric assistance reduces physical strain and allows riders to cover longer distances quickly,
+    minimizing travel time and fatigue. Budget models are low-cost to maintain and operate, making them accessible
+    for a wider range of people. Additionally, eBikes help reduce traffic congestion and carbon emissions,
+    supporting greener urban environments. Overall, budget eBikes provide cost-effective, efficient, and
+    sustainable transportation for daily commuting needs.
+    ------------------------------------------------------------
+    03 [assistant]
+    Summary -> users:1 assistants:1
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())