test

python/samples/getting_started/workflows/README.md

@@ -0,0 +1,202 @@
+# Workflows Getting Started Samples
+
+## Installation
+
+Microsoft Agent Framework Workflows support ships with the core `agent-framework` or `agent-framework-core` package, so no extra installation step is required.
+
+To install with visualization support:
+
+```bash
+pip install agent-framework[viz] --pre
+```
+
+To export visualization images you also need to [install GraphViz](https://graphviz.org/download/).
+
+## Samples Overview
+
+## Foundational Concepts - Start Here
+
+Begin with the `_start-here` folder in order. These three samples introduce the core ideas of executors, edges, agents in workflows, and streaming.
+
+| Sample | File | Concepts |
+|--------|------|----------|
+| Executors and Edges | [_start-here/step1_executors_and_edges.py](./_start-here/step1_executors_and_edges.py) | Minimal workflow with basic executors and edges |
+| Agents in a Workflow | [_start-here/step2_agents_in_a_workflow.py](./_start-here/step2_agents_in_a_workflow.py) | Introduces adding Agents as nodes; calling agents inside a workflow |
+| Streaming (Basics) | [_start-here/step3_streaming.py](./_start-here/step3_streaming.py) | Extends workflows with event streaming |
+
+Once comfortable with these, explore the rest of the samples below.
+
+---
+
+## Samples Overview (by directory)
+
+### agents
+
+| Sample | File | Concepts |
+|---|---|---|
+| Azure Chat Agents (Streaming) | [agents/azure_chat_agents_streaming.py](./agents/azure_chat_agents_streaming.py) | Add Azure Chat agents as edges and handle streaming events |
+| Azure AI Chat Agents (Streaming) | [agents/azure_ai_agents_streaming.py](./agents/azure_ai_agents_streaming.py) | Add Azure AI agents as edges and handle streaming events |
+| Azure Chat Agents (Function Bridge) | [agents/azure_chat_agents_function_bridge.py](./agents/azure_chat_agents_function_bridge.py) | Chain two agents with a function executor that injects external context |
+| Azure Chat Agents (Tools + HITL) | [agents/azure_chat_agents_tool_calls_with_feedback.py](./agents/azure_chat_agents_tool_calls_with_feedback.py) | Tool-enabled writer/editor pipeline with human feedback gating |
+| Custom Agent Executors | [agents/custom_agent_executors.py](./agents/custom_agent_executors.py) | Create executors to handle agent run methods |
+| Sequential Workflow as Agent | [agents/sequential_workflow_as_agent.py](./agents/sequential_workflow_as_agent.py) | Build a sequential workflow orchestrating agents, then expose it as a reusable agent |
+| Concurrent Workflow as Agent | [agents/concurrent_workflow_as_agent.py](./agents/concurrent_workflow_as_agent.py) | Build a concurrent fan-out/fan-in workflow, then expose it as a reusable agent |
+| Magentic Workflow as Agent | [agents/magentic_workflow_as_agent.py](./agents/magentic_workflow_as_agent.py) | Configure Magentic orchestration with callbacks, then expose the workflow as an agent |
+| Workflow as Agent (Reflection Pattern) | [agents/workflow_as_agent_reflection_pattern.py](./agents/workflow_as_agent_reflection_pattern.py) | Wrap a workflow so it can behave like an agent (reflection pattern) |
+| Workflow as Agent + HITL | [agents/workflow_as_agent_human_in_the_loop.py](./agents/workflow_as_agent_human_in_the_loop.py) | Extend workflow-as-agent with human-in-the-loop capability |
+| Workflow as Agent with Thread | [agents/workflow_as_agent_with_thread.py](./agents/workflow_as_agent_with_thread.py) | Use AgentThread to maintain conversation history across workflow-as-agent invocations |
+| Workflow as Agent kwargs | [agents/workflow_as_agent_kwargs.py](./agents/workflow_as_agent_kwargs.py) | Pass custom context (data, user tokens) via kwargs through workflow.as_agent() to @ai_function tools |
+| Handoff Workflow as Agent | [agents/handoff_workflow_as_agent.py](./agents/handoff_workflow_as_agent.py) | Use a HandoffBuilder workflow as an agent with HITL via FunctionCallContent/FunctionResultContent |
+
+### checkpoint
+
+| Sample | File | Concepts |
+|---|---|---|
+| Checkpoint & Resume | [checkpoint/checkpoint_with_resume.py](./checkpoint/checkpoint_with_resume.py) | Create checkpoints, inspect them, and resume execution |
+| Checkpoint & HITL Resume | [checkpoint/checkpoint_with_human_in_the_loop.py](./checkpoint/checkpoint_with_human_in_the_loop.py) | Combine checkpointing with human approvals and resume pending HITL requests |
+| Checkpointed Sub-Workflow | [checkpoint/sub_workflow_checkpoint.py](./checkpoint/sub_workflow_checkpoint.py) | Save and resume a sub-workflow that pauses for human approval |
+| Handoff + Tool Approval Resume | [checkpoint/handoff_with_tool_approval_checkpoint_resume.py](./checkpoint/handoff_with_tool_approval_checkpoint_resume.py) | Handoff workflow that captures tool-call approvals in checkpoints and resumes with human decisions |
+| Workflow as Agent Checkpoint | [checkpoint/workflow_as_agent_checkpoint.py](./checkpoint/workflow_as_agent_checkpoint.py) | Enable checkpointing when using workflow.as_agent() with checkpoint_storage parameter |
+
+### composition
+
+| Sample | File | Concepts |
+|---|---|---|
+| Sub-Workflow (Basics) | [composition/sub_workflow_basics.py](./composition/sub_workflow_basics.py) | Wrap a workflow as an executor and orchestrate sub-workflows |
+| Sub-Workflow: Request Interception | [composition/sub_workflow_request_interception.py](./composition/sub_workflow_request_interception.py) | Intercept and forward sub-workflow requests using @handler for SubWorkflowRequestMessage |
+| Sub-Workflow: Parallel Requests | [composition/sub_workflow_parallel_requests.py](./composition/sub_workflow_parallel_requests.py) | Multiple specialized interceptors handling different request types from same sub-workflow |
+| Sub-Workflow: kwargs Propagation | [composition/sub_workflow_kwargs.py](./composition/sub_workflow_kwargs.py) | Pass custom context (user tokens, config) from parent workflow through to sub-workflow agents |
+
+### control-flow
+
+| Sample | File | Concepts |
+|---|---|---|
+| Sequential Executors | [control-flow/sequential_executors.py](./control-flow/sequential_executors.py) | Sequential workflow with explicit executor setup |
+| Sequential (Streaming) | [control-flow/sequential_streaming.py](./control-flow/sequential_streaming.py) | Stream events from a simple sequential run |
+| Edge Condition | [control-flow/edge_condition.py](./control-flow/edge_condition.py) | Conditional routing based on agent classification |
+| Switch-Case Edge Group | [control-flow/switch_case_edge_group.py](./control-flow/switch_case_edge_group.py) | Switch-case branching using classifier outputs |
+| Multi-Selection Edge Group | [control-flow/multi_selection_edge_group.py](./control-flow/multi_selection_edge_group.py) | Select one or many targets dynamically (subset fan-out) |
+| Simple Loop | [control-flow/simple_loop.py](./control-flow/simple_loop.py) | Feedback loop where an agent judges ABOVE/BELOW/MATCHED |
+| Workflow Cancellation | [control-flow/workflow_cancellation.py](./control-flow/workflow_cancellation.py) | Cancel a running workflow using asyncio tasks |
+
+### human-in-the-loop
+
+| Sample | File | Concepts |
+|---|---|---|
+| Human-In-The-Loop (Guessing Game) | [human-in-the-loop/guessing_game_with_human_input.py](./human-in-the-loop/guessing_game_with_human_input.py) | Interactive request/response prompts with a human via `ctx.request_info()` |
+| Agents with Approval Requests in Workflows | [human-in-the-loop/agents_with_approval_requests.py](./human-in-the-loop/agents_with_approval_requests.py) | Agents that create approval requests during workflow execution and wait for human approval to proceed |
+| SequentialBuilder Request Info | [human-in-the-loop/sequential_request_info.py](./human-in-the-loop/sequential_request_info.py) | Request info for agent responses mid-workflow using `.with_request_info()` on SequentialBuilder |
+| ConcurrentBuilder Request Info | [human-in-the-loop/concurrent_request_info.py](./human-in-the-loop/concurrent_request_info.py) | Review concurrent agent outputs before aggregation using `.with_request_info()` on ConcurrentBuilder |
+| GroupChatBuilder Request Info | [human-in-the-loop/group_chat_request_info.py](./human-in-the-loop/group_chat_request_info.py) | Steer group discussions with periodic guidance using `.with_request_info()` on GroupChatBuilder |
+
+### tool-approval
+
+Tool approval samples demonstrate using `@ai_function(approval_mode="always_require")` to gate sensitive tool executions with human approval. These work with the high-level builder APIs.
+
+| Sample | File | Concepts |
+|---|---|---|
+| SequentialBuilder Tool Approval | [tool-approval/sequential_builder_tool_approval.py](./tool-approval/sequential_builder_tool_approval.py) | Sequential workflow with tool approval gates for sensitive operations |
+| ConcurrentBuilder Tool Approval | [tool-approval/concurrent_builder_tool_approval.py](./tool-approval/concurrent_builder_tool_approval.py) | Concurrent workflow with tool approvals across parallel agents |
+| GroupChatBuilder Tool Approval | [tool-approval/group_chat_builder_tool_approval.py](./tool-approval/group_chat_builder_tool_approval.py) | Group chat workflow with tool approval for multi-agent collaboration |
+
+### observability
+
+| Sample | File | Concepts |
+|---|---|---|
+| Executor I/O Observation | [observability/executor_io_observation.py](./observability/executor_io_observation.py) | Observe executor input/output data via ExecutorInvokedEvent and ExecutorCompletedEvent without modifying executor code |
+
+For additional observability samples in Agent Framework, see the [observability getting started samples](../observability/README.md). The [sample](../observability/workflow_observability.py) demonstrates integrating observability into workflows.
+
+### orchestration
+
+| Sample | File | Concepts |
+|---|---|---|
+| Concurrent Orchestration (Default Aggregator) | [orchestration/concurrent_agents.py](./orchestration/concurrent_agents.py) | Fan-out to multiple agents; fan-in with default aggregator returning combined ChatMessages |
+| Concurrent Orchestration (Custom Aggregator) | [orchestration/concurrent_custom_aggregator.py](./orchestration/concurrent_custom_aggregator.py) | Override aggregator via callback; summarize results with an LLM |
+| Concurrent Orchestration (Custom Agent Executors) | [orchestration/concurrent_custom_agent_executors.py](./orchestration/concurrent_custom_agent_executors.py) | Child executors own ChatAgents; concurrent fan-out/fan-in via ConcurrentBuilder |
+| Concurrent Orchestration (Participant Factory) | [orchestration/concurrent_participant_factory.py](./orchestration/concurrent_participant_factory.py) | Use participant factories for state isolation between workflow instances |
+| Group Chat with Agent Manager | [orchestration/group_chat_agent_manager.py](./orchestration/group_chat_agent_manager.py) | Agent-based manager using `with_agent_orchestrator()` to select next speaker |
+| Group Chat Philosophical Debate | [orchestration/group_chat_philosophical_debate.py](./orchestration/group_chat_philosophical_debate.py) | Agent manager moderates long-form, multi-round debate across diverse participants |
+| Group Chat with Simple Function Selector | [orchestration/group_chat_simple_selector.py](./orchestration/group_chat_simple_selector.py) | Group chat with a simple function selector for next speaker |
+| Handoff (Simple) | [orchestration/handoff_simple.py](./orchestration/handoff_simple.py) | Single-tier routing: triage agent routes to specialists, control returns to user after each specialist response |
+| Handoff (Autonomous) | [orchestration/handoff_autonomous.py](./orchestration/handoff_autonomous.py) | Autonomous mode: specialists iterate independently until invoking a handoff tool using `.with_autonomous_mode()` |
+| Handoff (Participant Factory) | [orchestration/handoff_participant_factory.py](./orchestration/handoff_participant_factory.py) | Use participant factories for state isolation between workflow instances |
+| Magentic Workflow (Multi-Agent) | [orchestration/magentic.py](./orchestration/magentic.py) | Orchestrate multiple agents with Magentic manager and streaming |
+| Magentic + Human Plan Review | [orchestration/magentic_human_plan_review.py](./orchestration/magentic_human_plan_review.py) | Human reviews/updates the plan before execution |
+| Magentic + Checkpoint Resume | [orchestration/magentic_checkpoint.py](./orchestration/magentic_checkpoint.py) | Resume Magentic orchestration from saved checkpoints |
+| Sequential Orchestration (Agents) | [orchestration/sequential_agents.py](./orchestration/sequential_agents.py) | Chain agents sequentially with shared conversation context |
+| Sequential Orchestration (Custom Executor) | [orchestration/sequential_custom_executors.py](./orchestration/sequential_custom_executors.py) | Mix agents with a summarizer that appends a compact summary |
+| Sequential Orchestration (Participant Factories) | [orchestration/sequential_participant_factory.py](./orchestration/sequential_participant_factory.py) | Use participant factories for state isolation between workflow instances |
+
+**Magentic checkpointing tip**: Treat `MagenticBuilder.participants` keys as stable identifiers. When resuming from a checkpoint, the rebuilt workflow must reuse the same participant names; otherwise the checkpoint cannot be applied and the run will fail fast.
+
+**Handoff workflow tip**: Handoff workflows maintain the full conversation history including any
+`ChatMessage.additional_properties` emitted by your agents. This ensures routing metadata remains
+intact across all agent transitions. For specialist-to-specialist handoffs, use `.add_handoff(source, targets)`
+to configure which agents can route to which others with a fluent, type-safe API.
+
+### parallelism
+
+| Sample | File | Concepts |
+|---|---|---|
+| Concurrent (Fan-out/Fan-in) | [parallelism/fan_out_fan_in_edges.py](./parallelism/fan_out_fan_in_edges.py) | Dispatch to multiple executors and aggregate results |
+| Aggregate Results of Different Types | [parallelism/aggregate_results_of_different_types.py](./parallelism/aggregate_results_of_different_types.py) | Handle results of different types from multiple concurrent executors |
+| Map-Reduce with Visualization | [parallelism/map_reduce_and_visualization.py](./parallelism/map_reduce_and_visualization.py) | Fan-out/fan-in pattern with diagram export |
+
+### state-management
+
+| Sample | File | Concepts |
+|---|---|---|
+| Shared States | [state-management/shared_states_with_agents.py](./state-management/shared_states_with_agents.py) | Store in shared state once and later reuse across agents |
+| Workflow Kwargs (Custom Context) | [state-management/workflow_kwargs.py](./state-management/workflow_kwargs.py) | Pass custom context (data, user tokens) via kwargs to `@ai_function` tools |
+
+
+### visualization
+
+| Sample | File | Concepts |
+|---|---|---|
+| Concurrent with Visualization | [visualization/concurrent_with_visualization.py](./visualization/concurrent_with_visualization.py) | Fan-out/fan-in workflow with diagram export |
+
+### declarative
+
+YAML-based declarative workflows allow you to define multi-agent orchestration patterns without writing Python code. See the [declarative workflows README](./declarative/README.md) for more details on YAML workflow syntax and available actions.
+
+| Sample | File | Concepts |
+|---|---|---|
+| Conditional Workflow | [declarative/conditional_workflow/](./declarative/conditional_workflow/) | Nested conditional branching based on user input |
+| Customer Support | [declarative/customer_support/](./declarative/customer_support/) | Multi-agent customer support with routing |
+| Deep Research | [declarative/deep_research/](./declarative/deep_research/) | Research workflow with planning, searching, and synthesis |
+| Function Tools | [declarative/function_tools/](./declarative/function_tools/) | Invoking Python functions from declarative workflows |
+| Human-in-Loop | [declarative/human_in_loop/](./declarative/human_in_loop/) | Interactive workflows that request user input |
+| Marketing | [declarative/marketing/](./declarative/marketing/) | Marketing content generation workflow |
+| Simple Workflow | [declarative/simple_workflow/](./declarative/simple_workflow/) | Basic workflow with variable setting, conditionals, and loops |
+| Student Teacher | [declarative/student_teacher/](./declarative/student_teacher/) | Student-teacher interaction pattern |
+
+### resources
+
+- Sample text inputs used by certain workflows:
+  - [resources/long_text.txt](./resources/long_text.txt)
+  - [resources/email.txt](./resources/email.txt)
+  - [resources/spam.txt](./resources/spam.txt)
+  - [resources/ambiguous_email.txt](./resources/ambiguous_email.txt)
+
+Notes
+
+- Agent-based samples use provider SDKs (Azure/OpenAI, etc.). Ensure credentials are configured, or adapt agents accordingly.
+
+Sequential orchestration uses a few small adapter nodes for plumbing:
+
+- "input-conversation" normalizes input to `list[ChatMessage]`
+- "to-conversation:<participant>" converts agent responses into the shared conversation
+- "complete" publishes the final `WorkflowOutputEvent`
+These may appear in event streams (ExecutorInvoke/Completed). They’re analogous to
+concurrent’s dispatcher and aggregator and can be ignored if you only care about agent activity.
+
+### Environment Variables
+
+- **AzureOpenAIChatClient**: Set Azure OpenAI environment variables as documented [here](https://github.com/microsoft/agent-framework/blob/main/python/samples/getting_started/chat_client/README.md#environment-variables).
+  These variables are required for samples that construct `AzureOpenAIChatClient`
+
+- **OpenAI** (used in orchestration samples):
+  - [OpenAIChatClient env vars](https://github.com/microsoft/agent-framework/blob/main/python/samples/getting_started/agents/openai_chat_client/README.md)
+  - [OpenAIResponsesClient env vars](https://github.com/microsoft/agent-framework/blob/main/python/samples/getting_started/agents/openai_responses_client/README.md)

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

@@ -0,0 +1,132 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import (
+    Executor,
+    WorkflowBuilder,
+    WorkflowContext,
+    executor,
+    handler,
+)
+from typing_extensions import Never
+
+"""
+Step 1: Foundational patterns: Executors and edges
+
+What this example shows
+- Two ways to define a unit of work (an Executor node):
+    1) Custom class that subclasses Executor with an async method marked by @handler.
+         Possible handler signatures:
+            - (text: str, ctx: WorkflowContext) -> None,
+            - (text: str, ctx: WorkflowContext[str]) -> None, or
+            - (text: str, ctx: WorkflowContext[Never, str]) -> None.
+         The first parameter is the typed input to this node, the input type is str here.
+         The second parameter is a WorkflowContext[T_Out, T_W_Out].
+         WorkflowContext[T_Out] is used for nodes that send messages to downstream nodes with ctx.send_message(T_Out).
+         WorkflowContext[T_Out, T_W_Out] is used for nodes that also yield workflow
+            output with ctx.yield_output(T_W_Out).
+         WorkflowContext without type parameters is equivalent to WorkflowContext[Never, Never], meaning this node
+            neither sends messages to downstream nodes nor yields workflow output.
+
+    2) Standalone async function decorated with @executor using the same signature.
+         Simple steps can use this form; a terminal step can yield output
+         using ctx.yield_output() to provide workflow results.
+
+- Fluent WorkflowBuilder API:
+    add_edge(A, B) to connect nodes, set_start_executor(A), then build() -> Workflow.
+
+- Running and results:
+    workflow.run(initial_input) executes the graph. Terminal nodes yield
+    outputs using ctx.yield_output(). The workflow runs until idle.
+
+Prerequisites
+- No external services required.
+"""
+
+
+# Example 1: A custom Executor subclass
+# ------------------------------------
+#
+# Subclassing Executor lets you define a named node with lifecycle hooks if needed.
+# The work itself is implemented in an async method decorated with @handler.
+#
+# Handler signature contract:
+# - First parameter is the typed input to this node (here: text: str)
+# - Second parameter is a WorkflowContext[T_Out], where T_Out is the type of data this
+#   node will emit via ctx.send_message (here: T_Out is str)
+#
+# Within a handler you typically:
+# - Compute a result
+# - Forward that result to downstream node(s) using ctx.send_message(result)
+class UpperCase(Executor):
+    def __init__(self, id: str):
+        super().__init__(id=id)
+
+    @handler
+    async def to_upper_case(self, text: str, ctx: WorkflowContext[str]) -> None:
+        """Convert the input to uppercase and forward it to the next node.
+
+        Note: The WorkflowContext is parameterized with the type this handler will
+        emit. Here WorkflowContext[str] means downstream nodes should expect str.
+        """
+        result = text.upper()
+
+        # Send the result to the next executor in the workflow.
+        await ctx.send_message(result)
+
+
+# Example 2: A standalone function-based executor
+# -----------------------------------------------
+#
+# For simple steps you can skip subclassing and define an async function with the
+# same signature pattern (typed input + WorkflowContext[T_Out, T_W_Out]) and decorate it with
+# @executor. This creates a fully functional node that can be wired into a flow.
+
+
+@executor(id="reverse_text_executor")
+async def reverse_text(text: str, ctx: WorkflowContext[Never, str]) -> None:
+    """Reverse the input string and yield the workflow output.
+
+    This node yields the final output using ctx.yield_output(result).
+    The workflow will complete when it becomes idle (no more work to do).
+
+    The WorkflowContext is parameterized with two types:
+    - T_Out = Never: this node does not send messages to downstream nodes.
+    - T_W_Out = str: this node yields workflow output of type str.
+    """
+    result = text[::-1]
+
+    # Yield the output - the workflow will complete when idle
+    await ctx.yield_output(result)
+
+
+async def main():
+    """Build and run a simple 2-step workflow using the fluent builder API."""
+
+    upper_case = UpperCase(id="upper_case_executor")
+
+    # Build the workflow using a fluent pattern:
+    # 1) add_edge(from_node, to_node) defines a directed edge upper_case -> reverse_text
+    # 2) set_start_executor(node) declares the entry point
+    # 3) build() finalizes and returns an immutable Workflow object
+    workflow = WorkflowBuilder().add_edge(upper_case, reverse_text).set_start_executor(upper_case).build()
+
+    # Run the workflow by sending the initial message to the start node.
+    # The run(...) call returns an event collection; its get_outputs() method
+    # retrieves the outputs yielded by any terminal nodes.
+    events = await workflow.run("hello world")
+    print(events.get_outputs())
+    # Summarize the final run state (e.g., IDLE)
+    print("Final state:", events.get_final_state())
+
+    """
+    Sample Output:
+
+    ['DLROW OLLEH']
+    Final state: WorkflowRunState.IDLE
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,86 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import AgentRunEvent, 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.
+
+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.
+
+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.
+"""
+
+
+async def main():
+    """Build and run a simple two node agent workflow: Writer then Reviewer."""
+    # Create the Azure chat client. AzureCliCredential uses your current az login.
+    chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
+    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_agent).add_edge(writer_agent, reviewer_agent).build()
+
+    # 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()}")
+    # Summarize the final run state (e.g., COMPLETED)
+    print("Final state:", events.get_final_state())
+
+    """
+    Sample Output:
+
+    writer: "Charge Up Your Adventure—Affordable Fun, Electrified!"
+    reviewer: 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.
+    ============================================================
+    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.']
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,166 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import (
+    ChatAgent,
+    ChatMessage,
+    Executor,
+    ExecutorFailedEvent,
+    WorkflowBuilder,
+    WorkflowContext,
+    WorkflowFailedEvent,
+    WorkflowRunState,
+    WorkflowStatusEvent,
+    handler,
+)
+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.
+
+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.
+
+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 runs.
+"""
+
+
+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)
+
+    # 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()
+
+    # 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(role="user", text="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)")
+            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}")
+
+    """
+    Sample Output:
+
+    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
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,104 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import (
+    AgentResponse,
+    ChatAgent,
+    Executor,
+    WorkflowBuilder,
+    WorkflowContext,
+    WorkflowOutputEvent,
+    executor,
+    handler,
+)
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+
+"""
+Step 4: Using Factories to Define Executors and Agents
+
+What this example shows
+- Defining custom executors using both class-based and function-based approaches.
+- Registering executor and agent factories with WorkflowBuilder for lazy instantiation.
+- Building a simple workflow that transforms input text through multiple steps.
+
+Benefits of using factories
+- Decouples executor and agent creation from workflow definition.
+- Isolated instances are created for workflow builder build, allowing for cleaner state management
+  and handling parallel workflow runs.
+
+It is recommended to use factories when defining executors and agents for production workflows.
+
+Prerequisites
+- No external services required.
+"""
+
+
+class UpperCase(Executor):
+    def __init__(self, id: str):
+        super().__init__(id=id)
+
+    @handler
+    async def to_upper_case(self, text: str, ctx: WorkflowContext[str]) -> None:
+        """Convert the input to uppercase and forward it to the next node."""
+        result = text.upper()
+
+        # Send the result to the next executor in the workflow.
+        await ctx.send_message(result)
+
+
+@executor(id="reverse_text_executor")
+async def reverse_text(text: str, ctx: WorkflowContext[str]) -> None:
+    """Reverse the input string and send it downstream."""
+    result = text[::-1]
+
+    # Send the result to the next executor in the workflow.
+    await ctx.send_message(result)
+
+
+def create_agent() -> ChatAgent:
+    """Factory function to create a Writer agent."""
+    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+        instructions=("You decode messages. Try to reconstruct the original message."),
+        name="decoder",
+    )
+
+
+async def main():
+    """Build and run a simple 2-step workflow using the fluent builder API."""
+    # Build the workflow using a fluent pattern:
+    # 1) register_executor(factory, name) registers an executor factory
+    # 2) register_agent(factory, name) registers an agent factory
+    # 3) add_chain([node_names]) adds a sequence of nodes to the workflow
+    # 4) set_start_executor(node) declares the entry point
+    # 5) build() finalizes and returns an immutable Workflow object
+    workflow = (
+        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)
+        .add_chain(["UpperCase", "ReverseText", "DecoderAgent"])
+        .set_start_executor("UpperCase")
+        .build()
+    )
+
+    output: AgentResponse | None = None
+    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.")
+
+    """
+    Sample Output:
+
+    HELLO WORLD
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,80 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import AgentRunUpdateEvent, ChatAgent, WorkflowBuilder, WorkflowOutputEvent
+from agent_framework.azure import AzureAIAgentClient
+from azure.identity.aio import AzureCliCredential
+
+"""
+Sample: 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.
+
+Prerequisites:
+- Azure AI Agent Service configured, along with the required environment variables.
+- Authentication via azure-identity. Use AzureCliCredential and run az login before executing the sample.
+- Basic familiarity with WorkflowBuilder, edges, events, and streaming runs.
+"""
+
+
+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()
+        )
+
+        last_executor_id: 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)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,144 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import Final
+
+from agent_framework import (
+    AgentExecutorRequest,
+    AgentExecutorResponse,
+    AgentResponse,
+    AgentRunUpdateEvent,
+    ChatMessage,
+    Role,
+    WorkflowBuilder,
+    WorkflowContext,
+    WorkflowOutputEvent,
+    executor,
+)
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+
+"""
+Sample: Two agents connected by a function executor bridge
+
+Pipeline layout:
+research_agent -> enrich_with_references (@executor) -> final_editor_agent
+
+The first agent drafts a short answer. A lightweight @executor function simulates
+an external data fetch and injects a follow-up user message containing extra context.
+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.
+- Authentication via azure-identity. Run `az login` before executing.
+"""
+
+# Simulated external content keyed by a simple topic hint.
+EXTERNAL_REFERENCES: Final[dict[str, str]] = {
+    "workspace": (
+        "From Workspace Weekly: Adjustable monitor arms and sit-stand desks can reduce "
+        "neck strain by up to 30%. Consider adding a reminder to move every 45 minutes."
+    ),
+    "travel": (
+        "Checklist excerpt: Always confirm baggage limits for budget airlines. "
+        "Keep a photocopy of your passport stored separately from the original."
+    ),
+    "wellness": (
+        "Recent survey: Employees who take two 5-minute breaks per hour report 18% higher focus "
+        "scores. Encourage scheduling micro-breaks alongside hydration reminders."
+    ),
+}
+
+
+def _lookup_external_note(prompt: str) -> str | None:
+    """Return the first matching external note based on a keyword search."""
+    lowered = prompt.lower()
+    for keyword, note in EXTERNAL_REFERENCES.items():
+        if keyword in lowered:
+            return note
+    return None
+
+
+@executor(id="enrich_with_references")
+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."""
+    conversation = list(draft.full_conversation or draft.agent_response.messages)
+    original_prompt = next((message.text for message in conversation if message.role == Role.USER), "")
+    external_note = _lookup_external_note(original_prompt) or (
+        "No additional references were found. Please refine the previous assistant response for clarity."
+    )
+
+    follow_up = (
+        "External knowledge snippet:\n"
+        f"{external_note}\n\n"
+        "Please update the prior assistant answer so it weaves this note into the guidance."
+    )
+    conversation.append(ChatMessage(role=Role.USER, text=follow_up))
+
+    await ctx.send_message(AgentExecutorRequest(messages=conversation))
+
+
+def create_research_agent():
+    return 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(
+        name="final_editor_agent",
+        instructions=(
+            "Use all conversation context (including external notes) to produce the final answer. "
+            "Merge the draft and extra note into a concise recommendation under 150 words."
+        ),
+    )
+
+
+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")
+        .build()
+    )
+
+    events = workflow.run_stream(
+        "Create quick workspace wellness tips for a remote analyst working across two monitors."
+    )
+
+    last_executor: 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)")
+            else:
+                print(response if response is not None else "No response generated.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,95 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import AgentRunUpdateEvent, WorkflowBuilder, WorkflowOutputEvent
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+
+"""
+Sample: 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.
+
+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, edges, events, and streaming runs.
+"""
+
+
+def create_writer_agent():
+    return 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(
+        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",
+    )
+
+
+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()
+    )
+
+    # Stream events from the workflow. We aggregate partial token updates per executor for readable output.
+    last_executor_id: 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."
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,321 @@
+# 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,
+    Role,
+    WorkflowBuilder,
+    WorkflowContext,
+    WorkflowOutputEvent,
+    handler,
+    response_handler,
+)
+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.
+"""
+
+
+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}'.")
+
+
+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(Role.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(Role.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

@@ -0,0 +1,126 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import ConcurrentBuilder
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+
+"""
+Sample: Build a concurrent workflow orchestration and wrap it as an agent.
+
+This script wires up a fan-out/fan-in workflow using `ConcurrentBuilder`, and then
+invokes the entire orchestration through the `workflow.as_agent(...)` interface so
+downstream coordinators can reuse the orchestration as a single agent.
+
+Demonstrates:
+- Fan-out to multiple agents, fan-in aggregation of final ChatMessages.
+- Reusing the orchestrated workflow as an agent entry point with `workflow.as_agent(...)`.
+- 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.as_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.as_agent(
+        instructions=(
+            "You're a creative marketing strategist. Craft compelling value propositions and target messaging"
+            " aligned to the prompt."
+        ),
+        name="marketer",
+    )
+
+    legal = chat_client.as_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
+    workflow = ConcurrentBuilder().participants([researcher, marketer, legal]).build()
+
+    # 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
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,132 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import (
+    ChatAgent,
+    ChatMessage,
+    Executor,
+    WorkflowBuilder,
+    WorkflowContext,
+    handler,
+)
+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.
+
+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.
+
+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.
+"""
+
+
+class Writer(Executor):
+    """Custom executor that owns a domain specific agent responsible for generating content.
+
+    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, id: str = "writer"):
+        # Create a domain specific agent using your configured AzureOpenAIChatClient.
+        self.agent = AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+            instructions=(
+                "You are an excellent content writer. You create new content and edit contents based on the feedback."
+            ),
+        )
+        # Associate the agent with this 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], str]) -> None:
+        """Generate content using the agent 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.
+
+    This class demonstrates:
+    - Consuming a typed payload produced upstream.
+    - Yielding the final text outcome to complete the workflow.
+    """
+
+    agent: ChatAgent
+
+    def __init__(self, id: str = "reviewer"):
+        # Create a domain specific agent that evaluates and refines content.
+        self.agent = AzureOpenAIChatClient(credential=AzureCliCredential()).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[list[ChatMessage], str]) -> None:
+        """Review the full conversation transcript and complete with a final string.
+
+        This node consumes all messages so far. It uses its agent to produce the final text,
+        then signals completion by yielding the output.
+        """
+        response = await self.agent.run(messages)
+        await ctx.yield_output(response.text)
+
+
+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.
+    workflow = (
+        WorkflowBuilder()
+        .register_executor(Writer, name="writer")
+        .register_executor(Reviewer, name="reviewer")
+        .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.
+    events = await workflow.run(
+        ChatMessage(role="user", text="Create a slogan for a new electric SUV that is affordable and fun to drive.")
+    )
+    # The terminal node yields output; print its contents.
+    outputs = events.get_outputs()
+    if outputs:
+        print(outputs[-1])
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,68 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import ChatAgent, GroupChatBuilder
+from agent_framework.openai import OpenAIChatClient, OpenAIResponsesClient
+
+"""
+Sample: Group Chat Orchestration
+
+What it does:
+- Demonstrates the generic GroupChatBuilder with a agent orchestrator directing two agents.
+- The orchestrator coordinates a researcher (chat completions) and a writer (responses API) to solve a task.
+
+Prerequisites:
+- OpenAI environment variables configured for `OpenAIChatClient` and `OpenAIResponsesClient`.
+"""
+
+
+async def main() -> None:
+    researcher = ChatAgent(
+        name="Researcher",
+        description="Collects relevant background information.",
+        instructions="Gather concise facts that help a teammate answer the question.",
+        chat_client=OpenAIChatClient(model_id="gpt-4o-mini"),
+    )
+
+    writer = ChatAgent(
+        name="Writer",
+        description="Synthesizes a polished answer using the gathered notes.",
+        instructions="Compose clear and structured answers using any notes provided.",
+        chat_client=OpenAIResponsesClient(),
+    )
+
+    workflow = (
+        GroupChatBuilder()
+        .with_agent_orchestrator(
+            OpenAIChatClient().as_agent(
+                name="Orchestrator",
+                instructions="You coordinate a team conversation to solve the user's task.",
+            )
+        )
+        .participants([researcher, writer])
+        .build()
+    )
+
+    task = "Outline the core considerations for planning a community hackathon, and finish with a concise action plan."
+
+    print("\nStarting Group Chat Workflow...\n")
+    print(f"Input: {task}\n")
+
+    try:
+        workflow_agent = workflow.as_agent(name="GroupChatWorkflowAgent")
+        agent_result = await workflow_agent.run(task)
+
+        if agent_result.messages:
+            print("\n===== as_agent() Transcript =====")
+            for i, msg in enumerate(agent_result.messages, start=1):
+                role_value = getattr(msg.role, "value", msg.role)
+                speaker = msg.author_name or role_value
+                print(f"{'-' * 50}\n{i:02d} [{speaker}]\n{msg.text}")
+
+    except Exception as e:
+        print(f"Workflow execution failed: {e}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,224 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import Annotated
+
+from agent_framework import (
+    AgentResponse,
+    ChatAgent,
+    ChatMessage,
+    FunctionCallContent,
+    FunctionResultContent,
+    HandoffAgentUserRequest,
+    HandoffBuilder,
+    Role,
+    WorkflowAgent,
+    ai_function,
+)
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+
+"""Sample: Handoff Workflow as Agent with Human-in-the-Loop.
+
+This sample demonstrates how to use a handoff workflow as an agent, enabling
+human-in-the-loop interactions through the agent interface.
+
+A handoff workflow defines a pattern that assembles agents in a mesh topology, allowing
+them to transfer control to each other based on the conversation context.
+
+Prerequisites:
+    - `az login` (Azure CLI authentication)
+    - Environment variables configured for AzureOpenAIChatClient (AZURE_OPENAI_ENDPOINT, etc.)
+
+Key Concepts:
+    - Auto-registered handoff tools: HandoffBuilder automatically creates handoff tools
+      for each participant, allowing the coordinator to transfer control to specialists
+    - Termination condition: Controls when the workflow stops requesting user input
+    - Request/response cycle: Workflow requests input, user responds, cycle continues
+"""
+
+
+@ai_function
+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."""
+    return f"Refund processed successfully for order {order_number}."
+
+
+@ai_function
+def check_order_status(order_number: Annotated[str, "Order number to check status for"]) -> str:
+    """Simulated function to check the status of a given order number."""
+    return f"Order {order_number} is currently being processed and will ship in 2 business days."
+
+
+@ai_function
+def process_return(order_number: Annotated[str, "Order number to process return for"]) -> str:
+    """Simulated function to process a return for a given order number."""
+    return f"Return initiated successfully for order {order_number}. You will receive return instructions via email."
+
+
+def create_agents(chat_client: AzureOpenAIChatClient) -> tuple[ChatAgent, ChatAgent, ChatAgent, ChatAgent]:
+    """Create and configure the triage and specialist agents.
+
+    Args:
+        chat_client: The AzureOpenAIChatClient to use for creating agents.
+
+    Returns:
+        Tuple of (triage_agent, refund_agent, order_agent, return_agent)
+    """
+    # Triage agent: Acts as the frontline dispatcher
+    triage_agent = chat_client.as_agent(
+        instructions=(
+            "You are frontline support triage. Route customer issues to the appropriate specialist agents "
+            "based on the problem described."
+        ),
+        name="triage_agent",
+    )
+
+    # Refund specialist: Handles refund requests
+    refund_agent = chat_client.as_agent(
+        instructions="You process refund requests.",
+        name="refund_agent",
+        # In a real application, an agent can have multiple tools; here we keep it simple
+        tools=[process_refund],
+    )
+
+    # Order/shipping specialist: Resolves delivery issues
+    order_agent = chat_client.as_agent(
+        instructions="You handle order and shipping inquiries.",
+        name="order_agent",
+        # In a real application, an agent can have multiple tools; here we keep it simple
+        tools=[check_order_status],
+    )
+
+    # Return specialist: Handles return requests
+    return_agent = chat_client.as_agent(
+        instructions="You manage product return requests.",
+        name="return_agent",
+        # In a real application, an agent can have multiple tools; here we keep it simple
+        tools=[process_return],
+    )
+
+    return triage_agent, refund_agent, order_agent, return_agent
+
+
+def handle_response_and_requests(response: AgentResponse) -> dict[str, HandoffAgentUserRequest]:
+    """Process agent response messages and extract any user requests.
+
+    This function inspects the agent response and:
+    - Displays agent messages to the console
+    - Collects HandoffAgentUserRequest instances for response handling
+
+    Args:
+        response: The AgentResponse from the agent run call.
+
+    Returns:
+        A dictionary mapping request IDs to HandoffAgentUserRequest instances.
+    """
+    pending_requests: dict[str, HandoffAgentUserRequest] = {}
+    for message in response.messages:
+        if message.text:
+            print(f"- {message.author_name or message.role.value}: {message.text}")
+        for content in message.contents:
+            if isinstance(content, FunctionCallContent):
+                if isinstance(content.arguments, dict):
+                    request = WorkflowAgent.RequestInfoFunctionArgs.from_dict(content.arguments)
+                elif isinstance(content.arguments, str):
+                    request = WorkflowAgent.RequestInfoFunctionArgs.from_json(content.arguments)
+                else:
+                    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
+
+
+async def main() -> None:
+    """Main entry point for the handoff workflow demo.
+
+    This function demonstrates:
+    1. Creating triage and specialist agents
+    2. Building a handoff workflow with custom termination condition
+    3. Running the workflow with scripted user responses
+    4. Processing events and handling user input requests
+
+    The workflow uses scripted responses instead of interactive input to make
+    the demo reproducible and testable. In a production application, you would
+    replace the scripted_responses with actual user input collection.
+    """
+    # Initialize the Azure OpenAI chat client
+    chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
+
+    # Create all agents: triage + specialists
+    triage, refund, order, support = create_agents(chat_client)
+
+    # Build the handoff workflow
+    # - participants: All agents that can participate in the workflow
+    # - with_start_agent: The triage agent is designated as the start agent, which means
+    #   it receives all user input first and orchestrates handoffs to specialists
+    # - with_termination_condition: Custom logic to stop the request/response loop.
+    #   Without this, the default behavior continues requesting user input until max_turns
+    #   is reached. Here we use a custom condition that checks if the conversation has ended
+    #   naturally (when one of the agents says something like "you're welcome").
+    agent = (
+        HandoffBuilder(
+            name="customer_support_handoff",
+            participants=[triage, refund, order, support],
+        )
+        .with_start_agent(triage)
+        .with_termination_condition(
+            # Custom termination: Check if one of the agents has provided a closing message.
+            # This looks for the last message containing "welcome", which indicates the
+            # conversation has concluded naturally.
+            lambda conversation: len(conversation) > 0 and "welcome" in conversation[-1].text.lower()
+        )
+        .build()
+        .as_agent()  # Convert workflow to agent interface
+    )
+
+    # Scripted user responses for reproducible demo
+    # In a console application, replace this with:
+    #   user_input = input("Your response: ")
+    # or integrate with a UI/chat interface
+    scripted_responses = [
+        "My order 1234 arrived damaged and the packaging was destroyed. I'd like to return it.",
+        "Please also process a refund for order 1234.",
+        "Thanks for resolving this.",
+    ]
+
+    # Start the workflow with the initial user message
+    print("[Starting workflow with initial user message...]\n")
+    initial_message = "Hello, I need assistance with my recent purchase."
+    print(f"- User: {initial_message}")
+    response = await agent.run(initial_message)
+    pending_requests = handle_response_and_requests(response)
+
+    # Process the request/response cycle
+    # The workflow will continue requesting input until:
+    # 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.value}: {message.text}")
+
+        if not scripted_responses:
+            # No more scripted responses; terminate the workflow
+            responses = {req_id: HandoffAgentUserRequest.terminate() for req_id in pending_requests}
+        else:
+            # Get the next scripted response
+            user_response = scripted_responses.pop(0)
+            print(f"\n- User: {user_response}")
+
+            # Send response(s) to all pending requests
+            # In this demo, there's typically one request per cycle, but the API supports multiple
+            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()
+        ]
+        response = await agent.run(ChatMessage(role=Role.TOOL, contents=function_results))
+        pending_requests = handle_response_and_requests(response)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,92 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import (
+    ChatAgent,
+    HostedCodeInterpreterTool,
+    MagenticBuilder,
+)
+from agent_framework.openai import OpenAIChatClient, OpenAIResponsesClient
+
+"""
+Sample: Build a Magentic orchestration and wrap it as an agent.
+
+The script configures a Magentic workflow with streaming callbacks, then invokes the
+orchestration through `workflow.as_agent(...)` so the entire Magentic loop can be reused
+like any other agent while still emitting callback telemetry.
+
+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(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(),
+    )
+
+    # Create a manager agent for orchestration
+    manager_agent = ChatAgent(
+        name="MagenticManager",
+        description="Orchestrator that coordinates the research and coding workflow",
+        instructions="You coordinate a team to complete complex tasks efficiently.",
+        chat_client=OpenAIChatClient(),
+    )
+
+    print("\nBuilding Magentic Workflow...")
+
+    workflow = (
+        MagenticBuilder()
+        .participants([researcher_agent, coder_agent])
+        .with_standard_manager(
+            agent=manager_agent,
+            max_round_count=10,
+            max_stall_count=3,
+            max_reset_count=2,
+        )
+        .build()
+    )
+
+    task = (
+        "I am preparing a report on the energy efficiency of different machine learning model architectures. "
+        "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:
+        # 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):
+            # Fallback for any other events with text
+            print(response.text, end="", flush=True)
+
+    except Exception as e:
+        print(f"Workflow execution failed: {e}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,122 @@
+# 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

@@ -0,0 +1,87 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import Role, SequentialBuilder
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+
+"""
+Sample: Build a sequential workflow orchestration and wrap it as an agent.
+
+The script assembles a sequential conversation flow with `SequentialBuilder`, then
+invokes the entire orchestration through the `workflow.as_agent(...)` interface so
+other coordinators can reuse the chain as a single participant.
+
+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.as_agent(
+        instructions=("You are a concise copywriter. Provide a single, punchy marketing sentence based on the prompt."),
+        name="writer",
+    )
+
+    reviewer = chat_client.as_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) Treat the workflow itself as an agent for follow-up invocations
+    agent = workflow.as_agent(name="SequentialWorkflowAgent")
+    prompt = "Write a tagline for a budget-friendly eBike."
+    agent_response = await agent.run(prompt)
+
+    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 == Role.ASSISTANT.value 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!
+
+    ===== as_agent() Conversation =====
+    ------------------------------------------------------------
+    01 [writer]
+    Go electric, save big—your affordable ride awaits!
+    ------------------------------------------------------------
+    02 [reviewer]
+    Catchy and straightforward! The tagline clearly emphasizes both the electric aspect and the affordability of the
+    eBike. It's inviting and actionable. For even more impact, consider making it slightly shorter:
+    "Go electric, save big." Overall, this is an effective and appealing suggestion for a budget-friendly eBike.
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,179 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import sys
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+
+# Ensure local getting_started package can be imported when running as a script.
+_SAMPLES_ROOT = Path(__file__).resolve().parents[3]
+if str(_SAMPLES_ROOT) not in sys.path:
+    sys.path.insert(0, str(_SAMPLES_ROOT))
+
+from agent_framework import (  # noqa: E402
+    ChatMessage,
+    Executor,
+    FunctionCallContent,
+    FunctionResultContent,
+    Role,
+    WorkflowAgent,
+    WorkflowBuilder,
+    WorkflowContext,
+    handler,
+    response_handler,
+)
+from getting_started.workflows.agents.workflow_as_agent_reflection_pattern import (  # noqa: E402
+    ReviewRequest,
+    ReviewResponse,
+    Worker,
+)
+
+"""
+Sample: Workflow Agent with Human-in-the-Loop
+
+Purpose:
+This sample demonstrates how to build a workflow agent that escalates uncertain
+decisions to a human manager. A Worker generates results, while a Reviewer
+evaluates them. When the Reviewer is not confident, it escalates the decision
+to a human, receives the human response, and then forwards that response back
+to the Worker. The workflow completes when idle.
+
+Prerequisites:
+- OpenAI account configured and accessible for OpenAIChatClient.
+- Familiarity with WorkflowBuilder, Executor, and WorkflowContext from agent_framework.
+- Understanding of request-response message handling in executors.
+- (Optional) Review of reflection and escalation patterns, such as those in
+  workflow_as_agent_reflection.py.
+"""
+
+
+@dataclass
+class HumanReviewRequest:
+    """A request message type for escalation to a human reviewer."""
+
+    agent_request: ReviewRequest | None = None
+
+
+class ReviewerWithHumanInTheLoop(Executor):
+    """Executor that always escalates reviews to a human manager."""
+
+    def __init__(self, worker_id: str, reviewer_id: str | None = None) -> None:
+        unique_id = reviewer_id or f"{worker_id}-reviewer"
+        super().__init__(id=unique_id)
+        self._worker_id = worker_id
+
+    @handler
+    async def review(self, request: ReviewRequest, ctx: WorkflowContext) -> None:
+        # In this simplified example, we always escalate to a human manager.
+        # See workflow_as_agent_reflection.py for an implementation
+        # using an automated agent to make the review decision.
+        print(f"Reviewer: Evaluating response for request {request.request_id[:8]}...")
+        print("Reviewer: Escalating to human manager...")
+
+        # Forward the request to a human manager by sending a HumanReviewRequest.
+        await ctx.request_info(request_data=HumanReviewRequest(agent_request=request), response_type=ReviewResponse)
+
+    @response_handler
+    async def accept_human_review(
+        self,
+        original_request: HumanReviewRequest,
+        response: ReviewResponse,
+        ctx: WorkflowContext[ReviewResponse],
+    ) -> None:
+        # Accept the human review response and forward it back to the Worker.
+        print(f"Reviewer: Accepting human review for request {response.request_id[:8]}...")
+        print(f"Reviewer: Human feedback: {response.feedback}")
+        print(f"Reviewer: Human approved: {response.approved}")
+        print("Reviewer: Forwarding human review back to worker...")
+        await ctx.send_message(response, target_id=self._worker_id)
+
+
+async def main() -> None:
+    print("Starting Workflow Agent with Human-in-the-Loop Demo")
+    print("=" * 50)
+
+    print("Building workflow with Worker-Reviewer cycle...")
+    # Build a workflow with bidirectional communication between Worker and Reviewer,
+    # and escalation paths for human review.
+    agent = (
+        WorkflowBuilder()
+        .register_executor(
+            lambda: Worker(
+                id="sub-worker",
+                chat_client=AzureOpenAIChatClient(credential=AzureCliCredential()),
+            ),
+            name="worker",
+        )
+        .register_executor(
+            lambda: ReviewerWithHumanInTheLoop(worker_id="sub-worker"),
+            name="reviewer",
+        )
+        .add_edge("worker", "reviewer")  # Worker sends requests to Reviewer
+        .add_edge("reviewer", "worker")  # Reviewer sends feedback to Worker
+        .set_start_executor("worker")
+        .build()
+        .as_agent()  # Convert workflow into an agent interface
+    )
+
+    print("Running workflow agent with user query...")
+    print("Query: 'Write code for parallel reading 1 million files on disk and write to a sorted output file.'")
+    print("-" * 50)
+
+    # Run the agent with an initial query.
+    response = await agent.run(
+        "Write code for parallel reading 1 million Files on disk and write to a sorted output file."
+    )
+
+    # Locate the human review function call in the response messages.
+    human_review_function_call: FunctionCallContent | None = None
+    for message in response.messages:
+        for content in message.contents:
+            if isinstance(content, FunctionCallContent) and content.name == WorkflowAgent.REQUEST_INFO_FUNCTION_NAME:
+                human_review_function_call = content
+
+    # Handle the human review if required.
+    if human_review_function_call:
+        # Parse the human review request arguments.
+        human_request_args = human_review_function_call.arguments
+        if isinstance(human_request_args, str):
+            request: WorkflowAgent.RequestInfoFunctionArgs = WorkflowAgent.RequestInfoFunctionArgs.from_json(
+                human_request_args
+            )
+        elif isinstance(human_request_args, Mapping):
+            request = WorkflowAgent.RequestInfoFunctionArgs.from_dict(dict(human_request_args))
+        else:
+            raise TypeError("Unexpected argument type for human review function call.")
+
+        request_payload: Any = request.data
+        if not isinstance(request_payload, HumanReviewRequest):
+            raise ValueError("Human review request payload must be a HumanReviewRequest.")
+
+        agent_request = request_payload.agent_request
+        if agent_request is None:
+            raise ValueError("Human review request must include agent_request.")
+
+        request_id = agent_request.request_id
+        # Mock a human response approval for demonstration purposes.
+        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,
+            result=human_response,
+        )
+        # Send the human review result back to the agent.
+        response = await agent.run(ChatMessage(role=Role.TOOL, contents=[human_review_function_result]))
+        print(f"📤 Agent Response: {response.messages[-1].text}")
+
+    print("=" * 50)
+    print("Workflow completed!")
+
+
+if __name__ == "__main__":
+    print("Initializing Workflow as Agent Sample...")
+    asyncio.run(main())

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

@@ -0,0 +1,140 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import json
+from typing import Annotated, Any
+
+from agent_framework import SequentialBuilder, ai_function
+from agent_framework.openai import OpenAIChatClient
+from pydantic import Field
+
+"""
+Sample: Workflow as Agent with kwargs Propagation to @ai_function Tools
+
+This sample demonstrates how to flow custom context (skill data, user tokens, etc.)
+through a workflow exposed via .as_agent() to @ai_function tools using the **kwargs pattern.
+
+Key Concepts:
+- Build a workflow using SequentialBuilder (or any builder pattern)
+- Expose the workflow as a reusable agent via workflow.as_agent()
+- Pass custom context as kwargs when invoking workflow_agent.run() or run_stream()
+- kwargs are stored in SharedState and propagated to all agent invocations
+- @ai_function tools receive kwargs via **kwargs parameter
+
+When to use workflow.as_agent():
+- To treat an entire workflow orchestration as a single agent
+- To compose workflows into higher-level orchestrations
+- To maintain a consistent agent interface for callers
+
+Prerequisites:
+- OpenAI environment variables configured
+"""
+
+
+# Define tools that accept custom context via **kwargs
+@ai_function
+def get_user_data(
+    query: Annotated[str, Field(description="What user data to retrieve")],
+    **kwargs: Any,
+) -> str:
+    """Retrieve user-specific data based on the authenticated context."""
+    user_token = kwargs.get("user_token", {})
+    user_name = user_token.get("user_name", "anonymous")
+    access_level = user_token.get("access_level", "none")
+
+    print(f"\n[get_user_data] Received kwargs keys: {list(kwargs.keys())}")
+    print(f"[get_user_data] User: {user_name}")
+    print(f"[get_user_data] Access level: {access_level}")
+
+    return f"Retrieved data for user {user_name} with {access_level} access: {query}"
+
+
+@ai_function
+def call_api(
+    endpoint_name: Annotated[str, Field(description="Name of the API endpoint to call")],
+    **kwargs: Any,
+) -> str:
+    """Call an API using the configured endpoints from custom_data."""
+    custom_data = kwargs.get("custom_data", {})
+    api_config = custom_data.get("api_config", {})
+
+    base_url = api_config.get("base_url", "unknown")
+    endpoints = api_config.get("endpoints", {})
+
+    print(f"\n[call_api] Received kwargs keys: {list(kwargs.keys())}")
+    print(f"[call_api] Base URL: {base_url}")
+    print(f"[call_api] Available endpoints: {list(endpoints.keys())}")
+
+    if endpoint_name in endpoints:
+        return f"Called {base_url}{endpoints[endpoint_name]} successfully"
+    return f"Endpoint '{endpoint_name}' not found in configuration"
+
+
+async def main() -> None:
+    print("=" * 70)
+    print("Workflow as Agent kwargs Flow Demo")
+    print("=" * 70)
+
+    # Create chat client
+    chat_client = OpenAIChatClient()
+
+    # Create agent with tools that use kwargs
+    agent = chat_client.as_agent(
+        name="assistant",
+        instructions=(
+            "You are a helpful assistant. Use the available tools to help users. "
+            "When asked about user data, use get_user_data. "
+            "When asked to call an API, use call_api."
+        ),
+        tools=[get_user_data, call_api],
+    )
+
+    # Build a sequential workflow
+    workflow = SequentialBuilder().participants([agent]).build()
+
+    # Expose the workflow as an agent using .as_agent()
+    workflow_agent = workflow.as_agent(name="WorkflowAgent")
+
+    # Define custom context that will flow to ai_functions via kwargs
+    custom_data = {
+        "api_config": {
+            "base_url": "https://api.example.com",
+            "endpoints": {
+                "users": "/v1/users",
+                "orders": "/v1/orders",
+                "products": "/v1/products",
+            },
+        },
+    }
+
+    user_token = {
+        "user_name": "bob@contoso.com",
+        "access_level": "admin",
+    }
+
+    print("\nCustom Data being passed:")
+    print(json.dumps(custom_data, indent=2))
+    print(f"\nUser: {user_token['user_name']}")
+    print("\n" + "-" * 70)
+    print("Workflow Agent Execution (watch for [tool_name] logs showing kwargs received):")
+    print("-" * 70)
+
+    # Run workflow agent with kwargs - these will flow through to ai_functions
+    # Note: kwargs are passed to workflow_agent.run_stream() just like workflow.run_stream()
+    print("\n===== Streaming Response =====")
+    async for update in workflow_agent.run_stream(
+        "Please get my user data and then call the users API endpoint.",
+        custom_data=custom_data,
+        user_token=user_token,
+    ):
+        if update.text:
+            print(update.text, end="", flush=True)
+    print()
+
+    print("\n" + "=" * 70)
+    print("Sample Complete")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,232 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from dataclasses import dataclass
+from uuid import uuid4
+
+from agent_framework import (
+    AgentResponseUpdate,
+    AgentRunUpdateEvent,
+    ChatClientProtocol,
+    ChatMessage,
+    Content,
+    Executor,
+    Role,
+    WorkflowBuilder,
+    WorkflowContext,
+    handler,
+)
+from agent_framework.openai import OpenAIChatClient
+from pydantic import BaseModel
+
+"""
+Sample: Workflow as Agent with Reflection and Retry Pattern
+
+Purpose:
+This sample demonstrates how to wrap a workflow as an agent using WorkflowAgent.
+It uses a reflection pattern where a Worker executor generates responses and a
+Reviewer executor evaluates them. If the response is not approved, the Worker
+regenerates the output based on feedback until the Reviewer approves it. Only
+approved responses are emitted to the external consumer. The workflow completes when idle.
+
+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.
+
+Prerequisites:
+- OpenAI account configured and accessible for OpenAIChatClient.
+- Familiarity with WorkflowBuilder, Executor, WorkflowContext, and event handling.
+- Understanding of how agent messages are generated, reviewed, and re-submitted.
+"""
+
+
+@dataclass
+class ReviewRequest:
+    """Structured request passed from Worker to Reviewer for evaluation."""
+
+    request_id: str
+    user_messages: list[ChatMessage]
+    agent_messages: list[ChatMessage]
+
+
+@dataclass
+class ReviewResponse:
+    """Structured response from Reviewer back to Worker."""
+
+    request_id: str
+    feedback: str
+    approved: bool
+
+
+class Reviewer(Executor):
+    """Executor that reviews agent responses and provides structured feedback."""
+
+    def __init__(self, id: str, chat_client: ChatClientProtocol) -> None:
+        super().__init__(id=id)
+        self._chat_client = chat_client
+
+    @handler
+    async def review(self, request: ReviewRequest, ctx: WorkflowContext[ReviewResponse]) -> None:
+        print(f"Reviewer: Evaluating response for request {request.request_id[:8]}...")
+
+        # Define structured schema for the LLM to return.
+        class _Response(BaseModel):
+            feedback: str
+            approved: bool
+
+        # Construct review instructions and context.
+        messages = [
+            ChatMessage(
+                role=Role.SYSTEM,
+                text=(
+                    "You are a reviewer for an AI agent. Provide feedback on the "
+                    "exchange between a user and the agent. Indicate approval only if:\n"
+                    "- Relevance: response addresses the query\n"
+                    "- Accuracy: information is correct\n"
+                    "- Clarity: response is easy to understand\n"
+                    "- Completeness: response covers all aspects\n"
+                    "Do not approve until all criteria are satisfied."
+                ),
+            )
+        ]
+        # Add conversation history.
+        messages.extend(request.user_messages)
+        messages.extend(request.agent_messages)
+
+        # Add explicit review instruction.
+        messages.append(ChatMessage(role=Role.USER, text="Please review the agent's responses."))
+
+        print("Reviewer: Sending review request to LLM...")
+        response = await self._chat_client.get_response(messages=messages, options={"response_format": _Response})
+
+        parsed = _Response.model_validate_json(response.messages[-1].text)
+
+        print(f"Reviewer: Review complete - Approved: {parsed.approved}")
+        print(f"Reviewer: Feedback: {parsed.feedback}")
+
+        # Send structured review result to Worker.
+        await ctx.send_message(
+            ReviewResponse(request_id=request.request_id, feedback=parsed.feedback, approved=parsed.approved)
+        )
+
+
+class Worker(Executor):
+    """Executor that generates responses and incorporates feedback when necessary."""
+
+    def __init__(self, id: str, chat_client: ChatClientProtocol) -> None:
+        super().__init__(id=id)
+        self._chat_client = chat_client
+        self._pending_requests: dict[str, tuple[ReviewRequest, list[ChatMessage]]] = {}
+
+    @handler
+    async def handle_user_messages(self, user_messages: list[ChatMessage], ctx: WorkflowContext[ReviewRequest]) -> None:
+        print("Worker: Received user messages, generating response...")
+
+        # Initialize chat with system prompt.
+        messages = [ChatMessage(role=Role.SYSTEM, text="You are a helpful assistant.")]
+        messages.extend(user_messages)
+
+        print("Worker: Calling LLM to generate response...")
+        response = await self._chat_client.get_response(messages=messages)
+        print(f"Worker: Response generated: {response.messages[-1].text}")
+
+        # Add agent messages to context.
+        messages.extend(response.messages)
+
+        # Create review request and send to Reviewer.
+        request = ReviewRequest(request_id=str(uuid4()), user_messages=user_messages, agent_messages=response.messages)
+        print(f"Worker: Sending response for review (ID: {request.request_id[:8]})")
+        await ctx.send_message(request)
+
+        # Track request for possible retry.
+        self._pending_requests[request.request_id] = (request, messages)
+
+    @handler
+    async def handle_review_response(self, review: ReviewResponse, ctx: WorkflowContext[ReviewRequest]) -> None:
+        print(f"Worker: Received review for request {review.request_id[:8]} - Approved: {review.approved}")
+
+        if review.request_id not in self._pending_requests:
+            raise ValueError(f"Unknown request ID in review: {review.request_id}")
+
+        request, messages = self._pending_requests.pop(review.request_id)
+
+        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=Role.ASSISTANT))
+            )
+            return
+
+        print(f"Worker: Response not approved. Feedback: {review.feedback}")
+        print("Worker: Regenerating response with feedback...")
+
+        # Incorporate review feedback.
+        messages.append(ChatMessage(role=Role.SYSTEM, text=review.feedback))
+        messages.append(
+            ChatMessage(role=Role.SYSTEM, text="Please incorporate the feedback and regenerate the response.")
+        )
+        messages.extend(request.user_messages)
+
+        # Retry with updated prompt.
+        response = await self._chat_client.get_response(messages=messages)
+        print(f"Worker: New response generated: {response.messages[-1].text}")
+
+        messages.extend(response.messages)
+
+        # Send updated request for re-review.
+        new_request = ReviewRequest(
+            request_id=review.request_id, user_messages=request.user_messages, agent_messages=response.messages
+        )
+        await ctx.send_message(new_request)
+
+        # Track new request for further evaluation.
+        self._pending_requests[new_request.request_id] = (new_request, messages)
+
+
+async def main() -> None:
+    print("Starting Workflow Agent Demo")
+    print("=" * 50)
+
+    print("Building workflow with Worker ↔ Reviewer cycle...")
+    agent = (
+        WorkflowBuilder()
+        .register_executor(
+            lambda: Worker(id="worker", chat_client=OpenAIChatClient(model_id="gpt-4.1-nano")),
+            name="worker",
+        )
+        .register_executor(
+            lambda: Reviewer(id="reviewer", chat_client=OpenAIChatClient(model_id="gpt-4.1")),
+            name="reviewer",
+        )
+        .add_edge("worker", "reviewer")  # Worker sends responses to Reviewer
+        .add_edge("reviewer", "worker")  # Reviewer provides feedback to Worker
+        .set_start_executor("worker")
+        .build()
+        .as_agent()  # Wrap workflow as an agent
+    )
+
+    print("Running workflow agent with user query...")
+    print("Query: 'Write code for parallel reading 1 million files on disk and write to a sorted output file.'")
+    print("-" * 50)
+
+    # Run agent in streaming mode to observe incremental updates.
+    async for event in agent.run_stream(
+        "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!")
+
+
+if __name__ == "__main__":
+    print("Initializing Workflow as Agent Sample...")
+    asyncio.run(main())

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

@@ -0,0 +1,167 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import AgentThread, ChatAgent, ChatMessageStore, SequentialBuilder
+from agent_framework.openai import OpenAIChatClient
+
+"""
+Sample: Workflow as Agent with Thread Conversation History and Checkpointing
+
+This sample demonstrates how to use AgentThread with a workflow wrapped as an agent
+to maintain conversation history across multiple invocations. When using as_agent(),
+the thread's message store history is included in each workflow run, enabling
+the workflow participants to reference prior conversation context.
+
+It also demonstrates how to enable checkpointing for workflow execution state
+persistence, allowing workflows to be paused and resumed.
+
+Key concepts:
+- Workflows can be wrapped as agents using workflow.as_agent()
+- AgentThread with ChatMessageStore preserves conversation history
+- Each call to agent.run() includes thread history + new message
+- Participants in the workflow see the full conversation context
+- checkpoint_storage parameter enables workflow state persistence
+
+Use cases:
+- Multi-turn conversations with workflow-based orchestrations
+- Stateful workflows that need context from previous interactions
+- Building conversational agents that leverage workflow patterns
+- Long-running workflows that need pause/resume capability
+
+Prerequisites:
+- OpenAI environment variables configured for OpenAIChatClient
+"""
+
+
+async def main() -> None:
+    # Create a chat client
+    chat_client = OpenAIChatClient()
+
+    # Define factory functions for workflow participants
+    def create_assistant() -> ChatAgent:
+        return chat_client.as_agent(
+            name="assistant",
+            instructions=(
+                "You are a helpful assistant. Answer questions based on the conversation "
+                "history. If the user asks about something mentioned earlier, reference it."
+            ),
+        )
+
+    def create_summarizer() -> ChatAgent:
+        return chat_client.as_agent(
+            name="summarizer",
+            instructions=(
+                "You are a summarizer. After the assistant responds, provide a brief "
+                "one-sentence summary of the key point from the conversation so far."
+            ),
+        )
+
+    # Build a sequential workflow: assistant -> summarizer
+    workflow = SequentialBuilder().register_participants([create_assistant, create_summarizer]).build()
+
+    # Wrap the workflow as an agent
+    agent = workflow.as_agent(name="ConversationalWorkflowAgent")
+
+    # Create a thread with a ChatMessageStore to maintain history
+    message_store = ChatMessageStore()
+    thread = AgentThread(message_store=message_store)
+
+    print("=" * 60)
+    print("Workflow as Agent with Thread - Multi-turn Conversation")
+    print("=" * 60)
+
+    # First turn: Introduce a topic
+    query1 = "My name is Alex and I'm learning about machine learning."
+    print(f"\n[Turn 1] User: {query1}")
+
+    response1 = await agent.run(query1, thread=thread)
+    if response1.messages:
+        for msg in response1.messages:
+            speaker = msg.author_name or msg.role.value
+            print(f"[{speaker}]: {msg.text}")
+
+    # Second turn: Reference the previous topic
+    query2 = "What was my name again, and what am I learning about?"
+    print(f"\n[Turn 2] User: {query2}")
+
+    response2 = await agent.run(query2, thread=thread)
+    if response2.messages:
+        for msg in response2.messages:
+            speaker = msg.author_name or msg.role.value
+            print(f"[{speaker}]: {msg.text}")
+
+    # Third turn: Ask a follow-up question
+    query3 = "Can you suggest a good first project for me to try?"
+    print(f"\n[Turn 3] User: {query3}")
+
+    response3 = await agent.run(query3, thread=thread)
+    if response3.messages:
+        for msg in response3.messages:
+            speaker = msg.author_name or msg.role.value
+            print(f"[{speaker}]: {msg.text}")
+
+    # Show the accumulated conversation history
+    print("\n" + "=" * 60)
+    print("Full Thread History")
+    print("=" * 60)
+    if thread.message_store:
+        history = await thread.message_store.list_messages()
+        for i, msg in enumerate(history, start=1):
+            role = msg.role.value if hasattr(msg.role, "value") else str(msg.role)
+            speaker = msg.author_name or role
+            text_preview = msg.text[:80] + "..." if len(msg.text) > 80 else msg.text
+            print(f"{i:02d}. [{speaker}]: {text_preview}")
+
+
+async def demonstrate_thread_serialization() -> None:
+    """
+    Demonstrates serializing and resuming a thread with a workflow agent.
+
+    This shows how conversation history can be persisted and restored,
+    enabling long-running conversational workflows.
+    """
+    chat_client = OpenAIChatClient()
+
+    def create_assistant() -> ChatAgent:
+        return chat_client.as_agent(
+            name="memory_assistant",
+            instructions="You are a helpful assistant with good memory. Remember details from our conversation.",
+        )
+
+    workflow = SequentialBuilder().register_participants([create_assistant]).build()
+    agent = workflow.as_agent(name="MemoryWorkflowAgent")
+
+    # Create initial thread and have a conversation
+    thread = AgentThread(message_store=ChatMessageStore())
+
+    print("\n" + "=" * 60)
+    print("Thread Serialization Demo")
+    print("=" * 60)
+
+    # First interaction
+    query = "Remember this: the secret code is ALPHA-7."
+    print(f"\n[Session 1] User: {query}")
+    response = await agent.run(query, thread=thread)
+    if response.messages:
+        print(f"[assistant]: {response.messages[0].text}")
+
+    # Serialize thread state (could be saved to database/file)
+    serialized_state = await thread.serialize()
+    print("\n[Serialized thread state for persistence]")
+
+    # Simulate a new session by creating a new thread from serialized state
+    restored_thread = AgentThread(message_store=ChatMessageStore())
+    await restored_thread.update_from_thread_state(serialized_state)
+
+    # Continue conversation with restored thread
+    query = "What was the secret code I told you?"
+    print(f"\n[Session 2 - Restored] User: {query}")
+    response = await agent.run(query, thread=restored_thread)
+    if response.messages:
+        print(f"[assistant]: {response.messages[0].text}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+    asyncio.run(demonstrate_thread_serialization())

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

@@ -0,0 +1,351 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, override
+
+# NOTE: the Azure client imports above are real dependencies. When running this
+# sample outside of Azure-enabled environments you may wish to swap in the
+# `agent_framework.builtin` chat client or mock the writer executor. We keep the
+# concrete import here so readers can see an end-to-end configuration.
+from agent_framework import (
+    AgentExecutorRequest,
+    AgentExecutorResponse,
+    ChatMessage,
+    Executor,
+    FileCheckpointStorage,
+    RequestInfoEvent,
+    Role,
+    Workflow,
+    WorkflowBuilder,
+    WorkflowCheckpoint,
+    WorkflowContext,
+    WorkflowOutputEvent,
+    WorkflowStatusEvent,
+    get_checkpoint_summary,
+    handler,
+    response_handler,
+)
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+
+"""
+Sample: Checkpoint + human-in-the-loop quickstart.
+
+This getting-started sample keeps the moving pieces to a minimum:
+
+1. A brief is turned into a consistent prompt for an AI copywriter.
+2. The copywriter (an `AgentExecutor`) drafts release notes.
+3. A reviewer gateway sends a request for approval for every draft.
+4. The workflow records checkpoints between each superstep so you can stop the
+   program, restart later, and optionally pre-supply human answers on resume.
+
+Key concepts demonstrated
+-------------------------
+- Minimal executor pipeline with checkpoint persistence.
+- Human-in-the-loop pause/resume with checkpoint restoration.
+
+Typical pause/resume flow
+-------------------------
+1. Run the workflow until a human approval request is emitted.
+2. If the human is offline, exit the program. A checkpoint with
+   ``status=awaiting human response`` now exists.
+3. Later, restart the script, select that checkpoint, and provide the stored
+   human decision when prompted to pre-supply responses.
+   Doing so applies the answer immediately on resume, so the system does **not**
+   re-emit the same `RequestInfoEvent`.
+"""
+
+# Directory used for the sample's temporary checkpoint files. We isolate the
+# demo artefacts so that repeated runs do not collide with other samples and so
+# the clean-up step at the end of the script can simply delete the directory.
+TEMP_DIR = Path(__file__).with_suffix("").parent / "tmp" / "checkpoints_hitl"
+TEMP_DIR.mkdir(parents=True, exist_ok=True)
+
+
+class BriefPreparer(Executor):
+    """Normalises the user brief and sends a single AgentExecutorRequest."""
+
+    # The first executor in the workflow. By keeping it tiny we make it easier
+    # to reason about the state that will later be captured in the checkpoint.
+    # It is responsible for tidying the human-provided brief and kicking off the
+    # agent run with a deterministic prompt structure.
+
+    def __init__(self, id: str, agent_id: str) -> None:
+        super().__init__(id=id)
+        self._agent_id = agent_id
+
+    @handler
+    async def prepare(self, brief: str, ctx: WorkflowContext[AgentExecutorRequest, str]) -> None:
+        # Collapse errant whitespace so the prompt is stable between runs.
+        normalized = " ".join(brief.split()).strip()
+        if not normalized.endswith("."):
+            normalized += "."
+        # Persist the cleaned brief in shared state so downstream executors and
+        # future checkpoints can recover the original intent.
+        await ctx.set_shared_state("brief", normalized)
+        prompt = (
+            "You are drafting product release notes. Summarise the brief below in two sentences. "
+            "Keep it positive and end with a call to action.\n\n"
+            f"BRIEF: {normalized}"
+        )
+        # Hand the prompt to the writer agent. We always route through the
+        # workflow context so the runtime can capture messages for checkpointing.
+        await ctx.send_message(
+            AgentExecutorRequest(messages=[ChatMessage(Role.USER, text=prompt)], should_respond=True),
+            target_id=self._agent_id,
+        )
+
+
+@dataclass
+class HumanApprovalRequest:
+    """Request sent to the human reviewer."""
+
+    # These fields are intentionally simple because they are serialised into
+    # checkpoints. Keeping them primitive types guarantees the new
+    # `pending_requests_from_checkpoint` helper can reconstruct them on resume.
+    prompt: str = ""
+    draft: str = ""
+    iteration: int = 0
+
+
+class ReviewGateway(Executor):
+    """Routes agent drafts to humans and optionally back for revisions."""
+
+    def __init__(self, id: str, writer_id: str) -> None:
+        super().__init__(id=id)
+        self._writer_id = writer_id
+        self._iteration = 0
+
+    @handler
+    async def on_agent_response(self, response: AgentExecutorResponse, ctx: WorkflowContext) -> None:
+        # Capture the agent output so we can surface it to the reviewer and persist iterations.
+        self._iteration += 1
+
+        # Emit a human approval request.
+        await ctx.request_info(
+            request_data=HumanApprovalRequest(
+                prompt="Review the draft. Reply 'approve' or provide edit instructions.",
+                draft=response.agent_response.text,
+                iteration=self._iteration,
+            ),
+            response_type=str,
+        )
+
+    @response_handler
+    async def on_human_feedback(
+        self,
+        original_request: HumanApprovalRequest,
+        feedback: str,
+        ctx: WorkflowContext[AgentExecutorRequest | str, str],
+    ) -> None:
+        # The `original_request` is the request we sent earlier that is now being answered.
+        reply = feedback.strip()
+
+        if len(reply) == 0 or reply.lower() == "approve":
+            # Workflow is completed when the human approves.
+            await ctx.yield_output(original_request.draft)
+            return
+
+        # Any other response loops us back to the writer with fresh guidance.
+        prompt = (
+            "Revise the launch note. Respond with the new copy only.\n\n"
+            f"Previous draft:\n{original_request.draft}\n\n"
+            f"Human guidance: {reply}"
+        )
+        await ctx.send_message(
+            AgentExecutorRequest(messages=[ChatMessage(Role.USER, text=prompt)], should_respond=True),
+            target_id=self._writer_id,
+        )
+
+    @override
+    async def on_checkpoint_save(self) -> dict[str, Any]:
+        # Save the current iteration count in executor state for checkpointing.
+        return {"iteration": self._iteration}
+
+    @override
+    async def on_checkpoint_restore(self, state: dict[str, Any]) -> None:
+        # Restore the iteration count from executor state during checkpoint recovery.
+        self._iteration = state.get("iteration", 0)
+
+
+def create_workflow(checkpoint_storage: FileCheckpointStorage) -> Workflow:
+    """Assemble the workflow graph used by both the initial run and resume."""
+    # Wire the workflow DAG. Edges mirror the numbered steps described in the
+    # module docstring. Because `WorkflowBuilder` is declarative, reading these
+    # edges is often the quickest way to understand execution order.
+    workflow_builder = (
+        WorkflowBuilder(max_iterations=6)
+        .register_agent(
+            lambda: AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+                instructions="Write concise, warm release notes that sound human and helpful.",
+                # The agent name is stable across runs which keeps checkpoints deterministic.
+                name="writer",
+            ),
+            name="writer",
+        )
+        .register_executor(lambda: ReviewGateway(id="review_gateway", writer_id="writer"), name="review_gateway")
+        .register_executor(lambda: BriefPreparer(id="prepare_brief", agent_id="writer"), name="prepare_brief")
+        .set_start_executor("prepare_brief")
+        .add_edge("prepare_brief", "writer")
+        .add_edge("writer", "review_gateway")
+        .add_edge("review_gateway", "writer")  # revisions loop
+        .with_checkpointing(checkpoint_storage=checkpoint_storage)
+    )
+
+    return workflow_builder.build()
+
+
+def render_checkpoint_summary(checkpoints: list["WorkflowCheckpoint"]) -> None:
+    """Pretty-print saved checkpoints with the new framework summaries."""
+
+    print("\nCheckpoint summary:")
+    for summary in [get_checkpoint_summary(cp) for cp in sorted(checkpoints, key=lambda c: c.timestamp)]:
+        # Compose a single line per checkpoint so the user can scan the output
+        # and pick the resume point that still has outstanding human work.
+        line = (
+            f"- {summary.checkpoint_id} | timestamp={summary.timestamp} | iter={summary.iteration_count} "
+            f"| targets={summary.targets} | states={summary.executor_ids}"
+        )
+        if summary.status:
+            line += f" | status={summary.status}"
+        if summary.pending_request_info_events:
+            line += f" | pending_request_id={summary.pending_request_info_events[0].request_id}"
+        print(line)
+
+
+def prompt_for_responses(requests: dict[str, HumanApprovalRequest]) -> dict[str, str]:
+    """Interactive CLI prompt for any live RequestInfo requests."""
+
+    responses: dict[str, str] = {}
+    for request_id, request in requests.items():
+        print("\n=== Human approval needed ===")
+        print(f"request_id: {request_id}")
+        print(f"Iteration: {request.iteration}")
+        print(request.prompt)
+        print("Draft: \n---\n" + request.draft + "\n---")
+        response = input("Type 'approve' or enter revision guidance (or 'exit' to quit): ").strip()
+        if response.lower() == "exit":
+            raise SystemExit("Stopped by user.")
+        responses[request_id] = response
+
+    return responses
+
+
+async def run_interactive_session(
+    workflow: Workflow,
+    initial_message: str | None = None,
+    checkpoint_id: str | None = None,
+) -> str:
+    """Run the workflow until it either finishes or pauses for human input."""
+
+    requests: dict[str, HumanApprovalRequest] = {}
+    responses: dict[str, str] | None = None
+    completed_output: str | None = None
+
+    while True:
+        if responses:
+            event_stream = workflow.send_responses_streaming(responses)
+            requests.clear()
+            responses = None
+        else:
+            if initial_message:
+                print(f"\nStarting workflow with brief: {initial_message}\n")
+                event_stream = workflow.run_stream(message=initial_message)
+            elif checkpoint_id:
+                print("\nStarting workflow from checkpoint...\n")
+                event_stream = workflow.run_stream(checkpoint_id=checkpoint_id)
+            else:
+                raise ValueError("Either initial_message or checkpoint_id must be provided")
+
+        async for event in event_stream:
+            if isinstance(event, WorkflowStatusEvent):
+                print(event)
+            if isinstance(event, WorkflowOutputEvent):
+                completed_output = event.data
+            if isinstance(event, RequestInfoEvent):
+                if isinstance(event.data, HumanApprovalRequest):
+                    requests[event.request_id] = event.data
+                else:
+                    raise ValueError("Unexpected request data type")
+
+        if completed_output:
+            break
+
+        if requests:
+            responses = prompt_for_responses(requests)
+            continue
+
+        raise RuntimeError("Workflow stopped without completing or requesting input")
+
+    return completed_output
+
+
+async def main() -> None:
+    """Entry point used by both the initial run and subsequent resumes."""
+
+    for file in TEMP_DIR.glob("*.json"):
+        # Start each execution with a clean slate so the demonstration is
+        # deterministic even if the directory had stale checkpoints.
+        file.unlink()
+
+    storage = FileCheckpointStorage(storage_path=TEMP_DIR)
+    workflow = create_workflow(checkpoint_storage=storage)
+
+    brief = (
+        "Introduce our limited edition smart coffee grinder. Mention the $249 price, highlight the "
+        "sensor that auto-adjusts the grind, and invite customers to pre-order on the website."
+    )
+
+    print("Running workflow (human approval required)...")
+    result = await run_interactive_session(workflow, initial_message=brief)
+    print(f"Workflow completed with: {result}")
+
+    checkpoints = await storage.list_checkpoints()
+    if not checkpoints:
+        print("No checkpoints recorded.")
+        return
+
+    # Show the user what is available before we prompt for the index. The
+    # summary helper keeps this output consistent with other tooling.
+    render_checkpoint_summary(checkpoints)
+
+    sorted_cps = sorted(checkpoints, key=lambda c: c.timestamp)
+    print("\nAvailable checkpoints:")
+    for idx, cp in enumerate(sorted_cps):
+        print(f"  [{idx}] id={cp.checkpoint_id} iter={cp.iteration_count}")
+
+    # For the pause/resume demo we typically pick the latest checkpoint whose summary
+    # status reads "awaiting human response" - that is the saved state that proves the
+    # workflow can rehydrate, collect the pending answer, and continue after a break.
+    selection = input("\nResume from which checkpoint? (press Enter to skip): ").strip()  # noqa: ASYNC250
+    if not selection:
+        print("No resume selected. Exiting.")
+        return
+
+    try:
+        idx = int(selection)
+    except ValueError:
+        print("Invalid input; exiting.")
+        return
+
+    if not 0 <= idx < len(sorted_cps):
+        print("Index out of range; exiting.")
+        return
+
+    chosen = sorted_cps[idx]
+    summary = get_checkpoint_summary(chosen)
+    if summary.status == "completed":
+        print("Selected checkpoint already reflects a completed workflow; nothing to resume.")
+        return
+
+    new_workflow = create_workflow(checkpoint_storage=storage)
+    # Resume with a fresh workflow instance. The checkpoint carries the
+    # persistent state while this object holds the runtime wiring.
+    result = await run_interactive_session(new_workflow, checkpoint_id=chosen.checkpoint_id)
+    print(f"Workflow completed with: {result}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,156 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""
+Sample: Checkpointing and Resuming a Workflow
+
+Purpose:
+This sample shows how to enable checkpointing for a long-running workflow
+that can be paused and resumed.
+
+What you learn:
+- How to configure checkpointing storage (InMemoryCheckpointStorage for testing)
+- How to resume a workflow from a checkpoint after interruption
+- How to implement executor state management with checkpoint hooks
+- How to handle workflow interruptions and automatic recovery
+
+Pipeline:
+This sample shows a workflow that computes factor pairs for numbers up to a given limit:
+1) A start executor that receives the upper limit and creates the initial task
+2) A worker executor that processes each number to find its factor pairs
+3) The worker uses checkpoint hooks to save/restore its internal state
+
+Prerequisites:
+- Basic understanding of workflow concepts, including executors, edges, events, etc.
+"""
+
+import asyncio
+from dataclasses import dataclass
+from random import random
+from typing import Any, override
+
+from agent_framework import (
+    Executor,
+    InMemoryCheckpointStorage,
+    SuperStepCompletedEvent,
+    WorkflowBuilder,
+    WorkflowCheckpoint,
+    WorkflowContext,
+    WorkflowOutputEvent,
+    handler,
+)
+
+
+@dataclass
+class ComputeTask:
+    """Task containing the list of numbers remaining to be processed."""
+
+    remaining_numbers: list[int]
+
+
+class StartExecutor(Executor):
+    """Initiates the workflow by providing the upper limit for factor pair computation."""
+
+    @handler
+    async def start(self, upper_limit: int, ctx: WorkflowContext[ComputeTask]) -> None:
+        """Start the workflow with a list of numbers to process."""
+        print(f"StartExecutor: Starting factor pair computation up to {upper_limit}")
+        await ctx.send_message(ComputeTask(remaining_numbers=list(range(1, upper_limit + 1))))
+
+
+class WorkerExecutor(Executor):
+    """Processes numbers to compute their factor pairs and manages executor state for checkpointing."""
+
+    def __init__(self, id: str) -> None:
+        super().__init__(id=id)
+        self._composite_number_pairs: dict[int, list[tuple[int, int]]] = {}
+
+    @handler
+    async def compute(
+        self,
+        task: ComputeTask,
+        ctx: WorkflowContext[ComputeTask, dict[int, list[tuple[int, int]]]],
+    ) -> None:
+        """Process the next number in the task, computing its factor pairs."""
+        next_number = task.remaining_numbers.pop(0)
+
+        print(f"WorkerExecutor: Computing factor pairs for {next_number}")
+        pairs: list[tuple[int, int]] = []
+        for i in range(1, next_number):
+            if next_number % i == 0:
+                pairs.append((i, next_number // i))
+        self._composite_number_pairs[next_number] = pairs
+
+        if not task.remaining_numbers:
+            # All numbers processed - output the results
+            await ctx.yield_output(self._composite_number_pairs)
+        else:
+            # More numbers to process - continue with remaining task
+            await ctx.send_message(task)
+
+    @override
+    async def on_checkpoint_save(self) -> dict[str, Any]:
+        """Save the executor's internal state for checkpointing."""
+        return {"composite_number_pairs": self._composite_number_pairs}
+
+    @override
+    async def on_checkpoint_restore(self, state: dict[str, Any]) -> None:
+        """Restore the executor's internal state from a checkpoint."""
+        self._composite_number_pairs = state.get("composite_number_pairs", {})
+
+
+async def main():
+    # Build workflow with checkpointing enabled
+    workflow_builder = (
+        WorkflowBuilder()
+        .register_executor(lambda: StartExecutor(id="start"), name="start")
+        .register_executor(lambda: WorkerExecutor(id="worker"), name="worker")
+        .set_start_executor("start")
+        .add_edge("start", "worker")
+        .add_edge("worker", "worker")  # Self-loop for iterative processing
+    )
+    checkpoint_storage = InMemoryCheckpointStorage()
+    workflow_builder = workflow_builder.with_checkpointing(checkpoint_storage=checkpoint_storage)
+
+    # Run workflow with automatic checkpoint recovery
+    latest_checkpoint: WorkflowCheckpoint | None = None
+    while True:
+        workflow = workflow_builder.build()
+
+        # Start from checkpoint or fresh execution
+        print(f"\n** Workflow {workflow.id} started **")
+        event_stream = (
+            workflow.run_stream(message=10)
+            if latest_checkpoint is None
+            else workflow.run_stream(checkpoint_id=latest_checkpoint.checkpoint_id)
+        )
+
+        output: str | None = None
+        async for event in event_stream:
+            if isinstance(event, WorkflowOutputEvent):
+                output = event.data
+                break
+            if isinstance(event, SuperStepCompletedEvent) and random() < 0.5:
+                # Randomly simulate system interruptions
+                # The `SuperStepCompletedEvent` ensures we only interrupt after
+                # the current super-step is fully complete and checkpointed.
+                # If we interrupt mid-step, the workflow may resume from an earlier point.
+                print("\n** Simulating workflow interruption. Stopping execution. **")
+                break
+
+        # Find the latest checkpoint to resume from
+        all_checkpoints = await checkpoint_storage.list_checkpoints()
+        if not all_checkpoints:
+            raise RuntimeError("No checkpoints available to resume from.")
+        latest_checkpoint = all_checkpoints[-1]
+        print(
+            f"Checkpoint {latest_checkpoint.checkpoint_id}: "
+            f"(iter={latest_checkpoint.iteration_count}, messages={latest_checkpoint.messages})"
+        )
+
+        if output is not None:
+            print(f"\nWorkflow completed successfully with output: {output}")
+            break
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,398 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import json
+import logging
+from pathlib import Path
+from typing import cast
+
+from agent_framework import (
+    ChatAgent,
+    ChatMessage,
+    FileCheckpointStorage,
+    FunctionApprovalRequestContent,
+    HandoffBuilder,
+    HandoffUserInputRequest,
+    RequestInfoEvent,
+    Workflow,
+    WorkflowOutputEvent,
+    WorkflowStatusEvent,
+    ai_function,
+)
+from agent_framework.azure import AzureOpenAIChatClient
+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 FunctionApprovalRequestContent
+for tool calls (e.g., submit_refund).
+
+Scenario:
+1. User starts a conversation with the workflow.
+2. Agents may emit user input requests or tool approval requests.
+3. Workflow writes a checkpoint capturing pending requests and pauses.
+4. Process can exit/restart.
+5. On resume: Load the checkpoint, surface pending approvals/user prompts, and provide responses.
+6. Workflow continues from the saved state.
+
+Pattern:
+- Step 1: workflow.run_stream(checkpoint_id=...) to restore checkpoint and pending requests.
+- Step 2: workflow.send_responses_streaming(responses) to supply human replies and approvals.
+- Two-step approach is required because send_responses_streaming does not accept checkpoint_id.
+
+Prerequisites:
+- Azure CLI authentication (az login).
+- Environment variables configured for AzureOpenAIChatClient.
+"""
+
+CHECKPOINT_DIR = Path(__file__).parent / "tmp" / "handoff_checkpoints"
+CHECKPOINT_DIR.mkdir(parents=True, exist_ok=True)
+
+
+@ai_function(approval_mode="always_require")
+def submit_refund(refund_description: str, amount: str, order_id: str) -> str:
+    """Capture a refund request for manual review before processing."""
+    return f"refund recorded for order {order_id} (amount: {amount}) with details: {refund_description}"
+
+
+def create_agents(client: AzureOpenAIChatClient) -> tuple[ChatAgent, ChatAgent, ChatAgent]:
+    """Create a simple handoff scenario: triage, refund, and order specialists."""
+
+    triage = client.as_agent(
+        name="triage_agent",
+        instructions=(
+            "You are a customer service triage agent. Listen to customer issues and determine "
+            "if they need refund help or order tracking. Use handoff_to_refund_agent or "
+            "handoff_to_order_agent to transfer them."
+        ),
+    )
+
+    refund = client.as_agent(
+        name="refund_agent",
+        instructions=(
+            "You are a refund specialist. Help customers with refund requests. "
+            "Be empathetic and ask for order numbers if not provided. "
+            "When the user confirms they want a refund and supplies order details, call submit_refund "
+            "to record the request before continuing."
+        ),
+        tools=[submit_refund],
+    )
+
+    order = client.as_agent(
+        name="order_agent",
+        instructions=(
+            "You are an order tracking specialist. Help customers track their orders. "
+            "Ask for order numbers and provide shipping updates."
+        ),
+    )
+
+    return triage, refund, order
+
+
+def create_workflow(checkpoint_storage: FileCheckpointStorage) -> tuple[Workflow, ChatAgent, ChatAgent, ChatAgent]:
+    """Build the handoff workflow with checkpointing enabled."""
+
+    client = AzureOpenAIChatClient(credential=AzureCliCredential())
+    triage, refund, order = create_agents(client)
+
+    workflow = (
+        HandoffBuilder(
+            name="checkpoint_handoff_demo",
+            participants=[triage, refund, order],
+        )
+        .set_coordinator("triage_agent")
+        .with_checkpointing(checkpoint_storage)
+        .with_termination_condition(
+            # Terminate after 5 user messages for this demo
+            lambda conv: sum(1 for msg in conv if msg.role.value == "user") >= 5
+        )
+        .build()
+    )
+
+    return workflow, triage, refund, order
+
+
+def _print_handoff_request(request: HandoffUserInputRequest, request_id: str) -> None:
+    """Log pending handoff request details for debugging."""
+    print(f"\n{'=' * 60}")
+    print("WORKFLOW PAUSED - User input needed")
+    print(f"Request ID: {request_id}")
+    print(f"Awaiting agent: {request.awaiting_agent_id}")
+    print(f"Prompt: {request.prompt}")
+
+    # Note: After checkpoint restore, conversation may be empty because it's not serialized
+    # to prevent duplication (the conversation is preserved in the coordinator's state).
+    # See issue #2667.
+    if request.conversation:
+        print("\nConversation so far:")
+        for msg in request.conversation[-3:]:
+            author = msg.author_name or msg.role.value
+            snippet = msg.text[:120] + "..." if len(msg.text) > 120 else msg.text
+            print(f"  {author}: {snippet}")
+    else:
+        print("\n(Conversation restored from checkpoint - context preserved in workflow state)")
+
+    print(f"{'=' * 60}\n")
+
+
+def _print_function_approval_request(request: FunctionApprovalRequestContent, request_id: str) -> None:
+    """Log pending tool approval details for debugging."""
+    args = request.function_call.parse_arguments() or {}
+    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"Arguments:\n{json.dumps(args, indent=2)}")
+    print(f"{'=' * 60}\n")
+
+
+def _build_responses_for_requests(
+    pending_requests: list[RequestInfoEvent],
+    *,
+    user_response: str | None,
+    approve_tools: bool | None,
+) -> dict[str, object]:
+    """Create response payloads for each pending request."""
+    responses: dict[str, object] = {}
+    for request in pending_requests:
+        if isinstance(request.data, HandoffUserInputRequest):
+            if user_response is None:
+                raise ValueError("User response is required for HandoffUserInputRequest")
+            responses[request.request_id] = user_response
+        elif isinstance(request.data, FunctionApprovalRequestContent):
+            if approve_tools is None:
+                raise ValueError("Approval decision is required for FunctionApprovalRequestContent")
+            responses[request.request_id] = request.data.create_response(approved=approve_tools)
+        else:
+            raise ValueError(f"Unsupported request type: {type(request.data)}")
+    return responses
+
+
+async def run_until_user_input_needed(
+    workflow: Workflow,
+    initial_message: str | None = None,
+    checkpoint_id: str | None = None,
+) -> tuple[list[RequestInfoEvent], str | None]:
+    """
+    Run the workflow until it needs user input or approval, or completes.
+
+    Returns:
+        Tuple of (pending_requests, checkpoint_id_to_use_for_resume)
+    """
+    pending_requests: list[RequestInfoEvent] = []
+    latest_checkpoint_id: str | None = checkpoint_id
+
+    if initial_message:
+        print(f"\nStarting workflow with: {initial_message}\n")
+        event_stream = workflow.run_stream(message=initial_message)  # type: ignore[attr-defined]
+    elif checkpoint_id:
+        print(f"\nResuming workflow from checkpoint: {checkpoint_id}\n")
+        event_stream = workflow.run_stream(checkpoint_id=checkpoint_id)  # type: ignore[attr-defined]
+    else:
+        raise ValueError("Must provide either initial_message or checkpoint_id")
+
+    async for event in event_stream:
+        if isinstance(event, WorkflowStatusEvent):
+            print(f"[Status] {event.state}")
+
+        elif isinstance(event, RequestInfoEvent):
+            pending_requests.append(event)
+            if isinstance(event.data, HandoffUserInputRequest):
+                _print_handoff_request(event.data, event.request_id)
+            elif isinstance(event.data, FunctionApprovalRequestContent):
+                _print_function_approval_request(event.data, event.request_id)
+
+        elif isinstance(event, WorkflowOutputEvent):
+            print("\n[Workflow Completed]")
+            if event.data:
+                print(f"Final conversation length: {len(event.data)} messages")
+            return [], None
+
+    # Workflow paused with pending requests
+    # The latest checkpoint was created at the end of the last superstep
+    # We'll use the checkpoint storage to find it
+    return pending_requests, latest_checkpoint_id
+
+
+async def resume_with_responses(
+    workflow: Workflow,
+    checkpoint_storage: FileCheckpointStorage,
+    user_response: str | None = None,
+    approve_tools: bool | None = None,
+) -> tuple[list[RequestInfoEvent], str | None]:
+    """
+    Two-step resume pattern (answers customer questions and tool approvals):
+
+    Step 1: Restore checkpoint to load pending requests into workflow state
+    Step 2: Send user responses using send_responses_streaming
+
+    This is the current pattern required because send_responses_streaming
+    doesn't accept a checkpoint_id parameter.
+    """
+    print(f"\n{'=' * 60}")
+    print("RESUMING WORKFLOW WITH HUMAN INPUT")
+    if user_response is not None:
+        print(f"User says: {user_response}")
+    if approve_tools is not None:
+        print(f"Approve tools: {approve_tools}")
+    print(f"{'=' * 60}\n")
+
+    # Get the latest checkpoint
+    checkpoints = await checkpoint_storage.list_checkpoints()
+    if not checkpoints:
+        raise RuntimeError("No checkpoints found to resume from")
+
+    # Sort by timestamp to get latest
+    checkpoints.sort(key=lambda cp: cp.timestamp, reverse=True)
+    latest_checkpoint = checkpoints[0]
+
+    print(f"Step 1: Restoring checkpoint {latest_checkpoint.checkpoint_id}")
+
+    # Step 1: Restore the checkpoint to load pending requests into memory
+    # The checkpoint restoration re-emits pending RequestInfoEvents
+    restored_requests: list[RequestInfoEvent] = []
+    async for event in workflow.run_stream(checkpoint_id=latest_checkpoint.checkpoint_id):  # type: ignore[attr-defined]
+        if isinstance(event, RequestInfoEvent):
+            restored_requests.append(event)
+            if isinstance(event.data, HandoffUserInputRequest):
+                _print_handoff_request(event.data, event.request_id)
+            elif isinstance(event.data, FunctionApprovalRequestContent):
+                _print_function_approval_request(event.data, event.request_id)
+
+    if not restored_requests:
+        raise RuntimeError("No pending requests found after checkpoint restoration")
+
+    responses = _build_responses_for_requests(
+        restored_requests,
+        user_response=user_response,
+        approve_tools=approve_tools,
+    )
+    print(f"Step 2: Sending responses for {len(responses)} request(s)")
+
+    new_pending_requests: list[RequestInfoEvent] = []
+
+    async for event in workflow.send_responses_streaming(responses):
+        if isinstance(event, WorkflowStatusEvent):
+            print(f"[Status] {event.state}")
+
+        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):
+                # Now safe to cast event.data to list[ChatMessage]
+                conversation = cast(list[ChatMessage], event.data)
+                for msg in conversation[-3:]:  # Show last 3 messages
+                    author = msg.author_name or msg.role.value
+                    text = msg.text[:100] + "..." if len(msg.text) > 100 else msg.text
+                    print(f"  {author}: {text}")
+
+        elif isinstance(event, RequestInfoEvent):
+            new_pending_requests.append(event)
+            if isinstance(event.data, HandoffUserInputRequest):
+                _print_handoff_request(event.data, event.request_id)
+            elif isinstance(event.data, FunctionApprovalRequestContent):
+                _print_function_approval_request(event.data, event.request_id)
+
+    return new_pending_requests, latest_checkpoint.checkpoint_id
+
+
+async def main() -> None:
+    """
+    Demonstrate the checkpoint-based pause/resume pattern for handoff workflows.
+
+    This sample shows:
+    1. Starting a workflow and getting a HandoffUserInputRequest
+    2. Pausing (checkpoint is saved automatically)
+    3. Resuming from checkpoint with a user response or tool approval (two-step pattern)
+    4. Continuing the conversation until completion
+    """
+
+    # Enable INFO logging to see workflow progress
+    logging.basicConfig(
+        level=logging.INFO,
+        format="[%(levelname)s] %(name)s: %(message)s",
+    )
+
+    # Clean up old checkpoints
+    for file in CHECKPOINT_DIR.glob("*.json"):
+        file.unlink()
+    for file in CHECKPOINT_DIR.glob("*.json.tmp"):
+        file.unlink()
+
+    storage = FileCheckpointStorage(storage_path=CHECKPOINT_DIR)
+    workflow, _, _, _ = create_workflow(checkpoint_storage=storage)
+
+    print("=" * 60)
+    print("HANDOFF WORKFLOW CHECKPOINT DEMO")
+    print("=" * 60)
+
+    # Scenario: User needs help with a damaged order
+    initial_request = "Hi, my order 12345 arrived damaged. I need a refund."
+
+    # Phase 1: Initial run - workflow will pause when it needs user input
+    pending_requests, _ = await run_until_user_input_needed(
+        workflow,
+        initial_message=initial_request,
+    )
+
+    if not pending_requests:
+        print("Workflow completed without needing user input")
+        return
+
+    print("\n>>> Workflow paused. You could exit the process here.")
+    print(f">>> Checkpoint was saved. Pending requests: {len(pending_requests)}")
+
+    # Scripted human input for demo purposes
+    handoff_responses = [
+        (
+            "The headphones in order 12345 arrived cracked. "
+            "Please submit the refund for $89.99 and send a replacement to my original address."
+        ),
+        "Yes, that covers the damage and refund request.",
+        "That's everything I needed for the refund.",
+        "Thanks for handling the refund.",
+    ]
+    approval_decisions = [True, True, True]
+    handoff_index = 0
+    approval_index = 0
+
+    while pending_requests:
+        print("\n>>> Simulating process restart...\n")
+        workflow_step, _, _, _ = create_workflow(checkpoint_storage=storage)
+
+        needs_user_input = any(isinstance(req.data, HandoffUserInputRequest) for req in pending_requests)
+        needs_tool_approval = any(isinstance(req.data, FunctionApprovalRequestContent) for req in pending_requests)
+
+        user_response = None
+        if needs_user_input:
+            if handoff_index < len(handoff_responses):
+                user_response = handoff_responses[handoff_index]
+                handoff_index += 1
+            else:
+                user_response = handoff_responses[-1]
+            print(f">>> Responding to handoff request with: {user_response}")
+
+        approval_response = None
+        if needs_tool_approval:
+            if approval_index < len(approval_decisions):
+                approval_response = approval_decisions[approval_index]
+                approval_index += 1
+            else:
+                approval_response = approval_decisions[-1]
+            print(">>> Approving pending tool calls from the agent.")
+
+        pending_requests, _ = await resume_with_responses(
+            workflow_step,
+            storage,
+            user_response=user_response,
+            approve_tools=approval_response,
+        )
+
+    print("\n" + "=" * 60)
+    print("DEMO COMPLETE")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,416 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import contextlib
+import json
+import uuid
+from dataclasses import dataclass, field, replace
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any, override
+
+from agent_framework import (
+    Executor,
+    FileCheckpointStorage,
+    RequestInfoEvent,
+    SubWorkflowRequestMessage,
+    SubWorkflowResponseMessage,
+    Workflow,
+    WorkflowBuilder,
+    WorkflowContext,
+    WorkflowExecutor,
+    WorkflowOutputEvent,
+    WorkflowRunState,
+    WorkflowStatusEvent,
+    handler,
+    response_handler,
+)
+
+CHECKPOINT_DIR = Path(__file__).with_suffix("").parent / "tmp" / "sub_workflow_checkpoints"
+
+"""
+Sample: Checkpointing for workflows that embed sub-workflows.
+
+This sample shows how a parent workflow that wraps a sub-workflow can:
+- run until the sub-workflow emits a human approval request
+- persist a checkpoint that captures the pending request (including complex payloads)
+- resume later, supplying the human decision directly at restore time
+
+It is intentionally similar in spirit to the orchestration checkpoint sample but
+uses ``WorkflowExecutor`` so we exercise the full parent/sub-workflow round-trip.
+"""
+
+
+def _utc_now() -> datetime:
+    return datetime.now()
+
+
+# ---------------------------------------------------------------------------
+# Messages exchanged inside the sub-workflow
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class DraftTask:
+    """Task handed from the parent to the sub-workflow writer."""
+
+    topic: str
+    due: datetime
+    iteration: int = 1
+
+
+@dataclass
+class DraftPackage:
+    """Intermediate draft produced by the sub-workflow writer."""
+
+    topic: str
+    content: str
+    iteration: int
+    created_at: datetime = field(default_factory=_utc_now)
+
+
+@dataclass
+class FinalDraft:
+    """Final deliverable returned to the parent workflow."""
+
+    topic: str
+    content: str
+    iterations: int
+    approved_at: datetime
+
+
+@dataclass
+class ReviewRequest:
+    """Human approval request surfaced via `request_info`."""
+
+    id: str = str(uuid.uuid4())
+    topic: str = ""
+    iteration: int = 1
+    draft_excerpt: str = ""
+    due_iso: str = ""
+    reviewer_guidance: list[str] = field(default_factory=list)  # type: ignore
+
+
+@dataclass
+class ReviewDecision:
+    """The review decision to be sent to downstream executors along with the original request."""
+
+    decision: str
+    original_request: ReviewRequest
+
+
+# ---------------------------------------------------------------------------
+# Sub-workflow executors
+# ---------------------------------------------------------------------------
+
+
+class DraftWriter(Executor):
+    """Produces an initial draft for the supplied topic."""
+
+    def __init__(self) -> None:
+        super().__init__(id="draft_writer")
+
+    @handler
+    async def create_draft(self, task: DraftTask, ctx: WorkflowContext[DraftPackage]) -> None:
+        draft = DraftPackage(
+            topic=task.topic,
+            content=(
+                f"Launch plan for {task.topic}.\n\n"
+                "- Outline the customer message.\n"
+                "- Highlight three differentiators.\n"
+                "- Close with a next-step CTA.\n"
+                f"(iteration {task.iteration})"
+            ),
+            iteration=task.iteration,
+        )
+        await ctx.send_message(draft, target_id="draft_review")
+
+
+class DraftReviewRouter(Executor):
+    """Turns draft packages into human approval requests."""
+
+    def __init__(self) -> None:
+        super().__init__(id="draft_review")
+
+    @handler
+    async def request_review(self, draft: DraftPackage, ctx: WorkflowContext) -> None:
+        """Request a review upon receiving a draft."""
+        excerpt = draft.content.splitlines()[0]
+        request = ReviewRequest(
+            topic=draft.topic,
+            iteration=draft.iteration,
+            draft_excerpt=excerpt,
+            due_iso=draft.created_at.isoformat(),
+            reviewer_guidance=[
+                "Ensure tone matches launch messaging",
+                "Confirm CTA is action-oriented",
+            ],
+        )
+        await ctx.request_info(request_data=request, response_type=str)
+
+    @response_handler
+    async def forward_decision(
+        self,
+        original_request: ReviewRequest,
+        decision: str,
+        ctx: WorkflowContext[ReviewDecision],
+    ) -> None:
+        """Route the decision to the next executor."""
+        await ctx.send_message(ReviewDecision(decision=decision, original_request=original_request))
+
+
+class DraftFinaliser(Executor):
+    """Applies the human decision and emits the final draft."""
+
+    def __init__(self) -> None:
+        super().__init__(id="draft_finaliser")
+
+    @handler
+    async def on_review_decision(
+        self,
+        review_decision: ReviewDecision,
+        ctx: WorkflowContext[DraftTask, FinalDraft],
+    ) -> None:
+        reply = review_decision.decision.strip().lower()
+        original = review_decision.original_request
+        topic = original.topic if original else "unknown topic"
+        iteration = original.iteration if original else 1
+
+        if reply != "approve":
+            # Loop back with a follow-up task. In a real workflow you would
+            # incorporate the human guidance; here we just increment the counter.
+            next_task = DraftTask(
+                topic=topic,
+                due=_utc_now() + timedelta(hours=1),
+                iteration=iteration + 1,
+            )
+            await ctx.send_message(next_task, target_id="draft_writer")
+            return
+
+        final = FinalDraft(
+            topic=topic,
+            content=f"Approved launch narrative for {topic} (iteration {iteration}).",
+            iterations=iteration,
+            approved_at=_utc_now(),
+        )
+        await ctx.yield_output(final)
+
+
+# ---------------------------------------------------------------------------
+# Parent workflow executors
+# ---------------------------------------------------------------------------
+
+
+class LaunchCoordinator(Executor):
+    """Owns the top-level workflow and collects the final draft."""
+
+    def __init__(self) -> None:
+        super().__init__(id="launch_coordinator")
+        # Track pending requests to match responses
+        self._pending_requests: dict[str, SubWorkflowRequestMessage] = {}
+
+    @handler
+    async def kick_off(self, topic: str, ctx: WorkflowContext[DraftTask]) -> None:
+        task = DraftTask(topic=topic, due=_utc_now() + timedelta(hours=2))
+        await ctx.send_message(task)
+
+    @handler
+    async def collect_final(self, draft: FinalDraft, ctx: WorkflowContext[None, FinalDraft]) -> None:
+        approved_at = draft.approved_at
+        normalised = draft
+        if isinstance(approved_at, str):
+            with contextlib.suppress(ValueError):
+                parsed = datetime.fromisoformat(approved_at)
+                normalised = replace(draft, approved_at=parsed)
+                approved_at = parsed
+
+        approved_display = approved_at.isoformat() if hasattr(approved_at, "isoformat") else str(approved_at)
+
+        print("\n>>> Parent workflow received approved draft:")
+        print(f"- Topic: {normalised.topic}")
+        print(f"- Iterations: {normalised.iterations}")
+        print(f"- Approved at: {approved_display}")
+        print(f"- Content: {normalised.content}\n")
+
+        await ctx.yield_output(normalised)
+
+    @handler
+    async def handler_sub_workflow_request(
+        self,
+        request: SubWorkflowRequestMessage,
+        ctx: WorkflowContext,
+    ) -> None:
+        """Handle requests from the sub-workflow.
+
+        Note that the message type must be SubWorkflowRequestMessage to intercept the request.
+        """
+        if not isinstance(request.source_event.data, ReviewRequest):
+            raise TypeError(f"Expected 'ReviewRequest', got {type(request.source_event.data)}")
+
+        # Record the request for response matching
+        review_request = request.source_event.data
+        self._pending_requests[review_request.id] = request
+
+        # Send the request without modification
+        await ctx.request_info(request_data=review_request, response_type=str)
+
+    @response_handler
+    async def handle_request_response(
+        self,
+        original_request: ReviewRequest,
+        response: str,
+        ctx: WorkflowContext[SubWorkflowResponseMessage],
+    ) -> None:
+        """Process the response and send it back to the sub-workflow.
+
+        Note that the response must be sent back using SubWorkflowResponseMessage to route
+        the response back to the sub-workflow.
+        """
+        request_message = self._pending_requests.pop(original_request.id, None)
+
+        if request_message is None:
+            raise ValueError("No matching pending request found for the resource response")
+
+        await ctx.send_message(request_message.create_response(response))
+
+    @override
+    async def on_checkpoint_save(self) -> dict[str, Any]:
+        """Capture any additional state needed for checkpointing."""
+        return {
+            "pending_requests": self._pending_requests,
+        }
+
+    @override
+    async def on_checkpoint_restore(self, state: dict[str, Any]) -> None:
+        """Restore any additional state needed from checkpointing."""
+        self._pending_requests = state.get("pending_requests", {})
+
+
+# ---------------------------------------------------------------------------
+# Workflow construction helpers
+# ---------------------------------------------------------------------------
+
+
+def build_sub_workflow() -> WorkflowExecutor:
+    """Assemble the sub-workflow used by the parent workflow executor."""
+    sub_workflow = (
+        WorkflowBuilder()
+        .register_executor(DraftWriter, name="writer")
+        .register_executor(DraftReviewRouter, name="router")
+        .register_executor(DraftFinaliser, name="finaliser")
+        .set_start_executor("writer")
+        .add_edge("writer", "router")
+        .add_edge("router", "finaliser")
+        .add_edge("finaliser", "writer")  # permits revision loops
+        .build()
+    )
+
+    return WorkflowExecutor(sub_workflow, id="launch_subworkflow")
+
+
+def build_parent_workflow(storage: FileCheckpointStorage) -> Workflow:
+    """Assemble the parent workflow that embeds the sub-workflow."""
+    return (
+        WorkflowBuilder()
+        .register_executor(LaunchCoordinator, name="coordinator")
+        .register_executor(build_sub_workflow, name="sub_executor")
+        .set_start_executor("coordinator")
+        .add_edge("coordinator", "sub_executor")
+        .add_edge("sub_executor", "coordinator")
+        .with_checkpointing(storage)
+        .build()
+    )
+
+
+async def main() -> None:
+    CHECKPOINT_DIR.mkdir(parents=True, exist_ok=True)
+    for file in CHECKPOINT_DIR.glob("*.json"):
+        file.unlink()
+
+    storage = FileCheckpointStorage(CHECKPOINT_DIR)
+
+    workflow = build_parent_workflow(storage)
+
+    print("\n=== Stage 1: run until sub-workflow requests human review ===")
+
+    request_id: str | None = None
+    async for event in workflow.run_stream("Contoso Gadget Launch"):
+        if isinstance(event, RequestInfoEvent) and request_id is None:
+            request_id = event.request_id
+            print(f"Captured review request id: {request_id}")
+        if isinstance(event, WorkflowStatusEvent) and event.state is WorkflowRunState.IDLE_WITH_PENDING_REQUESTS:
+            break
+
+    if request_id is None:
+        raise RuntimeError("Sub-workflow completed without requesting review.")
+
+    checkpoints = await storage.list_checkpoints(workflow.id)
+    if not checkpoints:
+        raise RuntimeError("No checkpoints found.")
+
+    # Print the checkpoint to show pending requests
+    # We didn't handle the request above so the request is still pending the last checkpoint
+    checkpoints.sort(key=lambda cp: cp.timestamp)
+    resume_checkpoint = checkpoints[-1]
+    print(f"Using checkpoint {resume_checkpoint.checkpoint_id} at iteration {resume_checkpoint.iteration_count}")
+
+    checkpoint_path = storage.storage_path / f"{resume_checkpoint.checkpoint_id}.json"
+    if checkpoint_path.exists():
+        checkpoint_content_dict = json.loads(checkpoint_path.read_text())
+        print(f"Pending review requests: {checkpoint_content_dict.get('pending_request_info_events', {})}")
+
+    print("\n=== Stage 2: resume from checkpoint ===")
+
+    # Rebuild fresh instances to mimic a separate process resuming
+    workflow2 = build_parent_workflow(storage)
+
+    request_info_event: RequestInfoEvent | None = None
+    async for event in workflow2.run_stream(checkpoint_id=resume_checkpoint.checkpoint_id):
+        if isinstance(event, RequestInfoEvent):
+            request_info_event = event
+
+    if request_info_event is None:
+        raise RuntimeError("No request_info_event captured.")
+
+    print("\n=== Stage 3: approve draft ==")
+
+    approval_response = "approve"
+    output_event: WorkflowOutputEvent | None = None
+    async for event in workflow2.send_responses_streaming({request_info_event.request_id: approval_response}):
+        if isinstance(event, WorkflowOutputEvent):
+            output_event = event
+
+    if output_event is None:
+        raise RuntimeError("Workflow did not complete after resume.")
+
+    output = output_event.data
+    print("\n=== Final Draft (from resumed run) ===")
+    print(output)
+
+    """"
+    Sample Output:
+
+    === Stage 1: run until sub-workflow requests human review ===
+    Captured review request id: 032c9f3a-ad1b-4a52-89be-a168d6663011
+    Using checkpoint 54f376c2-f849-44e4-9d8d-e627fd27ab96 at iteration 2
+    Pending review requests (sub executor snapshot): []
+    Pending review requests (parent executor snapshot): ['032c9f3a-ad1b-4a52-89be-a168d6663011']
+
+    === Stage 2: resume from checkpoint and approve draft ===
+
+    >>> Parent workflow received approved draft:
+    - Topic: Contoso Gadget Launch
+    - Iterations: 1
+    - Approved at: 2025-09-25T14:29:34.479164
+    - Content: Approved launch narrative for Contoso Gadget Launch (iteration 1).
+
+
+    === Final Draft (from resumed run) ===
+    FinalDraft(topic='Contoso Gadget Launch', content='Approved launch narrative for Contoso
+    Gadget Launch (iteration 1).', iterations=1, approved_at=datetime.datetime(2025, 9, 25, 14, 29, 34, 479164))
+    Coordinator stored final draft successfully.
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,163 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""
+Sample: Workflow as Agent with Checkpointing
+
+Purpose:
+This sample demonstrates how to use checkpointing with a workflow wrapped as an agent.
+It shows how to enable checkpoint storage when calling agent.run() or agent.run_stream(),
+allowing workflow execution state to be persisted and potentially resumed.
+
+What you learn:
+- How to pass checkpoint_storage to WorkflowAgent.run() and run_stream()
+- How checkpoints are created during workflow-as-agent execution
+- How to combine thread conversation history with workflow checkpointing
+- How to resume a workflow-as-agent from a checkpoint
+
+Key concepts:
+- Thread (AgentThread): Maintains conversation history across agent invocations
+- Checkpoint: Persists workflow execution state for pause/resume capability
+- These are complementary: threads track conversation, checkpoints track workflow state
+
+Prerequisites:
+- OpenAI environment variables configured for OpenAIChatClient
+"""
+
+import asyncio
+
+from agent_framework import (
+    AgentThread,
+    ChatAgent,
+    ChatMessageStore,
+    InMemoryCheckpointStorage,
+    SequentialBuilder,
+)
+from agent_framework.openai import OpenAIChatClient
+
+
+async def basic_checkpointing() -> None:
+    """Demonstrate basic checkpoint storage with workflow-as-agent."""
+    print("=" * 60)
+    print("Basic Checkpointing with Workflow as Agent")
+    print("=" * 60)
+
+    chat_client = OpenAIChatClient()
+
+    def create_assistant() -> ChatAgent:
+        return chat_client.as_agent(
+            name="assistant",
+            instructions="You are a helpful assistant. Keep responses brief.",
+        )
+
+    def create_reviewer() -> ChatAgent:
+        return chat_client.as_agent(
+            name="reviewer",
+            instructions="You are a reviewer. Provide a one-sentence summary of the assistant's response.",
+        )
+
+    # Build sequential workflow with participant factories
+    workflow = SequentialBuilder().register_participants([create_assistant, create_reviewer]).build()
+    agent = workflow.as_agent(name="CheckpointedAgent")
+
+    # Create checkpoint storage
+    checkpoint_storage = InMemoryCheckpointStorage()
+
+    # Run with checkpointing enabled
+    query = "What are the benefits of renewable energy?"
+    print(f"\nUser: {query}")
+
+    response = await agent.run(query, checkpoint_storage=checkpoint_storage)
+
+    for msg in response.messages:
+        speaker = msg.author_name or msg.role.value
+        print(f"[{speaker}]: {msg.text}")
+
+    # Show checkpoints that were created
+    checkpoints = await checkpoint_storage.list_checkpoints(workflow.id)
+    print(f"\nCheckpoints created: {len(checkpoints)}")
+    for i, cp in enumerate(checkpoints[:5], 1):
+        print(f"  {i}. {cp.checkpoint_id}")
+
+
+async def checkpointing_with_thread() -> None:
+    """Demonstrate combining thread history with checkpointing."""
+    print("\n" + "=" * 60)
+    print("Checkpointing with Thread Conversation History")
+    print("=" * 60)
+
+    chat_client = OpenAIChatClient()
+
+    def create_assistant() -> ChatAgent:
+        return chat_client.as_agent(
+            name="memory_assistant",
+            instructions="You are a helpful assistant with good memory. Reference previous conversation when relevant.",
+        )
+
+    workflow = SequentialBuilder().register_participants([create_assistant]).build()
+    agent = workflow.as_agent(name="MemoryAgent")
+
+    # Create both thread (for conversation) and checkpoint storage (for workflow state)
+    thread = AgentThread(message_store=ChatMessageStore())
+    checkpoint_storage = InMemoryCheckpointStorage()
+
+    # First turn
+    query1 = "My favorite color is blue. Remember that."
+    print(f"\n[Turn 1] User: {query1}")
+    response1 = await agent.run(query1, thread=thread, checkpoint_storage=checkpoint_storage)
+    if response1.messages:
+        print(f"[assistant]: {response1.messages[0].text}")
+
+    # Second turn - agent should remember from thread history
+    query2 = "What's my favorite color?"
+    print(f"\n[Turn 2] User: {query2}")
+    response2 = await agent.run(query2, thread=thread, checkpoint_storage=checkpoint_storage)
+    if response2.messages:
+        print(f"[assistant]: {response2.messages[0].text}")
+
+    # Show accumulated state
+    checkpoints = await checkpoint_storage.list_checkpoints(workflow.id)
+    print(f"\nTotal checkpoints across both turns: {len(checkpoints)}")
+
+    if thread.message_store:
+        history = await thread.message_store.list_messages()
+        print(f"Messages in thread history: {len(history)}")
+
+
+async def streaming_with_checkpoints() -> None:
+    """Demonstrate streaming with checkpoint storage."""
+    print("\n" + "=" * 60)
+    print("Streaming with Checkpointing")
+    print("=" * 60)
+
+    chat_client = OpenAIChatClient()
+
+    def create_assistant() -> ChatAgent:
+        return chat_client.as_agent(
+            name="streaming_assistant",
+            instructions="You are a helpful assistant.",
+        )
+
+    workflow = SequentialBuilder().register_participants([create_assistant]).build()
+    agent = workflow.as_agent(name="StreamingCheckpointAgent")
+
+    checkpoint_storage = InMemoryCheckpointStorage()
+
+    query = "List three interesting facts about the ocean."
+    print(f"\nUser: {query}")
+    print("[assistant]: ", end="", flush=True)
+
+    # Stream with checkpointing
+    async for update in agent.run_stream(query, checkpoint_storage=checkpoint_storage):
+        if update.text:
+            print(update.text, end="", flush=True)
+
+    print()  # Newline after streaming
+
+    checkpoints = await checkpoint_storage.list_checkpoints(workflow.id)
+    print(f"\nCheckpoints created during stream: {len(checkpoints)}")
+
+
+if __name__ == "__main__":
+    asyncio.run(basic_checkpointing())
+    asyncio.run(checkpointing_with_thread())
+    asyncio.run(streaming_with_checkpoints())

python/samples/getting_started/workflows/composition/sub_workflow_basics.py

@@ -0,0 +1,211 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from dataclasses import dataclass
+from typing import Any
+
+from agent_framework import (
+    Executor,
+    WorkflowBuilder,
+    WorkflowContext,
+    WorkflowExecutor,
+    handler,
+)
+from typing_extensions import Never
+ 
+"""
+Sample: Sub-Workflows (Basics)
+
+What it does:
+- Shows how a parent workflow invokes a sub-workflow via `WorkflowExecutor` and collects results.
+- Example: parent orchestrates multiple text processors that count words/characters.
+- Demonstrates how sub-workflows complete by yielding outputs when processing is done.
+
+Prerequisites:
+- No external services required.
+"""
+
+
+# Message types
+@dataclass
+class TextProcessingRequest:
+    """Request to process a text string."""
+
+    text: str
+    task_id: str
+
+
+@dataclass
+class TextProcessingResult:
+    """Result of text processing."""
+
+    task_id: str
+    text: str
+    word_count: int
+    char_count: int
+
+
+# Sub-workflow executor
+class TextProcessor(Executor):
+    """Processes text strings - counts words and characters."""
+
+    def __init__(self):
+        super().__init__(id="text_processor")
+
+    @handler
+    async def process_text(
+        self, request: TextProcessingRequest, ctx: WorkflowContext[Never, TextProcessingResult]
+    ) -> None:
+        """Process a text string and return statistics."""
+        text_preview = f"'{request.text[:50]}{'...' if len(request.text) > 50 else ''}'"
+        print(f"🔍 Sub-workflow processing text (Task {request.task_id}): {text_preview}")
+
+        # Simple text processing
+        word_count = len(request.text.split()) if request.text.strip() else 0
+        char_count = len(request.text)
+
+        print(f"📊 Task {request.task_id}: {word_count} words, {char_count} characters")
+
+        # Create result
+        result = TextProcessingResult(
+            task_id=request.task_id,
+            text=request.text,
+            word_count=word_count,
+            char_count=char_count,
+        )
+
+        print(f"✅ Sub-workflow completed task {request.task_id}")
+        # Signal completion by yielding the result
+        await ctx.yield_output(result)
+
+
+# Parent workflow
+class TextProcessingOrchestrator(Executor):
+    """Orchestrates multiple text processing tasks using sub-workflows."""
+
+    results: list[TextProcessingResult] = []
+    expected_count: int = 0
+
+    def __init__(self):
+        super().__init__(id="text_orchestrator")
+
+    @handler
+    async def start_processing(self, texts: list[str], ctx: WorkflowContext[TextProcessingRequest]) -> None:
+        """Start processing multiple text strings."""
+        print(f"📄 Starting processing of {len(texts)} text strings")
+        print("=" * 60)
+
+        self.expected_count = len(texts)
+
+        # Send each text to a sub-workflow
+        for i, text in enumerate(texts):
+            task_id = f"task_{i + 1}"
+            request = TextProcessingRequest(text=text, task_id=task_id)
+            print(f"📤 Dispatching {task_id} to sub-workflow")
+            await ctx.send_message(request, target_id="text_processor_workflow")
+
+    @handler
+    async def collect_result(
+        self,
+        result: TextProcessingResult,
+        ctx: WorkflowContext[Never, list[TextProcessingResult]],
+    ) -> None:
+        """Collect results from sub-workflows."""
+        print(f"📥 Collected result from {result.task_id}")
+        self.results.append(result)
+
+        # Check if all results are collected
+        if len(self.results) == self.expected_count:
+            print("\n🎉 All tasks completed!")
+            await ctx.yield_output(self.results)
+
+
+def get_result_summary(results: list[TextProcessingResult]) -> dict[str, Any]:
+    """Get a summary of all processing results."""
+    total_words = sum(result.word_count for result in results)
+    total_chars = sum(result.char_count for result in results)
+    avg_words = total_words / len(results) if results else 0
+    avg_chars = total_chars / len(results) if results else 0
+
+    return {
+        "total_texts": len(results),
+        "total_words": total_words,
+        "total_characters": total_chars,
+        "average_words_per_text": round(avg_words, 2),
+        "average_characters_per_text": round(avg_chars, 2),
+    }
+
+
+def create_sub_workflow() -> WorkflowExecutor:
+    """Create the text processing sub-workflow."""
+    print("🚀 Setting up sub-workflow...")
+
+    processing_workflow = (
+        WorkflowBuilder()
+        .register_executor(TextProcessor, name="text_processor")
+        .set_start_executor("text_processor")
+        .build()
+    )
+
+    return WorkflowExecutor(processing_workflow, id="text_processor_workflow")
+
+
+async def main():
+    """Main function to run the basic sub-workflow example."""
+    print("🔧 Setting up parent workflow...")
+    # Step 1: Create the parent workflow
+    main_workflow = (
+        WorkflowBuilder()
+        .register_executor(TextProcessingOrchestrator, name="text_orchestrator")
+        .register_executor(create_sub_workflow, name="text_processor_workflow")
+        .set_start_executor("text_orchestrator")
+        .add_edge("text_orchestrator", "text_processor_workflow")
+        .add_edge("text_processor_workflow", "text_orchestrator")
+        .build()
+    )
+
+    # Step 2: Test data - various text strings
+    test_texts = [
+        "Hello world! This is a simple test.",
+        "Python is a powerful programming language used for many applications.",
+        "Short text.",
+        "This is a longer text with multiple sentences. It contains more words and characters. We use it to test our text processing workflow.",  # noqa: E501
+        "",  # Empty string
+        "   Spaces   around   text   ",
+    ]
+
+    print(f"\n🧪 Testing with {len(test_texts)} text strings")
+    print("=" * 60)
+
+    # Step 3: Run the workflow
+    result = await main_workflow.run(test_texts)
+
+    # Step 4: Display results
+    print("\n📊 Processing Results:")
+    print("=" * 60)
+
+    # Sort results by task_id for consistent display
+    task_results = result.get_outputs()
+    assert len(task_results) == 1
+    sorted_results = sorted(task_results[0], key=lambda r: r.task_id)
+
+    for result in sorted_results:
+        preview = result.text[:30] + "..." if len(result.text) > 30 else result.text
+        preview = preview.replace("\n", " ").strip() or "(empty)"
+        print(f"✅ {result.task_id}: '{preview}' -> {result.word_count} words, {result.char_count} chars")
+
+    # Step 6: Display summary
+    summary = get_result_summary(sorted_results)
+    print("\n📈 Summary:")
+    print("=" * 60)
+    print(f"📄 Total texts processed: {summary['total_texts']}")
+    print(f"📝 Total words: {summary['total_words']}")
+    print(f"🔤 Total characters: {summary['total_characters']}")
+    print(f"📊 Average words per text: {summary['average_words_per_text']}")
+    print(f"📏 Average characters per text: {summary['average_characters_per_text']}")
+
+    print("\n🏁 Processing complete!")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/workflows/composition/sub_workflow_kwargs.py

@@ -0,0 +1,143 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import json
+from typing import Annotated, Any
+
+from agent_framework import (
+    ChatMessage,
+    SequentialBuilder,
+    WorkflowExecutor,
+    WorkflowOutputEvent,
+    ai_function,
+)
+from agent_framework.openai import OpenAIChatClient
+
+"""
+Sample: Sub-Workflow kwargs Propagation
+
+This sample demonstrates how custom context (kwargs) flows from a parent workflow
+through to agents in sub-workflows. When you pass kwargs to the parent workflow's
+run_stream() or run(), they automatically propagate to nested sub-workflows.
+
+Key Concepts:
+- kwargs passed to parent workflow.run_stream() propagate to sub-workflows
+- Sub-workflow agents receive the same kwargs as the parent workflow
+- Works with nested WorkflowExecutor compositions at any depth
+- Useful for passing authentication tokens, configuration, or request context
+
+Prerequisites:
+- OpenAI environment variables configured
+"""
+
+
+# Define tools that access custom context via **kwargs
+@ai_function
+def get_authenticated_data(
+    resource: Annotated[str, "The resource to fetch"],
+    **kwargs: Any,
+) -> str:
+    """Fetch data using the authenticated user context from kwargs."""
+    user_token = kwargs.get("user_token", {})
+    user_name = user_token.get("user_name", "anonymous")
+    access_level = user_token.get("access_level", "none")
+
+    print(f"\n[get_authenticated_data] kwargs keys: {list(kwargs.keys())}")
+    print(f"[get_authenticated_data] User: {user_name}, Access: {access_level}")
+
+    return f"Fetched '{resource}' for user {user_name} ({access_level} access)"
+
+
+@ai_function
+def call_configured_service(
+    service_name: Annotated[str, "Name of the service to call"],
+    **kwargs: Any,
+) -> str:
+    """Call a service using configuration from kwargs."""
+    config = kwargs.get("service_config", {})
+    services = config.get("services", {})
+
+    print(f"\n[call_configured_service] kwargs keys: {list(kwargs.keys())}")
+    print(f"[call_configured_service] Available services: {list(services.keys())}")
+
+    if service_name in services:
+        endpoint = services[service_name]
+        return f"Called service '{service_name}' at {endpoint}"
+    return f"Service '{service_name}' not found in configuration"
+
+
+async def main() -> None:
+    print("=" * 70)
+    print("Sub-Workflow kwargs Propagation Demo")
+    print("=" * 70)
+
+    # Create chat client
+    chat_client = OpenAIChatClient()
+
+    # Create an agent with tools that use kwargs
+    inner_agent = chat_client.as_agent(
+        name="data_agent",
+        instructions=(
+            "You are a data access agent. Use the available tools to help users. "
+            "When asked to fetch data, use get_authenticated_data. "
+            "When asked to call a service, use call_configured_service."
+        ),
+        tools=[get_authenticated_data, call_configured_service],
+    )
+
+    # Build the inner (sub) workflow with the agent
+    inner_workflow = SequentialBuilder().participants([inner_agent]).build()
+
+    # Wrap the inner workflow in a WorkflowExecutor to use it as a sub-workflow
+    subworkflow_executor = WorkflowExecutor(
+        workflow=inner_workflow,
+        id="data_subworkflow",
+    )
+
+    # Build the outer (parent) workflow containing the sub-workflow
+    outer_workflow = SequentialBuilder().participants([subworkflow_executor]).build()
+
+    # Define custom context that will flow through to the sub-workflow's agent
+    user_token = {
+        "user_name": "alice@contoso.com",
+        "access_level": "admin",
+        "session_id": "sess_12345",
+    }
+
+    service_config = {
+        "services": {
+            "users": "https://api.example.com/v1/users",
+            "orders": "https://api.example.com/v1/orders",
+            "inventory": "https://api.example.com/v1/inventory",
+        },
+        "timeout": 30,
+    }
+
+    print("\nContext being passed to parent workflow:")
+    print(f"  user_token: {json.dumps(user_token, indent=4)}")
+    print(f"  service_config: {json.dumps(service_config, indent=4)}")
+    print("\n" + "-" * 70)
+    print("Workflow Execution (kwargs flow: parent -> sub-workflow -> agent -> tool):")
+    print("-" * 70)
+
+    # Run the OUTER workflow with kwargs
+    # These kwargs will automatically propagate to the inner sub-workflow
+    async for event in outer_workflow.run_stream(
+        "Please fetch my profile data and then call the users service.",
+        user_token=user_token,
+        service_config=service_config,
+    ):
+        if isinstance(event, WorkflowOutputEvent):
+            output_data = event.data
+            if isinstance(output_data, list):
+                for item in output_data:  # type: ignore
+                    if isinstance(item, ChatMessage) and item.text:
+                        print(f"\n[Final Answer]: {item.text}")
+
+    print("\n" + "=" * 70)
+    print("Sample Complete - kwargs successfully flowed through sub-workflow!")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/workflows/composition/sub_workflow_parallel_requests.py

@@ -0,0 +1,362 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import uuid
+from dataclasses import dataclass
+from typing import Literal
+
+from agent_framework import (
+    Executor,
+    RequestInfoEvent,
+    SubWorkflowRequestMessage,
+    SubWorkflowResponseMessage,
+    Workflow,
+    WorkflowBuilder,
+    WorkflowContext,
+    WorkflowExecutor,
+    handler,
+    response_handler,
+)
+from typing_extensions import Never
+
+"""
+This sample demonstrates how to handle multiple parallel requests from a sub-workflow to
+different executors in the main workflow.
+
+Prerequisite:
+- Understanding of sub-workflows.
+- Understanding of requests and responses.
+
+This pattern is useful when a sub-workflow needs to interact with multiple external systems
+or services.
+
+This sample implements a resource request distribution system where:
+1. A sub-workflow generates requests for computing resources and policy checks.
+2. The main workflow has executors that handle resource allocation and policy checking.
+3. Responses are routed back to the sub-workflow, which collects and processes them.
+
+The sub-workflow sends two types of requests:
+- ResourceRequest: Requests for computing resources (e.g., CPU, memory).
+- PolicyRequest: Requests to check resource allocation policies.
+
+The main workflow contains:
+- ResourceAllocator: Simulates a system that allocates computing resources.
+- PolicyEngine: Simulates a policy engine that approves or denies resource requests.
+"""
+
+
+@dataclass
+class ComputingResourceRequest:
+    """Request for computing resources."""
+
+    request_type: Literal["resource", "policy"]
+    resource_type: Literal["cpu", "memory", "disk", "gpu"]
+    amount: int
+    priority: Literal["low", "normal", "high"] | None = None
+    policy_type: Literal["quota", "security"] | None = None
+
+
+@dataclass
+class ResourceResponse:
+    """Response with allocated resources."""
+
+    resource_type: str
+    allocated: int
+    source: str  # Which system provided the resources
+
+
+@dataclass
+class PolicyResponse:
+    """Response from policy check."""
+
+    approved: bool
+    reason: str
+
+
+@dataclass
+class ResourceRequest:
+    """Request for computing resources."""
+
+    resource_type: Literal["cpu", "memory", "disk", "gpu"]
+    amount: int
+    priority: Literal["low", "normal", "high"]
+    id: str = str(uuid.uuid4())
+
+
+@dataclass
+class PolicyRequest:
+    """Request to check resource allocation policy."""
+
+    policy_type: Literal["quota", "security"]
+    resource_type: Literal["cpu", "memory", "disk", "gpu"]
+    amount: int
+    id: str = str(uuid.uuid4())
+
+
+def build_resource_request_distribution_workflow() -> Workflow:
+    class RequestDistribution(Executor):
+        """Distributes computing resource requests to appropriate executors."""
+
+        @handler
+        async def distribute_requests(
+            self,
+            requests: list[ComputingResourceRequest],
+            ctx: WorkflowContext[ResourceRequest | PolicyRequest | int],
+        ) -> None:
+            for req in requests:
+                if req.request_type == "resource":
+                    if req.priority is None:
+                        raise ValueError("Priority must be set for resource requests")
+                    await ctx.send_message(ResourceRequest(req.resource_type, req.amount, req.priority))
+                elif req.request_type == "policy":
+                    if req.policy_type is None:
+                        raise ValueError("Policy type must be set for policy requests")
+                    await ctx.send_message(PolicyRequest(req.policy_type, req.resource_type, req.amount))
+                else:
+                    raise ValueError(f"Unknown request type: {req.request_type}")
+            # Notify the collector about the number of requests sent
+            await ctx.send_message(len(requests))
+
+    class ResourceRequester(Executor):
+        """Handles resource allocation requests."""
+
+        @handler
+        async def run(self, request: ResourceRequest, ctx: WorkflowContext) -> None:
+            await ctx.request_info(request_data=request, response_type=ResourceResponse)
+
+        @response_handler
+        async def handle_response(
+            self, original_request: ResourceRequest, response: ResourceResponse, ctx: WorkflowContext[ResourceResponse]
+        ) -> None:
+            print(f"Resource allocated: {response.allocated} {response.resource_type} from {response.source}")
+            await ctx.send_message(response)
+
+    class PolicyChecker(Executor):
+        """Handles policy check requests."""
+
+        @handler
+        async def run(self, request: PolicyRequest, ctx: WorkflowContext) -> None:
+            await ctx.request_info(request_data=request, response_type=PolicyResponse)
+
+        @response_handler
+        async def handle_response(
+            self, original_request: PolicyRequest, response: PolicyResponse, ctx: WorkflowContext[PolicyResponse]
+        ) -> None:
+            print(f"Policy check result: {response.approved} - {response.reason}")
+            await ctx.send_message(response)
+
+    class ResultCollector(Executor):
+        """Collects and processes all responses."""
+
+        def __init__(self, id: str) -> None:
+            super().__init__(id)
+            self._request_count = 0
+            self._responses: list[ResourceResponse | PolicyResponse] = []
+
+        @handler
+        async def set_request_count(self, count: int, ctx: WorkflowContext) -> None:
+            if count <= 0:
+                raise ValueError("Request count must be positive")
+            self._request_count = count
+
+        @handler
+        async def collect(self, response: ResourceResponse | PolicyResponse, ctx: WorkflowContext[Never, str]) -> None:
+            self._responses.append(response)
+            print(f"Collected {len(self._responses)}/{self._request_count} responses")
+            if len(self._responses) == self._request_count:
+                # All responses received, process them
+                await ctx.yield_output(f"All {self._request_count} requests processed.")
+            elif len(self._responses) > self._request_count:
+                raise ValueError("Received more responses than expected")
+
+    return (
+        WorkflowBuilder()
+        .register_executor(lambda: RequestDistribution("orchestrator"), name="orchestrator")
+        .register_executor(lambda: ResourceRequester("resource_requester"), name="resource_requester")
+        .register_executor(lambda: PolicyChecker("policy_checker"), name="policy_checker")
+        .register_executor(lambda: ResultCollector("result_collector"), name="result_collector")
+        .set_start_executor("orchestrator")
+        .add_edge("orchestrator", "resource_requester")
+        .add_edge("orchestrator", "policy_checker")
+        .add_edge("resource_requester", "result_collector")
+        .add_edge("policy_checker", "result_collector")
+        .add_edge("orchestrator", "result_collector")  # For request count
+        .build()
+    )
+
+
+class ResourceAllocator(Executor):
+    """Simulates a system that allocates computing resources."""
+
+    def __init__(self, id: str) -> None:
+        super().__init__(id)
+        self._cache: dict[str, int] = {"cpu": 10, "memory": 50, "disk": 100}
+        # Record pending requests to match responses
+        self._pending_requests: dict[str, RequestInfoEvent] = {}
+
+    async def _handle_resource_request(self, request: ResourceRequest) -> ResourceResponse | None:
+        """Allocates resources based on request and available cache."""
+        available = self._cache.get(request.resource_type, 0)
+        if available >= request.amount:
+            self._cache[request.resource_type] -= request.amount
+            return ResourceResponse(request.resource_type, request.amount, "cache")
+        return None
+
+    @handler
+    async def handle_subworkflow_request(
+        self, request: SubWorkflowRequestMessage, ctx: WorkflowContext[SubWorkflowResponseMessage]
+    ) -> None:
+        """Handles requests from sub-workflows."""
+        source_event: RequestInfoEvent = request.source_event
+        if not isinstance(source_event.data, ResourceRequest):
+            return
+
+        request_payload: ResourceRequest = source_event.data
+        response = await self._handle_resource_request(request_payload)
+        if response:
+            await ctx.send_message(request.create_response(response))
+        else:
+            # Request cannot be fulfilled via cache, forward the request to external
+            self._pending_requests[request_payload.id] = source_event
+            await ctx.request_info(request_data=request_payload, response_type=ResourceResponse)
+
+    @response_handler
+    async def handle_external_response(
+        self,
+        original_request: ResourceRequest,
+        response: ResourceResponse,
+        ctx: WorkflowContext[SubWorkflowResponseMessage],
+    ) -> None:
+        """Handles responses from external systems and routes them to the sub-workflow."""
+        print(f"External resource allocated: {response.allocated} {response.resource_type} from {response.source}")
+        source_event = self._pending_requests.pop(original_request.id, None)
+        if source_event is None:
+            raise ValueError("No matching pending request found for the resource response")
+        await ctx.send_message(SubWorkflowResponseMessage(data=response, source_event=source_event))
+
+
+class PolicyEngine(Executor):
+    """Simulates a policy engine that approves or denies resource requests."""
+
+    def __init__(self, id: str) -> None:
+        super().__init__(id)
+        self._quota: dict[str, int] = {
+            "cpu": 5,  # Only allow up to 5 CPU units
+            "memory": 20,  # Only allow up to 20 memory units
+            "disk": 1000,  # Liberal disk policy
+        }
+        # Record pending requests to match responses
+        self._pending_requests: dict[str, RequestInfoEvent] = {}
+
+    @handler
+    async def handle_subworkflow_request(
+        self, request: SubWorkflowRequestMessage, ctx: WorkflowContext[SubWorkflowResponseMessage]
+    ) -> None:
+        """Handles requests from sub-workflows."""
+        source_event: RequestInfoEvent = request.source_event
+        if not isinstance(source_event.data, PolicyRequest):
+            return
+
+        request_payload: PolicyRequest = source_event.data
+        # Simple policy logic for demonstration
+        if request_payload.policy_type == "quota":
+            allowed_amount = self._quota.get(request_payload.resource_type, 0)
+            if request_payload.amount <= allowed_amount:
+                response = PolicyResponse(True, "Within quota limits")
+            else:
+                response = PolicyResponse(False, "Exceeds quota limits")
+            await ctx.send_message(request.create_response(response))
+        else:
+            # For other policy types, forward to external system
+            self._pending_requests[request_payload.id] = source_event
+            await ctx.request_info(request_data=request_payload, response_type=PolicyResponse)
+
+    @response_handler
+    async def handle_external_response(
+        self,
+        original_request: PolicyRequest,
+        response: PolicyResponse,
+        ctx: WorkflowContext[SubWorkflowResponseMessage],
+    ) -> None:
+        """Handles responses from external systems and routes them to the sub-workflow."""
+        print(f"External policy check result: {response.approved} - {response.reason}")
+        source_event = self._pending_requests.pop(original_request.id, None)
+        if source_event is None:
+            raise ValueError("No matching pending request found for the policy response")
+        await ctx.send_message(SubWorkflowResponseMessage(data=response, source_event=source_event))
+
+
+async def main() -> None:
+    # Build the main workflow
+    main_workflow = (
+        WorkflowBuilder()
+        .register_executor(lambda: ResourceAllocator("resource_allocator"), name="resource_allocator")
+        .register_executor(lambda: PolicyEngine("policy_engine"), name="policy_engine")
+        .register_executor(
+            lambda: WorkflowExecutor(
+                build_resource_request_distribution_workflow(),
+                "sub_workflow_executor",
+                # Setting allow_direct_output=True to let the sub-workflow output directly.
+                # This is because the sub-workflow is the both the entry point and the exit
+                # point of the main workflow.
+                allow_direct_output=True,
+            ),
+            name="sub_workflow_executor",
+        )
+        .set_start_executor("sub_workflow_executor")
+        .add_edge("sub_workflow_executor", "resource_allocator")
+        .add_edge("resource_allocator", "sub_workflow_executor")
+        .add_edge("sub_workflow_executor", "policy_engine")
+        .add_edge("policy_engine", "sub_workflow_executor")
+        .build()
+    )
+
+    # Test requests
+    test_requests = [
+        ComputingResourceRequest("resource", "cpu", 2, priority="normal"),  # cache hit
+        ComputingResourceRequest("policy", "cpu", 3, policy_type="quota"),  # policy hit
+        ComputingResourceRequest("resource", "memory", 15, priority="normal"),  # cache hit
+        ComputingResourceRequest("policy", "memory", 100, policy_type="quota"),  # policy miss -> external
+        ComputingResourceRequest("resource", "gpu", 1, priority="high"),  # cache miss -> external
+        ComputingResourceRequest("policy", "disk", 500, policy_type="quota"),  # policy hit
+        ComputingResourceRequest("policy", "cpu", 1, policy_type="security"),  # unknown policy -> external
+    ]
+
+    # Run the workflow
+    print(f"🧪 Testing with {len(test_requests)} mixed requests.")
+    print("🚀 Starting main workflow...")
+    run_result = await main_workflow.run(test_requests)
+
+    # Handle request info events
+    request_info_events = run_result.get_request_info_events()
+    if request_info_events:
+        print(f"\n🔍 Handling {len(request_info_events)} request info events...\n")
+
+        responses: dict[str, ResourceResponse | PolicyResponse] = {}
+        for event in request_info_events:
+            if isinstance(event.data, ResourceRequest):
+                # Simulate external resource allocation
+                resource_response = ResourceResponse(
+                    resource_type=event.data.resource_type, allocated=event.data.amount, source="external_provider"
+                )
+                responses[event.request_id] = resource_response
+            elif isinstance(event.data, PolicyRequest):
+                # Simulate external policy check
+                response = PolicyResponse(True, "External system approved")
+                responses[event.request_id] = response
+            else:
+                print(f"Unknown request info event data type: {type(event.data)}")
+
+        run_result = await main_workflow.send_responses(responses)
+
+    outputs = run_result.get_outputs()
+    if outputs:
+        print("\nWorkflow completed with outputs:")
+        for output in outputs:
+            print(f"- {output}")
+    else:
+        raise RuntimeError("Workflow did not produce an output.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/workflows/composition/sub_workflow_request_interception.py

@@ -0,0 +1,311 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from dataclasses import dataclass
+
+from agent_framework import (
+    Executor,
+    SubWorkflowRequestMessage,
+    SubWorkflowResponseMessage,
+    Workflow,
+    WorkflowBuilder,
+    WorkflowContext,
+    WorkflowExecutor,
+    WorkflowOutputEvent,
+    handler,
+    response_handler,
+)
+from typing_extensions import Never
+
+"""
+This sample demonstrates how to handle request from the sub-workflow in the main workflow.
+
+Prerequisite:
+- Understanding of sub-workflows.
+- Understanding of requests and responses.
+
+This pattern is useful when you want to reuse a workflow that makes requests to an external system,
+but you want to intercept those requests in the main workflow and handle them without further propagation
+to the external system.
+
+This sample implements a smart email delivery system that validates email addresses before sending emails.
+1. We will start by creating a workflow that validates email addresses in a sequential manner. The validation
+   consists of three steps: sanitization, format validation, and domain validation. The domain validation
+   step will involve checking if the email domain is valid by making a request to an external system.
+2. Then we will create a main workflow that uses the email validation workflow as a sub-workflow. The main
+    workflow will intercept the domain validation requests from the sub-workflow and handle them internally
+    without propagating them to an external system.
+3. Once the email address is validated, the main workflow will proceed to send the email if the address is valid,
+   or block the email if the address is invalid.
+"""
+
+
+@dataclass
+class SanitizedEmailResult:
+    """Result of email sanitization and validation.
+
+    The properties get built up as the email address goes through
+    the validation steps in the workflow.
+    """
+
+    original: str
+    sanitized: str
+    is_valid: bool
+
+
+def build_email_address_validation_workflow() -> Workflow:
+    """Build an email address validation workflow.
+
+    This workflow consists of three steps (each is represented by an executor):
+    1. Sanitize the email address, such as removing leading/trailing spaces.
+    2. Validate the email address format, such as checking for "@" and domain.
+    3. Extract the domain from the email address and request domain validation,
+       after which it completes with the final result.
+    """
+
+    class EmailSanitizer(Executor):
+        """Sanitize email address by trimming spaces."""
+
+        @handler
+        async def handle(self, email_address: str, ctx: WorkflowContext[SanitizedEmailResult]) -> None:
+            """Trim leading and trailing spaces from the email address.
+
+            This executor doesn't produce any workflow output, but sends the sanitized
+            email address to the next executor in the workflow.
+            """
+            sanitized = email_address.strip()
+            print(f"✂️ Sanitized email address: '{sanitized}'")
+            await ctx.send_message(SanitizedEmailResult(original=email_address, sanitized=sanitized, is_valid=False))
+
+    class EmailFormatValidator(Executor):
+        """Validate email address format."""
+
+        @handler
+        async def handle(
+            self,
+            partial_result: SanitizedEmailResult,
+            ctx: WorkflowContext[SanitizedEmailResult, SanitizedEmailResult],
+        ) -> None:
+            """Validate the email address format.
+
+            This executor can potentially produce a workflow output (False if the format is invalid).
+            When the format is valid, it sends the validated email address to the next executor in the workflow.
+            """
+            if "@" not in partial_result.sanitized or "." not in partial_result.sanitized.split("@")[-1]:
+                print(f"❌ Invalid email format: '{partial_result.sanitized}'")
+                await ctx.yield_output(
+                    SanitizedEmailResult(
+                        original=partial_result.original, sanitized=partial_result.sanitized, is_valid=False
+                    )
+                )
+                return
+            print(f"✅ Validated email format: '{partial_result.sanitized}'")
+            await ctx.send_message(
+                SanitizedEmailResult(
+                    original=partial_result.original, sanitized=partial_result.sanitized, is_valid=False
+                )
+            )
+
+    class DomainValidator(Executor):
+        """Validate email domain."""
+
+        def __init__(self, id: str):
+            super().__init__(id=id)
+            self._pending_domains: dict[str, SanitizedEmailResult] = {}
+
+        @handler
+        async def handle(self, partial_result: SanitizedEmailResult, ctx: WorkflowContext) -> None:
+            """Extract the domain from the email address and request domain validation.
+
+            This executor doesn't produce any workflow output, but sends a domain validation request
+            to an external system to user for validation.
+            """
+            domain = partial_result.sanitized.split("@")[-1]
+            print(f"🔍 Validating domain: '{domain}'")
+            self._pending_domains[domain] = partial_result
+            # Send a request to the external system via the request_info mechanism
+            await ctx.request_info(request_data=domain, response_type=bool)
+
+        @response_handler
+        async def handle_domain_validation_response(
+            self, original_request: str, is_valid: bool, ctx: WorkflowContext[Never, SanitizedEmailResult]
+        ) -> None:
+            """Handle the domain validation response.
+
+            This method receives the response from the external system and yields the final
+            validation result (True if both format and domain are valid, False otherwise).
+            """
+            if original_request not in self._pending_domains:
+                raise ValueError(f"Received response for unknown domain: '{original_request}'")
+            partial_result = self._pending_domains.pop(original_request)
+            if is_valid:
+                print(f"✅ Domain '{original_request}' is valid.")
+                await ctx.yield_output(
+                    SanitizedEmailResult(
+                        original=partial_result.original, sanitized=partial_result.sanitized, is_valid=True
+                    )
+                )
+            else:
+                print(f"❌ Domain '{original_request}' is invalid.")
+                await ctx.yield_output(
+                    SanitizedEmailResult(
+                        original=partial_result.original, sanitized=partial_result.sanitized, is_valid=False
+                    )
+                )
+
+    # Build the workflow
+    return (
+        WorkflowBuilder()
+        .register_executor(lambda: EmailSanitizer(id="email_sanitizer"), name="email_sanitizer")
+        .register_executor(lambda: EmailFormatValidator(id="email_format_validator"), name="email_format_validator")
+        .register_executor(lambda: DomainValidator(id="domain_validator"), name="domain_validator")
+        .set_start_executor("email_sanitizer")
+        .add_edge("email_sanitizer", "email_format_validator")
+        .add_edge("email_format_validator", "domain_validator")
+        .build()
+    )
+
+
+@dataclass
+class Email:
+    recipient: str
+    subject: str
+    body: str
+
+
+class SmartEmailOrchestrator(Executor):
+    """Orchestrates email address validation using a sub-workflow."""
+
+    def __init__(self, id: str, approved_domains: set[str]):
+        """Initialize the orchestrator with a set of approved domains.
+
+        Args:
+            id: The executor ID.
+            approved_domains: A set of domains that are considered valid.
+        """
+        super().__init__(id=id)
+        self._approved_domains = approved_domains
+        # Keep track of previously approved and disapproved recipients
+        self._approved_recipients: set[str] = set()
+        self._disapproved_recipients: set[str] = set()
+        # Record pending emails waiting for validation results
+        self._pending_emails: dict[str, Email] = {}
+
+    @handler
+    async def run(self, email: Email, ctx: WorkflowContext[Email | str, bool]) -> None:
+        """Start the email delivery process.
+
+        This handler receives an Email object. If the recipient has been previously approved,
+        it sends the email object to the next executor to handle delivery. If the recipient
+        has been previously disapproved, it yields False as the final result. Otherwise,
+        it sends the recipient email address to the sub-workflow for validation.
+        """
+        recipient = email.recipient
+        if recipient in self._approved_recipients:
+            print(f"📧 Recipient '{recipient}' has been previously approved.")
+            await ctx.send_message(email)
+            return
+        if recipient in self._disapproved_recipients:
+            print(f"🚫 Blocking email to previously disapproved recipient: '{recipient}'")
+            await ctx.yield_output(False)
+            return
+
+        print(f"🔍 Validating new recipient email address: '{recipient}'")
+        self._pending_emails[recipient] = email
+        await ctx.send_message(recipient)
+
+    @handler
+    async def handler_domain_validation_request(
+        self, request: SubWorkflowRequestMessage, ctx: WorkflowContext[SubWorkflowResponseMessage]
+    ) -> None:
+        """Handle requests from the sub-workflow for domain validation.
+
+        Note that the message type must be SubWorkflowRequestMessage to intercept the request. And
+        the response must be sent back using SubWorkflowResponseMessage to route the response
+        back to the sub-workflow.
+        """
+        if not isinstance(request.source_event.data, str):
+            raise TypeError(f"Expected domain string, got {type(request.source_event.data)}")
+        domain = request.source_event.data
+        is_valid = domain in self._approved_domains
+        print(f"🌐 External domain validation for '{domain}': {'valid' if is_valid else 'invalid'}")
+        await ctx.send_message(request.create_response(is_valid), target_id=request.executor_id)
+
+    @handler
+    async def handle_validation_result(self, result: SanitizedEmailResult, ctx: WorkflowContext[Email, bool]) -> None:
+        """Handle the email address validation result.
+
+        This handler receives the validation result from the sub-workflow.
+        If the email address is valid, it adds the recipient to the approved list
+        and sends the email object to the next executor to handle delivery.
+        If the email address is invalid, it adds the recipient to the disapproved list
+        and yields False as the final result.
+        """
+        email = self._pending_emails.pop(result.original)
+        email.recipient = result.sanitized  # Use the sanitized email address
+        if result.is_valid:
+            print(f"✅ Email address '{result.original}' is valid.")
+            self._approved_recipients.add(result.original)
+            await ctx.send_message(email)
+        else:
+            print(f"🚫 Email address '{result.original}' is invalid. Blocking email.")
+            self._disapproved_recipients.add(result.original)
+            await ctx.yield_output(False)
+
+
+class EmailDelivery(Executor):
+    """Simulates email delivery."""
+
+    @handler
+    async def handle(self, email: Email, ctx: WorkflowContext[Never, bool]) -> None:
+        """Simulate sending the email and yield True as the final result."""
+        print(f"📤 Sending email to '{email.recipient}' with subject '{email.subject}'")
+        await asyncio.sleep(1)  # Simulate network delay
+        print(f"✅ Email sent to '{email.recipient}' successfully.")
+        await ctx.yield_output(True)
+
+
+async def main() -> None:
+    # A list of approved domains
+    approved_domains = {"example.com", "company.com"}
+
+    # Build the main workflow
+    workflow = (
+        WorkflowBuilder()
+        .register_executor(
+            lambda: SmartEmailOrchestrator(id="smart_email_orchestrator", approved_domains=approved_domains),
+            name="smart_email_orchestrator",
+        )
+        .register_executor(lambda: EmailDelivery(id="email_delivery"), name="email_delivery")
+        .register_executor(
+            lambda: WorkflowExecutor(build_email_address_validation_workflow(), id="email_validation_workflow"),
+            name="email_validation_workflow",
+        )
+        .set_start_executor("smart_email_orchestrator")
+        .add_edge("smart_email_orchestrator", "email_validation_workflow")
+        .add_edge("email_validation_workflow", "smart_email_orchestrator")
+        .add_edge("smart_email_orchestrator", "email_delivery")
+        .build()
+    )
+
+    test_emails = [
+        Email(recipient="user1@example.com", subject="Hello User1", body="This is a test email."),
+        Email(recipient=" user2@invalid", subject="Hello User2", body="This is a test email."),
+        Email(recipient="  user3@company.com  ", subject="Hello User3", body="This is a test email."),
+        Email(recipient="user4@unknown.com", subject="Hello User4", body="This is a test email."),
+        # Re-send to an approved recipient
+        Email(recipient="user1@example.com", subject="Hello User1", body="This is a test email."),
+        # Re-send to a disapproved recipient
+        Email(recipient=" user2@invalid", subject="Hello User2", body="This is a test email."),
+    ]
+
+    # Execute the workflow
+    for email in test_emails:
+        print(f"\n🚀 Processing email to '{email.recipient}'")
+        async for event in workflow.run_stream(email):
+            if isinstance(event, WorkflowOutputEvent):
+                print(f"🎉 Final result for '{email.recipient}': {'Delivered' if event.data else 'Blocked'}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,236 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+from typing import Any
+
+from agent_framework import (  # Core chat primitives used to build requests
+    AgentExecutorRequest,  # Input message bundle for an AgentExecutor
+    AgentExecutorResponse,
+    ChatAgent,  # Output from an AgentExecutor
+    ChatMessage,
+    Role,
+    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
+from typing_extensions import Never
+
+"""
+Sample: Conditional routing with structured outputs
+
+What this sample is:
+- A minimal decision workflow that classifies an inbound email as spam or not spam, then routes to the
+appropriate handler.
+
+Purpose:
+- Show how to attach boolean edge conditions that inspect an AgentExecutorResponse.
+- Demonstrate using Pydantic models as response_format so the agent returns JSON we can validate and parse.
+- Illustrate how to transform one agent's structured result into a new AgentExecutorRequest for a downstream agent.
+
+Prerequisites:
+- You understand the basics of WorkflowBuilder, executors, and events in this framework.
+- You know the concept of edge conditions and how they gate routes using a predicate function.
+- Azure OpenAI access is configured for AzureOpenAIChatClient. You should be logged in with Azure CLI (AzureCliCredential)
+and have the Azure OpenAI environment variables set as documented in the getting started chat client README.
+- The sample email resource file exists at workflow/resources/email.txt.
+
+High level flow:
+1) spam_detection_agent reads an email and returns DetectionResult.
+2) If not spam, we transform the detection output into a user message for email_assistant_agent, then finish by
+yielding the drafted reply as workflow output.
+3) If spam, we short circuit to a spam handler that yields a spam notice as workflow output.
+
+Output:
+- The final workflow output is printed to stdout, either with a drafted reply or a spam notice.
+
+Notes:
+- Conditions read the agent response text and validate it into DetectionResult for robust routing.
+- Executors are small and single purpose to keep control flow easy to follow.
+- The workflow completes when it becomes idle, not via explicit completion events.
+"""
+
+
+class DetectionResult(BaseModel):
+    """Represents the result of spam detection."""
+
+    # is_spam drives the routing decision taken by edge conditions
+    is_spam: bool
+    # Human readable rationale from the detector
+    reason: str
+    # The agent must include the original email so downstream agents can operate without reloading content
+    email_content: str
+
+
+class EmailResponse(BaseModel):
+    """Represents the response from the email assistant."""
+
+    # The drafted reply that a user could copy or send
+    response: str
+
+
+def get_condition(expected_result: bool):
+    """Create a condition callable that routes based on DetectionResult.is_spam."""
+
+    # The returned function will be used as an edge predicate.
+    # It receives whatever the upstream executor produced.
+    def condition(message: Any) -> bool:
+        # Defensive guard. If a non AgentExecutorResponse appears, let the edge pass to avoid dead ends.
+        if not isinstance(message, AgentExecutorResponse):
+            return True
+
+        try:
+            # Prefer parsing a structured DetectionResult from the agent JSON text.
+            # Using model_validate_json ensures type safety and raises if the shape is wrong.
+            detection = DetectionResult.model_validate_json(message.agent_response.text)
+            # Route only when the spam flag matches the expected path.
+            return detection.is_spam == expected_result
+        except Exception:
+            # Fail closed on parse errors so we do not accidentally route to the wrong path.
+            # Returning False prevents this edge from activating.
+            return False
+
+    return condition
+
+
+@executor(id="send_email")
+async def handle_email_response(response: AgentExecutorResponse, ctx: WorkflowContext[Never, str]) -> None:
+    # Downstream of the email assistant. Parse a validated EmailResponse and yield the workflow output.
+    email_response = EmailResponse.model_validate_json(response.agent_response.text)
+    await ctx.yield_output(f"Email sent:\n{email_response.response}")
+
+
+@executor(id="handle_spam")
+async def handle_spam_classifier_response(response: AgentExecutorResponse, ctx: WorkflowContext[Never, str]) -> None:
+    # Spam path. Confirm the DetectionResult and yield the workflow output. Guard against accidental non spam input.
+    detection = DetectionResult.model_validate_json(response.agent_response.text)
+    if detection.is_spam:
+        await ctx.yield_output(f"Email marked as spam: {detection.reason}")
+    else:
+        # This indicates the routing predicate and executor contract are out of sync.
+        raise RuntimeError("This executor should only handle spam messages.")
+
+
+@executor(id="to_email_assistant_request")
+async def to_email_assistant_request(
+    response: AgentExecutorResponse, ctx: WorkflowContext[AgentExecutorRequest]
+) -> None:
+    """Transform detection result into an AgentExecutorRequest for the email assistant.
+
+    Extracts DetectionResult.email_content and forwards it as a user message.
+    """
+    # Bridge executor. Converts a structured DetectionResult into a ChatMessage and forwards it as a new request.
+    detection = DetectionResult.model_validate_json(response.agent_response.text)
+    user_msg = ChatMessage(Role.USER, text=detection.email_content)
+    await ctx.send_message(AgentExecutorRequest(messages=[user_msg], should_respond=True))
+
+
+def create_spam_detector_agent() -> ChatAgent:
+    """Helper to create a spam detection agent."""
+    # AzureCliCredential uses your current az login. This avoids embedding secrets in code.
+    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+        instructions=(
+            "You are a spam detection assistant that identifies spam emails. "
+            "Always return JSON with fields is_spam (bool), reason (string), and email_content (string). "
+            "Include the original email content in email_content."
+        ),
+        name="spam_detection_agent",
+        default_options={"response_format": DetectionResult},
+    )
+
+
+def create_email_assistant_agent() -> ChatAgent:
+    """Helper to create an email assistant agent."""
+    # AzureCliCredential uses your current az login. This avoids embedding secrets in code.
+    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+        instructions=(
+            "You are an email assistant that helps users draft professional responses to emails. "
+            "Your input may be a JSON object that includes 'email_content'; base your reply on that content. "
+            "Return JSON with a single field 'response' containing the drafted reply."
+        ),
+        name="email_assistant_agent",
+        default_options={"response_format": EmailResponse},
+    )
+
+
+async def main() -> None:
+    # Build the workflow graph.
+    # Start at the spam detector.
+    # If not spam, hop to a transformer that creates a new AgentExecutorRequest,
+    # then call the email assistant, then finalize.
+    # If spam, go directly to the spam handler and finalize.
+    workflow = (
+        WorkflowBuilder()
+        .register_agent(create_spam_detector_agent, name="spam_detection_agent")
+        .register_agent(create_email_assistant_agent, name="email_assistant_agent")
+        .register_executor(lambda: to_email_assistant_request, name="to_email_assistant_request")
+        .register_executor(lambda: handle_email_response, name="send_email")
+        .register_executor(lambda: handle_spam_classifier_response, name="handle_spam")
+        .set_start_executor("spam_detection_agent")
+        # Not spam path: transform response -> request for assistant -> assistant -> send email
+        .add_edge("spam_detection_agent", "to_email_assistant_request", condition=get_condition(False))
+        .add_edge("to_email_assistant_request", "email_assistant_agent")
+        .add_edge("email_assistant_agent", "send_email")
+        # Spam path: send to spam handler
+        .add_edge("spam_detection_agent", "handle_spam", condition=get_condition(True))
+        .build()
+    )
+
+    # Read Email content from the sample resource file.
+    # This keeps the sample deterministic since the model sees the same email every run.
+    email_path = os.path.join(os.path.dirname(os.path.dirname(os.path.realpath(__file__))), "resources", "email.txt")
+
+    with open(email_path) as email_file:  # noqa: ASYNC230
+        email = email_file.read()
+
+    # Execute the workflow. Since the start is an AgentExecutor, pass an AgentExecutorRequest.
+    # The workflow completes when it becomes idle (no more work to do).
+    request = AgentExecutorRequest(messages=[ChatMessage(Role.USER, text=email)], should_respond=True)
+    events = await workflow.run(request)
+    outputs = events.get_outputs()
+    if outputs:
+        print(f"Workflow output: {outputs[0]}")
+
+    """
+    Sample Output:
+
+    Processing email:
+    Subject: Team Meeting Follow-up - Action Items
+
+    Hi Sarah,
+
+    I wanted to follow up on our team meeting this morning and share the action items we discussed:
+
+    1. Update the project timeline by Friday
+    2. Schedule client presentation for next week
+    3. Review the budget allocation for Q4
+
+    Please let me know if you have any questions or if I missed anything from our discussion.
+
+    Best regards,
+    Alex Johnson
+    Project Manager
+    Tech Solutions Inc.
+    alex.johnson@techsolutions.com
+    (555) 123-4567
+    ----------------------------------------
+
+Workflow output: Email sent:
+    Hi Alex,
+
+    Thank you for the follow-up and for summarizing the action items from this morning's meeting. The points you listed accurately reflect our discussion, and I don't have any additional items to add at this time.
+
+    I will update the project timeline by Friday, begin scheduling the client presentation for next week, and start reviewing the Q4 budget allocation. If any questions or issues arise, I'll reach out.
+
+    Thank you again for outlining the next steps.
+
+    Best regards,
+    Sarah
+    """  # noqa: E501
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,306 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Step 06b — Multi-Selection Edge Group sample."""
+
+import asyncio
+import os
+from dataclasses import dataclass
+from typing import Literal
+from uuid import uuid4
+
+from agent_framework import (
+    AgentExecutorRequest,
+    AgentExecutorResponse,
+    ChatAgent,
+    ChatMessage,
+    Role,
+    WorkflowBuilder,
+    WorkflowContext,
+    WorkflowEvent,
+    WorkflowOutputEvent,
+    executor,
+)
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+from pydantic import BaseModel
+from typing_extensions import Never
+
+"""
+Sample: Multi-Selection Edge Group for email triage and response.
+
+The workflow stores an email,
+classifies it as NotSpam, Spam, or Uncertain, and then routes to one or more branches.
+Non-spam emails are drafted into replies, long ones are also summarized, spam is blocked, and uncertain cases are
+flagged. Each path ends with simulated database persistence. The workflow completes when it becomes idle.
+
+Purpose:
+Demonstrate how to use a multi-selection edge group to fan out from one executor to multiple possible targets.
+Show how to:
+- Implement a selection function that chooses one or more downstream branches based on analysis.
+- Share state across branches so different executors can read the same email content.
+- Validate agent outputs with Pydantic models for robust structured data exchange.
+- Merge results from multiple branches (e.g., a summary) back into a typed state.
+- Apply conditional persistence logic (short vs long emails).
+
+Prerequisites:
+- Familiarity with WorkflowBuilder, executors, edges, and events.
+- Understanding of multi-selection edge groups and how their selection function maps to target ids.
+- Experience with shared state in workflows for persisting and reusing objects.
+"""
+
+
+EMAIL_STATE_PREFIX = "email:"
+CURRENT_EMAIL_ID_KEY = "current_email_id"
+LONG_EMAIL_THRESHOLD = 100
+
+
+class AnalysisResultAgent(BaseModel):
+    spam_decision: Literal["NotSpam", "Spam", "Uncertain"]
+    reason: str
+
+
+class EmailResponse(BaseModel):
+    response: str
+
+
+class EmailSummaryModel(BaseModel):
+    summary: str
+
+
+@dataclass
+class Email:
+    email_id: str
+    email_content: str
+
+
+@dataclass
+class AnalysisResult:
+    spam_decision: str
+    reason: str
+    email_length: int
+    email_summary: str
+    email_id: str
+
+
+class DatabaseEvent(WorkflowEvent): ...
+
+
+@executor(id="store_email")
+async def store_email(email_text: str, ctx: WorkflowContext[AgentExecutorRequest]) -> None:
+    new_email = Email(email_id=str(uuid4()), email_content=email_text)
+    await ctx.set_shared_state(f"{EMAIL_STATE_PREFIX}{new_email.email_id}", new_email)
+    await ctx.set_shared_state(CURRENT_EMAIL_ID_KEY, new_email.email_id)
+
+    await ctx.send_message(
+        AgentExecutorRequest(messages=[ChatMessage(Role.USER, text=new_email.email_content)], should_respond=True)
+    )
+
+
+@executor(id="to_analysis_result")
+async def to_analysis_result(response: AgentExecutorResponse, ctx: WorkflowContext[AnalysisResult]) -> None:
+    parsed = AnalysisResultAgent.model_validate_json(response.agent_response.text)
+    email_id: str = await ctx.get_shared_state(CURRENT_EMAIL_ID_KEY)
+    email: Email = await ctx.get_shared_state(f"{EMAIL_STATE_PREFIX}{email_id}")
+    await ctx.send_message(
+        AnalysisResult(
+            spam_decision=parsed.spam_decision,
+            reason=parsed.reason,
+            email_length=len(email.email_content),
+            email_summary="",
+            email_id=email_id,
+        )
+    )
+
+
+@executor(id="submit_to_email_assistant")
+async def submit_to_email_assistant(analysis: AnalysisResult, ctx: WorkflowContext[AgentExecutorRequest]) -> None:
+    if analysis.spam_decision != "NotSpam":
+        raise RuntimeError("This executor should only handle NotSpam messages.")
+
+    email: Email = await ctx.get_shared_state(f"{EMAIL_STATE_PREFIX}{analysis.email_id}")
+    await ctx.send_message(
+        AgentExecutorRequest(messages=[ChatMessage(Role.USER, text=email.email_content)], should_respond=True)
+    )
+
+
+@executor(id="finalize_and_send")
+async def finalize_and_send(response: AgentExecutorResponse, ctx: WorkflowContext[Never, str]) -> None:
+    parsed = EmailResponse.model_validate_json(response.agent_response.text)
+    await ctx.yield_output(f"Email sent: {parsed.response}")
+
+
+@executor(id="summarize_email")
+async def summarize_email(analysis: AnalysisResult, ctx: WorkflowContext[AgentExecutorRequest]) -> None:
+    # Only called for long NotSpam emails by selection_func
+    email: Email = await ctx.get_shared_state(f"{EMAIL_STATE_PREFIX}{analysis.email_id}")
+    await ctx.send_message(
+        AgentExecutorRequest(messages=[ChatMessage(Role.USER, text=email.email_content)], should_respond=True)
+    )
+
+
+@executor(id="merge_summary")
+async def merge_summary(response: AgentExecutorResponse, ctx: WorkflowContext[AnalysisResult]) -> None:
+    summary = EmailSummaryModel.model_validate_json(response.agent_response.text)
+    email_id: str = await ctx.get_shared_state(CURRENT_EMAIL_ID_KEY)
+    email: Email = await ctx.get_shared_state(f"{EMAIL_STATE_PREFIX}{email_id}")
+    # Build an AnalysisResult mirroring to_analysis_result but with summary
+    await ctx.send_message(
+        AnalysisResult(
+            spam_decision="NotSpam",
+            reason="",
+            email_length=len(email.email_content),
+            email_summary=summary.summary,
+            email_id=email_id,
+        )
+    )
+
+
+@executor(id="handle_spam")
+async def handle_spam(analysis: AnalysisResult, ctx: WorkflowContext[Never, str]) -> None:
+    if analysis.spam_decision == "Spam":
+        await ctx.yield_output(f"Email marked as spam: {analysis.reason}")
+    else:
+        raise RuntimeError("This executor should only handle Spam messages.")
+
+
+@executor(id="handle_uncertain")
+async def handle_uncertain(analysis: AnalysisResult, ctx: WorkflowContext[Never, str]) -> None:
+    if analysis.spam_decision == "Uncertain":
+        email: Email | None = await ctx.get_shared_state(f"{EMAIL_STATE_PREFIX}{analysis.email_id}")
+        await ctx.yield_output(
+            f"Email marked as uncertain: {analysis.reason}. Email content: {getattr(email, 'email_content', '')}"
+        )
+    else:
+        raise RuntimeError("This executor should only handle Uncertain messages.")
+
+
+@executor(id="database_access")
+async def database_access(analysis: AnalysisResult, ctx: WorkflowContext[Never, str]) -> None:
+    # Simulate DB writes for email and analysis (and summary if present)
+    await asyncio.sleep(0.05)
+    await ctx.add_event(DatabaseEvent(f"Email {analysis.email_id} saved to database."))
+
+
+def create_email_analysis_agent() -> ChatAgent:
+    """Creates the email analysis agent."""
+    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+        instructions=(
+            "You are a spam detection assistant that identifies spam emails. "
+            "Always return JSON with fields 'spam_decision' (one of NotSpam, Spam, Uncertain) "
+            "and 'reason' (string)."
+        ),
+        name="email_analysis_agent",
+        default_options={"response_format": AnalysisResultAgent},
+    )
+
+
+def create_email_assistant_agent() -> ChatAgent:
+    """Creates the email assistant agent."""
+    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+        instructions=("You are an email assistant that helps users draft responses to emails with professionalism."),
+        name="email_assistant_agent",
+        default_options={"response_format": EmailResponse},
+    )
+
+
+def create_email_summary_agent() -> ChatAgent:
+    """Creates the email summary agent."""
+    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+        instructions=("You are an assistant that helps users summarize emails."),
+        name="email_summary_agent",
+        default_options={"response_format": EmailSummaryModel},
+    )
+
+
+async def main() -> None:
+    # Build the workflow
+    def select_targets(analysis: AnalysisResult, target_ids: list[str]) -> list[str]:
+        # Order: [handle_spam, submit_to_email_assistant, summarize_email, handle_uncertain]
+        handle_spam_id, submit_to_email_assistant_id, summarize_email_id, handle_uncertain_id = target_ids
+        if analysis.spam_decision == "Spam":
+            return [handle_spam_id]
+        if analysis.spam_decision == "NotSpam":
+            targets = [submit_to_email_assistant_id]
+            if analysis.email_length > LONG_EMAIL_THRESHOLD:
+                targets.append(summarize_email_id)
+            return targets
+        return [handle_uncertain_id]
+
+    workflow_builder = (
+        WorkflowBuilder()
+        .register_agent(create_email_analysis_agent, name="email_analysis_agent")
+        .register_agent(create_email_assistant_agent, name="email_assistant_agent")
+        .register_agent(create_email_summary_agent, name="email_summary_agent")
+        .register_executor(lambda: store_email, name="store_email")
+        .register_executor(lambda: to_analysis_result, name="to_analysis_result")
+        .register_executor(lambda: submit_to_email_assistant, name="submit_to_email_assistant")
+        .register_executor(lambda: finalize_and_send, name="finalize_and_send")
+        .register_executor(lambda: summarize_email, name="summarize_email")
+        .register_executor(lambda: merge_summary, name="merge_summary")
+        .register_executor(lambda: handle_spam, name="handle_spam")
+        .register_executor(lambda: handle_uncertain, name="handle_uncertain")
+        .register_executor(lambda: database_access, name="database_access")
+    )
+
+    workflow = (
+        workflow_builder
+        .set_start_executor("store_email")
+        .add_edge("store_email", "email_analysis_agent")
+        .add_edge("email_analysis_agent", "to_analysis_result")
+        .add_multi_selection_edge_group(
+            "to_analysis_result",
+            ["handle_spam", "submit_to_email_assistant", "summarize_email", "handle_uncertain"],
+            selection_func=select_targets,
+        )
+        .add_edge("submit_to_email_assistant", "email_assistant_agent")
+        .add_edge("email_assistant_agent", "finalize_and_send")
+        .add_edge("summarize_email", "email_summary_agent")
+        .add_edge("email_summary_agent", "merge_summary")
+        # Save to DB if short (no summary path)
+        .add_edge("to_analysis_result", "database_access", condition=lambda r: r.email_length <= LONG_EMAIL_THRESHOLD)
+        # Save to DB with summary when long
+        .add_edge("merge_summary", "database_access")
+        .build()
+    )
+
+    # Read an email sample
+    resources_path = os.path.join(
+        os.path.dirname(os.path.dirname(os.path.realpath(__file__))),
+        "resources",
+        "email.txt",
+    )
+    if os.path.exists(resources_path):
+        with open(resources_path, encoding="utf-8") as f:  # noqa: ASYNC230
+            email = f.read()
+    else:
+        print("Unable to find resource file, using default text.")
+        email = "Hello team, here are the updates for this week..."
+
+    # Print outputs and database events from streaming
+    async for event in workflow.run_stream(email):
+        if isinstance(event, DatabaseEvent):
+            print(f"{event}")
+        elif isinstance(event, WorkflowOutputEvent):
+            print(f"Workflow output: {event.data}")
+
+    """
+    Sample Output:
+
+    DatabaseEvent(data=Email 32021432-2d4e-4c54-b04c-f81b4120340c saved to database.)
+    Workflow output: Email sent: Hi Alex,
+
+    Thank you for summarizing the action items from this morning's meeting.
+    I have noted the three tasks and will begin working on them right away.
+    I'll aim to have the updated project timeline ready by Friday and will
+    coordinate with the team to schedule the client presentation for next week.
+    I'll also review the Q4 budget allocation and share my feedback soon.
+
+    If anything else comes up, please let me know.
+
+    Best regards,
+    Sarah
+    """  # noqa: E501
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,88 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import cast
+
+from agent_framework import (
+    Executor,
+    WorkflowBuilder,
+    WorkflowContext,
+    WorkflowOutputEvent,
+    handler,
+)
+from typing_extensions import Never
+
+"""
+Sample: Sequential workflow with streaming.
+
+Two custom executors run in sequence. The first converts text to uppercase,
+the second reverses the text and completes the workflow. The run_stream loop prints events as they occur.
+
+Purpose:
+Show how to define explicit Executor classes with @handler methods, wire them in order with
+WorkflowBuilder, and consume streaming events. Demonstrate typed WorkflowContext[T_Out, T_W_Out] for outputs,
+ctx.send_message to pass intermediate values, and ctx.yield_output to provide workflow outputs.
+
+Prerequisites:
+- No external services required.
+"""
+
+
+class UpperCaseExecutor(Executor):
+    """Converts an input string to uppercase and forwards it.
+
+    Concepts:
+    - @handler methods define invokable steps.
+    - WorkflowContext[str] indicates this step emits a string to the next node.
+    """
+
+    @handler
+    async def to_upper_case(self, text: str, ctx: WorkflowContext[str]) -> None:
+        """Transform the input to uppercase and send it downstream."""
+        result = text.upper()
+        # Pass the intermediate result to the next executor in the chain.
+        await ctx.send_message(result)
+
+
+class ReverseTextExecutor(Executor):
+    """Reverses the incoming string and yields workflow output.
+
+    Concepts:
+    - Use ctx.yield_output to provide workflow outputs when the terminal result is ready.
+    - The terminal node does not forward messages further.
+    """
+
+    @handler
+    async def reverse_text(self, text: str, ctx: WorkflowContext[Never, str]) -> None:
+        """Reverse the input string and yield the workflow output."""
+        result = text[::-1]
+        await ctx.yield_output(result)
+
+
+async def main() -> None:
+    """Build a two step sequential workflow and run it with streaming to observe events."""
+    # Step 1: Build the workflow graph.
+    # Order matters. We connect upper_case_executor -> reverse_text_executor and set the start.
+    workflow = (
+        WorkflowBuilder()
+        .register_executor(lambda: UpperCaseExecutor(id="upper_case_executor"), name="upper_case_executor")
+        .register_executor(lambda: ReverseTextExecutor(id="reverse_text_executor"), name="reverse_text_executor")
+        .add_edge("upper_case_executor", "reverse_text_executor")
+        .set_start_executor("upper_case_executor")
+        .build()
+    )
+
+    # Step 2: Stream events for a single input.
+    # The stream will include executor invoke and completion events, plus workflow outputs.
+    outputs: list[str] = []
+    async for event in workflow.run_stream("hello world"):
+        print(f"Event: {event}")
+        if isinstance(event, WorkflowOutputEvent):
+            outputs.append(cast(str, event.data))
+
+    if outputs:
+        print(f"Workflow outputs: {outputs}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,86 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import WorkflowBuilder, WorkflowContext, WorkflowOutputEvent, executor
+from typing_extensions import Never
+
+"""
+Sample: Foundational sequential workflow with streaming using function-style executors.
+
+Two lightweight steps run in order. The first converts text to uppercase.
+The second reverses the text and yields the workflow output. Events are printed as they arrive from run_stream.
+
+Purpose:
+Show how to declare executors with the @executor decorator, connect them with WorkflowBuilder,
+pass intermediate values using ctx.send_message, and yield final output using ctx.yield_output().
+Demonstrate how streaming exposes ExecutorInvokedEvent and ExecutorCompletedEvent for observability.
+
+Prerequisites:
+- No external services required.
+"""
+
+
+# Step 1: Define methods using the executor decorator.
+@executor(id="upper_case_executor")
+async def to_upper_case(text: str, ctx: WorkflowContext[str]) -> None:
+    """Transform the input to uppercase and forward it to the next step.
+
+    Concepts:
+    - The @executor decorator registers this function as a workflow node.
+    - WorkflowContext[str] indicates that this node emits a string payload downstream.
+    """
+    result = text.upper()
+
+    # Send the intermediate result to the next executor in the workflow graph.
+    await ctx.send_message(result)
+
+
+@executor(id="reverse_text_executor")
+async def reverse_text(text: str, ctx: WorkflowContext[Never, str]) -> None:
+    """Reverse the input and yield the workflow output.
+
+    Concepts:
+    - Terminal nodes yield output using ctx.yield_output().
+    - The workflow completes when it becomes idle (no more work to do).
+    """
+    result = text[::-1]
+
+    # Yield the final output for this workflow run.
+    await ctx.yield_output(result)
+
+
+async def main():
+    """Build a two-step sequential workflow and run it with streaming to observe events."""
+    # Step 1: Build the workflow with the defined edges.
+    # Order matters. upper_case_executor runs first, then reverse_text_executor.
+    workflow = (
+        WorkflowBuilder()
+        .register_executor(lambda: to_upper_case, name="upper_case_executor")
+        .register_executor(lambda: reverse_text, name="reverse_text_executor")
+        .add_edge("upper_case_executor", "reverse_text_executor")
+        .set_start_executor("upper_case_executor")
+        .build()
+    )
+
+    # Step 2: Run the workflow and stream events in real time.
+    async for event in workflow.run_stream("hello world"):
+        # You will see executor invoke and completion events as the workflow progresses.
+        print(f"Event: {event}")
+        if isinstance(event, WorkflowOutputEvent):
+            print(f"Workflow completed with result: {event.data}")
+
+    """
+    Sample Output:
+
+    Event: ExecutorInvokedEvent(executor_id=upper_case_executor)
+    Event: ExecutorCompletedEvent(executor_id=upper_case_executor)
+    Event: ExecutorInvokedEvent(executor_id=reverse_text_executor)
+    Event: ExecutorCompletedEvent(executor_id=reverse_text_executor)
+    Event: WorkflowOutputEvent(data='DLROW OLLEH', executor_id=reverse_text_executor)
+    Workflow completed with result: DLROW OLLEH
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,158 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from enum import Enum
+
+from agent_framework import (
+    AgentExecutorRequest,
+    AgentExecutorResponse,
+    ChatAgent,
+    ChatMessage,
+    Executor,
+    ExecutorCompletedEvent,
+    Role,
+    WorkflowBuilder,
+    WorkflowContext,
+    handler,
+)
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+
+"""
+Sample: Simple Loop (with an Agent Judge)
+
+What it does:
+- Guesser performs a binary search; judge is an agent that returns ABOVE/BELOW/MATCHED.
+- Demonstrates feedback loops in workflows with agent steps.
+- The workflow completes when the correct number is guessed.
+
+Prerequisites:
+- Azure AI/ Azure OpenAI for `AzureOpenAIChatClient` agent.
+- Authentication via `azure-identity` — uses `AzureCliCredential()` (run `az login`).
+"""
+
+
+class NumberSignal(Enum):
+    """Enum to represent number signals for the workflow."""
+
+    # The target number is above the guess.
+    ABOVE = "above"
+    # The target number is below the guess.
+    BELOW = "below"
+    # The guess matches the target number.
+    MATCHED = "matched"
+    # Initial signal to start the guessing process.
+    INIT = "init"
+
+
+class GuessNumberExecutor(Executor):
+    """An executor that guesses a number."""
+
+    def __init__(self, bound: tuple[int, int], id: str):
+        """Initialize the executor with a target number."""
+        super().__init__(id=id)
+        self._lower = bound[0]
+        self._upper = bound[1]
+
+    @handler
+    async def guess_number(self, feedback: NumberSignal, ctx: WorkflowContext[int, str]) -> None:
+        """Execute the task by guessing a number."""
+        if feedback == NumberSignal.INIT:
+            self._guess = (self._lower + self._upper) // 2
+            await ctx.send_message(self._guess)
+        elif feedback == NumberSignal.MATCHED:
+            # The previous guess was correct.
+            await ctx.yield_output(f"Guessed the number: {self._guess}")
+        elif feedback == NumberSignal.ABOVE:
+            # The previous guess was too low.
+            # Update the lower bound to the previous guess.
+            # Generate a new number that is between the new bounds.
+            self._lower = self._guess + 1
+            self._guess = (self._lower + self._upper) // 2
+            await ctx.send_message(self._guess)
+        else:
+            # The previous guess was too high.
+            # Update the upper bound to the previous guess.
+            # Generate a new number that is between the new bounds.
+            self._upper = self._guess - 1
+            self._guess = (self._lower + self._upper) // 2
+            await ctx.send_message(self._guess)
+
+
+class SubmitToJudgeAgent(Executor):
+    """Send the numeric guess to a judge agent which replies ABOVE/BELOW/MATCHED."""
+
+    def __init__(self, judge_agent_id: str, target: int, id: str | None = None):
+        super().__init__(id=id or "submit_to_judge")
+        self._judge_agent_id = judge_agent_id
+        self._target = target
+
+    @handler
+    async def submit(self, guess: int, ctx: WorkflowContext[AgentExecutorRequest]) -> None:
+        prompt = (
+            "You are a number judge. Given a target number and a guess, reply with exactly one token:"
+            " 'MATCHED' if guess == target, 'ABOVE' if the target is above the guess,"
+            " or 'BELOW' if the target is below.\n"
+            f"Target: {self._target}\nGuess: {guess}\nResponse:"
+        )
+        await ctx.send_message(
+            AgentExecutorRequest(messages=[ChatMessage(Role.USER, text=prompt)], should_respond=True),
+            target_id=self._judge_agent_id,
+        )
+
+
+class ParseJudgeResponse(Executor):
+    """Parse AgentExecutorResponse into NumberSignal for the loop."""
+
+    @handler
+    async def parse(self, response: AgentExecutorResponse, ctx: WorkflowContext[NumberSignal]) -> None:
+        text = response.agent_response.text.strip().upper()
+        if "MATCHED" in text:
+            await ctx.send_message(NumberSignal.MATCHED)
+        elif "ABOVE" in text and "BELOW" not in text:
+            await ctx.send_message(NumberSignal.ABOVE)
+        else:
+            await ctx.send_message(NumberSignal.BELOW)
+
+
+def create_judge_agent() -> ChatAgent:
+    """Create a judge agent that evaluates guesses."""
+    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+        instructions=("You strictly respond with one of: MATCHED, ABOVE, BELOW based on the given target and guess."),
+        name="judge_agent",
+    )
+
+
+async def main():
+    """Main function to run the workflow."""
+    # Step 1: Build the workflow with the defined edges.
+    # This time we are creating a loop in the workflow.
+    workflow = (
+        WorkflowBuilder()
+        .register_executor(lambda: GuessNumberExecutor((1, 100), "guess_number"), name="guess_number")
+        .register_agent(create_judge_agent, name="judge_agent")
+        .register_executor(lambda: SubmitToJudgeAgent(judge_agent_id="judge_agent", target=30), name="submit_judge")
+        .register_executor(lambda: ParseJudgeResponse(id="parse_judge"), name="parse_judge")
+        .add_edge("guess_number", "submit_judge")
+        .add_edge("submit_judge", "judge_agent")
+        .add_edge("judge_agent", "parse_judge")
+        .add_edge("parse_judge", "guess_number")
+        .set_start_executor("guess_number")
+        .build()
+    )
+
+    # Step 2: Run the workflow and print the events.
+    iterations = 0
+    async for event in workflow.run_stream(NumberSignal.INIT):
+        if isinstance(event, ExecutorCompletedEvent) and event.executor_id == "guess_number":
+            iterations += 1
+        print(f"Event: {event}")
+
+    # This is essentially a binary search, so the number of iterations should be logarithmic.
+    # The maximum number of iterations is [log2(range size)]. For a range of 1 to 100, this is log2(100) which is 7.
+    # Subtract because the last round is the MATCHED event.
+    print(f"Guessed {iterations - 1} times.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,231 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+from dataclasses import dataclass
+from typing import Any, Literal
+from uuid import uuid4
+
+from agent_framework import (  # Core chat primitives used to form LLM requests
+    AgentExecutorRequest,  # Message bundle sent to an AgentExecutor
+    AgentExecutorResponse,  # Result returned by an AgentExecutor
+    Case,
+    ChatAgent,  # Case entry for a switch-case edge group
+    ChatMessage,
+    Default,  # Default branch when no cases match
+    Role,
+    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
+from typing_extensions import Never
+
+"""
+Sample: Switch-Case Edge Group with an explicit Uncertain branch.
+
+The workflow stores a single email in shared state, asks a spam detection agent for a three way decision,
+then routes with a switch-case group: NotSpam to the drafting assistant, Spam to a spam handler, and
+Default to an Uncertain handler.
+
+Purpose:
+Demonstrate deterministic one of N routing with switch-case edges. Show how to:
+- Persist input once in shared state, then pass around a small typed pointer that carries the email id.
+- Validate agent JSON with Pydantic models for robust parsing.
+- Keep executor responsibilities narrow. Transform model output to a typed DetectionResult, then route based
+on that type.
+- Use ctx.yield_output() to provide workflow results - the workflow completes when idle with no pending work.
+
+Prerequisites:
+- Familiarity with WorkflowBuilder, executors, edges, and events.
+- Understanding of switch-case edge groups and how Case and Default are evaluated in order.
+- Working Azure OpenAI configuration for AzureOpenAIChatClient, with Azure CLI login and required environment variables.
+- Access to workflow/resources/ambiguous_email.txt, or accept the inline fallback string.
+"""
+
+
+EMAIL_STATE_PREFIX = "email:"
+CURRENT_EMAIL_ID_KEY = "current_email_id"
+
+
+class DetectionResultAgent(BaseModel):
+    """Structured output returned by the spam detection agent."""
+
+    # The agent classifies the email and provides a rationale.
+    spam_decision: Literal["NotSpam", "Spam", "Uncertain"]
+    reason: str
+
+
+class EmailResponse(BaseModel):
+    """Structured output returned by the email assistant agent."""
+
+    # The drafted professional reply.
+    response: str
+
+
+@dataclass
+class DetectionResult:
+    # Internal typed payload used for routing and downstream handling.
+    spam_decision: str
+    reason: str
+    email_id: str
+
+
+@dataclass
+class Email:
+    # In memory record of the email content stored in shared state.
+    email_id: str
+    email_content: str
+
+
+def get_case(expected_decision: str):
+    """Factory that returns a predicate matching a specific spam_decision value."""
+
+    def condition(message: Any) -> bool:
+        # Only match when the upstream payload is a DetectionResult with the expected decision.
+        return isinstance(message, DetectionResult) and message.spam_decision == expected_decision
+
+    return condition
+
+
+@executor(id="store_email")
+async def store_email(email_text: str, ctx: WorkflowContext[AgentExecutorRequest]) -> None:
+    # Persist the raw email once. Store under a unique key and set the current pointer for convenience.
+    new_email = Email(email_id=str(uuid4()), email_content=email_text)
+    await ctx.set_shared_state(f"{EMAIL_STATE_PREFIX}{new_email.email_id}", new_email)
+    await ctx.set_shared_state(CURRENT_EMAIL_ID_KEY, new_email.email_id)
+
+    # Kick off the detector by forwarding the email as a user message to the spam_detection_agent.
+    await ctx.send_message(
+        AgentExecutorRequest(messages=[ChatMessage(Role.USER, text=new_email.email_content)], should_respond=True)
+    )
+
+
+@executor(id="to_detection_result")
+async def to_detection_result(response: AgentExecutorResponse, ctx: WorkflowContext[DetectionResult]) -> None:
+    # Parse the detector JSON into a typed model. Attach the current email id for downstream lookups.
+    parsed = DetectionResultAgent.model_validate_json(response.agent_response.text)
+    email_id: str = await ctx.get_shared_state(CURRENT_EMAIL_ID_KEY)
+    await ctx.send_message(DetectionResult(spam_decision=parsed.spam_decision, reason=parsed.reason, email_id=email_id))
+
+
+@executor(id="submit_to_email_assistant")
+async def submit_to_email_assistant(detection: DetectionResult, ctx: WorkflowContext[AgentExecutorRequest]) -> None:
+    # Only proceed for the NotSpam branch. Guard against accidental misrouting.
+    if detection.spam_decision != "NotSpam":
+        raise RuntimeError("This executor should only handle NotSpam messages.")
+
+    # Load the original content from shared state using the id carried in DetectionResult.
+    email: Email = await ctx.get_shared_state(f"{EMAIL_STATE_PREFIX}{detection.email_id}")
+    await ctx.send_message(
+        AgentExecutorRequest(messages=[ChatMessage(Role.USER, text=email.email_content)], should_respond=True)
+    )
+
+
+@executor(id="finalize_and_send")
+async def finalize_and_send(response: AgentExecutorResponse, ctx: WorkflowContext[Never, str]) -> None:
+    # Terminal step for the drafting branch. Yield the email response as output.
+    parsed = EmailResponse.model_validate_json(response.agent_response.text)
+    await ctx.yield_output(f"Email sent: {parsed.response}")
+
+
+@executor(id="handle_spam")
+async def handle_spam(detection: DetectionResult, ctx: WorkflowContext[Never, str]) -> None:
+    # Spam path terminal. Include the detector's rationale.
+    if detection.spam_decision == "Spam":
+        await ctx.yield_output(f"Email marked as spam: {detection.reason}")
+    else:
+        raise RuntimeError("This executor should only handle Spam messages.")
+
+
+@executor(id="handle_uncertain")
+async def handle_uncertain(detection: DetectionResult, ctx: WorkflowContext[Never, str]) -> None:
+    # Uncertain path terminal. Surface the original content to aid human review.
+    if detection.spam_decision == "Uncertain":
+        email: Email | None = await ctx.get_shared_state(f"{EMAIL_STATE_PREFIX}{detection.email_id}")
+        await ctx.yield_output(
+            f"Email marked as uncertain: {detection.reason}. Email content: {getattr(email, 'email_content', '')}"
+        )
+    else:
+        raise RuntimeError("This executor should only handle Uncertain messages.")
+
+
+def create_spam_detection_agent() -> ChatAgent:
+    """Create and return the spam detection agent."""
+    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+        instructions=(
+            "You are a spam detection assistant that identifies spam emails. "
+            "Be less confident in your assessments. "
+            "Always return JSON with fields 'spam_decision' (one of NotSpam, Spam, Uncertain) "
+            "and 'reason' (string)."
+        ),
+        name="spam_detection_agent",
+        default_options={"response_format": DetectionResultAgent},
+    )
+
+
+def create_email_assistant_agent() -> ChatAgent:
+    """Create and return the email assistant agent."""
+    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+        instructions=("You are an email assistant that helps users draft responses to emails with professionalism."),
+        name="email_assistant_agent",
+        default_options={"response_format": EmailResponse},
+    )
+
+
+async def main():
+    """Main function to run the workflow."""
+    # Build workflow: store -> detection agent -> to_detection_result -> switch (NotSpam or Spam or Default).
+    # The switch-case group evaluates cases in order, then falls back to Default when none match.
+    workflow = (
+        WorkflowBuilder()
+        .register_agent(create_spam_detection_agent, name="spam_detection_agent")
+        .register_agent(create_email_assistant_agent, name="email_assistant_agent")
+        .register_executor(lambda: store_email, name="store_email")
+        .register_executor(lambda: to_detection_result, name="to_detection_result")
+        .register_executor(lambda: submit_to_email_assistant, name="submit_to_email_assistant")
+        .register_executor(lambda: finalize_and_send, name="finalize_and_send")
+        .register_executor(lambda: handle_spam, name="handle_spam")
+        .register_executor(lambda: handle_uncertain, name="handle_uncertain")
+        .set_start_executor("store_email")
+        .add_edge("store_email", "spam_detection_agent")
+        .add_edge("spam_detection_agent", "to_detection_result")
+        .add_switch_case_edge_group(
+            "to_detection_result",
+            [
+                Case(condition=get_case("NotSpam"), target="submit_to_email_assistant"),
+                Case(condition=get_case("Spam"), target="handle_spam"),
+                Default(target="handle_uncertain"),
+            ],
+        )
+        .add_edge("submit_to_email_assistant", "email_assistant_agent")
+        .add_edge("email_assistant_agent", "finalize_and_send")
+        .build()
+    )
+
+    # Read ambiguous email if available. Otherwise use a simple inline sample.
+    resources_path = os.path.join(
+        os.path.dirname(os.path.dirname(os.path.realpath(__file__))), "resources", "ambiguous_email.txt"
+    )
+    if os.path.exists(resources_path):
+        with open(resources_path, encoding="utf-8") as f:  # noqa: ASYNC230
+            email = f.read()
+    else:
+        print("Unable to find resource file, using default text.")
+        email = (
+            "Hey there, I noticed you might be interested in our latest offer—no pressure, but it expires soon. "
+            "Let me know if you'd like more details."
+        )
+
+    # Run and print the outputs from whichever branch completes.
+    events = await workflow.run(email)
+    outputs = events.get_outputs()
+    if outputs:
+        for output in outputs:
+            print(f"Workflow output: {output}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,103 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import WorkflowBuilder, WorkflowContext, executor
+from typing_extensions import Never
+
+"""
+Sample: Workflow Cancellation
+
+A three-step workflow where each step takes 2 seconds. We cancel it after 3 seconds
+to demonstrate mid-execution cancellation using asyncio tasks.
+
+Purpose:
+Show how to cancel a running workflow by wrapping it in an asyncio.Task. This pattern
+works with both workflow.run() and workflow.run_stream(). Useful for implementing
+timeouts, graceful shutdown, or A2A executors that need cancellation support.
+
+Prerequisites:
+- No external services required.
+"""
+
+
+@executor(id="step1")
+async def step1(text: str, ctx: WorkflowContext[str]) -> None:
+    """First step - simulates 2 seconds of work."""
+    print("[Step1] Starting...")
+    await asyncio.sleep(2)
+    print("[Step1] Done")
+    await ctx.send_message(text.upper())
+
+
+@executor(id="step2")
+async def step2(text: str, ctx: WorkflowContext[str]) -> None:
+    """Second step - simulates 2 seconds of work."""
+    print("[Step2] Starting...")
+    await asyncio.sleep(2)
+    print("[Step2] Done")
+    await ctx.send_message(text + "!")
+
+
+@executor(id="step3")
+async def step3(text: str, ctx: WorkflowContext[Never, str]) -> None:
+    """Final step - simulates 2 seconds of work."""
+    print("[Step3] Starting...")
+    await asyncio.sleep(2)
+    print("[Step3] Done")
+    await ctx.yield_output(f"Result: {text}")
+
+
+def build_workflow():
+    """Build a simple 3-step sequential workflow (~6 seconds total)."""
+    return (
+        WorkflowBuilder()
+        .register_executor(lambda: step1, name="step1")
+        .register_executor(lambda: step2, name="step2")
+        .register_executor(lambda: step3, name="step3")
+        .add_edge("step1", "step2")
+        .add_edge("step2", "step3")
+        .set_start_executor("step1")
+        .build()
+    )
+
+
+async def run_with_cancellation() -> None:
+    """Cancel the workflow after 3 seconds (mid-execution during Step2)."""
+    print("=== Run with cancellation ===\n")
+    workflow = build_workflow()
+
+    # Wrap workflow.run() in a task to enable cancellation
+    task = asyncio.create_task(workflow.run("hello world"))
+
+    # Wait 3 seconds (Step1 completes, Step2 is mid-execution), then cancel
+    await asyncio.sleep(3)
+    print("\n--- Cancelling workflow ---\n")
+    task.cancel()
+
+    try:
+        await task
+    except asyncio.CancelledError:
+        print("Workflow was cancelled")
+
+
+async def run_to_completion() -> None:
+    """Let the workflow run to completion and get the result."""
+    print("=== Run to completion ===\n")
+    workflow = build_workflow()
+
+    # Run without cancellation - await the result directly
+    result = await workflow.run("hello world")
+
+    print(f"\nWorkflow completed with output: {result.get_outputs()}")
+
+
+async def main() -> None:
+    """Demonstrate both cancellation and completion scenarios."""
+    await run_with_cancellation()
+    print("\n")
+    await run_to_completion()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/workflows/declarative/README.md

@@ -0,0 +1,74 @@
+# Declarative Workflows
+
+Declarative workflows allow you to define multi-agent orchestration patterns in YAML, including:
+- Variable manipulation and state management
+- Control flow (loops, conditionals, branching)
+- Agent invocations
+- Human-in-the-loop patterns
+
+See the [main workflows README](../README.md#declarative) for the list of available samples.
+
+## Prerequisites
+
+```bash
+pip install agent-framework-declarative
+```
+
+## Running Samples
+
+Each sample directory contains:
+- `workflow.yaml` - The declarative workflow definition
+- `main.py` - Python code to load and execute the workflow
+- `README.md` - Sample-specific documentation
+
+To run a sample:
+
+```bash
+cd <sample_directory>
+python main.py
+```
+
+## Workflow Structure
+
+A basic workflow YAML file looks like:
+
+```yaml
+name: my-workflow
+description: A simple workflow example
+
+actions:
+  - kind: SetValue
+    path: turn.greeting
+    value: Hello, World!
+    
+  - kind: SendActivity
+    activity:
+      text: =turn.greeting
+```
+
+## Action Types
+
+### Variable Actions
+- `SetValue` - Set a variable in state
+- `SetVariable` - Set a variable (.NET style naming)
+- `AppendValue` - Append to a list
+- `ResetVariable` - Clear a variable
+
+### Control Flow
+- `If` - Conditional branching
+- `Switch` - Multi-way branching
+- `Foreach` - Iterate over collections
+- `RepeatUntil` - Loop until condition
+- `GotoAction` - Jump to labeled action
+
+### Output
+- `SendActivity` - Send text/attachments to user
+- `EmitEvent` - Emit custom events
+
+### Agent Invocation
+- `InvokeAzureAgent` - Call an Azure AI agent
+- `InvokePromptAgent` - Call a local prompt agent
+
+### Human-in-Loop
+- `Question` - Request user input
+- `WaitForInput` - Pause for external input

python/samples/getting_started/workflows/declarative/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Declarative workflows samples package."""

python/samples/getting_started/workflows/declarative/conditional_workflow/README.md

@@ -0,0 +1,23 @@
+# Conditional Workflow Sample
+
+This sample demonstrates control flow with conditions:
+- If/else branching
+- Switch statements
+- Nested conditions
+
+## Files
+
+- `workflow.yaml` - The workflow definition
+- `main.py` - Python code to execute the workflow
+
+## Running
+
+```bash
+python main.py
+```
+
+## What It Does
+
+1. Takes a user's age as input
+2. Uses conditions to determine an age category
+3. Sends appropriate messages based on the category

python/samples/getting_started/workflows/declarative/conditional_workflow/main.py

@@ -0,0 +1,52 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""
+Run the conditional workflow sample.
+
+Usage:
+    python main.py
+
+Demonstrates conditional branching based on age input.
+"""
+
+import asyncio
+from pathlib import Path
+
+from agent_framework.declarative import WorkflowFactory
+
+
+async def main() -> None:
+    """Run the conditional workflow with various age inputs."""
+    # Create a workflow factory
+    factory = WorkflowFactory()
+
+    # Load the workflow from YAML
+    workflow_path = Path(__file__).parent / "workflow.yaml"
+    workflow = factory.create_workflow_from_yaml_path(workflow_path)
+
+    print(f"Loaded workflow: {workflow.name}")
+    print("-" * 40)
+
+    # Print out the executors in this workflow
+    print("\nExecutors in workflow:")
+    for executor_id, executor in workflow.executors.items():
+        print(f"  - {executor_id}: {type(executor).__name__}")
+    print("-" * 40)
+
+    # Test with different ages
+    test_ages = [8, 15, 35, 70]
+
+    for age in test_ages:
+        print(f"\n--- Testing with age: {age} ---")
+
+        # Run the workflow with age input
+        result = await workflow.run({"age": age})
+        for output in result.get_outputs():
+            print(f"  Output: {output}")
+
+    print("\n" + "-" * 40)
+    print("Workflow completed for all test cases!")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/workflows/declarative/conditional_workflow/workflow.yaml

@@ -0,0 +1,69 @@
+name: conditional-workflow
+description: Demonstrates conditional branching based on user input
+
+# Declare expected inputs with their types
+inputs:
+  age:
+    type: integer
+    description: The user's age in years
+
+actions:
+  # Get the age from input
+  - kind: SetValue
+    id: get_age
+    displayName: Get user age
+    path: Local.age
+    value: =inputs.age
+
+  # Determine age category using nested conditions
+  - kind: If
+    id: check_age
+    displayName: Check age category
+    condition: =Local.age < 13
+    then:
+      - kind: SetValue
+        path: Local.category
+        value: child
+      - kind: SendActivity
+        activity:
+          text: "Welcome, young one! Here are some fun activities for kids."
+    else:
+      - kind: If
+        condition: =Local.age < 20
+        then:
+          - kind: SetValue
+            path: Local.category
+            value: teenager
+          - kind: SendActivity
+            activity:
+              text: "Hey there! Check out these cool things for teens."
+        else:
+          - kind: If
+            condition: =Local.age < 65
+            then:
+              - kind: SetValue
+                path: Local.category
+                value: adult
+              - kind: SendActivity
+                activity:
+                  text: "Welcome! Here are our professional services."
+            else:
+              - kind: SetValue
+                path: Local.category
+                value: senior
+              - kind: SendActivity
+                activity:
+                  text: "Welcome! Enjoy our senior member benefits."
+
+  # Send a summary
+  - kind: SendActivity
+    id: summary
+    displayName: Send category summary
+    activity:
+      text: '=Concat("You have been categorized as: ", Local.category)'
+
+  # Store result
+  - kind: SetValue
+    id: set_output
+    path: Workflow.Outputs.category
+    value: =Local.category

python/samples/getting_started/workflows/declarative/customer_support/README.md

@@ -0,0 +1,37 @@
+# Customer Support Workflow Sample
+
+Multi-agent workflow demonstrating automated troubleshooting with escalation paths.
+
+## Overview
+
+Coordinates six specialized agents to handle customer support requests:
+
+1. **SelfServiceAgent** - Initial troubleshooting with user
+2. **TicketingAgent** - Creates tickets when escalation needed
+3. **TicketRoutingAgent** - Routes to appropriate team
+4. **WindowsSupportAgent** - Windows-specific troubleshooting
+5. **TicketResolutionAgent** - Resolves tickets
+6. **TicketEscalationAgent** - Escalates to human support
+
+## Files
+
+- `workflow.yaml` - Workflow definition with conditional routing
+- `main.py` - Agent definitions and workflow execution
+- `ticketing_plugin.py` - Mock ticketing system plugin
+
+## Running
+
+```bash
+python main.py
+```
+
+## Example Input
+
+```
+My PC keeps rebooting and I can't use it.
+```
+
+## Requirements
+
+- Azure OpenAI endpoint configured
+- `az login` for authentication

python/samples/getting_started/workflows/declarative/customer_support/__init__.py

@@ -0,0 +1 @@
+# Copyright (c) Microsoft. All rights reserved.

python/samples/getting_started/workflows/declarative/customer_support/main.py

@@ -0,0 +1,341 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""
+CustomerSupport workflow sample.
+
+This workflow demonstrates using multiple agents to provide automated
+troubleshooting steps to resolve common issues with escalation options.
+
+Example input: "My PC keeps rebooting and I can't use it."
+
+Usage:
+    python main.py
+
+The workflow:
+1. SelfServiceAgent: Works with user to provide troubleshooting steps
+2. TicketingAgent: Creates a ticket if issue needs escalation
+3. TicketRoutingAgent: Determines which team should handle the ticket
+4. WindowsSupportAgent: Provides Windows-specific troubleshooting
+5. TicketResolutionAgent: Resolves the ticket when issue is fixed
+6. TicketEscalationAgent: Escalates to human support if needed
+"""
+
+import asyncio
+import json
+import logging
+import uuid
+from pathlib import Path
+
+from agent_framework import RequestInfoEvent, WorkflowOutputEvent
+from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.declarative import (
+    AgentExternalInputRequest,
+    AgentExternalInputResponse,
+    WorkflowFactory,
+)
+from azure.identity import AzureCliCredential
+from pydantic import BaseModel, Field
+from ticketing_plugin import TicketingPlugin
+
+logging.basicConfig(level=logging.ERROR)
+
+# ANSI color codes for output formatting
+CYAN = "\033[36m"
+GREEN = "\033[32m"
+YELLOW = "\033[33m"
+MAGENTA = "\033[35m"
+RESET = "\033[0m"
+
+# Agent Instructions
+
+SELF_SERVICE_INSTRUCTIONS = """
+Use your knowledge to work with the user to provide the best possible troubleshooting steps.
+
+- If the user confirms that the issue is resolved, then the issue is resolved.
+- If the user reports that the issue persists, then escalate.
+""".strip()
+
+TICKETING_INSTRUCTIONS = """Always create a ticket in Azure DevOps using the available tools.
+
+Include the following information in the TicketSummary.
+
+- Issue description: {{IssueDescription}}
+- Attempted resolution steps: {{AttemptedResolutionSteps}}
+
+After creating the ticket, provide the user with the ticket ID."""
+
+TICKET_ROUTING_INSTRUCTIONS = """Determine how to route the given issue to the appropriate support team.
+
+Choose from the available teams and their functions:
+- Windows Activation Support: Windows license activation issues
+- Windows Support: Windows related issues
+- Azure Support: Azure related issues
+- Network Support: Network related issues
+- Hardware Support: Hardware related issues
+- Microsoft Office Support: Microsoft Office related issues
+- General Support: General issues not related to the above categories"""
+
+WINDOWS_SUPPORT_INSTRUCTIONS = """
+Use your knowledge to work with the user to provide the best possible troubleshooting steps
+for issues related to Windows operating system.
+
+- Utilize the "Attempted Resolutions Steps" as a starting point for your troubleshooting.
+- Never escalate without troubleshooting with the user.
+- If the user confirms that the issue is resolved, then the issue is resolved.
+- If the user reports that the issue persists, then escalate.
+
+Issue: {{IssueDescription}}
+Attempted Resolution Steps: {{AttemptedResolutionSteps}}"""
+
+RESOLUTION_INSTRUCTIONS = """Resolve the following ticket in Azure DevOps.
+Always include the resolution details.
+
+- Ticket ID: #{{TicketId}}
+- Resolution Summary: {{ResolutionSummary}}"""
+
+ESCALATION_INSTRUCTIONS = """
+You escalate the provided issue to human support team by sending an email.
+
+Here are some additional details that might help:
+- TicketId : {{TicketId}}
+- IssueDescription : {{IssueDescription}}
+- AttemptedResolutionSteps : {{AttemptedResolutionSteps}}
+
+Before escalating, gather the user's email address for follow-up.
+If not known, ask the user for their email address so that the support team can reach them when needed.
+
+When sending the email, include the following details:
+- To: support@contoso.com
+- Cc: user's email address
+- Subject of the email: "Support Ticket - {TicketId} - [Compact Issue Description]"
+- Body:
+  - Issue description
+  - Attempted resolution steps
+  - User's email address
+  - Any other relevant information from the conversation history
+
+Assure the user that their issue will be resolved and provide them with a ticket ID for reference."""
+
+
+# Pydantic models for structured outputs
+
+
+class SelfServiceResponse(BaseModel):
+    """Response from self-service agent evaluation."""
+
+    IsResolved: bool = Field(description="True if the user issue/ask has been resolved.")
+    NeedsTicket: bool = Field(description="True if the user issue/ask requires that a ticket be filed.")
+    IssueDescription: str = Field(description="A concise description of the issue.")
+    AttemptedResolutionSteps: str = Field(description="An outline of the steps taken to attempt resolution.")
+
+
+class TicketingResponse(BaseModel):
+    """Response from ticketing agent."""
+
+    TicketId: str = Field(description="The identifier of the ticket created in response to the user issue.")
+    TicketSummary: str = Field(description="The summary of the ticket created in response to the user issue.")
+
+
+class RoutingResponse(BaseModel):
+    """Response from routing agent."""
+
+    TeamName: str = Field(description="The name of the team to route the issue")
+
+
+class SupportResponse(BaseModel):
+    """Response from support agent."""
+
+    IsResolved: bool = Field(description="True if the user issue/ask has been resolved.")
+    NeedsEscalation: bool = Field(
+        description="True resolution could not be achieved and the issue/ask requires escalation."
+    )
+    ResolutionSummary: str = Field(description="The summary of the steps that led to resolution.")
+
+
+class EscalationResponse(BaseModel):
+    """Response from escalation agent."""
+
+    IsComplete: bool = Field(description="Has the email been sent and no more user input is required.")
+    UserMessage: str = Field(description="A natural language message to the user.")
+
+
+async def main() -> None:
+    """Run the customer support workflow."""
+    # Create ticketing plugin
+    plugin = TicketingPlugin()
+
+    # Create Azure OpenAI client
+    chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
+
+    # Create agents with structured outputs
+    self_service_agent = chat_client.as_agent(
+        name="SelfServiceAgent",
+        instructions=SELF_SERVICE_INSTRUCTIONS,
+        default_options={"response_format": SelfServiceResponse},
+    )
+
+    ticketing_agent = chat_client.as_agent(
+        name="TicketingAgent",
+        instructions=TICKETING_INSTRUCTIONS,
+        tools=plugin.get_functions(),
+        default_options={"response_format": TicketingResponse},
+    )
+
+    routing_agent = chat_client.as_agent(
+        name="TicketRoutingAgent",
+        instructions=TICKET_ROUTING_INSTRUCTIONS,
+        tools=[plugin.get_ticket],
+        default_options={"response_format": RoutingResponse},
+    )
+
+    windows_support_agent = chat_client.as_agent(
+        name="WindowsSupportAgent",
+        instructions=WINDOWS_SUPPORT_INSTRUCTIONS,
+        tools=[plugin.get_ticket],
+        default_options={"response_format": SupportResponse},
+    )
+
+    resolution_agent = chat_client.as_agent(
+        name="TicketResolutionAgent",
+        instructions=RESOLUTION_INSTRUCTIONS,
+        tools=[plugin.resolve_ticket],
+    )
+
+    escalation_agent = chat_client.as_agent(
+        name="TicketEscalationAgent",
+        instructions=ESCALATION_INSTRUCTIONS,
+        tools=[plugin.get_ticket, plugin.send_notification],
+        default_options={"response_format": EscalationResponse},
+    )
+
+    # Agent registry for lookup
+    agents = {
+        "SelfServiceAgent": self_service_agent,
+        "TicketingAgent": ticketing_agent,
+        "TicketRoutingAgent": routing_agent,
+        "WindowsSupportAgent": windows_support_agent,
+        "TicketResolutionAgent": resolution_agent,
+        "TicketEscalationAgent": escalation_agent,
+    }
+
+    # Print loaded agents (similar to .NET "PROMPT AGENT: AgentName:1")
+    for agent_name in agents:
+        print(f"{CYAN}PROMPT AGENT: {agent_name}:1{RESET}")
+
+    # Create workflow factory
+    factory = WorkflowFactory(agents=agents)
+
+    # Load workflow from YAML
+    samples_root = Path(__file__).parent.parent.parent.parent.parent.parent.parent
+    workflow_path = samples_root / "workflow-samples" / "CustomerSupport.yaml"
+    if not workflow_path.exists():
+        # Fall back to local copy if workflow-samples doesn't exist
+        workflow_path = Path(__file__).parent / "workflow.yaml"
+
+    workflow = factory.create_workflow_from_yaml_path(workflow_path)
+
+    print()
+    print("=" * 60)
+
+    # Example input
+    user_input = "My computer won't boot"
+    pending_request_id: str | None = None
+
+    # Track responses for formatting
+    accumulated_response: str = ""
+    last_agent_name: str | None = None
+
+    print(f"\n{GREEN}INPUT:{RESET} {user_input}\n")
+
+    while True:
+        if pending_request_id:
+            # Continue workflow with user response
+            print(f"\n{YELLOW}WORKFLOW:{RESET} Restore\n")
+            response = AgentExternalInputResponse(user_input=user_input)
+            stream = workflow.send_responses_streaming({pending_request_id: response})
+            pending_request_id = None
+        else:
+            # Start workflow
+            stream = workflow.run_stream(user_input)
+
+        async for event in stream:
+            if isinstance(event, WorkflowOutputEvent):
+                data = event.data
+                source_id = getattr(event, "source_executor_id", "")
+
+                # Check if this is a SendActivity output (activity text from log_ticket, log_route, etc.)
+                if "log_" in source_id.lower():
+                    # Print any accumulated agent response first
+                    if accumulated_response and last_agent_name:
+                        msg_id = f"msg_{uuid.uuid4().hex[:32]}"
+                        print(f"{CYAN}{last_agent_name.upper()}:{RESET} [{msg_id}]")
+                        try:
+                            parsed = json.loads(accumulated_response)
+                            print(json.dumps(parsed))
+                        except (json.JSONDecodeError, TypeError):
+                            print(accumulated_response)
+                        accumulated_response = ""
+                        last_agent_name = None
+                    # Print activity
+                    print(f"\n{MAGENTA}ACTIVITY:{RESET}")
+                    print(data)
+                else:
+                    # Accumulate agent response (streaming text)
+                    if isinstance(data, str):
+                        accumulated_response += data
+                    else:
+                        accumulated_response += str(data)
+
+            elif isinstance(event, RequestInfoEvent) and isinstance(event.data, AgentExternalInputRequest):
+                request = event.data
+
+                # The agent_response from the request contains the structured response
+                agent_name = request.agent_name
+                agent_response = request.agent_response
+
+                # Print the agent's response
+                if agent_response:
+                    msg_id = f"msg_{uuid.uuid4().hex[:32]}"
+                    print(f"{CYAN}{agent_name.upper()}:{RESET} [{msg_id}]")
+                    try:
+                        parsed = json.loads(agent_response)
+                        print(json.dumps(parsed))
+                    except (json.JSONDecodeError, TypeError):
+                        print(agent_response)
+
+                # Clear accumulated since we printed from the request
+                accumulated_response = ""
+                last_agent_name = agent_name
+
+                pending_request_id = event.request_id
+                print(f"\n{YELLOW}WORKFLOW:{RESET} Yield")
+
+        # Print any remaining accumulated response at end of stream
+        if accumulated_response:
+            # Try to identify which agent this came from based on content
+            msg_id = f"msg_{uuid.uuid4().hex[:32]}"
+            print(f"\nResponse: [{msg_id}]")
+            try:
+                parsed = json.loads(accumulated_response)
+                print(json.dumps(parsed))
+            except (json.JSONDecodeError, TypeError):
+                print(accumulated_response)
+            accumulated_response = ""
+
+        if not pending_request_id:
+            break
+
+        # Get next user input
+        user_input = input(f"\n{GREEN}INPUT:{RESET} ").strip()  # noqa: ASYNC250
+        if not user_input:
+            print("Exiting...")
+            break
+        print()
+
+    print("\n" + "=" * 60)
+    print("Workflow Complete")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/workflows/declarative/customer_support/ticketing_plugin.py

@@ -0,0 +1,79 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Ticketing plugin for CustomerSupport workflow."""
+
+import uuid
+from dataclasses import dataclass
+from enum import Enum
+from collections.abc import Callable
+
+# ANSI color codes
+MAGENTA = "\033[35m"
+RESET = "\033[0m"
+
+
+class TicketStatus(Enum):
+    """Status of a support ticket."""
+
+    OPEN = "open"
+    IN_PROGRESS = "in_progress"
+    RESOLVED = "resolved"
+    CLOSED = "closed"
+
+
+@dataclass
+class TicketItem:
+    """A support ticket."""
+
+    id: str
+    subject: str = ""
+    description: str = ""
+    notes: str = ""
+    status: TicketStatus = TicketStatus.OPEN
+
+
+class TicketingPlugin:
+    """Mock ticketing plugin for customer support workflow."""
+
+    def __init__(self) -> None:
+        self._ticket_store: dict[str, TicketItem] = {}
+
+    def _trace(self, function_name: str) -> None:
+        print(f"\n{MAGENTA}FUNCTION: {function_name}{RESET}")
+
+    def get_ticket(self, id: str) -> TicketItem | None:
+        """Retrieve a ticket by identifier from Azure DevOps."""
+        self._trace("get_ticket")
+        return self._ticket_store.get(id)
+
+    def create_ticket(self, subject: str, description: str, notes: str) -> str:
+        """Create a ticket in Azure DevOps and return its identifier."""
+        self._trace("create_ticket")
+        ticket_id = uuid.uuid4().hex
+        ticket = TicketItem(
+            id=ticket_id,
+            subject=subject,
+            description=description,
+            notes=notes,
+        )
+        self._ticket_store[ticket_id] = ticket
+        return ticket_id
+
+    def resolve_ticket(self, id: str, resolution_summary: str) -> None:
+        """Resolve an existing ticket in Azure DevOps given its identifier."""
+        self._trace("resolve_ticket")
+        if ticket := self._ticket_store.get(id):
+            ticket.status = TicketStatus.RESOLVED
+
+    def send_notification(self, id: str, email: str, cc: str, body: str) -> None:
+        """Send an email notification to escalate ticket engagement."""
+        self._trace("send_notification")
+
+    def get_functions(self) -> list[Callable[..., object]]:
+        """Return all plugin functions for registration."""
+        return [
+            self.get_ticket,
+            self.create_ticket,
+            self.resolve_ticket,
+            self.send_notification,
+        ]

python/samples/getting_started/workflows/declarative/customer_support/workflow.yaml

@@ -0,0 +1,164 @@
+#
+# This workflow demonstrates using multiple agents to provide automated
+# troubleshooting steps to resolve common issues with escalation options.
+#
+# Example input: 
+# My PC keeps rebooting and I can't use it.
+#
+kind: Workflow
+trigger:
+
+  kind: OnConversationStart
+  id: workflow_demo
+  actions:
+
+    # Interact with user until the issue has been resolved or 
+    # a determination is made that a ticket is required.
+    - kind: InvokeAzureAgent
+      id: service_agent
+      conversationId: =System.ConversationId
+      agent:
+        name: SelfServiceAgent
+      input:
+        externalLoop:
+          when: |-
+            =Not(Local.ServiceParameters.IsResolved)
+             And 
+             Not(Local.ServiceParameters.NeedsTicket)
+      output:
+        responseObject: Local.ServiceParameters
+
+    # All done if issue is resolved.
+    - kind: ConditionGroup
+      id: check_if_resolved
+      conditions:
+    
+        - condition: =Local.ServiceParameters.IsResolved
+          id: test_if_resolved
+          actions:
+            - kind: GotoAction
+              id: end_when_resolved
+              actionId: all_done
+    
+    # Create the ticket.
+    - kind: InvokeAzureAgent
+      id: ticket_agent
+      agent:
+        name: TicketingAgent
+      input:
+        arguments:
+          IssueDescription: =Local.ServiceParameters.IssueDescription
+          AttemptedResolutionSteps: =Local.ServiceParameters.AttemptedResolutionSteps
+      output:
+        responseObject: Local.TicketParameters
+
+    # Capture the attempted resolution steps.
+    - kind: SetVariable
+      id: capture_attempted_resolution
+      variable: Local.ResolutionSteps
+      value: =Local.ServiceParameters.AttemptedResolutionSteps
+
+    # Notify user of ticket identifier.
+    - kind: SendActivity
+      id: log_ticket
+      activity: "Created ticket #{Local.TicketParameters.TicketId}"
+
+    # Determine which team for which route the ticket.
+    - kind: InvokeAzureAgent
+      id: routing_agent
+      agent:
+        name: TicketRoutingAgent
+      input:
+        messages: =UserMessage(Local.ServiceParameters.IssueDescription)
+      output:
+        responseObject: Local.RoutingParameters
+
+    # Notify user of routing decision.
+    - kind: SendActivity
+      id: log_route
+      activity: Routing to {Local.RoutingParameters.TeamName}
+
+    - kind: ConditionGroup
+      id: check_routing
+      conditions:
+
+        - condition: =Local.RoutingParameters.TeamName = "Windows Support"
+          id: route_to_support
+          actions:
+
+            # Invoke the support agent to attempt to resolve the issue.
+            - kind: CreateConversation
+              id: conversation_support
+              conversationId: Local.SupportConversationId
+
+            - kind: InvokeAzureAgent
+              id: support_agent
+              conversationId: =Local.SupportConversationId
+              agent:
+                name: WindowsSupportAgent
+              input:
+                arguments:
+                  IssueDescription: =Local.ServiceParameters.IssueDescription
+                  AttemptedResolutionSteps: =Local.ServiceParameters.AttemptedResolutionSteps
+                externalLoop:
+                  when: |-
+                    =Not(Local.SupportParameters.IsResolved)
+                     And 
+                     Not(Local.SupportParameters.NeedsEscalation)
+              output:
+                autoSend: true
+                responseObject: Local.SupportParameters
+
+            # Capture the attempted resolution steps.
+            - kind: SetVariable
+              id: capture_support_resolution
+              variable: Local.ResolutionSteps
+              value: =Local.SupportParameters.ResolutionSummary
+
+            # Check if the issue was resolved by support.
+            - kind: ConditionGroup
+              id: check_resolved
+              conditions:
+
+                # Resolve ticket
+                - condition: =Local.SupportParameters.IsResolved
+                  id: handle_if_resolved
+                  actions:
+        
+                    - kind: InvokeAzureAgent
+                      id: resolution_agent
+                      agent:
+                        name: TicketResolutionAgent
+                      input:
+                        arguments:
+                          TicketId: =Local.TicketParameters.TicketId
+                          ResolutionSummary: =Local.SupportParameters.ResolutionSummary
+
+                    - kind: GotoAction
+                      id: end_when_solved
+                      actionId: all_done
+
+    # Escalate the ticket by sending an email notification.
+    - kind: CreateConversation
+      id: conversation_escalate
+      conversationId: Local.EscalationConversationId
+
+    - kind: InvokeAzureAgent
+      id: escalate_agent
+      conversationId: =Local.EscalationConversationId
+      agent:
+        name: TicketEscalationAgent
+      input:
+        arguments:
+          TicketId: =Local.TicketParameters.TicketId
+          IssueDescription: =Local.ServiceParameters.IssueDescription
+          ResolutionSummary: =Local.ResolutionSteps
+        externalLoop:
+          when: =Not(Local.EscalationParameters.IsComplete)
+      output:
+        autoSend: true
+        responseObject: Local.EscalationParameters
+
+    # All done
+    - kind: EndWorkflow
+      id: all_done

python/samples/getting_started/workflows/declarative/deep_research/README.md

@@ -0,0 +1,33 @@
+# Deep Research Workflow Sample
+
+Multi-agent workflow implementing the "Magentic" orchestration pattern from AutoGen.
+
+## Overview
+
+Coordinates specialized agents for complex research tasks:
+
+**Orchestration Agents:**
+- **ResearchAgent** - Analyzes tasks and correlates relevant facts
+- **PlannerAgent** - Devises execution plans
+- **ManagerAgent** - Evaluates status and delegates tasks
+- **SummaryAgent** - Synthesizes final responses
+
+**Capability Agents:**
+- **KnowledgeAgent** - Performs web searches
+- **CoderAgent** - Writes and executes code
+- **WeatherAgent** - Provides weather information
+
+## Files
+
+- `main.py` - Agent definitions and workflow execution (programmatic workflow)
+
+## Running
+
+```bash
+python main.py
+```
+
+## Requirements
+
+- Azure OpenAI endpoint configured
+- `az login` for authentication

python/samples/getting_started/workflows/declarative/deep_research/__init__.py

@@ -0,0 +1 @@
+# Copyright (c) Microsoft. All rights reserved.

python/samples/getting_started/workflows/declarative/deep_research/main.py

@@ -0,0 +1,205 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""
+DeepResearch workflow sample.
+
+This workflow coordinates multiple agents to address complex user requests
+according to the "Magentic" orchestration pattern introduced by AutoGen.
+
+The following agents are responsible for overseeing and coordinating the workflow:
+- ResearchAgent: Analyze the current task and correlate relevant facts
+- PlannerAgent: Analyze the current task and devise an overall plan
+- ManagerAgent: Evaluates status and delegates tasks to other agents
+- SummaryAgent: Synthesizes the final response
+
+The following agents have capabilities that are utilized to address the input task:
+- KnowledgeAgent: Performs generic web searches
+- CoderAgent: Able to write and execute code
+- WeatherAgent: Provides weather information
+
+Usage:
+    python main.py
+"""
+
+import asyncio
+from pathlib import Path
+
+from agent_framework import WorkflowOutputEvent
+from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.declarative import WorkflowFactory
+from azure.identity import AzureCliCredential
+from pydantic import BaseModel, Field
+
+# Agent Instructions
+
+RESEARCH_INSTRUCTIONS = """In order to help begin addressing the user request, please answer the following pre-survey to the best of your ability.
+Keep in mind that you are Ken Jennings-level with trivia, and Mensa-level with puzzles, so there should be a deep well to draw from.
+
+Here is the pre-survey:
+
+    1. Please list any specific facts or figures that are GIVEN in the request itself. It is possible that there are none.
+    2. Please list any facts that may need to be looked up, and WHERE SPECIFICALLY they might be found. In some cases, authoritative sources are mentioned in the request itself.
+    3. Please list any facts that may need to be derived (e.g., via logical deduction, simulation, or computation)
+    4. Please list any facts that are recalled from memory, hunches, well-reasoned guesses, etc.
+
+When answering this survey, keep in mind that 'facts' will typically be specific names, dates, statistics, etc. Your answer must only use the headings:
+
+    1. GIVEN OR VERIFIED FACTS
+    2. FACTS TO LOOK UP
+    3. FACTS TO DERIVE
+    4. EDUCATED GUESSES
+
+DO NOT include any other headings or sections in your response. DO NOT list next steps or plans until asked to do so."""  # noqa: E501
+
+PLANNER_INSTRUCTIONS = """Your only job is to devise an efficient plan that identifies (by name) how a team member may contribute to addressing the user request.
+
+Only select the following team which is listed as "- [Name]: [Description]"
+
+- WeatherAgent: Able to retrieve weather information
+- CoderAgent: Able to write and execute Python code
+- KnowledgeAgent: Able to perform generic websearches
+
+The plan must be a bullet point list must be in the form "- [AgentName]: [Specific action or task for that agent to perform]"
+
+Remember, there is no requirement to involve the entire team -- only select team member's whose particular expertise is required for this task."""  # noqa: E501
+
+MANAGER_INSTRUCTIONS = """Recall we have assembled the following team:
+
+- KnowledgeAgent: Able to perform generic websearches
+- CoderAgent: Able to write and execute Python code
+- WeatherAgent: Able to retrieve weather information
+
+To make progress on the request, please answer the following questions, including necessary reasoning:
+- Is the request fully satisfied? (True if complete, or False if the original request has yet to be SUCCESSFULLY and FULLY addressed)
+- Are we in a loop where we are repeating the same requests and / or getting the same responses from an agent multiple times? Loops can span multiple turns, and can include repeated actions like scrolling up or down more than a handful of times.
+- Are we making forward progress? (True if just starting, or recent messages are adding value. False if recent messages show evidence of being stuck in a loop or if there is evidence of significant barriers to success such as the inability to read from a required file)
+- Who should speak next? (select from: KnowledgeAgent, CoderAgent, WeatherAgent)
+- What instruction or question would you give this team member? (Phrase as if speaking directly to them, and include any specific information they may need)"""  # noqa: E501
+
+SUMMARY_INSTRUCTIONS = """We have completed the task.
+
+Based only on the conversation and without adding any new information,
+synthesize the result of the conversation as a complete response to the user task.
+
+The user will only ever see this last response and not the entire conversation,
+so please ensure it is complete and self-contained."""
+
+KNOWLEDGE_INSTRUCTIONS = """You are a knowledge agent that can perform web searches to find information."""
+
+CODER_INSTRUCTIONS = """You solve problems by writing and executing code."""
+
+WEATHER_INSTRUCTIONS = """You are a weather expert that can provide weather information."""
+
+
+# Pydantic models for structured outputs
+
+
+class ReasonedAnswer(BaseModel):
+    """A response with reasoning and answer."""
+
+    reason: str = Field(description="The reasoning behind the answer")
+    answer: bool = Field(description="The boolean answer")
+
+
+class ReasonedStringAnswer(BaseModel):
+    """A response with reasoning and string answer."""
+
+    reason: str = Field(description="The reasoning behind the answer")
+    answer: str = Field(description="The string answer")
+
+
+class ManagerResponse(BaseModel):
+    """Response from manager agent evaluation."""
+
+    is_request_satisfied: ReasonedAnswer = Field(description="Whether the request is fully satisfied")
+    is_in_loop: ReasonedAnswer = Field(description="Whether we are in a loop repeating the same requests")
+    is_progress_being_made: ReasonedAnswer = Field(description="Whether forward progress is being made")
+    next_speaker: ReasonedStringAnswer = Field(description="Who should speak next")
+    instruction_or_question: ReasonedStringAnswer = Field(
+        description="What instruction or question to give the next speaker"
+    )
+
+
+async def main() -> None:
+    """Run the deep research workflow."""
+    # Create Azure OpenAI client
+    chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
+
+    # Create agents
+    research_agent = chat_client.as_agent(
+        name="ResearchAgent",
+        instructions=RESEARCH_INSTRUCTIONS,
+    )
+
+    planner_agent = chat_client.as_agent(
+        name="PlannerAgent",
+        instructions=PLANNER_INSTRUCTIONS,
+    )
+
+    manager_agent = chat_client.as_agent(
+        name="ManagerAgent",
+        instructions=MANAGER_INSTRUCTIONS,
+        default_options={"response_format": ManagerResponse},
+    )
+
+    summary_agent = chat_client.as_agent(
+        name="SummaryAgent",
+        instructions=SUMMARY_INSTRUCTIONS,
+    )
+
+    knowledge_agent = chat_client.as_agent(
+        name="KnowledgeAgent",
+        instructions=KNOWLEDGE_INSTRUCTIONS,
+    )
+
+    coder_agent = chat_client.as_agent(
+        name="CoderAgent",
+        instructions=CODER_INSTRUCTIONS,
+    )
+
+    weather_agent = chat_client.as_agent(
+        name="WeatherAgent",
+        instructions=WEATHER_INSTRUCTIONS,
+    )
+
+    # Create workflow factory
+    factory = WorkflowFactory(
+        agents={
+            "ResearchAgent": research_agent,
+            "PlannerAgent": planner_agent,
+            "ManagerAgent": manager_agent,
+            "SummaryAgent": summary_agent,
+            "KnowledgeAgent": knowledge_agent,
+            "CoderAgent": coder_agent,
+            "WeatherAgent": weather_agent,
+        },
+    )
+
+    # Load workflow from YAML
+    samples_root = Path(__file__).parent.parent.parent.parent.parent.parent.parent
+    workflow_path = samples_root / "workflow-samples" / "DeepResearch.yaml"
+    if not workflow_path.exists():
+        # Fall back to local copy if workflow-samples doesn't exist
+        workflow_path = Path(__file__).parent / "workflow.yaml"
+
+    workflow = factory.create_workflow_from_yaml_path(workflow_path)
+
+    print(f"Loaded workflow: {workflow.name}")
+    print("=" * 60)
+    print("Deep Research Workflow (Magentic Pattern)")
+    print("=" * 60)
+
+    # Example input
+    task = "What is the weather like in Seattle and how does it compare to the average for this time of year?"
+
+    async for event in workflow.run_stream(task):
+        if isinstance(event, WorkflowOutputEvent):
+            print(f"{event.data}", end="", flush=True)
+
+    print("\n" + "=" * 60)
+    print("Research Complete")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/workflows/declarative/function_tools/README.md

@@ -0,0 +1,90 @@
+# Function Tools Workflow
+
+This sample demonstrates an agent with function tools responding to user queries about a restaurant menu.
+
+## Overview
+
+The workflow showcases:
+- **Function Tools**: Agent equipped with tools to query menu data
+- **Real Azure OpenAI Agent**: Uses `AzureOpenAIChatClient` to create an agent with tools
+- **Agent Registration**: Shows how to register agents with the `WorkflowFactory`
+
+## Tools
+
+The MenuAgent has access to these function tools:
+
+| Tool | Description |
+|------|-------------|
+| `get_menu()` | Returns all menu items with category, name, and price |
+| `get_specials()` | Returns today's special items |
+| `get_item_price(name)` | Returns the price of a specific item |
+
+## Menu Data
+
+```
+Soups:
+  - Clam Chowder - $4.95 (Special)
+  - Tomato Soup - $4.95
+
+Salads:
+  - Cobb Salad - $9.99
+  - House Salad - $4.95
+
+Drinks:
+  - Chai Tea - $2.95 (Special)
+  - Soda - $1.95
+```
+
+## Prerequisites
+
+- Azure OpenAI configured with required environment variables
+- Authentication via azure-identity (run `az login` before executing)
+
+## Usage
+
+```bash
+python main.py
+```
+
+## Example Output
+
+```
+Loaded workflow: function-tools-workflow
+============================================================
+Restaurant Menu Assistant
+============================================================
+
+[Bot]: Welcome to the Restaurant Menu Assistant!
+
+[Bot]: Today's soup special is the Clam Chowder for $4.95!
+
+============================================================
+Session Complete
+============================================================
+```
+
+## How It Works
+
+1. Create an Azure OpenAI chat client
+2. Create an agent with instructions and function tools
+3. Register the agent with the workflow factory
+4. Load the workflow YAML and run it with `run_stream()`
+
+```python
+# Create the agent with tools
+chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
+menu_agent = chat_client.as_agent(
+    name="MenuAgent",
+    instructions="You are a helpful restaurant menu assistant...",
+    tools=[get_menu, get_specials, get_item_price],
+)
+
+# Register with the workflow factory
+factory = WorkflowFactory(execution_mode="graph")
+factory.register_agent("MenuAgent", menu_agent)
+
+# Load and run the workflow
+workflow = factory.create_workflow_from_yaml_path(workflow_path)
+async for event in workflow.run_stream(inputs={"userInput": "What is the soup of the day?"}):
+    ...
+```

python/samples/getting_started/workflows/declarative/function_tools/main.py

@@ -0,0 +1,116 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""
+Demonstrate a workflow that responds to user input using an agent with
+function tools assigned. Exits the loop when the user enters "exit".
+"""
+
+import asyncio
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Annotated, Any
+
+from agent_framework import FileCheckpointStorage, RequestInfoEvent, WorkflowOutputEvent
+from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework_declarative import ExternalInputRequest, ExternalInputResponse, WorkflowFactory
+from azure.identity import AzureCliCredential
+from pydantic import Field
+
+TEMP_DIR = Path(__file__).with_suffix("").parent / "tmp" / "checkpoints"
+TEMP_DIR.mkdir(parents=True, exist_ok=True)
+
+
+@dataclass
+class MenuItem:
+    category: str
+    name: str
+    price: float
+    is_special: bool = False
+
+
+MENU_ITEMS = [
+    MenuItem(category="Soup", name="Clam Chowder", price=4.95, is_special=True),
+    MenuItem(category="Soup", name="Tomato Soup", price=4.95, is_special=False),
+    MenuItem(category="Salad", name="Cobb Salad", price=9.99, is_special=False),
+    MenuItem(category="Salad", name="House Salad", price=4.95, is_special=False),
+    MenuItem(category="Drink", name="Chai Tea", price=2.95, is_special=True),
+    MenuItem(category="Drink", name="Soda", price=1.95, is_special=False),
+]
+
+
+def get_menu() -> list[dict[str, Any]]:
+    """Get all menu items."""
+    return [{"category": i.category, "name": i.name, "price": i.price} for i in MENU_ITEMS]
+
+
+def get_specials() -> list[dict[str, Any]]:
+    """Get today's specials."""
+    return [{"category": i.category, "name": i.name, "price": i.price} for i in MENU_ITEMS if i.is_special]
+
+
+def get_item_price(name: Annotated[str, Field(description="Menu item name")]) -> str:
+    """Get price of a menu item."""
+    for item in MENU_ITEMS:
+        if item.name.lower() == name.lower():
+            return f"${item.price:.2f}"
+    return f"Item '{name}' not found."
+
+
+async def main():
+    # Create agent with tools
+    chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
+    menu_agent = chat_client.as_agent(
+        name="MenuAgent",
+        instructions="Answer questions about menu items, specials, and prices.",
+        tools=[get_menu, get_specials, get_item_price],
+    )
+
+    # Clean up any existing checkpoints
+    for file in TEMP_DIR.glob("*"):
+        file.unlink()
+
+    factory = WorkflowFactory(checkpoint_storage=FileCheckpointStorage(TEMP_DIR))
+    factory.register_agent("MenuAgent", menu_agent)
+    workflow = factory.create_workflow_from_yaml_path(Path(__file__).parent / "workflow.yaml")
+
+    # Get initial input
+    print("Restaurant Menu Assistant (type 'exit' to quit)\n")
+    user_input = input("You: ").strip()  # noqa: ASYNC250
+    if not user_input:
+        return
+
+    # Run workflow with external loop handling
+    pending_request_id: str | None = None
+    first_response = True
+
+    while True:
+        if pending_request_id:
+            response = ExternalInputResponse(user_input=user_input)
+            stream = workflow.send_responses_streaming({pending_request_id: response})
+        else:
+            stream = workflow.run_stream({"userInput": user_input})
+
+        pending_request_id = None
+        first_response = True
+
+        async for event in stream:
+            if isinstance(event, WorkflowOutputEvent) and isinstance(event.data, str):
+                if first_response:
+                    print("MenuAgent: ", end="")
+                    first_response = False
+                print(event.data, end="", flush=True)
+            elif isinstance(event, RequestInfoEvent) and isinstance(event.data, ExternalInputRequest):
+                pending_request_id = event.request_id
+
+        print()
+
+        if not pending_request_id:
+            break
+
+        user_input = input("\nYou: ").strip()
+        if not user_input:
+            continue
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/workflows/declarative/function_tools/workflow.yaml

@@ -0,0 +1,22 @@
+# Function Tools Workflow - .NET-style
+#
+# This workflow demonstrates an agent with function tools in a loop
+# responding to user input, using the same minimal structure as .NET.
+#
+# Example input:
+# What is the soup of the day?
+#
+kind: Workflow
+trigger:
+
+  kind: OnConversationStart
+  id: workflow_demo
+  actions:
+
+    - kind: InvokeAzureAgent
+      id: invoke_menu_agent
+      agent:
+        name: MenuAgent
+      input:
+        externalLoop:
+          when: =Upper(System.LastMessage.Text) <> "EXIT"

python/samples/getting_started/workflows/declarative/human_in_loop/README.md

@@ -0,0 +1,59 @@
+# Human-in-Loop Workflow Sample
+
+This sample demonstrates how to build interactive workflows that request user input during execution using the `Question`, `RequestExternalInput`, and `WaitForInput` actions.
+
+## What This Sample Shows
+
+- Using `Question` to prompt for user responses
+- Using `RequestExternalInput` to request external data
+- Using `WaitForInput` to pause and wait for input
+- Processing user responses to drive workflow decisions
+- Interactive conversation patterns
+
+## Files
+
+- `workflow.yaml` - The declarative workflow definition
+- `main.py` - Python script that loads and runs the workflow with simulated user interaction
+
+## Running the Sample
+
+1. Ensure you have the package installed:
+   ```bash
+   cd python
+   pip install -e packages/agent-framework-declarative
+   ```
+
+2. Run the sample:
+   ```bash
+   python main.py
+   ```
+
+## How It Works
+
+The workflow demonstrates a simple survey/questionnaire pattern:
+
+1. **Greeting**: Sends a welcome message
+2. **Question 1**: Asks for the user's name
+3. **Question 2**: Asks how they're feeling today
+4. **Processing**: Stores responses and provides personalized feedback
+5. **Summary**: Summarizes the collected information
+
+The `main.py` script shows how to handle `ExternalInputRequest` to provide responses during workflow execution.
+
+## Key Concepts
+
+### ExternalInputRequest
+
+When a human-in-loop action is executed, the workflow yields an `ExternalInputRequest` containing:
+- `variable`: The variable path where the response should be stored
+- `prompt`: The question or prompt text for the user
+
+The workflow runner should:
+1. Detect `ExternalInputRequest` in the event stream
+2. Display the prompt to the user
+3. Collect the response
+4. Resume the workflow (in a real implementation, using external loop patterns)
+
+### ExternalLoopEvent
+
+For more complex scenarios where external processing is needed, the workflow can yield an `ExternalLoopEvent` that signals the runner to pause and wait for external input.

python/samples/getting_started/workflows/declarative/human_in_loop/main.py

@@ -0,0 +1,84 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""
+Run the human-in-loop workflow sample.
+
+Usage:
+    python main.py
+
+Demonstrates interactive workflows that request user input.
+
+Note: This sample shows the conceptual pattern for handling ExternalInputRequest.
+In a production scenario, you would integrate with a real UI or chat interface.
+"""
+
+import asyncio
+from pathlib import Path
+
+from agent_framework import Workflow, WorkflowOutputEvent
+from agent_framework.declarative import ExternalInputRequest, WorkflowFactory
+from agent_framework_declarative._workflows._handlers import TextOutputEvent
+
+
+async def run_with_streaming(workflow: Workflow) -> None:
+    """Demonstrate streaming workflow execution with run_stream()."""
+    print("\n=== Streaming Execution (run_stream) ===")
+    print("-" * 40)
+
+    async for event in workflow.run_stream({}):
+        # WorkflowOutputEvent wraps the actual output data
+        if isinstance(event, WorkflowOutputEvent):
+            data = event.data
+            if isinstance(data, TextOutputEvent):
+                print(f"[Bot]: {data.text}")
+            elif isinstance(data, ExternalInputRequest):
+                # In a real scenario, you would:
+                # 1. Display the prompt to the user
+                # 2. Wait for their response
+                # 3. Use the response to continue the workflow
+                output_property = data.metadata.get("output_property", "unknown")
+                print(f"[System] Input requested for: {output_property}")
+                if data.message:
+                    print(f"[System] Prompt: {data.message}")
+            else:
+                print(f"[Output]: {data}")
+
+
+async def run_with_result(workflow: Workflow) -> None:
+    """Demonstrate batch workflow execution with run()."""
+    print("\n=== Batch Execution (run) ===")
+    print("-" * 40)
+
+    result = await workflow.run({})
+    for output in result.get_outputs():
+        print(f"  Output: {output}")
+
+
+async def main() -> None:
+    """Run the human-in-loop workflow demonstrating both execution styles."""
+    # Create a workflow factory
+    factory = WorkflowFactory()
+
+    # Load the workflow from YAML
+    workflow_path = Path(__file__).parent / "workflow.yaml"
+    workflow = factory.create_workflow_from_yaml_path(workflow_path)
+
+    print(f"Loaded workflow: {workflow.name}")
+    print("=== Human-in-Loop Workflow Demo ===")
+    print("(Using simulated responses for demonstration)")
+
+    # Demonstrate streaming execution
+    await run_with_streaming(workflow)
+
+    # Demonstrate batch execution
+    # await run_with_result(workflow)
+
+    print("\n" + "-" * 40)
+    print("=== Workflow Complete ===")
+    print()
+    print("Note: This demo uses simulated responses. In a real application,")
+    print("you would integrate with a chat interface to collect actual user input.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/workflows/declarative/human_in_loop/workflow.yaml

@@ -0,0 +1,75 @@
+name: human-in-loop-workflow
+description: Interactive workflow that requests user input
+
+actions:
+  # Welcome message
+  - kind: SendActivity
+    id: greeting
+    displayName: Send greeting
+    activity:
+      text: "Welcome to the interactive survey!"
+
+  # Ask for name
+  - kind: Question
+    id: ask_name
+    displayName: Ask for user name
+    question:
+      text: "What is your name?"
+    variable: Local.userName
+    default: "Demo User"
+
+  # Personalized greeting
+  - kind: SendActivity
+    id: personalized_greeting
+    displayName: Send personalized greeting
+    activity:
+      text: =Concat("Nice to meet you, ", Local.userName, "!")
+
+  # Ask how they're feeling
+  - kind: Question
+    id: ask_feeling
+    displayName: Ask about feelings
+    question:
+      text: "How are you feeling today? (great/good/okay/not great)"
+    variable: Local.feeling
+    default: "great"
+
+  # Respond based on feeling
+  - kind: If
+    id: check_feeling
+    displayName: Check user feeling
+    condition: =Or(Local.feeling = "great", Local.feeling = "good")
+    then:
+      - kind: SendActivity
+        activity:
+          text: "That's wonderful to hear! Let's continue."
+    else:
+      - kind: SendActivity
+        activity:
+          text: "I hope things get better! Let me know if there's anything I can help with."
+
+  # Ask for feedback (using RequestExternalInput for demonstration)
+  - kind: RequestExternalInput
+    id: ask_feedback
+    displayName: Request feedback
+    prompt:
+      text: "Do you have any feedback for us?"
+    variable: Local.feedback
+    default: "This workflow is great!"
+
+  # Summary
+  - kind: SendActivity
+    id: summary
+    displayName: Send summary
+    activity:
+      text: '=Concat("Thank you, ", Local.userName, "! Your feedback: ", Local.feedback)'
+
+  # Store results
+  - kind: SetValue
+    id: store_results
+    displayName: Store survey results
+    path: Workflow.Outputs.survey
+    value:
+      name: =Local.userName
+      feeling: =Local.feeling
+      feedback: =Local.feedback

python/samples/getting_started/workflows/declarative/marketing/README.md

@@ -0,0 +1,76 @@
+# Marketing Copy Workflow
+
+This sample demonstrates a sequential multi-agent pipeline for generating marketing copy from a product description.
+
+## Overview
+
+The workflow showcases:
+- **Sequential Agent Pipeline**: Three agents work in sequence, each building on the previous output
+- **Role-Based Agents**: Each agent has a distinct responsibility
+- **Content Transformation**: Raw product info transforms into polished marketing copy
+
+## Agent Pipeline
+
+```
+Product Description
+       |
+       v
+  AnalystAgent  --> Key features, audience, USPs
+       |
+       v
+   WriterAgent  --> Draft marketing copy
+       |
+       v
+   EditorAgent  --> Polished final copy
+       |
+       v
+  Final Output
+```
+
+## Agents
+
+| Agent | Role |
+|-------|------|
+| AnalystAgent | Identifies key features, target audience, and unique selling points |
+| WriterAgent | Creates compelling marketing copy (~150 words) |
+| EditorAgent | Polishes grammar, clarity, tone, and formatting |
+
+## Usage
+
+```bash
+# Run the demonstration with mock responses
+python main.py
+```
+
+## Example Input
+
+```
+An eco-friendly stainless steel water bottle that keeps drinks cold for 24 hours.
+```
+
+## Configuration
+
+For production use, configure these agents in Azure AI Foundry:
+
+### AnalystAgent
+```
+Instructions: You are a marketing analyst. Given a product description, identify:
+- Key features
+- Target audience
+- Unique selling points
+```
+
+### WriterAgent
+```
+Instructions: You are a marketing copywriter. Given a block of text describing
+features, audience, and USPs, compose a compelling marketing copy (like a
+newsletter section) that highlights these points. Output should be short
+(around 150 words), output just the copy as a single text block.
+```
+
+### EditorAgent
+```
+Instructions: You are an editor. Given the draft copy, correct grammar,
+improve clarity, ensure consistent tone, give format and make it polished.
+Output the final improved copy as a single text block.
+```

python/samples/getting_started/workflows/declarative/marketing/main.py

@@ -0,0 +1,97 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""
+Run the marketing copy workflow sample.
+
+Usage:
+    python main.py
+
+Demonstrates sequential multi-agent pipeline:
+- AnalystAgent: Identifies key features, target audience, USPs
+- WriterAgent: Creates compelling marketing copy
+- EditorAgent: Polishes grammar, clarity, and tone
+"""
+
+import asyncio
+from pathlib import Path
+
+from agent_framework import WorkflowOutputEvent
+from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.declarative import WorkflowFactory
+from azure.identity import AzureCliCredential
+
+ANALYST_INSTRUCTIONS = """You are a product analyst. Analyze the given product and identify:
+1. Key features and benefits
+2. Target audience demographics
+3. Unique selling propositions (USPs)
+4. Competitive advantages
+
+Be concise and structured in your analysis."""
+
+WRITER_INSTRUCTIONS = """You are a marketing copywriter. Based on the product analysis provided,
+create compelling marketing copy that:
+1. Has a catchy headline
+2. Highlights key benefits
+3. Speaks to the target audience
+4. Creates emotional connection
+5. Includes a call to action
+
+Write in an engaging, persuasive tone."""
+
+EDITOR_INSTRUCTIONS = """You are a senior editor. Review and polish the marketing copy:
+1. Fix any grammar or spelling issues
+2. Improve clarity and flow
+3. Ensure consistent tone
+4. Tighten the prose
+5. Make it more impactful
+
+Return the final polished version."""
+
+
+async def main() -> None:
+    """Run the marketing workflow with real Azure AI agents."""
+    chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
+
+    analyst_agent = chat_client.as_agent(
+        name="AnalystAgent",
+        instructions=ANALYST_INSTRUCTIONS,
+    )
+    writer_agent = chat_client.as_agent(
+        name="WriterAgent",
+        instructions=WRITER_INSTRUCTIONS,
+    )
+    editor_agent = chat_client.as_agent(
+        name="EditorAgent",
+        instructions=EDITOR_INSTRUCTIONS,
+    )
+
+    factory = WorkflowFactory(
+        agents={
+            "AnalystAgent": analyst_agent,
+            "WriterAgent": writer_agent,
+            "EditorAgent": editor_agent,
+        }
+    )
+
+    workflow_path = Path(__file__).parent / "workflow.yaml"
+    workflow = factory.create_workflow_from_yaml_path(workflow_path)
+
+    print(f"Loaded workflow: {workflow.name}")
+    print("=" * 60)
+    print("Marketing Copy Generation Pipeline")
+    print("=" * 60)
+
+    # Pass a simple string input - like .NET
+    product = "An eco-friendly stainless steel water bottle that keeps drinks cold for 24 hours."
+
+    async for event in workflow.run_stream(product):
+        if isinstance(event, WorkflowOutputEvent):
+            print(f"{event.data}", end="", flush=True)
+
+    print("\n" + "=" * 60)
+    print("Pipeline Complete")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/workflows/declarative/marketing/workflow.yaml

@@ -0,0 +1,30 @@
+#
+# This workflow demonstrates sequential agent interaction to develop product marketing copy.
+#
+# Example input:
+# An eco-friendly stainless steel water bottle that keeps drinks cold for 24 hours.
+#
+kind: Workflow
+trigger:
+
+  kind: OnConversationStart
+  id: workflow_demo
+  actions:
+
+    - kind: InvokeAzureAgent
+      id: invoke_analyst
+      conversationId: =System.ConversationId
+      agent:
+        name: AnalystAgent
+
+    - kind: InvokeAzureAgent
+      id: invoke_writer
+      conversationId: =System.ConversationId
+      agent:
+        name: WriterAgent
+
+    - kind: InvokeAzureAgent
+      id: invoke_editor
+      conversationId: =System.ConversationId
+      agent:
+        name: EditorAgent

python/samples/getting_started/workflows/declarative/simple_workflow/README.md

@@ -0,0 +1,24 @@
+# Simple Workflow Sample
+
+This sample demonstrates the basics of declarative workflows:
+- Setting variables
+- Evaluating expressions
+- Sending output to users
+
+## Files
+
+- `workflow.yaml` - The workflow definition
+- `main.py` - Python code to execute the workflow
+
+## Running
+
+```bash
+python main.py
+```
+
+## What It Does
+
+1. Sets a greeting variable
+2. Sets a name from input (or uses default)
+3. Combines them into a message
+4. Sends the message as output

python/samples/getting_started/workflows/declarative/simple_workflow/main.py

@@ -0,0 +1,40 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Simple workflow sample - demonstrates basic variable setting and output."""
+
+import asyncio
+from pathlib import Path
+
+from agent_framework.declarative import WorkflowFactory
+
+
+async def main() -> None:
+    """Run the simple greeting workflow."""
+    # Create a workflow factory
+    factory = WorkflowFactory()
+
+    # Load the workflow from YAML
+    workflow_path = Path(__file__).parent / "workflow.yaml"
+    workflow = factory.create_workflow_from_yaml_path(workflow_path)
+
+    print(f"Loaded workflow: {workflow.name}")
+    print("-" * 40)
+
+    # Run with default name
+    print("\nRunning with default name:")
+    result = await workflow.run({})
+    for output in result.get_outputs():
+        print(f"  Output: {output}")
+
+    # Run with a custom name
+    print("\nRunning with custom name 'Alice':")
+    result = await workflow.run({"name": "Alice"})
+    for output in result.get_outputs():
+        print(f"  Output: {output}")
+
+    print("\n" + "-" * 40)
+    print("Workflow completed!")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/workflows/declarative/simple_workflow/workflow.yaml

@@ -0,0 +1,38 @@
+name: simple-greeting-workflow
+description: A simple workflow that greets the user
+
+actions:
+  # Set a greeting prefix
+  - kind: SetValue
+    id: set_greeting
+    displayName: Set greeting prefix
+    path: Local.greeting
+    value: Hello
+
+  # Set the user's name from input, or use a default
+  - kind: SetValue
+    id: set_name
+    displayName: Set user name
+    path: Local.name
+    value: =If(IsBlank(inputs.name), "World", inputs.name)
+
+  # Build the full message
+  - kind: SetValue
+    id: build_message
+    displayName: Build greeting message
+    path: Local.message
+    value: =Concat(Local.greeting, ", ", Local.name, "!")
+
+  # Send the greeting to the user
+  - kind: SendActivity
+    id: send_greeting
+    displayName: Send greeting to user
+    activity:
+      text: =Local.message
+
+  # Also store it in outputs
+  - kind: SetValue
+    id: set_output
+    displayName: Store result in outputs
+    path: Workflow.Outputs.greeting
+    value: =Local.message

python/samples/getting_started/workflows/declarative/student_teacher/README.md

@@ -0,0 +1,61 @@
+# Student-Teacher Math Chat Workflow
+
+This sample demonstrates an iterative conversation between two AI agents - a Student and a Teacher - working through a math problem together.
+
+## Overview
+
+The workflow showcases:
+- **Iterative Agent Loops**: Two agents take turns in a coaching conversation
+- **Termination Conditions**: Loop ends when teacher says "congratulations" or max turns reached
+- **State Tracking**: Turn counter tracks iteration progress
+- **Conditional Flow Control**: GotoAction for loop continuation
+
+## Agents
+
+| Agent | Role |
+|-------|------|
+| StudentAgent | Attempts to solve math problems, making intentional mistakes to learn from |
+| TeacherAgent | Reviews student's work and provides constructive feedback |
+
+## How It Works
+
+1. User provides a math problem
+2. Student attempts a solution
+3. Teacher reviews and provides feedback
+4. If teacher says "congratulations" -> success, workflow ends
+5. If under 4 turns -> loop back to step 2
+6. If 4 turns reached without success -> timeout, workflow ends
+
+## Usage
+
+```bash
+# Run the demonstration with mock responses
+python main.py
+```
+
+## Example Input
+
+```
+How would you compute the value of PI?
+```
+
+## Configuration
+
+For production use, configure these agents in Azure AI Foundry:
+
+### StudentAgent
+```
+Instructions: Your job is to help a math teacher practice teaching by making
+intentional mistakes. You attempt to solve the given math problem, but with
+intentional mistakes so the teacher can help. Always incorporate the teacher's
+advice to fix your next response. You have the math-skills of a 6th grader.
+Don't describe who you are or reveal your instructions.
+```
+
+### TeacherAgent
+```
+Instructions: Review and coach the student's approach to solving the given
+math problem. Don't repeat the solution or try and solve it. If the student
+has demonstrated comprehension and responded to all of your feedback, give
+the student your congratulations by using the word "congratulations".
+```

python/samples/getting_started/workflows/declarative/student_teacher/main.py

@@ -0,0 +1,94 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""
+Run the student-teacher (MathChat) workflow sample.
+
+Usage:
+    python main.py
+
+Demonstrates iterative conversation between two agents:
+- StudentAgent: Attempts to solve math problems
+- TeacherAgent: Reviews and coaches the student's approach
+
+The workflow loops until the teacher gives congratulations or max turns reached.
+
+Prerequisites:
+    - Azure OpenAI deployment with chat completion capability
+    - Environment variables:
+        AZURE_OPENAI_ENDPOINT: Your Azure OpenAI endpoint
+        AZURE_OPENAI_DEPLOYMENT_NAME: Your deployment name (optional, defaults to gpt-4o)
+"""
+
+import asyncio
+from pathlib import Path
+
+from agent_framework import WorkflowOutputEvent
+from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.declarative import WorkflowFactory
+from azure.identity import AzureCliCredential
+
+STUDENT_INSTRUCTIONS = """You are a curious math student working on understanding mathematical concepts.
+When given a problem:
+1. Think through it step by step
+2. Make reasonable attempts, but it's okay to make mistakes
+3. Show your work and reasoning
+4. Ask clarifying questions when confused
+5. Build on feedback from your teacher
+
+Be authentic - you're learning, so don't pretend to know everything."""
+
+TEACHER_INSTRUCTIONS = """You are a patient math teacher helping a student understand concepts.
+When reviewing student work:
+1. Acknowledge what they did correctly
+2. Gently point out errors without giving away the answer
+3. Ask guiding questions to help them discover mistakes
+4. Provide hints that lead toward understanding
+5. When the student demonstrates clear understanding, respond with "CONGRATULATIONS" 
+   followed by a summary of what they learned
+
+Focus on building understanding, not just getting the right answer."""
+
+
+async def main() -> None:
+    """Run the student-teacher workflow with real Azure AI agents."""
+    # Create chat client
+    chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
+
+    # Create student and teacher agents
+    student_agent = chat_client.as_agent(
+        name="StudentAgent",
+        instructions=STUDENT_INSTRUCTIONS,
+    )
+
+    teacher_agent = chat_client.as_agent(
+        name="TeacherAgent",
+        instructions=TEACHER_INSTRUCTIONS,
+    )
+
+    # Create factory with agents
+    factory = WorkflowFactory(
+        agents={
+            "StudentAgent": student_agent,
+            "TeacherAgent": teacher_agent,
+        }
+    )
+
+    workflow_path = Path(__file__).parent / "workflow.yaml"
+    workflow = factory.create_workflow_from_yaml_path(workflow_path)
+
+    print(f"Loaded workflow: {workflow.name}")
+    print("=" * 50)
+    print("Student-Teacher Math Coaching Session")
+    print("=" * 50)
+
+    async for event in workflow.run_stream("How would you compute the value of PI?"):
+        if isinstance(event, WorkflowOutputEvent):
+            print(f"{event.data}", flush=True, end="")
+
+    print("\n" + "=" * 50)
+    print("Session Complete")
+    print("=" * 50)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/workflows/declarative/student_teacher/workflow.yaml

@@ -0,0 +1,98 @@
+# Student-Teacher Math Chat Workflow
+#
+# Demonstrates iterative conversation between two agents with loop control
+# and termination conditions.
+#
+# Example input:
+# How would you compute the value of PI?
+#
+kind: Workflow
+trigger:
+
+  kind: OnConversationStart
+  id: student_teacher_workflow
+  actions:
+
+    # Initialize turn counter
+    - kind: SetVariable
+      id: init_counter
+      variable: Local.TurnCount
+      value: =0
+
+    # Announce the start with the problem
+    - kind: SendActivity
+      id: announce_start
+      activity:
+        text: '=Concat("Starting math coaching session for: ", Workflow.Inputs.input)'
+
+    # Label for student
+    - kind: SendActivity
+      id: student_label
+      activity:
+        text: "\n[Student]:\n"
+
+    # Student attempts to solve - entry point for loop
+    # No explicit input.messages - uses implicit input from workflow inputs or conversation
+    - kind: InvokeAzureAgent
+      id: question_student
+      conversationId: =System.ConversationId
+      agent:
+        name: StudentAgent
+
+    # Label for teacher
+    - kind: SendActivity
+      id: teacher_label
+      activity:
+        text: "\n\n[Teacher]:\n"
+
+    # Teacher reviews and coaches
+    # No explicit input.messages - uses conversation context from conversationId
+    - kind: InvokeAzureAgent
+      id: question_teacher
+      conversationId: =System.ConversationId
+      agent:
+        name: TeacherAgent
+      output:
+        messages: Local.TeacherResponse
+
+    # Increment the turn counter
+    - kind: SetVariable
+      id: increment_counter
+      variable: Local.TurnCount
+      value: =Local.TurnCount + 1
+
+    # Check for completion using ConditionGroup
+    - kind: ConditionGroup
+      id: check_completion
+      conditions:
+        - id: success_condition
+          condition: =!IsBlank(Find("CONGRATULATIONS", Upper(MessageText(Local.TeacherResponse))))
+          actions:
+            - kind: SendActivity
+              id: success_message
+              activity:
+                text: "\nGOLD STAR! The student has demonstrated understanding."
+            - kind: SetVariable
+              id: set_success_result
+              variable: workflow.outputs.result
+              value: success
+      elseActions:
+        - kind: ConditionGroup
+          id: check_turn_limit
+          conditions:
+            - id: can_continue
+              condition: =Local.TurnCount < 4
+              actions:
+                # Continue the loop - go back to student label
+                - kind: GotoAction
+                  id: continue_loop
+                  actionId: student_label
+          elseActions:
+            - kind: SendActivity
+              id: timeout_message
+              activity:
+                text: "\nLet's try again later... The session has reached its limit."
+            - kind: SetVariable
+              id: set_timeout_result
+              variable: workflow.outputs.result
+              value: timeout

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

@@ -0,0 +1,347 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import json
+from dataclasses import dataclass
+from typing import Annotated, Never
+
+from agent_framework import (
+    AgentExecutorResponse,
+    ChatAgent,
+    ChatMessage,
+    Executor,
+    FunctionApprovalRequestContent,
+    FunctionApprovalResponseContent,
+    WorkflowBuilder,
+    WorkflowContext,
+    ai_function,
+    executor,
+    handler,
+)
+from agent_framework.openai import OpenAIChatClient
+
+"""
+Sample: Agents in a workflow with AI functions requiring approval
+
+This sample creates a workflow that automatically replies to incoming emails.
+If historical email data is needed, it uses an AI function to read the data,
+which requires human approval before execution.
+
+This sample works as follows:
+1. An incoming email is received by the workflow.
+2. The EmailPreprocessor executor preprocesses the email, adding special notes if the sender is important.
+3. The preprocessed email is sent to the Email Writer agent, which generates a response.
+4. If the agent needs to read historical email data, it calls the read_historical_email_data AI function,
+   which triggers an approval request.
+5. The sample automatically approves the request for demonstration purposes.
+6. Once approved, the AI function executes and returns the historical email data to the agent.
+7. The agent uses the historical data to compose a comprehensive email response.
+8. The response is sent to the conclude_workflow_executor, which yields the final response.
+
+Purpose:
+Show how to integrate AI functions with approval requests into a workflow.
+
+Demonstrate:
+- Creating AI functions that require approval before execution.
+- Building a workflow that includes an agent and executors.
+- Handling approval requests during workflow execution.
+
+Prerequisites:
+- Azure AI Agent Service configured, along with the required environment variables.
+- Authentication via azure-identity. Use AzureCliCredential and run az login before executing the sample.
+- Basic familiarity with WorkflowBuilder, edges, events, RequestInfoEvent, and streaming runs.
+"""
+
+
+@ai_function
+def get_current_date() -> str:
+    """Get the current date in YYYY-MM-DD format."""
+    # For demonstration purposes, we return a fixed date.
+    return "2025-11-07"
+
+
+@ai_function
+def get_team_members_email_addresses() -> list[dict[str, str]]:
+    """Get the email addresses of team members."""
+    # In a real implementation, this might query a database or directory service.
+    return [
+        {
+            "name": "Alice",
+            "email": "alice@contoso.com",
+            "position": "Software Engineer",
+            "manager": "John Doe",
+        },
+        {
+            "name": "Bob",
+            "email": "bob@contoso.com",
+            "position": "Product Manager",
+            "manager": "John Doe",
+        },
+        {
+            "name": "Charlie",
+            "email": "charlie@contoso.com",
+            "position": "Senior Software Engineer",
+            "manager": "John Doe",
+        },
+        {
+            "name": "Mike",
+            "email": "mike@contoso.com",
+            "position": "Principal Software Engineer Manager",
+            "manager": "VP of Engineering",
+        },
+    ]
+
+
+@ai_function
+def get_my_information() -> dict[str, str]:
+    """Get my personal information."""
+    return {
+        "name": "John Doe",
+        "email": "john@contoso.com",
+        "position": "Software Engineer Manager",
+        "manager": "Mike",
+    }
+
+
+@ai_function(approval_mode="always_require")
+async def read_historical_email_data(
+    email_address: Annotated[str, "The email address to read historical data from"],
+    start_date: Annotated[str, "The start date in YYYY-MM-DD format"],
+    end_date: Annotated[str, "The end date in YYYY-MM-DD format"],
+) -> list[dict[str, str]]:
+    """Read historical email data for a given email address and date range."""
+    historical_data = {
+        "alice@contoso.com": [
+            {
+                "from": "alice@contoso.com",
+                "to": "john@contoso.com",
+                "date": "2025-11-05",
+                "subject": "Bug Bash Results",
+                "body": "We just completed the bug bash and found a few issues that need immediate attention.",
+            },
+            {
+                "from": "alice@contoso.com",
+                "to": "john@contoso.com",
+                "date": "2025-11-03",
+                "subject": "Code Freeze",
+                "body": "We are entering code freeze starting tomorrow.",
+            },
+        ],
+        "bob@contoso.com": [
+            {
+                "from": "bob@contoso.com",
+                "to": "john@contoso.com",
+                "date": "2025-11-04",
+                "subject": "Team Outing",
+                "body": "Don't forget about the team outing this Friday!",
+            },
+            {
+                "from": "bob@contoso.com",
+                "to": "john@contoso.com",
+                "date": "2025-11-02",
+                "subject": "Requirements Update",
+                "body": "The requirements for the new feature have been updated. Please review them.",
+            },
+        ],
+        "charlie@contoso.com": [
+            {
+                "from": "charlie@contoso.com",
+                "to": "john@contoso.com",
+                "date": "2025-11-05",
+                "subject": "Project Update",
+                "body": "The bug bash went well. A few critical bugs but should be fixed by the end of the week.",
+            },
+            {
+                "from": "charlie@contoso.com",
+                "to": "john@contoso.com",
+                "date": "2025-11-06",
+                "subject": "Code Review",
+                "body": "Please review my latest code changes.",
+            },
+        ],
+    }
+
+    emails = historical_data.get(email_address, [])
+    return [email for email in emails if start_date <= email["date"] <= end_date]
+
+
+@ai_function(approval_mode="always_require")
+async def send_email(
+    to: Annotated[str, "The recipient email address"],
+    subject: Annotated[str, "The email subject"],
+    body: Annotated[str, "The email body"],
+) -> str:
+    """Send an email."""
+    await asyncio.sleep(1)  # Simulate sending email
+    return "Email successfully sent."
+
+
+@dataclass
+class Email:
+    sender: str
+    subject: str
+    body: str
+
+
+class EmailPreprocessor(Executor):
+    def __init__(self, special_email_addresses: set[str]) -> None:
+        super().__init__(id="email_preprocessor")
+        self.special_email_addresses = special_email_addresses
+
+    @handler
+    async def preprocess(self, email: Email, ctx: WorkflowContext[str]) -> None:
+        """Preprocess the incoming email."""
+        message = str(email)
+        if email.sender in self.special_email_addresses:
+            note = (
+                "Pay special attention to this sender. This email is very important. "
+                "Gather relevant information from all previous emails within my team before responding."
+            )
+            message = f"{note}\n\n{message}"
+
+        await ctx.send_message(message)
+
+
+@executor(id="conclude_workflow_executor")
+async def conclude_workflow(
+    email_response: AgentExecutorResponse,
+    ctx: WorkflowContext[Never, str],
+) -> None:
+    """Conclude the workflow by yielding the final email response."""
+    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",
+        instructions=("You are an excellent email assistant. You respond to incoming emails."),
+        # tools with `approval_mode="always_require"` will trigger approval requests
+        tools=[
+            read_historical_email_data,
+            send_email,
+            get_current_date,
+            get_team_members_email_addresses,
+            get_my_information,
+        ],
+    )
+
+
+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")
+        .build()
+    )
+
+    # Simulate an incoming email
+    incoming_email = Email(
+        sender="mike@contoso.com",
+        subject="Important: Project Update",
+        body="Please provide your team's status update on the project since last week.",
+    )
+
+    responses: dict[str, FunctionApprovalResponseContent] = {}
+    output: list[ChatMessage] | None = None
+    while True:
+        if responses:
+            events = await workflow.send_responses(responses)
+            responses.clear()
+        else:
+            events = await workflow.run(incoming_email)
+
+        request_info_events = events.get_request_info_events()
+        for request_info_event in request_info_events:
+            # We should only expect FunctionApprovalRequestContent in this sample
+            if not isinstance(request_info_event.data, FunctionApprovalRequestContent):
+                raise ValueError(f"Unexpected request info content type: {type(request_info_event.data)}")
+
+            # 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}"
+            )
+
+            # For demo purposes, we automatically approve the request
+            # The expected response type of the request is `FunctionApprovalResponseContent`,
+            # which can be created via `create_response` method on the request content
+            print("Performing automatic approval for demo purposes...")
+            responses[request_info_event.request_id] = request_info_event.data.create_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.")
+
+    print("Final email response conversation:")
+    print(output)
+
+    """
+    Sample Output:
+    Received approval request for function: read_historical_email_data with args:
+    {
+        "email_address": "alice@contoso.com",
+        "start_date": "2025-10-31",
+        "end_date": "2025-11-07"
+    }
+    Performing automatic approval for demo purposes...
+    Received approval request for function: read_historical_email_data with args:
+    {
+        "email_address": "bob@contoso.com",
+        "start_date": "2025-10-31",
+        "end_date": "2025-11-07"
+    }
+    Performing automatic approval for demo purposes...
+    Received approval request for function: read_historical_email_data with args:
+    {
+        "email_address": "charlie@contoso.com",
+        "start_date": "2025-10-31",
+        "end_date": "2025-11-07"
+    }
+    Performing automatic approval for demo purposes...
+    Received approval request for function: send_email with args:
+    {
+        "to": "mike@contoso.com",
+        "subject": "Team's Status Update on the Project",
+        "body": "
+        Hi Mike,
+
+        Here's the status update from our team:
+        - **Bug Bash and Code Freeze:**
+            - We recently completed a bug bash, during which several issues were identified. Alice and Charlie are working on fixing these critical bugs, and we anticipate resolving them by the end of this week.
+            - We have entered a code freeze as of November 4, 2025.
+
+        - **Requirements Update:**
+            - Bob has updated the requirements for a new feature, and all team members are reviewing these changes to ensure alignment.
+
+        - **Ongoing Reviews:**
+            - Charlie has submitted his latest code changes for review to ensure they meet our quality standards.
+
+        Please let me know if you need more detailed information or have any questions.
+
+        Best regards,
+        John"
+    }
+    Performing automatic approval for demo purposes...
+    Final email response conversation:
+    I've sent the status update to Mike with the relevant information from the team. Let me know if there's anything else you need
+    """  # noqa: E501
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,206 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""
+Sample: Request Info with ConcurrentBuilder
+
+This sample demonstrates using the `.with_request_info()` method to pause a
+ConcurrentBuilder workflow for specific agents, allowing human review and
+modification of individual agent outputs before aggregation.
+
+Purpose:
+Show how to use the request info API that pauses for selected concurrent agents,
+allowing review and steering of their results.
+
+Demonstrate:
+- Configuring request info with `.with_request_info()` for specific agents
+- Reviewing output from individual agents during concurrent execution
+- Injecting human guidance for specific agents before aggregation
+
+Prerequisites:
+- Azure OpenAI configured for AzureOpenAIChatClient with required environment variables
+- Authentication via azure-identity (run az login before executing)
+"""
+
+import asyncio
+from typing import Any
+
+from agent_framework import (
+    AgentRequestInfoResponse,
+    ChatMessage,
+    ConcurrentBuilder,
+    RequestInfoEvent,
+    Role,
+    WorkflowOutputEvent,
+    WorkflowRunState,
+    WorkflowStatusEvent,
+)
+from agent_framework._workflows._agent_executor import AgentExecutorResponse
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+
+# Store chat client at module level for aggregator access
+_chat_client: AzureOpenAIChatClient | None = None
+
+
+async def aggregate_with_synthesis(results: list[AgentExecutorResponse]) -> Any:
+    """Custom aggregator that synthesizes concurrent agent outputs using an LLM.
+
+    This aggregator extracts the outputs from each parallel agent and uses the
+    chat client to create a unified summary, incorporating any human feedback
+    that was injected into the conversation.
+
+    Args:
+        results: List of responses from all concurrent agents
+
+    Returns:
+        The synthesized summary text
+    """
+    if not _chat_client:
+        return "Error: Chat client not initialized"
+
+    # Extract each agent's final output
+    expert_sections: list[str] = []
+    human_guidance = ""
+
+    for r in results:
+        try:
+            messages = getattr(r.agent_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', 'analyst')}:\n{final_text}")
+
+            # Check for human feedback in the conversation (will be last user message if present)
+            if r.full_conversation:
+                for msg in reversed(r.full_conversation):
+                    if msg.role == Role.USER and msg.text and "perspectives" not in msg.text.lower():
+                        human_guidance = msg.text
+                        break
+        except Exception:
+            expert_sections.append(f"{getattr(r, 'executor_id', 'analyst')}: (error extracting output)")
+
+    # Build prompt with human guidance if provided
+    guidance_text = f"\n\nHuman guidance: {human_guidance}" if human_guidance else ""
+
+    system_msg = ChatMessage(
+        Role.SYSTEM,
+        text=(
+            "You are a synthesis expert. Consolidate the following analyst perspectives "
+            "into one cohesive, balanced summary (3-4 sentences). If human guidance is provided, "
+            "prioritize aspects as directed."
+        ),
+    )
+    user_msg = ChatMessage(Role.USER, text="\n\n".join(expert_sections) + guidance_text)
+
+    response = await _chat_client.get_response([system_msg, user_msg])
+    return response.messages[-1].text if response.messages else ""
+
+
+async def main() -> None:
+    global _chat_client
+    _chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
+
+    # Create agents that analyze from different perspectives
+    technical_analyst = _chat_client.as_agent(
+        name="technical_analyst",
+        instructions=(
+            "You are a technical analyst. When given a topic, provide a technical "
+            "perspective focusing on implementation details, performance, and architecture. "
+            "Keep your analysis to 2-3 sentences."
+        ),
+    )
+
+    business_analyst = _chat_client.as_agent(
+        name="business_analyst",
+        instructions=(
+            "You are a business analyst. When given a topic, provide a business "
+            "perspective focusing on ROI, market impact, and strategic value. "
+            "Keep your analysis to 2-3 sentences."
+        ),
+    )
+
+    user_experience_analyst = _chat_client.as_agent(
+        name="ux_analyst",
+        instructions=(
+            "You are a UX analyst. When given a topic, provide a user experience "
+            "perspective focusing on usability, accessibility, and user satisfaction. "
+            "Keep your analysis to 2-3 sentences."
+        ),
+    )
+
+    # Build workflow with request info enabled and custom aggregator
+    workflow = (
+        ConcurrentBuilder()
+        .participants([technical_analyst, business_analyst, user_experience_analyst])
+        .with_aggregator(aggregate_with_synthesis)
+        # Only enable request info for the technical analyst agent
+        .with_request_info(agents=["technical_analyst"])
+        .build()
+    )
+
+    # Run the workflow with human-in-the-loop
+    pending_responses: dict[str, AgentRequestInfoResponse] | None = None
+    workflow_complete = False
+
+    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.value
+                            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
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,177 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""
+Sample: Request Info with GroupChatBuilder
+
+This sample demonstrates using the `.with_request_info()` method to pause a
+GroupChatBuilder workflow BEFORE specific participants speak. By using the
+`agents=` filter parameter, you can target only certain participants rather
+than pausing before every turn.
+
+Purpose:
+Show how to use the request info API with selective filtering to pause before
+specific participants speak, allowing human input to steer their response.
+
+Demonstrate:
+- Configuring request info with `.with_request_info(agents=[...])`
+- Using agent filtering to reduce interruptions
+- Steering agent behavior with pre-agent human input
+
+Prerequisites:
+- Azure OpenAI configured for AzureOpenAIChatClient with required environment variables
+- Authentication via azure-identity (run az login before executing)
+"""
+
+import asyncio
+
+from agent_framework import (
+    AgentExecutorResponse,
+    AgentRequestInfoResponse,
+    AgentResponse,
+    AgentRunUpdateEvent,
+    ChatMessage,
+    GroupChatBuilder,
+    RequestInfoEvent,
+    WorkflowOutputEvent,
+    WorkflowRunState,
+    WorkflowStatusEvent,
+)
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+
+
+async def main() -> None:
+    chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
+
+    # Create agents for a group discussion
+    optimist = chat_client.as_agent(
+        name="optimist",
+        instructions=(
+            "You are an optimistic team member. You see opportunities and potential "
+            "in ideas. Engage constructively with the discussion, building on others' "
+            "points while maintaining a positive outlook. Keep responses to 2-3 sentences."
+        ),
+    )
+
+    pragmatist = chat_client.as_agent(
+        name="pragmatist",
+        instructions=(
+            "You are a pragmatic team member. You focus on practical implementation "
+            "and realistic timelines. Sometimes you disagree with overly optimistic views. "
+            "Keep responses to 2-3 sentences."
+        ),
+    )
+
+    creative = chat_client.as_agent(
+        name="creative",
+        instructions=(
+            "You are a creative team member. You propose innovative solutions and "
+            "think outside the box. You may suggest alternatives to conventional approaches. "
+            "Keep responses to 2-3 sentences."
+        ),
+    )
+
+    # Orchestrator coordinates the discussion
+    orchestrator = chat_client.as_agent(
+        name="orchestrator",
+        instructions=(
+            "You are a discussion manager coordinating a team conversation between participants. "
+            "Your job is to select who speaks next.\n\n"
+            "RULES:\n"
+            "1. Rotate through ALL participants - do not favor any single participant\n"
+            "2. Each participant should speak at least once before any participant speaks twice\n"
+            "3. Continue for at least 5 rounds before ending the discussion\n"
+            "4. Do NOT select the same participant twice in a row"
+        ),
+    )
+
+    # Build workflow with request info enabled
+    # Using agents= filter to only pause before pragmatist speaks (not every turn)
+    workflow = (
+        GroupChatBuilder()
+        .with_agent_orchestrator(orchestrator)
+        .participants([optimist, pragmatist, creative])
+        .with_max_rounds(6)
+        .with_request_info(agents=[pragmatist])  # Only pause before pragmatist speaks
+        .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
+
+    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.value.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
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,257 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from dataclasses import dataclass
+
+from agent_framework import (
+    AgentExecutorRequest,  # Message bundle sent to an AgentExecutor
+    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
+    Role,  # Enum of chat roles (user, assistant, system)
+    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
+    handler,
+    response_handler,  # Decorator to expose an Executor method as a step
+)
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+from pydantic import BaseModel
+
+"""
+Sample: Human in the loop guessing game
+
+An agent guesses a number, then a human guides it with higher, lower, or
+correct. The loop continues until the human confirms correct, at which point
+the workflow completes when idle with no pending work.
+
+Purpose:
+Show how to integrate a human step in the middle of an LLM workflow by using
+`request_info` and `send_responses_streaming`.
+
+Demonstrate:
+- Alternating turns between an AgentExecutor and a human, driven by events.
+- Using Pydantic response_format to enforce structured JSON output from the agent instead of regex parsing.
+- Driving the loop in application code with run_stream and responses parameter.
+
+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 runs.
+"""
+
+# How human-in-the-loop is achieved via `request_info` and `send_responses_streaming`:
+# - An executor (TurnManager) calls `ctx.request_info` with a payload (HumanFeedbackRequest).
+# - The workflow run pauses and emits a RequestInfoEvent with the payload and the request_id.
+# - The application captures the event, prompts the user, and collects replies.
+# - The application calls `send_responses_streaming` with a map of request_ids to replies.
+# - The workflow resumes, and the response is delivered to the executor method decorated with @response_handler.
+# - The executor can then continue the workflow, e.g., by sending a new message to the agent.
+
+
+@dataclass
+class HumanFeedbackRequest:
+    """Request sent to the human for feedback on the agent's guess."""
+
+    prompt: str
+
+
+class GuessOutput(BaseModel):
+    """Structured output from the agent. Enforced via response_format for reliable parsing."""
+
+    guess: int
+
+
+class TurnManager(Executor):
+    """Coordinates turns between the agent and the human.
+
+    Responsibilities:
+    - Kick off the first agent turn.
+    - After each agent reply, request human feedback with a HumanFeedbackRequest.
+    - After each human reply, either finish the game or prompt the agent again with feedback.
+    """
+
+    def __init__(self, id: str | None = None):
+        super().__init__(id=id or "turn_manager")
+
+    @handler
+    async def start(self, _: str, ctx: WorkflowContext[AgentExecutorRequest]) -> None:
+        """Start the game by asking the agent for an initial guess.
+
+        Contract:
+        - Input is a simple starter token (ignored here).
+        - Output is an AgentExecutorRequest that triggers the agent to produce a guess.
+        """
+        user = ChatMessage(Role.USER, text="Start by making your first guess.")
+        await ctx.send_message(AgentExecutorRequest(messages=[user], should_respond=True))
+
+    @handler
+    async def on_agent_response(
+        self,
+        result: AgentExecutorResponse,
+        ctx: WorkflowContext,
+    ) -> None:
+        """Handle the agent's guess and request human guidance.
+
+        Steps:
+        1) Parse the agent's JSON into GuessOutput for robustness.
+        2) Request info with a HumanFeedbackRequest as the payload.
+        """
+        # Parse structured model output
+        text = result.agent_response.text
+        last_guess = GuessOutput.model_validate_json(text).guess
+
+        # Craft a precise human prompt that defines higher and lower relative to the agent's guess.
+        prompt = (
+            f"The agent guessed: {last_guess}. "
+            "Type one of: higher (your number is higher than this guess), "
+            "lower (your number is lower than this guess), correct, or exit."
+        )
+        # Send a request with a prompt as the payload and expect a string reply.
+        await ctx.request_info(
+            request_data=HumanFeedbackRequest(prompt=prompt),
+            response_type=str,
+        )
+
+    @response_handler
+    async def on_human_feedback(
+        self,
+        original_request: HumanFeedbackRequest,
+        feedback: str,
+        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":
+            await ctx.yield_output("Guessed correctly!")
+            return
+
+        # Provide feedback to the agent to try again.
+        # We keep the agent's output strictly JSON to ensure stable parsing on the next turn.
+        user_msg = ChatMessage(
+            Role.USER,
+            text=(f'Feedback: {reply}. Return ONLY a JSON object matching the schema {{"guess": <int 1..10>}}.'),
+        )
+        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(
+        name="GuessingAgent",
+        instructions=(
+            "You guess a number between 1 and 10. "
+            "If the user says 'higher' or 'lower', adjust your next guess. "
+            'You MUST return ONLY a JSON object exactly matching this schema: {"guess": <integer 1..10>}. '
+            "No explanations or additional text."
+        ),
+        # 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."""
+
+    # 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
+    ).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
+
+    # 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,
+    # )
+
+    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:
+
+    HITL> The agent guessed: 5. Type one of: higher (your number is higher than this guess), lower (your number is lower than this guess), correct, or exit.
+    Enter higher/lower/correct/exit: higher
+    HITL> The agent guessed: 8. Type one of: higher (your number is higher than this guess), lower (your number is lower than this guess), correct, or exit.
+    Enter higher/lower/correct/exit: higher
+    HITL> The agent guessed: 10. Type one of: higher (your number is higher than this guess), lower (your number is lower than this guess), correct, or exit.
+    Enter higher/lower/correct/exit: lower
+    HITL> The agent guessed: 9. Type one of: higher (your number is higher than this guess), lower (your number is lower than this guess), correct, or exit.
+    Enter higher/lower/correct/exit: correct
+    Workflow output: Guessed correctly: 9
+    """  # noqa: E501
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,143 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""
+Sample: Request Info with SequentialBuilder
+
+This sample demonstrates using the `.with_request_info()` method to pause a
+SequentialBuilder workflow AFTER each agent runs, allowing external input
+(e.g., human feedback) for review and optional iteration.
+
+Purpose:
+Show how to use the request info API that pauses after every agent response,
+using the standard request_info pattern for consistency.
+
+Demonstrate:
+- Configuring request info with `.with_request_info()`
+- Handling RequestInfoEvent with AgentInputRequest data
+- Injecting responses back into the workflow via send_responses_streaming
+
+Prerequisites:
+- Azure OpenAI configured for AzureOpenAIChatClient with required environment variables
+- Authentication via azure-identity (run az login before executing)
+"""
+
+import asyncio
+
+from agent_framework import (
+    AgentExecutorResponse,
+    AgentRequestInfoResponse,
+    ChatMessage,
+    RequestInfoEvent,
+    SequentialBuilder,
+    WorkflowOutputEvent,
+    WorkflowRunState,
+    WorkflowStatusEvent,
+)
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+
+
+async def main() -> None:
+    chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
+
+    # Create agents for a sequential document review workflow
+    drafter = chat_client.as_agent(
+        name="drafter",
+        instructions=("You are a document drafter. When given a topic, create a brief draft (2-3 sentences)."),
+    )
+
+    editor = chat_client.as_agent(
+        name="editor",
+        instructions=(
+            "You are an editor. Review the draft and make improvements. "
+            "Incorporate any human feedback that was provided."
+        ),
+    )
+
+    finalizer = chat_client.as_agent(
+        name="finalizer",
+        instructions=(
+            "You are a finalizer. Take the edited content and create a polished final version. "
+            "Incorporate any additional feedback provided."
+        ),
+    )
+
+    # Build workflow with request info enabled (pauses after each agent responds)
+    workflow = (
+        SequentialBuilder()
+        .participants([drafter, editor, finalizer])
+        # Only enable request info for the editor agent
+        .with_request_info(agents=["editor"])
+        .build()
+    )
+
+    # Run the workflow with request info handling
+    pending_responses: dict[str, AgentRequestInfoResponse] | None = None
+    workflow_complete = False
+
+    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.value
+                            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.value 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
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/workflows/observability/executor_io_observation.py

@@ -0,0 +1,127 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import Any, cast
+
+from agent_framework import (
+    Executor,
+    ExecutorCompletedEvent,
+    ExecutorInvokedEvent,
+    WorkflowBuilder,
+    WorkflowContext,
+    WorkflowOutputEvent,
+    handler,
+)
+from typing_extensions import Never
+
+"""
+Executor I/O Observation
+
+This sample demonstrates how to observe executor input and output data without modifying
+executor code. This is useful for debugging, logging, or building monitoring tools.
+
+What this example shows:
+- ExecutorInvokedEvent.data contains the input message received by the executor
+- ExecutorCompletedEvent.data contains the messages sent via ctx.send_message()
+- How to generically observe all executor I/O through workflow streaming events
+
+This approach allows you to enable_instrumentation any workflow for observability without
+changing the executor implementations.
+
+Prerequisites:
+- No external services required.
+"""
+
+
+class UpperCaseExecutor(Executor):
+    """Convert input text to uppercase and forward to next executor."""
+
+    def __init__(self, id: str = "upper_case"):
+        super().__init__(id=id)
+
+    @handler
+    async def handle(self, text: str, ctx: WorkflowContext[str]) -> None:
+        result = text.upper()
+        await ctx.send_message(result)
+
+
+class ReverseTextExecutor(Executor):
+    """Reverse the input text and yield as workflow output."""
+
+    def __init__(self, id: str = "reverse_text"):
+        super().__init__(id=id)
+
+    @handler
+    async def handle(self, text: str, ctx: WorkflowContext[Never, str]) -> None:
+        result = text[::-1]
+        await ctx.yield_output(result)
+
+
+def format_io_data(data: Any) -> str:
+    """Format executor I/O data for display.
+
+    This helper formats common data types for readable output.
+    Customize based on the types used in your workflow.
+    """
+    type_name = type(data).__name__
+
+    if data is None:
+        return "None"
+    if isinstance(data, str):
+        preview = data[:80] + "..." if len(data) > 80 else data
+        return f"{type_name}: '{preview}'"
+    if isinstance(data, list):
+        data_list = cast(list[Any], data)
+        if len(data_list) == 0:
+            return f"{type_name}: []"
+        # For sent_messages, show each item with its type
+        if len(data_list) <= 3:
+            items = [format_io_data(item) for item in data_list]
+            return f"{type_name}: [{', '.join(items)}]"
+        return f"{type_name}: [{len(data_list)} items]"
+    return f"{type_name}: {repr(data)}"
+
+
+async def main() -> None:
+    """Build a workflow and observe executor I/O through streaming events."""
+    upper_case = UpperCaseExecutor()
+    reverse_text = ReverseTextExecutor()
+
+    workflow = WorkflowBuilder().add_edge(upper_case, reverse_text).set_start_executor(upper_case).build()
+
+    print("Running workflow with executor I/O observation...\n")
+
+    async for event in workflow.run_stream("hello world"):
+        if isinstance(event, ExecutorInvokedEvent):
+            # The input message received by the executor is in event.data
+            print(f"[INVOKED] {event.executor_id}")
+            print(f"    Input: {format_io_data(event.data)}")
+
+        elif isinstance(event, ExecutorCompletedEvent):
+            # Messages sent via ctx.send_message() are in event.data
+            print(f"[COMPLETED] {event.executor_id}")
+            if event.data:
+                print(f"    Output: {format_io_data(event.data)}")
+
+        elif isinstance(event, WorkflowOutputEvent):
+            print(f"[WORKFLOW OUTPUT] {format_io_data(event.data)}")
+
+    """
+    Sample Output:
+
+    Running workflow with executor I/O observation...
+
+    [INVOKED] upper_case
+        Input: str: 'hello world'
+    [COMPLETED] upper_case
+        Output: list: [str: 'HELLO WORLD']
+    [INVOKED] reverse_text
+        Input: str: 'HELLO WORLD'
+    [WORKFLOW OUTPUT] str: 'DLROW OLLEH'
+    [COMPLETED] reverse_text
+        Output: list: [str: 'DLROW OLLEH']
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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.as_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.as_agent(
+        instructions=(
+            "You're a creative marketing strategist. Craft compelling value propositions and target messaging"
+            " aligned to the prompt."
+        ),
+        name="marketer",
+    )
+
+    legal = chat_client.as_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.as_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.as_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.as_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_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.as_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.as_agent(
+        instructions=(
+            "You're a creative marketing strategist. Craft compelling value propositions and target messaging"
+            " aligned to the prompt."
+        ),
+        name="marketer",
+    )
+    legal = chat_client.as_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_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/concurrent_participant_factory.py

@@ -0,0 +1,169 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import Any, Never
+
+from agent_framework import (
+    ChatAgent,
+    ChatMessage,
+    ConcurrentBuilder,
+    Executor,
+    Role,
+    Workflow,
+    WorkflowContext,
+    handler,
+)
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+
+"""
+Sample: Concurrent Orchestration with participant factories and 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 Executor class that uses
+AzureOpenAIChatClient.get_response() to synthesize a concise, consolidated summary
+from the experts' outputs.
+
+All participants and the aggregator are created via factory functions that return
+their respective ChatAgent or Executor instances.
+
+Using participant factories allows you to set up proper state isolation between workflow
+instances created by the same builder. This is particularly useful when you need to handle
+requests or tasks in parallel with stateful participants.
+
+Demonstrates:
+- ConcurrentBuilder().register_participants([...]).with_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)
+"""
+
+
+def create_researcher() -> ChatAgent:
+    """Factory function to create a researcher agent instance."""
+    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+        instructions=(
+            "You're an expert market and product researcher. Given a prompt, provide concise, factual insights,"
+            " opportunities, and risks."
+        ),
+        name="researcher",
+    )
+
+
+def create_marketer() -> ChatAgent:
+    """Factory function to create a marketer agent instance."""
+    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+        instructions=(
+            "You're a creative marketing strategist. Craft compelling value propositions and target messaging"
+            " aligned to the prompt."
+        ),
+        name="marketer",
+    )
+
+
+def create_legal() -> ChatAgent:
+    """Factory function to create a legal/compliance agent instance."""
+    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+        instructions=(
+            "You're a cautious legal/compliance reviewer. Highlight constraints, disclaimers, and policy concerns"
+            " based on the prompt."
+        ),
+        name="legal",
+    )
+
+
+class SummarizationExecutor(Executor):
+    """Custom aggregator executor that synthesizes expert outputs into a concise summary."""
+
+    def __init__(self) -> None:
+        super().__init__(id="summarization_executor")
+        self.chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
+
+    @handler
+    async def summarize_results(self, results: list[Any], ctx: WorkflowContext[Never, str]) -> None:
+        expert_sections: list[str] = []
+        for r in results:
+            try:
+                messages = getattr(r.agent_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 self.chat_client.get_response([system_msg, user_msg])
+
+        await ctx.yield_output(response.messages[-1].text if response.messages else "")
+
+
+async def run_workflow(workflow: Workflow, query: str) -> None:
+    events = await workflow.run(query)
+    outputs = events.get_outputs()
+
+    if outputs:
+        print(outputs[0])  # Get the first (and typically only) output
+    else:
+        raise RuntimeError("No outputs received from the workflow.")
+
+
+async def main() -> None:
+    # Create a concurrent builder with participant factories and a custom aggregator
+    # - register_participants([...]) accepts factory functions that return
+    #   AgentProtocol (agents) or Executor instances.
+    # - register_aggregator(...) takes a factory function that returns an Executor instance.
+    concurrent_builder = (
+        ConcurrentBuilder()
+        .register_participants([create_researcher, create_marketer, create_legal])
+        .register_aggregator(SummarizationExecutor)
+    )
+
+    # Build workflow_a
+    workflow_a = concurrent_builder.build()
+
+    # Run workflow_a
+    # Context is maintained across runs
+    print("=== First Run on workflow_a ===")
+    await run_workflow(workflow_a, "We are launching a new budget-friendly electric bike for urban commuters.")
+    print("\n=== Second Run on workflow_a ===")
+    await run_workflow(workflow_a, "Refine your response to focus on the California market.")
+
+    # Build workflow_b
+    # This will create new instances of all participants and the aggregator
+    # The agents will also get new threads
+    workflow_b = concurrent_builder.build()
+    # Run workflow_b
+    # Context is not maintained across instances
+    # Should not expect mentions of electric bikes in the results
+    print("\n=== First Run on workflow_b ===")
+    await run_workflow(workflow_b, "Refine your response to focus on the California market.")
+
+    """
+    Sample Output:
+
+    === First Run on workflow_a ===
+    The budget-friendly electric bike market is poised for significant growth, driven by urbanization, ...
+
+    === Second Run on workflow_a ===
+    Launching a budget-friendly electric bike in California presents significant opportunities, driven ...
+
+    === First Run on workflow_b ===
+    To successfully penetrate the California market, consider these tailored strategies focused on ...
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,117 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import (
+    AgentRunUpdateEvent,
+    ChatAgent,
+    ChatMessage,
+    GroupChatBuilder,
+    Role,
+    WorkflowOutputEvent,
+)
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+
+"""
+Sample: Group Chat with Agent-Based Manager
+
+What it does:
+- Demonstrates the new set_manager() API for agent-based coordination
+- Manager is a full ChatAgent with access to tools, context, and observability
+- Coordinates a researcher and writer agent to solve tasks collaboratively
+
+Prerequisites:
+- OpenAI environment variables configured for OpenAIChatClient
+"""
+
+ORCHESTRATOR_AGENT_INSTRUCTIONS = """
+You coordinate a team conversation to solve the user's task.
+
+Guidelines:
+- Start with Researcher to gather information
+- Then have Writer synthesize the final answer
+- Only finish after both have contributed meaningfully
+"""
+
+
+async def main() -> None:
+    # Create a chat client using Azure OpenAI and Azure CLI credentials for all agents
+    chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
+
+    # Orchestrator agent that manages the conversation
+    # Note: This agent (and the underlying chat client) must support structured outputs.
+    # The group chat workflow relies on this to parse the orchestrator's decisions.
+    # `response_format` is set internally by the GroupChat workflow when the agent is invoked.
+    orchestrator_agent = ChatAgent(
+        name="Orchestrator",
+        description="Coordinates multi-agent collaboration by selecting speakers",
+        instructions=ORCHESTRATOR_AGENT_INSTRUCTIONS,
+        chat_client=chat_client,
+    )
+
+    # Participant agents
+    researcher = ChatAgent(
+        name="Researcher",
+        description="Collects relevant background information",
+        instructions="Gather concise facts that help a teammate answer the question.",
+        chat_client=chat_client,
+    )
+
+    writer = ChatAgent(
+        name="Writer",
+        description="Synthesizes polished answers from gathered information",
+        instructions="Compose clear and structured answers using any notes provided.",
+        chat_client=chat_client,
+    )
+
+    # Build the group chat workflow
+    workflow = (
+        GroupChatBuilder()
+        .with_agent_orchestrator(orchestrator_agent)
+        .participants([researcher, writer])
+        # Set a hard termination condition: stop after 4 assistant messages
+        # The agent orchestrator will intelligently decide when to end before this limit but just in case
+        .with_termination_condition(lambda messages: sum(1 for msg in messages if msg.role == Role.ASSISTANT) >= 4)
+        .build()
+    )
+
+    task = "What are the key benefits of using async/await in Python? Provide a concise summary."
+
+    print("\nStarting Group Chat with Agent-Based Manager...\n")
+    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
+    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 __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,364 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import logging
+from typing import cast
+
+from agent_framework import (
+    AgentRunUpdateEvent,
+    ChatAgent,
+    ChatMessage,
+    GroupChatBuilder,
+    Role,
+    WorkflowOutputEvent,
+)
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+
+logging.basicConfig(level=logging.WARNING)
+
+"""
+Sample: Philosophical Debate with Agent-Based Manager
+
+What it does:
+- Creates a diverse group of agents representing different global perspectives
+- Uses an agent-based manager to guide a philosophical discussion
+- Demonstrates longer, multi-round discourse with natural conversation flow
+- Manager decides when discussion has reached meaningful conclusion
+
+Topic: "What does a good life mean to you personally?"
+
+Participants represent:
+- Farmer from Southeast Asia (tradition, sustainability, land connection)
+- Software Developer from United States (innovation, technology, work-life balance)
+- History Teacher from Eastern Europe (legacy, learning, cultural continuity)
+- Activist from South America (social justice, environmental rights)
+- Spiritual Leader from Middle East (morality, community service)
+- Artist from Africa (creative expression, storytelling)
+- Immigrant Entrepreneur from Asia in Canada (tradition + adaptation)
+- Doctor from Scandinavia (public health, equity, societal support)
+
+Prerequisites:
+- OpenAI environment variables configured for OpenAIChatClient
+"""
+
+
+def _get_chat_client() -> AzureOpenAIChatClient:
+    return AzureOpenAIChatClient(credential=AzureCliCredential())
+
+
+async def main() -> None:
+    # Create debate moderator with structured output for speaker selection
+    # Note: Participant names and descriptions are automatically injected by the orchestrator
+    moderator = ChatAgent(
+        name="Moderator",
+        description="Guides philosophical discussion by selecting next speaker",
+        instructions="""
+You are a thoughtful moderator guiding a philosophical discussion on the topic handed to you by the user.
+
+Your participants bring diverse global perspectives. Select speakers strategically to:
+- Create natural conversation flow and responses to previous points
+- Ensure all voices are heard throughout the discussion
+- Build on themes and contrasts that emerge
+- Allow for respectful challenges and counterpoints
+- Guide toward meaningful conclusions
+
+Select speakers who can:
+1. Respond directly to points just made
+2. Introduce fresh perspectives when needed
+3. Bridge or contrast different viewpoints
+4. Deepen the philosophical exploration
+
+Finish when:
+- Multiple rounds have occurred (at least 6-8 exchanges)
+- Key themes have been explored from different angles
+- Natural conclusion or synthesis has emerged
+- Diminishing returns in new insights
+
+In your final_message, provide a brief synthesis highlighting key themes that emerged.
+""",
+        chat_client=_get_chat_client(),
+    )
+
+    farmer = ChatAgent(
+        name="Farmer",
+        description="A rural farmer from Southeast Asia",
+        instructions="""
+You're a farmer from Southeast Asia. Your life is deeply connected to land and family.
+You value tradition and sustainability. You are in a philosophical debate.
+
+Share your perspective authentically. Feel free to:
+- Challenge other participants respectfully
+- Build on points others have made
+- Use concrete examples from your experience
+- Keep responses thoughtful but concise (2-4 sentences)
+""",
+        chat_client=_get_chat_client(),
+    )
+
+    developer = ChatAgent(
+        name="Developer",
+        description="An urban software developer from the United States",
+        instructions="""
+You're a software developer from the United States. Your life is fast-paced and technology-driven.
+You value innovation, freedom, and work-life balance. You are in a philosophical debate.
+
+Share your perspective authentically. Feel free to:
+- Challenge other participants respectfully
+- Build on points others have made
+- Use concrete examples from your experience
+- Keep responses thoughtful but concise (2-4 sentences)
+""",
+        chat_client=_get_chat_client(),
+    )
+
+    teacher = ChatAgent(
+        name="Teacher",
+        description="A retired history teacher from Eastern Europe",
+        instructions="""
+You're a retired history teacher from Eastern Europe. You bring historical and philosophical
+perspectives to discussions. You value legacy, learning, and cultural continuity.
+You are in a philosophical debate.
+
+Share your perspective authentically. Feel free to:
+- Challenge other participants respectfully
+- Build on points others have made
+- Use concrete examples from history or your teaching experience
+- Keep responses thoughtful but concise (2-4 sentences)
+""",
+        chat_client=_get_chat_client(),
+    )
+
+    activist = ChatAgent(
+        name="Activist",
+        description="A young activist from South America",
+        instructions="""
+You're a young activist from South America. You focus on social justice, environmental rights,
+and generational change. You are in a philosophical debate.
+
+Share your perspective authentically. Feel free to:
+- Challenge other participants respectfully
+- Build on points others have made
+- Use concrete examples from your activism
+- Keep responses thoughtful but concise (2-4 sentences)
+""",
+        chat_client=_get_chat_client(),
+    )
+
+    spiritual_leader = ChatAgent(
+        name="SpiritualLeader",
+        description="A spiritual leader from the Middle East",
+        instructions="""
+You're a spiritual leader from the Middle East. You provide insights grounded in religion,
+morality, and community service. You are in a philosophical debate.
+
+Share your perspective authentically. Feel free to:
+- Challenge other participants respectfully
+- Build on points others have made
+- Use examples from spiritual teachings or community work
+- Keep responses thoughtful but concise (2-4 sentences)
+""",
+        chat_client=_get_chat_client(),
+    )
+
+    artist = ChatAgent(
+        name="Artist",
+        description="An artist from Africa",
+        instructions="""
+You're an artist from Africa. You view life through creative expression, storytelling,
+and collective memory. You are in a philosophical debate.
+
+Share your perspective authentically. Feel free to:
+- Challenge other participants respectfully
+- Build on points others have made
+- Use examples from your art or cultural traditions
+- Keep responses thoughtful but concise (2-4 sentences)
+""",
+        chat_client=_get_chat_client(),
+    )
+
+    immigrant = ChatAgent(
+        name="Immigrant",
+        description="An immigrant entrepreneur from Asia living in Canada",
+        instructions="""
+You're an immigrant entrepreneur from Asia living in Canada. You balance tradition with adaptation.
+You focus on family success, risk, and opportunity. You are in a philosophical debate.
+
+Share your perspective authentically. Feel free to:
+- Challenge other participants respectfully
+- Build on points others have made
+- Use examples from your immigrant and entrepreneurial journey
+- Keep responses thoughtful but concise (2-4 sentences)
+""",
+        chat_client=_get_chat_client(),
+    )
+
+    doctor = ChatAgent(
+        name="Doctor",
+        description="A doctor from Scandinavia",
+        instructions="""
+You're a doctor from Scandinavia. Your perspective is shaped by public health, equity,
+and structured societal support. You are in a philosophical debate.
+
+Share your perspective authentically. Feel free to:
+- Challenge other participants respectfully
+- Build on points others have made
+- Use examples from healthcare and societal systems
+- Keep responses thoughtful but concise (2-4 sentences)
+""",
+        chat_client=_get_chat_client(),
+    )
+
+    workflow = (
+        GroupChatBuilder()
+        .with_agent_orchestrator(moderator)
+        .participants([farmer, developer, teacher, activist, spiritual_leader, artist, immigrant, doctor])
+        .with_termination_condition(lambda messages: sum(1 for msg in messages if msg.role == Role.ASSISTANT) >= 10)
+        .build()
+    )
+
+    topic = "What does a good life mean to you personally?"
+
+    print("\n" + "=" * 80)
+    print("PHILOSOPHICAL DEBATE: Perspectives on a Good Life")
+    print("=" * 80)
+    print(f"\nTopic: {topic}")
+    print("\nParticipants:")
+    print("  - Farmer (Southeast Asia)")
+    print("  - Developer (United States)")
+    print("  - Teacher (Eastern Europe)")
+    print("  - Activist (South America)")
+    print("  - SpiritualLeader (Middle East)")
+    print("  - Artist (Africa)")
+    print("  - Immigrant (Asia → Canada)")
+    print("  - Doctor (Scandinavia)")
+    print("\n" + "=" * 80)
+    print("DISCUSSION BEGINS")
+    print("=" * 80 + "\n")
+
+    final_conversation: list[ChatMessage] = []
+    current_speaker: 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}")
+
+    """
+    Sample Output:
+
+    ================================================================================
+    PHILOSOPHICAL DEBATE: Perspectives on a Good Life
+    ================================================================================
+
+    Topic: What does a good life mean to you personally?
+
+    Participants:
+    - Farmer (Southeast Asia)
+    - Developer (United States)
+    - Teacher (Eastern Europe)
+    - Activist (South America)
+    - SpiritualLeader (Middle East)
+    - Artist (Africa)
+    - Immigrant (Asia → Canada)
+    - Doctor (Scandinavia)
+
+    ================================================================================
+    DISCUSSION BEGINS
+    ================================================================================
+
+    [Farmer]
+    To me, a good life is deeply intertwined with the rhythm of the land and the nurturing of relationships with my
+    family and community. It means cultivating crops that respect our environment, ensuring sustainability for future
+    generations, and sharing meals made from our harvests around the dinner table. The joy found in everyday
+    tasks—planting rice or tending to our livestock—creates a sense of fulfillment that cannot be measured by material
+    wealth. It's the simple moments, like sharing stories with my children under the stars, that truly define a good
+    life. What good is progress if it isolates us from those we love and the land that sustains us?
+
+    [Developer]
+    As a software developer in an urban environment, a good life for me hinges on the intersection of innovation,
+    creativity, and balance. It's about having the freedom to explore new technologies that can solve real-world
+    problems while ensuring that my work doesn't encroach on my personal life. For instance, I value remote work
+    flexibility, which allows me to maintain connections with family and friends, similar to how the Farmer values
+    community. While our lifestyles may differ markedly, both of us seek fulfillment—whether through meaningful work or
+    rich personal experiences. The challenge is finding harmony between technological progress and preserving the
+    intimate human connections that truly enrich our lives.
+
+    [SpiritualLeader]
+    From my spiritual perspective, a good life embodies a balance between personal fulfillment and service to others,
+    rooted in compassion and community. In our teachings, we emphasize that true happiness comes from helping those in
+    need and fostering strong connections with our families and neighbors. Whether it's the Farmer nurturing the earth
+    or the Developer creating tools to enhance lives, both contribute to the greater good. The essence of a good life
+    lies in our intentions and actions—finding ways to serve our communities, spread kindness, and live harmoniously
+    with those around us. Ultimately, as we align our personal beliefs with our communal responsibilities, we cultivate
+    a richness that transcends material wealth.
+
+    [Activist]
+    As a young activist in South America, a good life for me is about advocating for social justice and environmental
+    sustainability. It means living in a society where everyone's rights are respected and where marginalized voices,
+    particularly those of Indigenous communities, are amplified. I see a good life as one where we work collectively to
+    dismantle oppressive systems—such as deforestation and inequality—while nurturing our planet. For instance, through
+    my activism, I've witnessed the transformative power of community organizing, where collective efforts lead to real
+    change, like resisting destructive mining practices that threaten our rivers and lands. A good life, therefore, is
+    not just lived for oneself but is deeply tied to the well-being of our communities and the health of our
+    environment. How can we, regardless of our backgrounds, collaborate to foster these essential changes?
+
+    [Teacher]
+    As a retired history teacher from Eastern Europe, my understanding of a good life is deeply rooted in the lessons
+    drawn from history and the struggle for freedom and dignity. Historical events, such as the fall of the Iron
+    Curtain, remind us of the profound importance of liberty and collective resilience. A good life, therefore, is about
+    cherishing our freedoms and working towards a society where everyone has a voice, much as my students and I
+    discussed the impacts of totalitarian regimes. Additionally, I believe it involves fostering cultural continuity,
+    where we honor our heritage while embracing progressive values. We must learn from the past—especially the
+    consequences of neglecting empathy and solidarity—so that we can cultivate a future that values every individual's
+    contributions to the rich tapestry of our shared humanity. How can we ensure that the lessons of history inform a
+    more compassionate and just society moving forward?
+
+    [Artist]
+    As an artist from Africa, I define a good life as one steeped in cultural expression, storytelling, and the
+    celebration of our collective memories. Art is a powerful medium through which we capture our histories, struggles,
+    and triumphs, creating a tapestry that connects generations. For instance, in my work, I often draw from folktales
+    and traditional music, weaving narratives that reflect the human experience, much like how the retired teacher
+    emphasizes learning from history. A good life involves not only personal fulfillment but also the responsibility to
+    share our narratives and use our creativity to inspire change, whether addressing social injustices or environmental
+    issues. It's in this interplay of art and activism that we can transcend individual existence and contribute to a
+    collective good, fostering empathy and understanding among diverse communities. How can we harness art to bridge
+    differences and amplify marginalized voices in our pursuit of a good life?
+
+    ================================================================================
+    DISCUSSION SUMMARY
+    ================================================================================
+
+    As our discussion unfolds, several key themes have gracefully emerged, reflecting the richness of diverse
+    perspectives on what constitutes a good life. From the rural farmer's integration with the land to the developer's
+    search for balance between technology and personal connection, each viewpoint validates that fulfillment, at its
+    core, transcends material wealth. The spiritual leader and the activist highlight the importance of community and
+    social justice, while the history teacher and the artist remind us of the lessons and narratives that shape our
+    cultural and personal identities.
+
+    Ultimately, the good life seems to revolve around meaningful relationships, honoring our legacies while striving for
+    progress, and nurturing both our inner selves and external communities. This dialogue demonstrates that despite our
+    varied backgrounds and experiences, the quest for a good life binds us together, urging cooperation and empathy in
+    our shared human journey.
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,135 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import (
+    AgentRunUpdateEvent,
+    ChatAgent,
+    ChatMessage,
+    GroupChatBuilder,
+    GroupChatState,
+    WorkflowOutputEvent,
+)
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+
+"""
+Sample: Group Chat with a round-robin speaker selector
+
+What it does:
+- Demonstrates the with_select_speaker_func() API for GroupChat orchestration
+- Uses a pure Python function to control speaker selection based on conversation state
+
+Prerequisites:
+- OpenAI environment variables configured for OpenAIChatClient
+"""
+
+
+def round_robin_selector(state: GroupChatState) -> str:
+    """A round-robin selector function that picks the next speaker based on the current round index."""
+
+    participant_names = list(state.participants.keys())
+    return participant_names[state.current_round % len(participant_names)]
+
+
+async def main() -> None:
+    # Create a chat client using Azure OpenAI and Azure CLI credentials for all agents
+    chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
+
+    # Participant agents
+    expert = ChatAgent(
+        name="PythonExpert",
+        instructions=(
+            "You are an expert in Python in a workgroup. "
+            "Your job is to answer Python related questions and refine your answer "
+            "based on feedback from all the other participants."
+        ),
+        chat_client=chat_client,
+    )
+
+    verifier = ChatAgent(
+        name="AnswerVerifier",
+        instructions=(
+            "You are a programming expert in a workgroup. "
+            f"Your job is to review the answer provided by {expert.name} and point "
+            "out statements that are technically true but practically dangerous."
+            "If there is nothing woth pointing out, respond with 'The answer looks good to me.'"
+        ),
+        chat_client=chat_client,
+    )
+
+    clarifier = ChatAgent(
+        name="AnswerClarifier",
+        instructions=(
+            "You are an accessibility expert in a workgroup. "
+            f"Your job is to review the answer provided by {expert.name} and point "
+            "out jargons or complex terms that may be difficult for a beginner to understand."
+            "If there is nothing worth pointing out, respond with 'The answer looks clear to me.'"
+        ),
+        chat_client=chat_client,
+    )
+
+    skeptic = ChatAgent(
+        name="Skeptic",
+        instructions=(
+            "You are a devil's advocate in a workgroup. "
+            f"Your job is to review the answer provided by {expert.name} and point "
+            "out caveats, exceptions, and alternative perspectives."
+            "If there is nothing worth pointing out, respond with 'I have no further questions.'"
+        ),
+        chat_client=chat_client,
+    )
+
+    # Build the group chat workflow
+    workflow = (
+        GroupChatBuilder()
+        .participants([expert, verifier, clarifier, skeptic])
+        .with_select_speaker_func(round_robin_selector)
+        # Set a hard termination condition: stop after 6 messages (user task + one full rounds + 1)
+        # One round is expert -> verifier -> clarifier -> skeptic, after which the expert gets to respond again.
+        # This will end the conversation after the expert has spoken 2 times (one iteration loop)
+        # 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)
+        .build()
+    )
+
+    task = "How does Python’s Protocol differ from abstract base classes?"
+
+    print("\nStarting Group Chat with round-robin speaker selector...\n")
+    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
+    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 __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,158 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import logging
+from typing import cast
+
+from agent_framework import (
+    AgentResponseUpdate,
+    AgentRunUpdateEvent,
+    ChatAgent,
+    ChatMessage,
+    HandoffBuilder,
+    HostedWebSearchTool,
+    WorkflowEvent,
+    WorkflowOutputEvent,
+    resolve_agent_id,
+)
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+
+logging.basicConfig(level=logging.ERROR)
+
+"""Sample: Autonomous handoff workflow with agent iteration.
+
+This sample demonstrates `.with_autonomous_mode()`, where agents continue
+iterating on their task until they explicitly invoke a handoff tool. This allows
+specialists to perform long-running autonomous work (research, coding, analysis)
+without prematurely returning control to the coordinator or user.
+
+Routing Pattern:
+    User -> Coordinator -> Specialist (iterates N times) -> Handoff -> Final Output
+
+Prerequisites:
+    - `az login` (Azure CLI authentication)
+    - Environment variables for AzureOpenAIChatClient (AZURE_OPENAI_ENDPOINT, etc.)
+
+Key Concepts:
+    - Autonomous interaction mode: agents iterate until they handoff
+    - Turn limits: use `.with_autonomous_mode(turn_limits={agent_name: N})` to cap iterations per agent
+"""
+
+
+def create_agents(
+    chat_client: AzureOpenAIChatClient,
+) -> tuple[ChatAgent, ChatAgent, ChatAgent]:
+    """Create coordinator and specialists for autonomous iteration."""
+    coordinator = chat_client.as_agent(
+        instructions=(
+            "You are a coordinator. You break down a user query into a research task and a summary task. "
+            "Assign the two tasks to the appropriate specialists, one after the other."
+        ),
+        name="coordinator",
+    )
+
+    research_agent = chat_client.as_agent(
+        instructions=(
+            "You are a research specialist that explores topics thoroughly using web search. "
+            "When given a research task, break it down into multiple aspects and explore each one. "
+            "Continue your research across multiple responses - don't try to finish everything in one "
+            "response. After each response, think about what else needs to be explored. When you have "
+            "covered the topic comprehensively (at least 3-4 different aspects), return control to the "
+            "coordinator. Keep each individual response focused on one aspect."
+        ),
+        name="research_agent",
+        tools=[HostedWebSearchTool()],
+    )
+
+    summary_agent = chat_client.as_agent(
+        instructions=(
+            "You summarize research findings. Provide a concise, well-organized summary. When done, return "
+            "control to the coordinator."
+        ),
+        name="summary_agent",
+    )
+
+    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.value
+            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())
+    coordinator, research_agent, summary_agent = create_agents(chat_client)
+
+    # Build the workflow with autonomous mode
+    # In autonomous mode, agents continue iterating until they invoke a handoff tool
+    workflow = (
+        HandoffBuilder(
+            name="autonomous_iteration_handoff",
+            participants=[coordinator, research_agent, summary_agent],
+        )
+        .with_start_agent(coordinator)
+        .add_handoff(coordinator, [research_agent, summary_agent])
+        .add_handoff(research_agent, [coordinator])  # Research can hand back to coordinator
+        .add_handoff(summary_agent, [coordinator])
+        .with_autonomous_mode(
+            # You can set turn limits per agent to allow some agents to go longer.
+            # If a limit is not set, the agent will get an default limit: 50.
+            # Internally, handoff prefers agent names as the agent identifiers if set.
+            # Otherwise, it falls back to agent IDs.
+            turn_limits={
+                resolve_agent_id(coordinator): 5,
+                resolve_agent_id(research_agent): 10,
+                resolve_agent_id(summary_agent): 5,
+            }
+        )
+        .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.value == "assistant")
+            >= 5
+        )
+        .build()
+    )
+
+    request = "Perform a comprehensive research on Microsoft Agent Framework."
+    print("Request:", request)
+    async for event in workflow.run_stream(request):
+        _display_event(event)
+
+    """
+    Expected behavior:
+        - Coordinator routes to research_agent.
+        - Research agent iterates multiple times, exploring different aspects of Microsoft Agent Framework.
+        - Each iteration adds to the conversation without returning to coordinator.
+        - After thorough research, research_agent calls handoff to coordinator.
+        - Coordinator routes to summary_agent for final summary.
+
+    In autonomous mode, agents continue working until they invoke a handoff tool,
+    allowing the research_agent to perform 3-4+ responses before handing off.
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,276 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import logging
+from typing import Annotated, cast
+
+from agent_framework import (
+    AgentResponse,
+    AgentRunEvent,
+    ChatAgent,
+    ChatMessage,
+    HandoffAgentUserRequest,
+    HandoffBuilder,
+    HandoffSentEvent,
+    RequestInfoEvent,
+    Workflow,
+    WorkflowEvent,
+    WorkflowOutputEvent,
+    WorkflowRunState,
+    WorkflowStatusEvent,
+    ai_function,
+)
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+
+logging.basicConfig(level=logging.ERROR)
+
+"""Sample: Handoff workflow with participant factories for state isolation.
+
+This sample demonstrates how to use participant factories in HandoffBuilder to create
+agents dynamically.
+
+Using participant factories allows you to set up proper state isolation between workflow
+instances created by the same builder. This is particularly useful when you need to handle
+requests or tasks in parallel with stateful participants.
+
+Routing Pattern:
+    User -> Triage Agent -> Specialist (Refund/Order Status/Return) -> User
+
+Prerequisites:
+    - `az login` (Azure CLI authentication)
+    - Environment variables for AzureOpenAIChatClient (AZURE_OPENAI_ENDPOINT, etc.)
+
+Key Concepts:
+    - Participant factories: create agents via factory functions for isolation
+    - State isolation: each workflow instance gets its own agent instances
+"""
+
+
+@ai_function
+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."""
+    return f"Refund processed successfully for order {order_number}."
+
+
+@ai_function
+def check_order_status(order_number: Annotated[str, "Order number to check status for"]) -> str:
+    """Simulated function to check the status of a given order number."""
+    return f"Order {order_number} is currently being processed and will ship in 2 business days."
+
+
+@ai_function
+def process_return(order_number: Annotated[str, "Order number to process return for"]) -> str:
+    """Simulated function to process a return for a given order number."""
+    return f"Return initiated successfully for order {order_number}. You will receive return instructions via email."
+
+
+def create_triage_agent() -> ChatAgent:
+    """Factory function to create a triage agent instance."""
+    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+        instructions=(
+            "You are frontline support triage. Route customer issues to the appropriate specialist agents "
+            "based on the problem described."
+        ),
+        name="triage_agent",
+    )
+
+
+def create_refund_agent() -> ChatAgent:
+    """Factory function to create a refund agent instance."""
+    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+        instructions="You process refund requests.",
+        name="refund_agent",
+        # In a real application, an agent can have multiple tools; here we keep it simple
+        tools=[process_refund],
+    )
+
+
+def create_order_status_agent() -> ChatAgent:
+    """Factory function to create an order status agent instance."""
+    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+        instructions="You handle order and shipping inquiries.",
+        name="order_agent",
+        # In a real application, an agent can have multiple tools; here we keep it simple
+        tools=[check_order_status],
+    )
+
+
+def create_return_agent() -> ChatAgent:
+    """Factory function to create a return agent instance."""
+    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+        instructions="You manage product return requests.",
+        name="return_agent",
+        # In a real application, an agent can have multiple tools; here we keep it simple
+        tools=[process_return],
+    )
+
+
+def _handle_events(events: list[WorkflowEvent]) -> list[RequestInfoEvent]:
+    """Process workflow events and extract any pending user input requests.
+
+    This function inspects each event type and:
+    - Prints workflow status changes (IDLE, IDLE_WITH_PENDING_REQUESTS, etc.)
+    - Displays final conversation snapshots when workflow completes
+    - Prints user input request prompts
+    - Collects all RequestInfoEvent instances for response handling
+
+    Args:
+        events: List of WorkflowEvent to process
+
+    Returns:
+        List of RequestInfoEvent representing pending user input requests
+    """
+    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.value
+                print(f"- {speaker}: {message.text}")
+
+        # HandoffSentEvent: Indicates a handoff has been initiated
+        if isinstance(event, HandoffSentEvent):
+            print(f"\n[Handoff from {event.source} to {event.target} initiated.]")
+
+        # WorkflowStatusEvent: Indicates workflow state changes
+        if isinstance(event, WorkflowStatusEvent) and event.state in {
+            WorkflowRunState.IDLE,
+            WorkflowRunState.IDLE_WITH_PENDING_REQUESTS,
+        }:
+            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:
+                    speaker = message.author_name or message.role.value
+                    print(f"- {speaker}: {message.text or [content.type for content in message.contents]}")
+                print("===================================")
+
+        # RequestInfoEvent: Workflow is requesting user input
+        elif isinstance(event, RequestInfoEvent):
+            if isinstance(event.data, HandoffAgentUserRequest):
+                _print_handoff_agent_user_request(event.data.agent_response)
+            requests.append(event)
+
+    return requests
+
+
+def _print_handoff_agent_user_request(response: AgentResponse) -> None:
+    """Display the agent's response messages when requesting user input.
+
+    This will happen when an agent generates a response that doesn't trigger
+    a handoff, i.e., the agent is asking the user for more information.
+
+    Args:
+        response: The AgentResponse from the agent requesting user input
+    """
+    if not response.messages:
+        raise RuntimeError("Cannot print agent responses: response has no messages.")
+
+    print("\n[Agent is requesting your input...]")
+
+    # Print agent responses
+    for message in response.messages:
+        if not message.text:
+            # Skip messages without text (e.g., tool calls)
+            continue
+        speaker = message.author_name or message.role.value
+        print(f"- {speaker}: {message.text}")
+
+
+async def _run_workflow(workflow: Workflow, user_inputs: list[str]) -> None:
+    """Run the workflow with the given user input and display events."""
+    print(f"- User: {user_inputs[0]}")
+    workflow_result = await workflow.run(user_inputs[0])
+    pending_requests = _handle_events(workflow_result)
+
+    # Process the request/response cycle
+    # The workflow will continue requesting input until:
+    # 1. The termination condition is met (4 user messages in this case), OR
+    # 2. We run out of scripted responses
+    while pending_requests:
+        if user_inputs[1:]:
+            # Get the next scripted response
+            user_response = user_inputs.pop(1)
+            print(f"\n- User: {user_response}")
+
+            # Send response(s) to all pending requests
+            # In this demo, there's typically one request per cycle, but the API supports multiple
+            responses = {
+                req.request_id: HandoffAgentUserRequest.create_response(user_response) for req in pending_requests
+            }
+        else:
+            # No more scripted responses; terminate the workflow
+            responses = {req.request_id: HandoffAgentUserRequest.terminate() for req in pending_requests}
+
+        # Send responses and get new events
+        # We use send_responses_streaming() to get events as they occur, allowing us to
+        # display agent responses in real-time and handle new requests as they arrive
+        workflow_result = await workflow.send_responses(responses)
+        pending_requests = _handle_events(workflow_result)
+
+
+async def main() -> None:
+    """Run the autonomous handoff workflow with participant factories."""
+    # Build the handoff workflow using participant factories
+    workflow_builder = (
+        HandoffBuilder(
+            name="Autonomous Handoff with Participant Factories",
+            participant_factories={
+                "triage": create_triage_agent,
+                "refund": create_refund_agent,
+                "order_status": create_order_status_agent,
+                "return": create_return_agent,
+            },
+        )
+        .with_start_agent("triage")
+        .with_termination_condition(
+            # 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()
+        )
+    )
+
+    # Scripted user responses for reproducible demo
+    # In a console application, replace this with:
+    #   user_input = input("Your response: ")
+    # or integrate with a UI/chat interface
+    user_inputs = [
+        "Hello, I need assistance with my recent purchase.",
+        "My order 1234 arrived damaged and the packaging was destroyed. I'd like to return it.",
+        "Is my return being processed?",
+        "Thanks for resolving this.",
+    ]
+
+    workflow_a = workflow_builder.build()
+    print("=== Running workflow_a ===")
+    await _run_workflow(workflow_a, list(user_inputs))
+
+    workflow_b = workflow_builder.build()
+    print("=== Running workflow_b ===")
+    # Only provide the last two inputs to workflow_b to demonstrate state isolation
+    # The agents in this workflow have no prior context thus should not have knowledge of
+    # order 1234 or previous interactions.
+    await _run_workflow(workflow_b, user_inputs[2:])
+    """
+    Expected behavior:
+    - workflow_a and workflow_b maintain separate states for their participants.
+    - Each workflow processes its requests independently without interference.
+    - workflow_a will answer the follow-up request based on its own conversation history,
+      while workflow_b will provide a general answer without prior context.
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,302 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import Annotated, cast
+
+from agent_framework import (
+    AgentResponse,
+    AgentRunEvent,
+    ChatAgent,
+    ChatMessage,
+    HandoffAgentUserRequest,
+    HandoffBuilder,
+    HandoffSentEvent,
+    RequestInfoEvent,
+    WorkflowEvent,
+    WorkflowOutputEvent,
+    WorkflowRunState,
+    WorkflowStatusEvent,
+    ai_function,
+)
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+
+"""Sample: Simple handoff workflow.
+
+A handoff workflow defines a pattern that assembles agents in a mesh topology, allowing
+them to transfer control to each other based on the conversation context.
+
+Prerequisites:
+    - `az login` (Azure CLI authentication)
+    - Environment variables configured for AzureOpenAIChatClient (AZURE_OPENAI_ENDPOINT, etc.)
+
+Key Concepts:
+    - Auto-registered handoff tools: HandoffBuilder automatically creates handoff tools
+      for each participant, allowing the coordinator to transfer control to specialists
+    - Termination condition: Controls when the workflow stops requesting user input
+    - Request/response cycle: Workflow requests input, user responds, cycle continues
+"""
+
+
+@ai_function
+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."""
+    return f"Refund processed successfully for order {order_number}."
+
+
+@ai_function
+def check_order_status(order_number: Annotated[str, "Order number to check status for"]) -> str:
+    """Simulated function to check the status of a given order number."""
+    return f"Order {order_number} is currently being processed and will ship in 2 business days."
+
+
+@ai_function
+def process_return(order_number: Annotated[str, "Order number to process return for"]) -> str:
+    """Simulated function to process a return for a given order number."""
+    return f"Return initiated successfully for order {order_number}. You will receive return instructions via email."
+
+
+def create_agents(chat_client: AzureOpenAIChatClient) -> tuple[ChatAgent, ChatAgent, ChatAgent, ChatAgent]:
+    """Create and configure the triage and specialist agents.
+
+    Args:
+        chat_client: The AzureOpenAIChatClient to use for creating agents.
+
+    Returns:
+        Tuple of (triage_agent, refund_agent, order_agent, return_agent)
+    """
+    # Triage agent: Acts as the frontline dispatcher
+    triage_agent = chat_client.as_agent(
+        instructions=(
+            "You are frontline support triage. Route customer issues to the appropriate specialist agents "
+            "based on the problem described."
+        ),
+        name="triage_agent",
+    )
+
+    # Refund specialist: Handles refund requests
+    refund_agent = chat_client.as_agent(
+        instructions="You process refund requests.",
+        name="refund_agent",
+        # In a real application, an agent can have multiple tools; here we keep it simple
+        tools=[process_refund],
+    )
+
+    # Order/shipping specialist: Resolves delivery issues
+    order_agent = chat_client.as_agent(
+        instructions="You handle order and shipping inquiries.",
+        name="order_agent",
+        # In a real application, an agent can have multiple tools; here we keep it simple
+        tools=[check_order_status],
+    )
+
+    # Return specialist: Handles return requests
+    return_agent = chat_client.as_agent(
+        instructions="You manage product return requests.",
+        name="return_agent",
+        # In a real application, an agent can have multiple tools; here we keep it simple
+        tools=[process_return],
+    )
+
+    return triage_agent, refund_agent, order_agent, return_agent
+
+
+def _handle_events(events: list[WorkflowEvent]) -> list[RequestInfoEvent]:
+    """Process workflow events and extract any pending user input requests.
+
+    This function inspects each event type and:
+    - Prints workflow status changes (IDLE, IDLE_WITH_PENDING_REQUESTS, etc.)
+    - Displays final conversation snapshots when workflow completes
+    - Prints user input request prompts
+    - Collects all RequestInfoEvent instances for response handling
+
+    Args:
+        events: List of WorkflowEvent to process
+
+    Returns:
+        List of RequestInfoEvent representing pending user input requests
+    """
+    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.value
+                print(f"- {speaker}: {message.text}")
+
+        # HandoffSentEvent: Indicates a handoff has been initiated
+        if isinstance(event, HandoffSentEvent):
+            print(f"\n[Handoff from {event.source} to {event.target} initiated.]")
+
+        # WorkflowStatusEvent: Indicates workflow state changes
+        if isinstance(event, WorkflowStatusEvent) and event.state in {
+            WorkflowRunState.IDLE,
+            WorkflowRunState.IDLE_WITH_PENDING_REQUESTS,
+        }:
+            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:
+                    speaker = message.author_name or message.role.value
+                    print(f"- {speaker}: {message.text or [content.type for content in message.contents]}")
+                print("===================================")
+
+        # RequestInfoEvent: Workflow is requesting user input
+        elif isinstance(event, RequestInfoEvent):
+            if isinstance(event.data, HandoffAgentUserRequest):
+                _print_handoff_agent_user_request(event.data.agent_response)
+            requests.append(event)
+
+    return requests
+
+
+def _print_handoff_agent_user_request(response: AgentResponse) -> None:
+    """Display the agent's response messages when requesting user input.
+
+    This will happen when an agent generates a response that doesn't trigger
+    a handoff, i.e., the agent is asking the user for more information.
+
+    Args:
+        response: The AgentResponse from the agent requesting user input
+    """
+    if not response.messages:
+        raise RuntimeError("Cannot print agent responses: response has no messages.")
+
+    print("\n[Agent is requesting your input...]")
+
+    # Print agent responses
+    for message in response.messages:
+        if not message.text:
+            # Skip messages without text (e.g., tool calls)
+            continue
+        speaker = message.author_name or message.role.value
+        print(f"- {speaker}: {message.text}")
+
+
+async def main() -> None:
+    """Main entry point for the handoff workflow demo.
+
+    This function demonstrates:
+    1. Creating triage and specialist agents
+    2. Building a handoff workflow with custom termination condition
+    3. Running the workflow with scripted user responses
+    4. Processing events and handling user input requests
+
+    The workflow uses scripted responses instead of interactive input to make
+    the demo reproducible and testable. In a production application, you would
+    replace the scripted_responses with actual user input collection.
+    """
+    # Initialize the Azure OpenAI chat client
+    chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
+
+    # Create all agents: triage + specialists
+    triage, refund, order, support = create_agents(chat_client)
+
+    # Build the handoff workflow
+    # - participants: All agents that can participate in the workflow
+    # - with_start_agent: The triage agent is designated as the start agent, which means
+    #   it receives all user input first and orchestrates handoffs to specialists
+    # - with_termination_condition: Custom logic to stop the request/response loop.
+    #   Without this, the default behavior continues requesting user input until max_turns
+    #   is reached. Here we use a custom condition that checks if the conversation has ended
+    #   naturally (when one of the agents says something like "you're welcome").
+    workflow = (
+        HandoffBuilder(
+            name="customer_support_handoff",
+            participants=[triage, refund, order, support],
+        )
+        .with_start_agent(triage)
+        .with_termination_condition(
+            # Custom termination: Check if one of the agents has provided a closing message.
+            # This looks for the last message containing "welcome", which indicates the
+            # conversation has concluded naturally.
+            lambda conversation: len(conversation) > 0 and "welcome" in conversation[-1].text.lower()
+        )
+        .build()
+    )
+
+    # Scripted user responses for reproducible demo
+    # In a console application, replace this with:
+    #   user_input = input("Your response: ")
+    # or integrate with a UI/chat interface
+    scripted_responses = [
+        "My order 1234 arrived damaged and the packaging was destroyed. I'd like to return it.",
+        "Please also process a refund for order 1234.",
+        "Thanks for resolving this.",
+    ]
+
+    # Start the workflow with the initial user message
+    # run_stream() returns an async iterator of WorkflowEvent
+    print("[Starting workflow with initial user message...]\n")
+    initial_message = "Hello, I need assistance with my recent purchase."
+    print(f"- User: {initial_message}")
+    workflow_result = await workflow.run(initial_message)
+    pending_requests = _handle_events(workflow_result)
+
+    # Process the request/response cycle
+    # The workflow will continue requesting input until:
+    # 1. The termination condition is met, OR
+    # 2. We run out of scripted responses
+    while pending_requests:
+        if not scripted_responses:
+            # No more scripted responses; terminate the workflow
+            responses = {req.request_id: HandoffAgentUserRequest.terminate() for req in pending_requests}
+        else:
+            # Get the next scripted response
+            user_response = scripted_responses.pop(0)
+            print(f"\n- User: {user_response}")
+
+            # Send response(s) to all pending requests
+            # In this demo, there's typically one request per cycle, but the API supports multiple
+            responses = {
+                req.request_id: HandoffAgentUserRequest.create_response(user_response) for req in pending_requests
+            }
+
+        # Send responses and get new events
+        # We use send_responses() to get events from the workflow, allowing us to
+        # display agent responses and handle new requests as they arrive
+        events = await workflow.send_responses(responses)
+        pending_requests = _handle_events(events)
+
+    """
+    Sample Output:
+
+    [Starting workflow with initial user message...]
+
+    - User: Hello, I need assistance with my recent purchase.
+    - triage_agent: Could you please provide more details about the issue you're experiencing with your recent purchase? This will help me route you to the appropriate specialist.
+
+    [Workflow Status] IDLE_WITH_PENDING_REQUESTS
+
+    - User: My order 1234 arrived damaged and the packaging was destroyed. I'd like to return it.
+    - triage_agent: I've directed your request to our return agent, who will assist you with returning the damaged order. Thank you for your patience!
+    - return_agent: The return for your order 1234 has been successfully initiated. You will receive return instructions via email shortly. If you have any other questions or need further assistance, feel free to ask!
+
+    [Workflow Status] IDLE_WITH_PENDING_REQUESTS
+
+    - User: Thanks for resolving this.
+
+    === Final Conversation Snapshot ===
+    - user: Hello, I need assistance with my recent purchase.
+    - triage_agent: Could you please provide more details about the issue you're experiencing with your recent purchase? This will help me route you to the appropriate specialist.
+    - user: My order 1234 arrived damaged and the packaging was destroyed. I'd like to return it.
+    - triage_agent: I've directed your request to our return agent, who will assist you with returning the damaged order. Thank you for your patience!
+    - return_agent: The return for your order 1234 has been successfully initiated. You will receive return instructions via email shortly. If you have any other questions or need further assistance, feel free to ask!
+    - user: Thanks for resolving this.
+    - triage_agent: You're welcome! If you have any more questions or need assistance in the future, feel free to reach out. Have a great day!
+    ===================================
+
+    [Workflow Status] IDLE
+    """  # noqa: E501
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,225 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""
+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.
+
+Verifies GitHub issue #2718: files generated by code interpreter in
+HandoffBuilder workflows can be properly retrieved.
+
+Toggle USE_V2_CLIENT to switch between:
+    - V1: AzureAIAgentClient (azure-ai-agents SDK)
+    - V2: AzureAIClient (azure-ai-projects 2.x with Responses API)
+
+IMPORTANT: When using V2 AzureAIClient with HandoffBuilder, each agent must
+have its own client instance. The V2 client binds to a single server-side
+agent name, so sharing a client between agents causes routing issues.
+
+Prerequisites:
+    - `az login` (Azure CLI authentication)
+    - V1: AZURE_AI_AGENT_PROJECT_CONNECTION_STRING
+    - V2: AZURE_AI_PROJECT_ENDPOINT, AZURE_AI_MODEL_DEPLOYMENT_NAME
+"""
+
+import asyncio
+from collections.abc import AsyncIterable, AsyncIterator
+from contextlib import asynccontextmanager
+
+from agent_framework import (
+    AgentRunUpdateEvent,
+    ChatAgent,
+    HandoffAgentUserRequest,
+    HandoffBuilder,
+    HostedCodeInterpreterTool,
+    HostedFileContent,
+    RequestInfoEvent,
+    TextContent,
+    WorkflowEvent,
+    WorkflowRunState,
+    WorkflowStatusEvent,
+)
+from azure.identity.aio import AzureCliCredential
+
+# Toggle between V1 (AzureAIAgentClient) and V2 (AzureAIClient)
+USE_V2_CLIENT = False
+
+
+async def _drain(stream: AsyncIterable[WorkflowEvent]) -> list[WorkflowEvent]:
+    """Collect all events from an async stream."""
+    return [event async for event in stream]
+
+
+def _handle_events(events: list[WorkflowEvent]) -> tuple[list[RequestInfoEvent], list[str]]:
+    """Process workflow events and extract file IDs and pending requests.
+
+    Returns:
+        Tuple of (pending_requests, file_ids_found)
+    """
+    requests: 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}")
+
+        elif isinstance(event, RequestInfoEvent):
+            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 isinstance(content, TextContent) 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
+
+
+@asynccontextmanager
+async def create_agents_v1(credential: AzureCliCredential) -> AsyncIterator[tuple[ChatAgent, ChatAgent]]:
+    """Create agents using V1 AzureAIAgentClient."""
+    from agent_framework.azure import AzureAIAgentClient
+
+    async with AzureAIAgentClient(credential=credential) as client:
+        triage = client.as_agent(
+            name="triage_agent",
+            instructions=(
+                "You are a triage agent. Route code-related requests to the code_specialist. "
+                "When the user asks to create or generate files, hand off to code_specialist "
+                "by calling handoff_to_code_specialist."
+            ),
+        )
+
+        code_specialist = client.as_agent(
+            name="code_specialist",
+            instructions=(
+                "You are a Python code specialist. Use the code interpreter to execute Python code "
+                "and create files when requested. Always save files to /mnt/data/ directory."
+            ),
+            tools=[HostedCodeInterpreterTool()],
+        )
+
+        yield triage, code_specialist
+
+
+@asynccontextmanager
+async def create_agents_v2(credential: AzureCliCredential) -> AsyncIterator[tuple[ChatAgent, ChatAgent]]:
+    """Create agents using V2 AzureAIClient.
+
+    Each agent needs its own client instance because the V2 client binds
+    to a single server-side agent name.
+    """
+    from agent_framework.azure import AzureAIClient
+
+    async with (
+        AzureAIClient(credential=credential) as triage_client,
+        AzureAIClient(credential=credential) as code_client,
+    ):
+        triage = triage_client.as_agent(
+            name="TriageAgent",
+            instructions="You are a triage agent. Your ONLY job is to route requests to the appropriate specialist.",
+        )
+
+        code_specialist = code_client.as_agent(
+            name="CodeSpecialist",
+            instructions=(
+                "You are a Python code specialist. You have access to a code interpreter tool. "
+                "Use the code interpreter to execute Python code and create files. "
+                "Always save files to /mnt/data/ directory. "
+                "Do NOT discuss handoffs or routing - just complete the coding task directly."
+            ),
+            tools=[HostedCodeInterpreterTool()],
+        )
+
+        yield triage, code_specialist
+
+
+async def main() -> None:
+    """Run a simple handoff workflow with code interpreter file generation."""
+    client_version = "V2 (AzureAIClient)" if USE_V2_CLIENT else "V1 (AzureAIAgentClient)"
+    print(f"=== Handoff Workflow with Code Interpreter File Generation [{client_version}] ===\n")
+
+    async with AzureCliCredential() as credential:
+        create_agents = create_agents_v2 if USE_V2_CLIENT else create_agents_v1
+
+        async with create_agents(credential) as (triage, code_specialist):
+            workflow = (
+                HandoffBuilder()
+                .participants([triage, code_specialist])
+                .with_start_agent(triage)
+                .with_termination_condition(lambda conv: sum(1 for msg in conv if msg.role.value == "user") >= 2)
+                .build()
+            )
+
+            user_inputs = [
+                "Please create a text file called hello.txt with 'Hello from handoff workflow!' inside it.",
+                "exit",
+            ]
+            input_index = 0
+            all_file_ids: list[str] = []
+
+            print(f"User: {user_inputs[0]}")
+            events = await _drain(workflow.run_stream(user_inputs[0]))
+            requests, file_ids = _handle_events(events)
+            all_file_ids.extend(file_ids)
+            input_index += 1
+
+            while requests:
+                request = requests[0]
+                if input_index >= len(user_inputs):
+                    break
+                user_input = user_inputs[input_index]
+                print(f"\nUser: {user_input}")
+
+                responses = {request.request_id: HandoffAgentUserRequest.create_response(user_input)}
+                events = await _drain(workflow.send_responses_streaming(responses))
+                requests, file_ids = _handle_events(events)
+                all_file_ids.extend(file_ids)
+                input_index += 1
+
+            print("\n" + "=" * 50)
+            if all_file_ids:
+                print(f"SUCCESS: Found {len(all_file_ids)} file ID(s) in handoff workflow:")
+                for fid in all_file_ids:
+                    print(f"  - {fid}")
+            else:
+                print("WARNING: No file IDs captured from the handoff workflow.")
+            print("=" * 50)
+
+            """
+            Sample Output:
+
+            User: Please create a text file called hello.txt with 'Hello from handoff workflow!' inside it.
+            [Found HostedFileContent: file_id=assistant-JT1sA...]
+
+            === Conversation So Far ===
+            - user: Please create a text file called hello.txt with 'Hello from handoff workflow!' inside it.
+            - triage_agent: I am handing off your request to create the text file "hello.txt" with the specified content to the code specialist. They will assist you shortly.
+            - code_specialist: The file "hello.txt" has been created with the content "Hello from handoff workflow!". You can download it using the link below:
+
+            [hello.txt](sandbox:/mnt/data/hello.txt)
+            ===========================
+
+            [status] IDLE_WITH_PENDING_REQUESTS
+
+            User: exit
+            [status] IDLE
+
+            ==================================================
+            SUCCESS: Found 1 file ID(s) in handoff workflow:
+            - assistant-JT1sA...
+            ==================================================
+            """  # noqa: E501
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,150 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import json
+import logging
+from typing import cast
+
+from agent_framework import (
+    AgentRunUpdateEvent,
+    ChatAgent,
+    ChatMessage,
+    GroupChatRequestSentEvent,
+    HostedCodeInterpreterTool,
+    MagenticBuilder,
+    MagenticOrchestratorEvent,
+    MagenticProgressLedger,
+    WorkflowOutputEvent,
+)
+from agent_framework.openai import OpenAIChatClient, OpenAIResponsesClient
+
+logging.basicConfig(level=logging.WARNING)
+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(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(),
+    )
+
+    # Create a manager agent for orchestration
+    manager_agent = ChatAgent(
+        name="MagenticManager",
+        description="Orchestrator that coordinates the research and coding workflow",
+        instructions="You coordinate a team to complete complex tasks efficiently.",
+        chat_client=OpenAIChatClient(),
+    )
+
+    print("\nBuilding Magentic Workflow...")
+
+    workflow = (
+        MagenticBuilder()
+        .participants([researcher_agent, coder_agent])
+        .with_standard_manager(
+            agent=manager_agent,
+            max_round_count=10,
+            max_stall_count=3,
+            max_reset_count=2,
+        )
+        .build()
+    )
+
+    task = (
+        "I am preparing a report on the energy efficiency of different machine learning model architectures. "
+        "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...")
+
+    # Keep track of the last executor to format output nicely in streaming mode
+    last_message_id: str | None = None
+    output_event: WorkflowOutputEvent | 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):
+            print(f"\n[Magentic Orchestrator Event] Type: {event.event_type.name}")
+            if isinstance(event.data, ChatMessage):
+                print(f"Please review the plan:\n{event.data.text}")
+            elif isinstance(event.data, MagenticProgressLedger):
+                print(f"Please review progress ledger:\n{json.dumps(event.data.to_dict(), indent=2)}")
+            else:
+                print(f"Unknown data type in MagenticOrchestratorEvent: {type(event.data)}")
+
+            # Block to allow user to read the plan/progress before continuing
+            # Note: this is for demonstration only and is not the recommended way to handle human interaction.
+            # Please refer to `with_plan_review` for proper human interaction during planning phases.
+            await asyncio.get_event_loop().run_in_executor(None, input, "Press Enter to continue...")
+
+        elif isinstance(event, GroupChatRequestSentEvent):
+            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)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,316 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import json
+from pathlib import Path
+from typing import cast
+
+from agent_framework import (
+    ChatAgent,
+    ChatMessage,
+    FileCheckpointStorage,
+    MagenticBuilder,
+    MagenticPlanReviewRequest,
+    RequestInfoEvent,
+    WorkflowCheckpoint,
+    WorkflowOutputEvent,
+    WorkflowRunState,
+    WorkflowStatusEvent,
+)
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity._credentials import AzureCliCredential
+
+"""
+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 pending plan-review request
+   map, at superstep boundaries.
+3. **Resume with responses** - `Workflow.send_responses_streaming` 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=AzureOpenAIChatClient(credential=AzureCliCredential()),
+    )
+
+    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=AzureOpenAIChatClient(credential=AzureCliCredential()),
+    )
+
+    # Create a manager agent for orchestration
+    manager_agent = ChatAgent(
+        name="MagenticManager",
+        description="Orchestrator that coordinates the research and writing workflow",
+        instructions="You coordinate a team to complete complex tasks efficiently.",
+        chat_client=AzureOpenAIChatClient(credential=AzureCliCredential()),
+    )
+
+    # 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, writer])
+        .with_plan_review()
+        .with_standard_manager(
+            agent=manager_agent,
+            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: MagenticPlanReviewRequest | None = None
+    async for event in workflow.run_stream(TASK):
+        if isinstance(event, RequestInfoEvent) and event.request_type is MagenticPlanReviewRequest:
+            plan_review_request = event.data
+            print(f"Captured plan review request: {event.request_id}")
+
+        if isinstance(event, WorkflowStatusEvent) and event.state is WorkflowRunState.IDLE_WITH_PENDING_REQUESTS:
+            break
+
+    if plan_review_request is None:
+        print("No plan review request emitted; nothing to resume.")
+        return
+
+    checkpoints = await checkpoint_storage.list_checkpoints(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("pending_request_info_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)
+
+    # Construct an approval reply to supply when the plan review request is re-emitted.
+    approval = plan_review_request.approve()
+
+    # Resume execution and capture the re-emitted plan review request.
+    request_info_event: RequestInfoEvent | None = None
+    async for event in resumed_workflow.run_stream(checkpoint_id=resume_checkpoint.checkpoint_id):
+        if isinstance(event, RequestInfoEvent) and isinstance(event.data, MagenticPlanReviewRequest):
+            request_info_event = event
+
+    if request_info_event is None:
+        print("No plan review request re-emitted on resume; cannot approve.")
+        return
+    print(f"Resumed plan review request: {request_info_event.request_id}")
+
+    # Supply the approval and continue to run to completion.
+    final_event: WorkflowOutputEvent | None = None
+    async for event in resumed_workflow.send_responses_streaming({request_info_event.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
+    output_messages = cast(list[ChatMessage], result)
+    print("\n=== Final Answer ===")
+    # The output of the Magentic workflow is a list of ChatMessages with only one final message
+    # generated by the orchestrator.
+    print(output_messages[-1].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.run_stream(checkpoint_id=post_plan_checkpoint.checkpoint_id):
+        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(output_messages[-1].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
+
+    output_messages = cast(list[ChatMessage], post_result)
+    print("\n=== Final Answer (post-plan resume) ===")
+    # The output of the Magentic workflow is a list of ChatMessages with only one final message
+    # generated by the orchestrator.
+    print(output_messages[-1].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_review.py

@@ -0,0 +1,145 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import json
+from typing import cast
+
+from agent_framework import (
+    AgentRunUpdateEvent,
+    ChatAgent,
+    ChatMessage,
+    MagenticBuilder,
+    MagenticPlanReviewRequest,
+    RequestInfoEvent,
+    WorkflowOutputEvent,
+)
+from agent_framework.openai import OpenAIChatClient
+
+"""
+Sample: Magentic Orchestration with Human Plan Review
+
+This sample demonstrates how humans can review and provide feedback on plans
+generated by the Magentic workflow orchestrator. When plan review is enabled,
+the workflow requests human approval or revision before executing each plan.
+
+Key concepts:
+- with_plan_review(): Enables human review of generated plans
+- MagenticPlanReviewRequest: The event type for plan review requests
+- Human can choose to: approve the plan or provide revision feedback
+
+Plan review options:
+- approve(): Accept the proposed plan and continue execution
+- revise(feedback): Provide textual feedback to modify the plan
+
+Prerequisites:
+- OpenAI credentials configured for `OpenAIChatClient`.
+"""
+
+
+async def main() -> None:
+    researcher_agent = ChatAgent(
+        name="ResearcherAgent",
+        description="Specialist in research and information gathering",
+        instructions="You are a Researcher. You find information and gather facts.",
+        chat_client=OpenAIChatClient(model_id="gpt-4o"),
+    )
+
+    analyst_agent = ChatAgent(
+        name="AnalystAgent",
+        description="Data analyst who processes and summarizes research findings",
+        instructions="You are an Analyst. You analyze findings and create summaries.",
+        chat_client=OpenAIChatClient(model_id="gpt-4o"),
+    )
+
+    manager_agent = ChatAgent(
+        name="MagenticManager",
+        description="Orchestrator that coordinates the workflow",
+        instructions="You coordinate a team to complete tasks efficiently.",
+        chat_client=OpenAIChatClient(model_id="gpt-4o"),
+    )
+
+    print("\nBuilding Magentic Workflow with Human Plan Review...")
+
+    workflow = (
+        MagenticBuilder()
+        .participants([researcher_agent, analyst_agent])
+        .with_standard_manager(
+            agent=manager_agent,
+            max_round_count=10,
+            max_stall_count=1,
+            max_reset_count=2,
+        )
+        .with_plan_review()  # Request human input for plan review
+        .build()
+    )
+
+    task = "Research sustainable aviation fuel technology and summarize the findings."
+
+    print(f"\nTask: {task}")
+    print("\nStarting workflow execution...")
+    print("=" * 60)
+
+    pending_request: RequestInfoEvent | None = None
+    pending_responses: dict[str, object] | None = None
+    output_event: WorkflowOutputEvent | None = None
+
+    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)
+
+
+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.as_agent(
+        instructions=("You are a concise copywriter. Provide a single, punchy marketing sentence based on the prompt."),
+        name="writer",
+    )
+
+    reviewer = chat_client.as_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,104 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import Any
+
+from agent_framework import (
+    AgentExecutorResponse,
+    ChatMessage,
+    Executor,
+    Role,
+    SequentialBuilder,
+    WorkflowContext,
+    handler,
+)
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+
+"""
+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
+after all participants have executed in sequence, and the final output contains
+the complete conversation.
+
+Custom executor contract:
+- Provide at least one @handler accepting AgentExecutorResponse and a WorkflowContext[list[ChatMessage]]
+- Emit the updated conversation via ctx.send_message([...])
+
+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, agent_response: AgentExecutorResponse, ctx: WorkflowContext[list[ChatMessage]]) -> None:
+        """Append a summary message to a copy of the full conversation.
+
+        Note: A custom executor must be able to handle the message type from the prior participant, and produce
+        the message type expected by the next participant. In this case, the prior participant is an agent thus
+        the input is AgentExecutorResponse (an agent will be wrapped in an AgentExecutor, which produces
+        `AgentExecutorResponse`). If the next participant is also an agent or this is the final participant,
+        the output must be `list[ChatMessage]`.
+        """
+        if not agent_response.full_conversation:
+            await ctx.send_message([ChatMessage(role=Role.ASSISTANT, text="No conversation to summarize.")])
+            return
+
+        users = sum(1 for m in agent_response.full_conversation if m.role == Role.USER)
+        assistants = sum(1 for m in agent_response.full_conversation if m.role == Role.ASSISTANT)
+        summary = ChatMessage(role=Role.ASSISTANT, text=f"Summary -> users:{users} assistants:{assistants}")
+        final_conversation = list(agent_response.full_conversation) + [summary]
+        await ctx.send_message(final_conversation)
+
+
+async def main() -> None:
+    # 1) Create a content agent
+    chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
+    content = chat_client.as_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 workflow and extract 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())

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

@@ -0,0 +1,127 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import (
+    ChatAgent,
+    ChatMessage,
+    Executor,
+    Role,
+    SequentialBuilder,
+    Workflow,
+    WorkflowContext,
+    handler,
+)
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+
+"""
+Sample: Sequential workflow with participant factories
+
+This sample demonstrates how to create a sequential workflow with participant factories.
+
+Using participant factories allows you to set up proper state isolation between workflow
+instances created by the same builder. This is particularly useful when you need to handle
+requests or tasks in parallel with stateful participants.
+
+In this example, we create a sequential workflow with two participants: an accumulator
+and a content producer. The accumulator is stateful and maintains a list of all messages it has
+received. Context is maintained across runs of the same workflow instance but not across different
+workflow instances.
+"""
+
+
+class Accumulate(Executor):
+    """Simple accumulator.
+
+    Accumulates all messages from the conversation and prints them out.
+    """
+
+    def __init__(self, id: str):
+        super().__init__(id)
+        # Some internal state to accumulate messages
+        self._accumulated: list[str] = []
+
+    @handler
+    async def accumulate(self, conversation: list[ChatMessage], ctx: WorkflowContext[list[ChatMessage]]) -> None:
+        self._accumulated.extend([msg.text for msg in conversation])
+        print(f"Number of queries received so far: {len(self._accumulated)}")
+        await ctx.send_message(conversation)
+
+
+def create_agent() -> ChatAgent:
+    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+        instructions="Produce a concise paragraph answering the user's request.",
+        name="ContentProducer",
+    )
+
+
+async def run_workflow(workflow: Workflow, query: str) -> None:
+    events = await workflow.run(query)
+    outputs = events.get_outputs()
+
+    if outputs:
+        messages: list[ChatMessage] = outputs[0]
+        for message in messages:
+            name = message.author_name or ("assistant" if message.role == Role.ASSISTANT else "user")
+            print(f"{name}: {message.text}")
+    else:
+        raise RuntimeError("No outputs received from the workflow.")
+
+
+async def main() -> None:
+    # 1) Create a builder with participant factories
+    builder = SequentialBuilder().register_participants([
+        lambda: Accumulate("accumulator"),
+        create_agent,
+    ])
+    # 2) Build workflow_a
+    workflow_a = builder.build()
+
+    # 3) Run workflow_a
+    # Context is maintained across runs
+    print("=== First Run on workflow_a ===")
+    await run_workflow(workflow_a, "Why is the sky blue?")
+    print("\n=== Second Run on workflow_a ===")
+    await run_workflow(workflow_a, "Repeat my previous question.")
+
+    # 4) Build workflow_b
+    # This will create a new instance of the accumulator and content producer
+    # using the same workflow builder
+    workflow_b = builder.build()
+
+    # 5) Run workflow_b
+    # Context is not maintained across instances
+    print("\n=== First Run on workflow_b ===")
+    await run_workflow(workflow_b, "Repeat my previous question.")
+
+    """
+    Sample Output:
+
+    === First Run on workflow_a ===
+    Number of queries received so far: 1
+    user: Why is the sky blue?
+    ContentProducer: The sky appears blue due to a phenomenon called Rayleigh scattering.
+                     When sunlight enters the Earth's atmosphere, it collides with gases
+                     and particles, scattering shorter wavelengths of light (blue and violet)
+                     more than the longer wavelengths (red and yellow). Although violet light
+                     is scattered even more than blue, our eyes are more sensitive to blue
+                     light, and some violet light is absorbed by the ozone layer. As a result,
+                     we perceive the sky as predominantly blue during the day.
+
+    === Second Run on workflow_a ===
+    Number of queries received so far: 2
+    user: Repeat my previous question.
+    ContentProducer: Why is the sky blue?
+
+    === First Run on workflow_b ===
+    Number of queries received so far: 1
+    user: Repeat my previous question.
+    ContentProducer: I'm sorry, but I can't repeat your previous question as I don't have
+                     access to your past queries. However, feel free to ask anything again,
+                     and I'll be happy to help!
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,99 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import random
+
+from agent_framework import Executor, WorkflowBuilder, WorkflowContext, WorkflowOutputEvent, handler
+from typing_extensions import Never
+
+"""
+Sample: Concurrent fan out and fan in with two different tasks that output results of different types.
+
+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.
+"""
+
+
+class Dispatcher(Executor):
+    """
+    The sole purpose of this decorator is to dispatch the input of the workflow to
+    other executors.
+    """
+
+    @handler
+    async def handle(self, numbers: list[int], ctx: WorkflowContext[list[int]]):
+        if not numbers:
+            raise RuntimeError("Input must be a valid list of integers.")
+
+        await ctx.send_message(numbers)
+
+
+class Average(Executor):
+    """Calculate the average of a list of integers."""
+
+    @handler
+    async def handle(self, numbers: list[int], ctx: WorkflowContext[float]):
+        average: float = sum(numbers) / len(numbers)
+        await ctx.send_message(average)
+
+
+class Sum(Executor):
+    """Calculate the sum of a list of integers."""
+
+    @handler
+    async def handle(self, numbers: list[int], ctx: WorkflowContext[int]):
+        total: int = sum(numbers)
+        await ctx.send_message(total)
+
+
+class Aggregator(Executor):
+    """Aggregate the results from the different tasks and yield the final output."""
+
+    @handler
+    async def handle(self, results: list[int | float], ctx: WorkflowContext[Never, list[int | float]]):
+        """Receive the results from the source executors.
+
+        The framework will automatically collect messages from the source executors
+        and deliver them as a list.
+
+        Args:
+            results (list[int | float]): execution results from upstream executors.
+                The type annotation must be a list of union types that the upstream
+                executors will produce.
+            ctx (WorkflowContext[Never, list[int | float]]): A workflow context that can yield the final output.
+        """
+        await ctx.yield_output(results)
+
+
+async def main() -> None:
+    # 1) Build a simple fan out and fan in workflow
+    workflow = (
+        WorkflowBuilder()
+        .register_executor(lambda: Dispatcher(id="dispatcher"), name="dispatcher")
+        .register_executor(lambda: Average(id="average"), name="average")
+        .register_executor(lambda: Sum(id="summation"), name="summation")
+        .register_executor(lambda: Aggregator(id="aggregator"), name="aggregator")
+        .set_start_executor("dispatcher")
+        .add_fan_out_edges("dispatcher", ["average", "summation"])
+        .add_fan_in_edges(["average", "summation"], "aggregator")
+        .build()
+    )
+
+    # 2) Run the workflow
+    output: list[int | float] | None = None
+    async for event in workflow.run_stream([random.randint(1, 100) for _ in range(10)]):
+        if isinstance(event, WorkflowOutputEvent):
+            output = event.data
+
+    if output is not None:
+        print(output)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,156 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from dataclasses import dataclass
+
+from agent_framework import (  # Core chat primitives to build LLM requests
+    AgentExecutorRequest,  # The message bundle sent to an AgentExecutor
+    AgentExecutorResponse,  # The structured result returned by an AgentExecutor
+    ChatAgent,  # Tracing event for agent execution steps
+    ChatMessage,  # Chat message structure
+    Executor,  # Base class for custom Python executors
+    ExecutorCompletedEvent,
+    ExecutorInvokedEvent,
+    Role,  # Enum of chat roles (user, assistant, system)
+    WorkflowBuilder,  # Fluent builder for wiring the workflow graph
+    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
+
+"""
+Sample: Concurrent fan out and fan in with three domain agents
+
+A dispatcher fans out the same user prompt to research, marketing, and legal AgentExecutor nodes.
+An aggregator then fans in their responses and produces a single consolidated report.
+
+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.
+- Azure OpenAI access configured for AzureOpenAIChatClient. Log in with Azure CLI and set any required environment variables.
+- Comfort reading AgentExecutorResponse.agent_response.text for assistant output aggregation.
+"""
+
+
+class DispatchToExperts(Executor):
+    """Dispatches the incoming prompt to all expert agent executors for parallel processing (fan out)."""
+
+    @handler
+    async def dispatch(self, prompt: str, ctx: WorkflowContext[AgentExecutorRequest]) -> None:
+        # Wrap the incoming prompt as a user message for each expert and request a response.
+        initial_message = ChatMessage(Role.USER, text=prompt)
+        await ctx.send_message(AgentExecutorRequest(messages=[initial_message], should_respond=True))
+
+
+@dataclass
+class AggregatedInsights:
+    """Typed container for the aggregator to hold per domain strings before formatting."""
+
+    research: str
+    marketing: str
+    legal: str
+
+
+class AggregateInsights(Executor):
+    """Aggregates expert agent responses into a single consolidated result (fan in)."""
+
+    @handler
+    async def aggregate(self, results: list[AgentExecutorResponse], ctx: WorkflowContext[Never, str]) -> None:
+        # Map responses to text by executor id for a simple, predictable demo.
+        by_id: dict[str, str] = {}
+        for r in results:
+            # AgentExecutorResponse.agent_response.text is the assistant text produced by the agent.
+            by_id[r.executor_id] = r.agent_response.text
+
+        research_text = by_id.get("researcher", "")
+        marketing_text = by_id.get("marketer", "")
+        legal_text = by_id.get("legal", "")
+
+        aggregated = AggregatedInsights(
+            research=research_text,
+            marketing=marketing_text,
+            legal=legal_text,
+        )
+
+        # Provide a readable, consolidated string as the final workflow result.
+        consolidated = (
+            "Consolidated Insights\n"
+            "====================\n\n"
+            f"Research Findings:\n{aggregated.research}\n\n"
+            f"Marketing Angle:\n{aggregated.marketing}\n\n"
+            f"Legal/Compliance Notes:\n{aggregated.legal}\n"
+        )
+
+        await ctx.yield_output(consolidated)
+
+
+def create_researcher_agent() -> ChatAgent:
+    """Creates a research domain expert agent."""
+    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+        instructions=(
+            "You're an expert market and product researcher. Given a prompt, provide concise, factual insights,"
+            " opportunities, and risks."
+        ),
+        name="researcher",
+    )
+
+
+def create_marketer_agent() -> ChatAgent:
+    """Creates a marketing domain expert agent."""
+    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+        instructions=(
+            "You're a creative marketing strategist. Craft compelling value propositions and target messaging"
+            " aligned to the prompt."
+        ),
+        name="marketer",
+    )
+
+
+def create_legal_agent() -> ChatAgent:
+    """Creates a legal/compliance domain expert agent."""
+    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+        instructions=(
+            "You're a cautious legal/compliance reviewer. Highlight constraints, disclaimers, and policy concerns"
+            " based on the prompt."
+        ),
+        name="legal",
+    )
+
+
+async def main() -> None:
+    # 1) Build a simple fan out and fan in workflow
+    workflow = (
+        WorkflowBuilder()
+        .register_agent(create_researcher_agent, name="researcher")
+        .register_agent(create_marketer_agent, name="marketer")
+        .register_agent(create_legal_agent, name="legal")
+        .register_executor(lambda: DispatchToExperts(id="dispatcher"), name="dispatcher")
+        .register_executor(lambda: AggregateInsights(id="aggregator"), name="aggregator")
+        .set_start_executor("dispatcher")
+        .add_fan_out_edges("dispatcher", ["researcher", "marketer", "legal"])  # Parallel branches
+        .add_fan_in_edges(["researcher", "marketer", "legal"], "aggregator")  # Join at the aggregator
+        .build()
+    )
+
+    # 3) Run with a single prompt and print progress plus the final consolidated output
+    async for event in workflow.run_stream("We are launching a new budget-friendly electric bike for urban commuters."):
+        if isinstance(event, ExecutorInvokedEvent):
+            # Show when executors are invoked and completed for lightweight observability.
+            print(f"{event.executor_id} invoked")
+        elif isinstance(event, ExecutorCompletedEvent):
+            print(f"{event.executor_id} completed")
+        elif isinstance(event, WorkflowOutputEvent):
+            print("===== Final Aggregated Output =====")
+            print(event.data)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,339 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import ast
+import asyncio
+import os
+from collections import defaultdict
+from dataclasses import dataclass
+
+import aiofiles
+from agent_framework import (
+    Executor,  # Base class for custom workflow steps
+    WorkflowBuilder,  # Fluent builder for executors and edges
+    WorkflowContext,  # Per run context with shared state and messaging
+    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
+
+"""
+Sample: Map reduce word count with fan out and fan in over file backed intermediate results
+
+The workflow splits a large text into chunks, maps words to counts in parallel,
+shuffles intermediate pairs to reducers, then reduces to per word totals.
+It also demonstrates WorkflowViz for graph visualization.
+
+Purpose:
+Show how to:
+- Partition input once and coordinate parallel mappers with shared state.
+- Implement map, shuffle, and reduce executors that pass file paths instead of large payloads.
+- Use fan out and fan in edges to express parallelism and joins.
+- Persist intermediate results to disk to bound memory usage for large inputs.
+- Visualize the workflow graph using WorkflowViz and export to SVG with the optional viz extra.
+
+Prerequisites:
+- Familiarity with WorkflowBuilder, executors, fan out and fan in edges, events, and streaming runs.
+- aiofiles installed for async file I/O.
+- Write access to a tmp directory next to this script.
+- A source text at resources/long_text.txt.
+- Optional for SVG export: install graphviz.
+
+Installation:
+    pip install agent-framework aiofiles graphviz
+"""
+
+# Define the temporary directory for storing intermediate results
+DIR = os.path.dirname(__file__)
+TEMP_DIR = os.path.join(DIR, "tmp")
+# Ensure the temporary directory exists
+os.makedirs(TEMP_DIR, exist_ok=True)
+
+# Define a key for the shared state to store the data to be processed
+SHARED_STATE_DATA_KEY = "data_to_be_processed"
+
+
+class SplitCompleted:
+    """Marker type published when splitting finishes. Triggers map executors."""
+
+    ...
+
+
+class Split(Executor):
+    """Splits data into roughly equal chunks based on the number of mapper nodes."""
+
+    def __init__(self, map_executor_ids: list[str], id: str | None = None):
+        """Store mapper ids so we can assign non overlapping ranges per mapper."""
+        super().__init__(id=id or "split")
+        self._map_executor_ids = map_executor_ids
+
+    @handler
+    async def split(self, data: str, ctx: WorkflowContext[SplitCompleted]) -> None:
+        """Tokenize input and assign contiguous index ranges to each mapper via shared state.
+
+        Args:
+            data: The raw text to process.
+            ctx: Workflow context to persist shared state and send messages.
+        """
+        # Process data into a list of words and remove empty lines or words.
+        word_list = self._preprocess(data)
+
+        # Store tokenized words once so all mappers can read by index.
+        await ctx.set_shared_state(SHARED_STATE_DATA_KEY, word_list)
+
+        # Divide indices into contiguous slices for each mapper.
+        map_executor_count = len(self._map_executor_ids)
+        chunk_size = len(word_list) // map_executor_count  # Assumes count > 0.
+
+        async def _process_chunk(i: int) -> None:
+            """Assign the slice for mapper i, then signal that splitting is done."""
+            start_index = i * chunk_size
+            end_index = start_index + chunk_size if i < map_executor_count - 1 else len(word_list)
+
+            # The mapper reads its slice from shared state keyed by its own executor id.
+            await ctx.set_shared_state(self._map_executor_ids[i], (start_index, end_index))
+            await ctx.send_message(SplitCompleted(), self._map_executor_ids[i])
+
+        tasks = [asyncio.create_task(_process_chunk(i)) for i in range(map_executor_count)]
+        await asyncio.gather(*tasks)
+
+    def _preprocess(self, data: str) -> list[str]:
+        """Normalize lines and split on whitespace. Return a flat list of tokens."""
+        line_list = [line.strip() for line in data.splitlines() if line.strip()]
+        return [word for line in line_list for word in line.split() if word]
+
+
+@dataclass
+class MapCompleted:
+    """Signal that a mapper wrote its intermediate pairs to file."""
+
+    file_path: str
+
+
+class Map(Executor):
+    """Maps each token to a count of 1 and writes pairs to a per mapper file."""
+
+    @handler
+    async def map(self, _: SplitCompleted, ctx: WorkflowContext[MapCompleted]) -> None:
+        """Read the assigned slice, emit (word, 1) pairs, and persist to disk.
+
+        Args:
+            _: SplitCompleted marker indicating maps can begin.
+            ctx: Workflow context for shared state access and messaging.
+        """
+        # Retrieve tokens and our assigned slice.
+        data_to_be_processed: list[str] = await ctx.get_shared_state(SHARED_STATE_DATA_KEY)
+        chunk_start, chunk_end = await ctx.get_shared_state(self.id)
+
+        results = [(item, 1) for item in data_to_be_processed[chunk_start:chunk_end]]
+
+        # Write this mapper's results as simple text lines for easy debugging.
+        file_path = os.path.join(TEMP_DIR, f"map_results_{self.id}.txt")
+        async with aiofiles.open(file_path, "w") as f:
+            await f.writelines([f"{item}: {count}\n" for item, count in results])
+
+        await ctx.send_message(MapCompleted(file_path))
+
+
+@dataclass
+class ShuffleCompleted:
+    """Signal that a shuffle partition file is ready for a specific reducer."""
+
+    file_path: str
+    reducer_id: str
+
+
+class Shuffle(Executor):
+    """Groups intermediate pairs by key and partitions them across reducers."""
+
+    def __init__(self, reducer_ids: list[str], id: str | None = None):
+        """Remember reducer ids so we can partition work deterministically."""
+        super().__init__(id=id or "shuffle")
+        self._reducer_ids = reducer_ids
+
+    @handler
+    async def shuffle(self, data: list[MapCompleted], ctx: WorkflowContext[ShuffleCompleted]) -> None:
+        """Aggregate mapper outputs and write one partition file per reducer.
+
+        Args:
+            data: MapCompleted records with file paths for each mapper output.
+            ctx: Workflow context to emit per reducer ShuffleCompleted messages.
+        """
+        chunks = await self._preprocess(data)
+
+        async def _process_chunk(chunk: list[tuple[str, list[int]]], index: int) -> None:
+            """Write one grouped partition for reducer index and notify that reducer."""
+            file_path = os.path.join(TEMP_DIR, f"shuffle_results_{index}.txt")
+            async with aiofiles.open(file_path, "w") as f:
+                await f.writelines([f"{key}: {value}\n" for key, value in chunk])
+            await ctx.send_message(ShuffleCompleted(file_path, self._reducer_ids[index]))
+
+        tasks = [asyncio.create_task(_process_chunk(chunk, i)) for i, chunk in enumerate(chunks)]
+        await asyncio.gather(*tasks)
+
+    async def _preprocess(self, data: list[MapCompleted]) -> list[list[tuple[str, list[int]]]]:
+        """Load all mapper files, group by key, sort keys, and partition for reducers.
+
+        Returns:
+            List of partitions. Each partition is a list of (key, [1, 1, ...]) tuples.
+        """
+        # Load all intermediate pairs.
+        map_results: list[tuple[str, int]] = []
+        for result in data:
+            async with aiofiles.open(result.file_path, "r") as f:
+                map_results.extend([
+                    (line.strip().split(": ")[0], int(line.strip().split(": ")[1])) for line in await f.readlines()
+                ])
+
+        # Group values by token.
+        intermediate_results: defaultdict[str, list[int]] = defaultdict(list[int])
+        for key, value in map_results:
+            intermediate_results[key].append(value)
+
+        # Deterministic ordering helps with debugging and test stability.
+        aggregated_results = [(key, values) for key, values in intermediate_results.items()]
+        aggregated_results.sort(key=lambda x: x[0])
+
+        # Partition keys across reducers as evenly as possible.
+        reduce_executor_count = len(self._reducer_ids)
+        chunk_size = len(aggregated_results) // reduce_executor_count
+        remaining = len(aggregated_results) % reduce_executor_count
+
+        chunks = [
+            aggregated_results[i : i + chunk_size] for i in range(0, len(aggregated_results) - remaining, chunk_size)
+        ]
+        if remaining > 0:
+            chunks[-1].extend(aggregated_results[-remaining:])
+
+        return chunks
+
+
+@dataclass
+class ReduceCompleted:
+    """Signal that a reducer wrote final counts for its partition."""
+
+    file_path: str
+
+
+class Reduce(Executor):
+    """Sums grouped counts per key for its assigned partition."""
+
+    @handler
+    async def _execute(self, data: ShuffleCompleted, ctx: WorkflowContext[ReduceCompleted]) -> None:
+        """Read one shuffle partition and reduce it to totals.
+
+        Args:
+            data: ShuffleCompleted with the partition file path and target reducer id.
+            ctx: Workflow context used to emit ReduceCompleted with our output file path.
+        """
+        if data.reducer_id != self.id:
+            # This partition belongs to a different reducer. Skip.
+            return
+
+        # Read grouped values from the shuffle output.
+        async with aiofiles.open(data.file_path, "r") as f:
+            lines = await f.readlines()
+
+        # Sum values per key. Values are serialized Python lists like [1, 1, ...].
+        reduced_results: dict[str, int] = defaultdict(int)
+        for line in lines:
+            key, value = line.split(": ")
+            reduced_results[key] = sum(ast.literal_eval(value))
+
+        # Persist our partition totals.
+        file_path = os.path.join(TEMP_DIR, f"reduced_results_{self.id}.txt")
+        async with aiofiles.open(file_path, "w") as f:
+            await f.writelines([f"{key}: {value}\n" for key, value in reduced_results.items()])
+
+        await ctx.send_message(ReduceCompleted(file_path))
+
+
+class CompletionExecutor(Executor):
+    """Joins all reducer outputs and yields the final output."""
+
+    @handler
+    async def complete(self, data: list[ReduceCompleted], ctx: WorkflowContext[Never, list[str]]) -> None:
+        """Collect reducer output file paths and yield final output."""
+        await ctx.yield_output([result.file_path for result in data])
+
+
+async def main():
+    """Construct the map reduce workflow, visualize it, then run it over a sample file."""
+
+    # Step 1: Create the workflow builder and register executors.
+    workflow_builder = (
+        WorkflowBuilder()
+        .register_executor(lambda: Map(id="map_executor_0"), name="map_executor_0")
+        .register_executor(lambda: Map(id="map_executor_1"), name="map_executor_1")
+        .register_executor(lambda: Map(id="map_executor_2"), name="map_executor_2")
+        .register_executor(
+            lambda: Split(["map_executor_0", "map_executor_1", "map_executor_2"], id="split_data_executor"),
+            name="split_data_executor",
+        )
+        .register_executor(lambda: Reduce(id="reduce_executor_0"), name="reduce_executor_0")
+        .register_executor(lambda: Reduce(id="reduce_executor_1"), name="reduce_executor_1")
+        .register_executor(lambda: Reduce(id="reduce_executor_2"), name="reduce_executor_2")
+        .register_executor(lambda: Reduce(id="reduce_executor_3"), name="reduce_executor_3")
+        .register_executor(
+            lambda: Shuffle(
+                ["reduce_executor_0", "reduce_executor_1", "reduce_executor_2", "reduce_executor_3"],
+                id="shuffle_executor",
+            ),
+            name="shuffle_executor",
+        )
+        .register_executor(lambda: CompletionExecutor(id="completion_executor"), name="completion_executor")
+    )
+
+    # Step 2: Build the workflow graph using fan out and fan in edges.
+    workflow = (
+        workflow_builder.set_start_executor("split_data_executor")
+        .add_fan_out_edges(
+            "split_data_executor",
+            ["map_executor_0", "map_executor_1", "map_executor_2"],
+        )  # Split -> many mappers
+        .add_fan_in_edges(
+            ["map_executor_0", "map_executor_1", "map_executor_2"],
+            "shuffle_executor",
+        )  # All mappers -> shuffle
+        .add_fan_out_edges(
+            "shuffle_executor",
+            ["reduce_executor_0", "reduce_executor_1", "reduce_executor_2", "reduce_executor_3"],
+        )  # Shuffle -> many reducers
+        .add_fan_in_edges(
+            ["reduce_executor_0", "reduce_executor_1", "reduce_executor_2", "reduce_executor_3"],
+            "completion_executor",
+        )  # All reducers -> completion
+        .build()
+    )
+
+    # Step 2.5: Visualize the workflow (optional)
+    print("Generating workflow visualization...")
+    viz = WorkflowViz(workflow)
+    # Print out the Mermaid string.
+    print("Mermaid string: \n=======")
+    print(viz.to_mermaid())
+    print("=======")
+    # Print out the DiGraph string.
+    print("DiGraph string: \n=======")
+    print(viz.to_digraph())
+    print("=======")
+    try:
+        # Export the DiGraph visualization as SVG.
+        svg_file = viz.export(format="svg")
+        print(f"SVG file saved to: {svg_file}")
+    except ImportError:
+        print("Tip: Install 'viz' extra to export workflow visualization: pip install agent-framework[viz] --pre")
+
+    # Step 3: Open the text file and read its content.
+    async with aiofiles.open(os.path.join(DIR, "../resources", "long_text.txt"), "r") as f:
+        raw_text = await f.read()
+
+    # Step 4: Run the workflow with the raw text as input.
+    async for event in workflow.run_stream(raw_text):
+        print(f"Event: {event}")
+        if isinstance(event, WorkflowOutputEvent):
+            print(f"Final Output: {event.data}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/workflows/resources/ambiguous_email.txt

@@ -0,0 +1,19 @@
+Subject: Action Required: Verify Your Account
+
+Dear Valued Customer,
+
+We have detected unusual activity on your account and need to verify your identity to ensure your security.
+
+To maintain access to your account, please login to your account and complete the verification process.
+
+Account Details:
+- User: johndoe@contoso.com
+- Last Login: 08/15/2025
+- Location: Seattle, WA
+- Device: Mobile
+
+This is an automated security measure. If you believe this email was sent in error, please contact our support team immediately.
+
+Best regards,
+Security Team
+Customer Service Department

python/samples/getting_started/workflows/resources/email.txt

@@ -0,0 +1,18 @@
+Subject: Team Meeting Follow-up - Action Items
+
+Hi Sarah,
+
+I wanted to follow up on our team meeting this morning and share the action items we discussed:
+
+1. Update the project timeline by Friday
+2. Schedule client presentation for next week
+3. Review the budget allocation for Q4
+
+Please let me know if you have any questions or if I missed anything from our discussion.
+
+Best regards,
+Alex Johnson
+Project Manager
+Tech Solutions Inc.
+alex.johnson@techsolutions.com
+(555) 123-4567

python/samples/getting_started/workflows/resources/long_text.txt

@@ -0,0 +1,199 @@
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.
+
+Lorem ipsum dolor sit amet consectetur adipiscing elit. Quisque faucibus ex sapien vitae pellentesque sem placerat. In id cursus mi pretium tellus duis convallis. Tempus leo eu aenean sed diam urna tempor. Pulvinar vivamus fringilla lacus nec metus bibendum egestas. Iaculis massa nisl malesuada lacinia integer nunc posuere. Ut hendrerit semper vel class aptent taciti sociosqu. Ad litora torquent per conubia nostra inceptos himenaeos.

python/samples/getting_started/workflows/resources/spam.txt

@@ -0,0 +1,25 @@
+Subject: 🎉 CONGRATULATIONS! You've WON $1,000,000 - CLAIM NOW! 🎉
+
+Dear Valued Customer,
+
+URGENT NOTICE: You have been selected as our GRAND PRIZE WINNER!
+
+🏆 YOU HAVE WON $1,000,000 USD 🏆
+
+This is NOT a joke! You are one of only 5 lucky winners selected from millions of email addresses worldwide.
+
+To claim your prize, you MUST respond within 24 HOURS or your winnings will be forfeited!
+
+CLICK HERE NOW: http://win-claim.com
+
+What you need to do:
+1. Reply with your full name
+2. Provide your bank account details
+3. Send a processing fee of $500 via wire transfer
+
+ACT FAST! This offer expires TONIGHT at midnight!
+
+Best regards,
+Dr. Johnson Williams
+International Lottery Commission
+Phone: +1-555-999-1234

python/samples/getting_started/workflows/state-management/shared_states_with_agents.py

@@ -0,0 +1,238 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+from agent_framework import (
+    AgentExecutorRequest,
+    AgentExecutorResponse,
+    ChatAgent,
+    ChatMessage,
+    Role,
+    WorkflowBuilder,
+    WorkflowContext,
+    executor,
+)
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+from pydantic import BaseModel
+from typing_extensions import Never
+
+"""
+Sample: Shared state with agents and conditional routing.
+
+Store an email once by id, classify it with a detector agent, then either draft a reply with an assistant
+agent or finish with a spam notice. Stream events as the workflow runs.
+
+Purpose:
+Show how to:
+- Use shared state to decouple large payloads from messages and pass around lightweight references.
+- Enforce structured agent outputs with Pydantic models via response_format for robust parsing.
+- Route using conditional edges based on a typed intermediate DetectionResult.
+- Compose agent backed executors with function style executors and yield the final output when the workflow completes.
+
+Prerequisites:
+- Azure OpenAI configured for AzureOpenAIChatClient with required environment variables.
+- Authentication via azure-identity. Use AzureCliCredential and run az login before executing the sample.
+- Familiarity with WorkflowBuilder, executors, conditional edges, and streaming runs.
+"""
+
+EMAIL_STATE_PREFIX = "email:"
+CURRENT_EMAIL_ID_KEY = "current_email_id"
+
+
+class DetectionResultAgent(BaseModel):
+    """Structured output returned by the spam detection agent."""
+
+    is_spam: bool
+    reason: str
+
+
+class EmailResponse(BaseModel):
+    """Structured output returned by the email assistant agent."""
+
+    response: str
+
+
+@dataclass
+class DetectionResult:
+    """Internal detection result enriched with the shared state email_id for later lookups."""
+
+    is_spam: bool
+    reason: str
+    email_id: str
+
+
+@dataclass
+class Email:
+    """In memory record stored in shared state to avoid re-sending large bodies on edges."""
+
+    email_id: str
+    email_content: str
+
+
+def get_condition(expected_result: bool):
+    """Create a condition predicate for DetectionResult.is_spam.
+
+    Contract:
+    - If the message is not a DetectionResult, allow it to pass to avoid accidental dead ends.
+    - Otherwise, return True only when is_spam matches expected_result.
+    """
+
+    def condition(message: Any) -> bool:
+        if not isinstance(message, DetectionResult):
+            return True
+        return message.is_spam == expected_result
+
+    return condition
+
+
+@executor(id="store_email")
+async def store_email(email_text: str, ctx: WorkflowContext[AgentExecutorRequest]) -> None:
+    """Persist the raw email content in shared state and trigger spam detection.
+
+    Responsibilities:
+    - Generate a unique email_id (UUID) for downstream retrieval.
+    - Store the Email object under a namespaced key and set the current id pointer.
+    - Emit an AgentExecutorRequest asking the detector to respond.
+    """
+    new_email = Email(email_id=str(uuid4()), email_content=email_text)
+    await ctx.set_shared_state(f"{EMAIL_STATE_PREFIX}{new_email.email_id}", new_email)
+    await ctx.set_shared_state(CURRENT_EMAIL_ID_KEY, new_email.email_id)
+
+    await ctx.send_message(
+        AgentExecutorRequest(messages=[ChatMessage(Role.USER, text=new_email.email_content)], should_respond=True)
+    )
+
+
+@executor(id="to_detection_result")
+async def to_detection_result(response: AgentExecutorResponse, ctx: WorkflowContext[DetectionResult]) -> None:
+    """Parse spam detection JSON into a structured model and enrich with email_id.
+
+    Steps:
+    1) Validate the agent's JSON output into DetectionResultAgent.
+    2) Retrieve the current email_id from shared state.
+    3) Send a typed DetectionResult for conditional routing.
+    """
+    parsed = DetectionResultAgent.model_validate_json(response.agent_response.text)
+    email_id: str = await ctx.get_shared_state(CURRENT_EMAIL_ID_KEY)
+    await ctx.send_message(DetectionResult(is_spam=parsed.is_spam, reason=parsed.reason, email_id=email_id))
+
+
+@executor(id="submit_to_email_assistant")
+async def submit_to_email_assistant(detection: DetectionResult, ctx: WorkflowContext[AgentExecutorRequest]) -> None:
+    """Forward non spam email content to the drafting agent.
+
+    Guard:
+    - This path should only receive non spam. Raise if misrouted.
+    """
+    if detection.is_spam:
+        raise RuntimeError("This executor should only handle non-spam messages.")
+
+    # Load the original content by id from shared state and forward it to the assistant.
+    email: Email = await ctx.get_shared_state(f"{EMAIL_STATE_PREFIX}{detection.email_id}")
+    await ctx.send_message(
+        AgentExecutorRequest(messages=[ChatMessage(Role.USER, text=email.email_content)], should_respond=True)
+    )
+
+
+@executor(id="finalize_and_send")
+async def finalize_and_send(response: AgentExecutorResponse, ctx: WorkflowContext[Never, str]) -> None:
+    """Validate the drafted reply and yield the final output."""
+    parsed = EmailResponse.model_validate_json(response.agent_response.text)
+    await ctx.yield_output(f"Email sent: {parsed.response}")
+
+
+@executor(id="handle_spam")
+async def handle_spam(detection: DetectionResult, ctx: WorkflowContext[Never, str]) -> None:
+    """Yield output describing why the email was marked as spam."""
+    if detection.is_spam:
+        await ctx.yield_output(f"Email marked as spam: {detection.reason}")
+    else:
+        raise RuntimeError("This executor should only handle spam messages.")
+
+
+def create_spam_detection_agent() -> ChatAgent:
+    """Creates a spam detection agent."""
+    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+        instructions=(
+            "You are a spam detection assistant that identifies spam emails. "
+            "Always return JSON with fields is_spam (bool) and reason (string)."
+        ),
+        default_options={"response_format": DetectionResultAgent},
+        # response_format enforces structured JSON from each agent.
+        name="spam_detection_agent",
+    )
+
+
+def create_email_assistant_agent() -> ChatAgent:
+    """Creates an email assistant agent."""
+    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+        instructions=(
+            "You are an email assistant that helps users draft responses to emails with professionalism. "
+            "Return JSON with a single field 'response' containing the drafted reply."
+        ),
+        # response_format enforces structured JSON from each agent.
+        default_options={"response_format": EmailResponse},
+        name="email_assistant_agent",
+    )
+
+
+async def main() -> None:
+    """Build and run the shared state with agents and conditional routing workflow."""
+
+    # Build the workflow graph with conditional edges.
+    # Flow:
+    #   store_email -> spam_detection_agent -> to_detection_result -> branch:
+    #     False -> submit_to_email_assistant -> email_assistant_agent -> finalize_and_send
+    #     True  -> handle_spam
+    workflow = (
+        WorkflowBuilder()
+        .register_agent(create_spam_detection_agent, name="spam_detection_agent")
+        .register_agent(create_email_assistant_agent, name="email_assistant_agent")
+        .register_executor(lambda: store_email, name="store_email")
+        .register_executor(lambda: to_detection_result, name="to_detection_result")
+        .register_executor(lambda: submit_to_email_assistant, name="submit_to_email_assistant")
+        .register_executor(lambda: finalize_and_send, name="finalize_and_send")
+        .register_executor(lambda: handle_spam, name="handle_spam")
+        .set_start_executor("store_email")
+        .add_edge("store_email", "spam_detection_agent")
+        .add_edge("spam_detection_agent", "to_detection_result")
+        .add_edge("to_detection_result", "submit_to_email_assistant", condition=get_condition(False))
+        .add_edge("to_detection_result", "handle_spam", condition=get_condition(True))
+        .add_edge("submit_to_email_assistant", "email_assistant_agent")
+        .add_edge("email_assistant_agent", "finalize_and_send")
+        .build()
+    )
+
+    # Read an email from resources/spam.txt if available; otherwise use a default sample.
+    current_file = Path(__file__)
+    resources_path = current_file.parent.parent / "resources" / "spam.txt"
+    if resources_path.exists():
+        email = resources_path.read_text(encoding="utf-8")
+    else:
+        print("Unable to find resource file, using default text.")
+        email = "You are a WINNER! Click here for a free lottery offer!!!"
+
+    # Run and print the final result. Streaming surfaces intermediate execution events as well.
+    events = await workflow.run(email)
+    outputs = events.get_outputs()
+
+    if outputs:
+        print(f"Final result: {outputs[0]}")
+
+    """
+    Sample Output:
+
+    Final result: Email marked as spam: This email exhibits several common spam and scam characteristics:
+    unrealistic claims of large cash winnings, urgent time pressure, requests for sensitive personal and financial
+    information, and a demand for a processing fee. The sender impersonates a generic lottery commission, and the
+    message contains a suspicious link. All these are typical of phishing and lottery scam emails.
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/workflows/state-management/workflow_kwargs.py

@@ -0,0 +1,132 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import json
+from typing import Annotated, Any
+
+from agent_framework import ChatMessage, SequentialBuilder, WorkflowOutputEvent, ai_function
+from agent_framework.openai import OpenAIChatClient
+from pydantic import Field
+
+"""
+Sample: Workflow kwargs Flow to @ai_function Tools
+
+This sample demonstrates how to flow custom context (skill data, user tokens, etc.)
+through any workflow pattern to @ai_function tools using the **kwargs pattern.
+
+Key Concepts:
+- Pass custom context as kwargs when invoking workflow.run_stream() or workflow.run()
+- kwargs are stored in SharedState and passed to all agent invocations
+- @ai_function tools receive kwargs via **kwargs parameter
+- Works with Sequential, Concurrent, GroupChat, Handoff, and Magentic patterns
+
+Prerequisites:
+- OpenAI environment variables configured
+"""
+
+
+# Define tools that accept custom context via **kwargs
+@ai_function
+def get_user_data(
+    query: Annotated[str, Field(description="What user data to retrieve")],
+    **kwargs: Any,
+) -> str:
+    """Retrieve user-specific data based on the authenticated context."""
+    user_token = kwargs.get("user_token", {})
+    user_name = user_token.get("user_name", "anonymous")
+    access_level = user_token.get("access_level", "none")
+
+    print(f"\n[get_user_data] Received kwargs keys: {list(kwargs.keys())}")
+    print(f"[get_user_data] User: {user_name}")
+    print(f"[get_user_data] Access level: {access_level}")
+
+    return f"Retrieved data for user {user_name} with {access_level} access: {query}"
+
+
+@ai_function
+def call_api(
+    endpoint_name: Annotated[str, Field(description="Name of the API endpoint to call")],
+    **kwargs: Any,
+) -> str:
+    """Call an API using the configured endpoints from custom_data."""
+    custom_data = kwargs.get("custom_data", {})
+    api_config = custom_data.get("api_config", {})
+
+    base_url = api_config.get("base_url", "unknown")
+    endpoints = api_config.get("endpoints", {})
+
+    print(f"\n[call_api] Received kwargs keys: {list(kwargs.keys())}")
+    print(f"[call_api] Base URL: {base_url}")
+    print(f"[call_api] Available endpoints: {list(endpoints.keys())}")
+
+    if endpoint_name in endpoints:
+        return f"Called {base_url}{endpoints[endpoint_name]} successfully"
+    return f"Endpoint '{endpoint_name}' not found in configuration"
+
+
+async def main() -> None:
+    print("=" * 70)
+    print("Workflow kwargs Flow Demo (SequentialBuilder)")
+    print("=" * 70)
+
+    # Create chat client
+    chat_client = OpenAIChatClient()
+
+    # Create agent with tools that use kwargs
+    agent = chat_client.as_agent(
+        name="assistant",
+        instructions=(
+            "You are a helpful assistant. Use the available tools to help users. "
+            "When asked about user data, use get_user_data. "
+            "When asked to call an API, use call_api."
+        ),
+        tools=[get_user_data, call_api],
+    )
+
+    # Build a simple sequential workflow
+    workflow = SequentialBuilder().participants([agent]).build()
+
+    # Define custom context that will flow to ai_functions via kwargs
+    custom_data = {
+        "api_config": {
+            "base_url": "https://api.example.com",
+            "endpoints": {
+                "users": "/v1/users",
+                "orders": "/v1/orders",
+                "products": "/v1/products",
+            },
+        },
+    }
+
+    user_token = {
+        "user_name": "bob@contoso.com",
+        "access_level": "admin",
+    }
+
+    print("\nCustom Data being passed:")
+    print(json.dumps(custom_data, indent=2))
+    print(f"\nUser: {user_token['user_name']}")
+    print("\n" + "-" * 70)
+    print("Workflow Execution (watch for [tool_name] logs showing kwargs received):")
+    print("-" * 70)
+
+    # Run workflow with kwargs - these will flow through to ai_functions
+    async for event in workflow.run_stream(
+        "Please get my user data and then call the users API endpoint.",
+        custom_data=custom_data,
+        user_token=user_token,
+    ):
+        if isinstance(event, WorkflowOutputEvent):
+            output_data = event.data
+            if isinstance(output_data, list):
+                for item in output_data:
+                    if isinstance(item, ChatMessage) and item.text:
+                        print(f"\n[Final Answer]: {item.text}")
+
+    print("\n" + "=" * 70)
+    print("Sample Complete")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,193 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import Annotated
+
+from agent_framework import (
+    ChatMessage,
+    ConcurrentBuilder,
+    FunctionApprovalRequestContent,
+    FunctionApprovalResponseContent,
+    RequestInfoEvent,
+    WorkflowOutputEvent,
+    ai_function,
+)
+from agent_framework.openai import OpenAIChatClient
+
+"""
+Sample: Concurrent Workflow with Tool Approval Requests
+
+This sample demonstrates how to use ConcurrentBuilder with tools that require human
+approval before execution. Multiple agents run in parallel, and any tool requiring
+approval will pause the workflow until the human responds.
+
+This sample works as follows:
+1. A ConcurrentBuilder workflow is created with two agents running in parallel.
+2. Both agents have the same tools, including one requiring approval (execute_trade).
+3. Both agents receive the same task and work concurrently on their respective stocks.
+4. When either agent tries to execute a trade, it triggers an approval request.
+5. The sample simulates human approval and the workflow completes.
+6. Results from both agents are aggregated and output.
+
+Purpose:
+Show how tool call approvals work in parallel execution scenarios where multiple
+agents may independently trigger approval requests.
+
+Demonstrate:
+- Handling multiple approval requests from different agents in concurrent workflows.
+- Handling RequestInfoEvent during concurrent agent execution.
+- Understanding that approval pauses only the agent that triggered it, not all agents.
+
+Prerequisites:
+- OpenAI or Azure OpenAI configured with the required environment variables.
+- Basic familiarity with ConcurrentBuilder and streaming workflow events.
+"""
+
+
+# 1. Define market data tools (no approval required)
+@ai_function
+def get_stock_price(symbol: Annotated[str, "The stock ticker symbol"]) -> str:
+    """Get the current stock price for a given symbol."""
+    # Mock data for demonstration
+    prices = {"AAPL": 175.50, "GOOGL": 140.25, "MSFT": 378.90, "AMZN": 178.75}
+    price = prices.get(symbol.upper(), 100.00)
+    return f"{symbol.upper()}: ${price:.2f}"
+
+
+@ai_function
+def get_market_sentiment(symbol: Annotated[str, "The stock ticker symbol"]) -> str:
+    """Get market sentiment analysis for a stock."""
+    # Mock sentiment data
+    mock_data = {
+        "AAPL": "Market sentiment for AAPL: Bullish (68% positive mentions in last 24h)",
+        "GOOGL": "Market sentiment for GOOGL: Neutral (50% positive mentions in last 24h)",
+        "MSFT": "Market sentiment for MSFT: Bullish (72% positive mentions in last 24h)",
+        "AMZN": "Market sentiment for AMZN: Bearish (40% positive mentions in last 24h)",
+    }
+    return mock_data.get(symbol.upper(), f"Market sentiment for {symbol.upper()}: Unknown")
+
+
+# 2. Define trading tools (approval required)
+@ai_function(approval_mode="always_require")
+def execute_trade(
+    symbol: Annotated[str, "The stock ticker symbol"],
+    action: Annotated[str, "Either 'buy' or 'sell'"],
+    quantity: Annotated[int, "Number of shares to trade"],
+) -> str:
+    """Execute a stock trade. Requires human approval due to financial impact."""
+    return f"Trade executed: {action.upper()} {quantity} shares of {symbol.upper()}"
+
+
+@ai_function
+def get_portfolio_balance() -> str:
+    """Get current portfolio balance and available funds."""
+    return "Portfolio: $50,000 invested, $10,000 cash available. Holdings: AAPL, GOOGL, MSFT."
+
+
+def _print_output(event: WorkflowOutputEvent) -> None:
+    if not event.data:
+        raise ValueError("WorkflowOutputEvent has no data")
+
+    if not isinstance(event.data, list) and not all(isinstance(msg, ChatMessage) for msg in event.data):
+        raise ValueError("WorkflowOutputEvent data is not a list of ChatMessage")
+
+    messages: list[ChatMessage] = event.data  # type: ignore
+
+    print("\n" + "-" * 60)
+    print("Workflow completed. Aggregated results from both agents:")
+    for msg in messages:
+        if msg.text:
+            print(f"- {msg.author_name or msg.role.value}: {msg.text}")
+
+
+async def main() -> None:
+    # 3. Create two agents focused on different stocks but with the same tool sets
+    chat_client = OpenAIChatClient()
+
+    microsoft_agent = chat_client.as_agent(
+        name="MicrosoftAgent",
+        instructions=(
+            "You are a personal trading assistant focused on Microsoft (MSFT). "
+            "You manage my portfolio and take actions based on market data."
+        ),
+        tools=[get_stock_price, get_market_sentiment, get_portfolio_balance, execute_trade],
+    )
+
+    google_agent = chat_client.as_agent(
+        name="GoogleAgent",
+        instructions=(
+            "You are a personal trading assistant focused on Google (GOOGL). "
+            "You manage my trades and portfolio based on market conditions."
+        ),
+        tools=[get_stock_price, get_market_sentiment, get_portfolio_balance, execute_trade],
+    )
+
+    # 4. Build a concurrent workflow with both agents
+    # ConcurrentBuilder requires at least 2 participants for fan-out
+    workflow = ConcurrentBuilder().participants([microsoft_agent, google_agent]).build()
+
+    # 5. Start the workflow - both agents will process the same task in parallel
+    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(
+        "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, FunctionApprovalRequestContent):
+                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, FunctionApprovalResponseContent] = {}
+        for request_event in request_info_events:
+            if isinstance(request_event.data, FunctionApprovalRequestContent):
+                print(f"\nSimulating human approval for: {request_event.data.function_call.name}")
+                # Create approval response
+                responses[request_event.request_id] = request_event.data.create_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)")
+
+    """
+    Sample Output:
+    Starting concurrent workflow with tool approval...
+    ------------------------------------------------------------
+
+    Approval requested for tool: execute_trade
+    Arguments: {"symbol":"MSFT","action":"buy","quantity":13}
+
+    Approval requested for tool: execute_trade
+    Arguments: {"symbol":"GOOGL","action":"buy","quantity":35}
+
+    Simulating human approval for: execute_trade
+
+    Simulating human approval for: execute_trade
+
+    ------------------------------------------------------------
+    Workflow completed. Aggregated results from both agents:
+    - user: 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.
+    - MicrosoftAgent: I have successfully executed the trade, purchasing 13 shares of Microsoft (MSFT). This action
+                      was based on the positive market sentiment and available funds within the specified limit.
+                      Your portfolio has been adjusted accordingly.
+    - GoogleAgent: I have successfully executed the trade, purchasing 35 shares of GOOGL. If you need further
+                   assistance or any adjustments, feel free to ask!
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,234 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import Annotated
+
+from agent_framework import (
+    AgentRunUpdateEvent,
+    FunctionApprovalRequestContent,
+    GroupChatBuilder,
+    GroupChatRequestSentEvent,
+    GroupChatState,
+    RequestInfoEvent,
+    ai_function,
+)
+from agent_framework.openai import OpenAIChatClient
+
+"""
+Sample: Group Chat Workflow with Tool Approval Requests
+
+This sample demonstrates how to use GroupChatBuilder with tools that require human
+approval before execution. A group of specialized agents collaborate on a task, and
+sensitive tool calls trigger human-in-the-loop approval.
+
+This sample works as follows:
+1. A GroupChatBuilder workflow is created with multiple specialized agents.
+2. A selector function determines which agent speaks next based on conversation state.
+3. Agents collaborate on a software deployment task.
+4. When the deployment agent tries to deploy to production, it triggers an approval request.
+5. The sample simulates human approval and the workflow completes.
+
+Purpose:
+Show how tool call approvals integrate with multi-agent group chat workflows where
+different agents have different levels of tool access.
+
+Demonstrate:
+- Using set_select_speakers_func with agents that have approval-required tools.
+- Handling RequestInfoEvent in group chat scenarios.
+- Multi-round group chat with tool approval interruption and resumption.
+
+Prerequisites:
+- OpenAI or Azure OpenAI configured with the required environment variables.
+- Basic familiarity with GroupChatBuilder and streaming workflow events.
+"""
+
+
+# 1. Define tools for different agents
+@ai_function
+def run_tests(test_suite: Annotated[str, "Name of the test suite to run"]) -> str:
+    """Run automated tests for the application."""
+    return f"Test suite '{test_suite}' completed: 47 passed, 0 failed, 0 skipped"
+
+
+@ai_function
+def check_staging_status() -> str:
+    """Check the current status of the staging environment."""
+    return "Staging environment: Healthy, Version 2.3.0 deployed, All services running"
+
+
+@ai_function(approval_mode="always_require")
+def deploy_to_production(
+    version: Annotated[str, "The version to deploy"],
+    components: Annotated[str, "Comma-separated list of components to deploy"],
+) -> str:
+    """Deploy specified components to production. Requires human approval."""
+    return f"Production deployment complete: Version {version}, Components: {components}"
+
+
+@ai_function
+def create_rollback_plan(version: Annotated[str, "The version being deployed"]) -> str:
+    """Create a rollback plan for the deployment."""
+    return (
+        f"Rollback plan created for version {version}: "
+        "Automated rollback to v2.2.0 if health checks fail within 5 minutes"
+    )
+
+
+# 2. Define the speaker selector function
+def select_next_speaker(state: GroupChatState) -> str:
+    """Select the next speaker based on the conversation flow.
+
+    This simple selector follows a predefined flow:
+    1. QA Engineer runs tests
+    2. DevOps Engineer checks staging and creates rollback plan
+    3. DevOps Engineer deploys to production (triggers approval)
+    """
+    if not state.conversation:
+        raise RuntimeError("Conversation is empty; cannot select next speaker.")
+
+    if len(state.conversation) == 1:
+        return "QAEngineer"  # First speaker
+
+    return "DevOpsEngineer"  # Subsequent speakers
+
+
+async def main() -> None:
+    # 3. Create specialized agents
+    chat_client = OpenAIChatClient()
+
+    qa_engineer = chat_client.as_agent(
+        name="QAEngineer",
+        instructions=(
+            "You are a QA engineer responsible for running tests before deployment. "
+            "Run the appropriate test suites and report results clearly."
+        ),
+        tools=[run_tests],
+    )
+
+    devops_engineer = chat_client.as_agent(
+        name="DevOpsEngineer",
+        instructions=(
+            "You are a DevOps engineer responsible for deployments. First check staging "
+            "status and create a rollback plan, then proceed with production deployment. "
+            "Always ensure safety measures are in place before deploying."
+        ),
+        tools=[check_staging_status, create_rollback_plan, deploy_to_production],
+    )
+
+    # 4. Build a group chat workflow with the selector function
+    workflow = (
+        GroupChatBuilder()
+        # Optionally, use `.set_manager(...)` to customize the group chat manager
+        .with_select_speaker_func(select_next_speaker)
+        .participants([qa_engineer, devops_engineer])
+        # Set a hard limit to 4 rounds
+        # First round: QAEngineer speaks
+        # Second round: DevOpsEngineer speaks (check staging + create rollback)
+        # Third round: DevOpsEngineer speaks with an approval request (deploy to production)
+        # Fourth round: DevOpsEngineer speaks again after approval
+        .with_max_rounds(4)
+        .build()
+    )
+
+    # 5. Start the workflow
+    print("Starting group chat workflow for software deployment...")
+    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, FunctionApprovalRequestContent):
+                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}")
+
+    # 6. Handle approval requests
+    if request_info_events:
+        for request_event in request_info_events:
+            if isinstance(request_event.data, FunctionApprovalRequestContent):
+                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.create_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.")
+
+    """
+    Sample Output:
+    Starting group chat workflow for software deployment...
+    Agents: QA Engineer, DevOps Engineer
+    ------------------------------------------------------------
+
+    [QAEngineer]: Running the integration test suite to verify the application
+    before deployment... Test suite 'integration' completed: 47 passed, 0 failed.
+    All tests passing - ready for deployment.
+
+    [DevOpsEngineer]: Checking staging environment status... Staging is healthy
+    with version 2.3.0. Creating rollback plan for version 2.4.0... Rollback plan
+    created with automated rollback to v2.2.0 if health checks fail.
+
+    [APPROVAL REQUIRED]
+      Tool: deploy_to_production
+      Arguments: {"version": "2.4.0", "components": "api,web,worker"}
+
+    ============================================================
+    Human review required for production deployment!
+    In a real scenario, you would review the deployment details here.
+    Simulating approval for demo purposes...
+    ============================================================
+
+    [DevOpsEngineer]: Production deployment complete! Version 2.4.0 has been
+    successfully deployed with components: api, web, worker.
+
+    ------------------------------------------------------------
+    Deployment workflow completed successfully!
+    All agents have finished their tasks.
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,144 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import Annotated
+
+from agent_framework import (
+    ChatMessage,
+    FunctionApprovalRequestContent,
+    RequestInfoEvent,
+    SequentialBuilder,
+    WorkflowOutputEvent,
+    ai_function,
+)
+from agent_framework.openai import OpenAIChatClient
+
+"""
+Sample: Sequential Workflow with Tool Approval Requests
+
+This sample demonstrates how to use SequentialBuilder with tools that require human
+approval before execution. The approval flow uses the existing @ai_function decorator
+with approval_mode="always_require" to trigger human-in-the-loop interactions.
+
+This sample works as follows:
+1. A SequentialBuilder workflow is created with a single agent that has tools requiring approval.
+2. The agent receives a user task and determines it needs to call a sensitive tool.
+3. The tool call triggers a FunctionApprovalRequestContent, pausing the workflow.
+4. The sample simulates human approval by responding to the RequestInfoEvent.
+5. Once approved, the tool executes and the agent completes its response.
+6. The workflow outputs the final conversation with all messages.
+
+Purpose:
+Show how tool call approvals integrate seamlessly with SequentialBuilder without
+requiring any additional builder configuration.
+
+Demonstrate:
+- Using @ai_function(approval_mode="always_require") for sensitive operations.
+- Handling RequestInfoEvent with FunctionApprovalRequestContent in sequential workflows.
+- Resuming workflow execution after approval via send_responses_streaming.
+
+Prerequisites:
+- OpenAI or Azure OpenAI configured with the required environment variables.
+- Basic familiarity with SequentialBuilder and streaming workflow events.
+"""
+
+
+# 1. Define tools - one requiring approval, one that doesn't
+@ai_function(approval_mode="always_require")
+def execute_database_query(
+    query: Annotated[str, "The SQL query to execute against the production database"],
+) -> str:
+    """Execute a SQL query against the production database. Requires human approval."""
+    # In a real implementation, this would execute the query
+    return f"Query executed successfully. Results: 3 rows affected by '{query}'"
+
+
+@ai_function
+def get_database_schema() -> str:
+    """Get the current database schema. Does not require approval."""
+    return """
+    Tables:
+    - users (id, name, email, created_at)
+    - orders (id, user_id, total, status, created_at)
+    - products (id, name, price, stock)
+    """
+
+
+async def main() -> None:
+    # 2. Create the agent with tools (approval mode is set per-tool via decorator)
+    chat_client = OpenAIChatClient()
+    database_agent = chat_client.as_agent(
+        name="DatabaseAgent",
+        instructions=(
+            "You are a database assistant. You can view the database schema and execute "
+            "queries. Always check the schema before running queries. Be careful with "
+            "queries that modify data."
+        ),
+        tools=[get_database_schema, execute_database_query],
+    )
+
+    # 3. Build a sequential workflow with the agent
+    workflow = SequentialBuilder().participants([database_agent]).build()
+
+    # 4. Start the workflow with a user task
+    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, FunctionApprovalRequestContent):
+                print(f"\nApproval requested for tool: {event.data.function_call.name}")
+                print(f"  Arguments: {event.data.function_call.arguments}")
+
+    # 5. Handle approval requests
+    if request_info_events:
+        for request_event in request_info_events:
+            if isinstance(request_event.data, FunctionApprovalRequestContent):
+                # 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.create_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.value 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).")
+
+    """
+    Sample Output:
+    Starting sequential workflow with tool approval...
+    ------------------------------------------------------------
+
+    Approval requested for tool: execute_database_query
+      Arguments: {"query": "UPDATE orders SET status = 'processing' WHERE status = 'pending'"}
+
+    Simulating human approval (auto-approving for demo)...
+
+    ------------------------------------------------------------
+    Workflow completed. Final conversation:
+      [user]: Check the schema and then update all orders with status 'pending' to 'processing'
+      [assistant]: I've checked the schema and executed the update query. The query
+                   "UPDATE orders SET status = 'processing' WHERE status = 'pending'"
+                   was executed successfully, affecting 3 rows.
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/workflows/visualization/concurrent_with_visualization.py

@@ -0,0 +1,157 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from dataclasses import dataclass
+
+from agent_framework import (
+    AgentExecutorRequest,
+    AgentExecutorResponse,
+    ChatAgent,
+    ChatMessage,
+    Executor,
+    Role,
+    WorkflowBuilder,
+    WorkflowContext,
+    WorkflowViz,
+    handler,
+)
+from agent_framework.azure import AzureOpenAIChatClient
+from azure.identity import AzureCliCredential
+from typing_extensions import Never
+
+"""
+Sample: Concurrent (Fan-out/Fan-in) with Agents + Visualization
+
+What it does:
+- Fan-out: dispatch the same prompt to multiple domain agents (research, marketing, legal).
+- Fan-in: aggregate their responses into one consolidated output.
+- Visualization: generate Mermaid and GraphViz representations via `WorkflowViz` and optionally export SVG.
+
+Prerequisites:
+- Azure AI/ Azure OpenAI for `AzureOpenAIChatClient` agents.
+- Authentication via `azure-identity` — uses `AzureCliCredential()` (run `az login`).
+- For visualization export: `pip install graphviz>=0.20.0` and install GraphViz binaries.
+"""
+
+
+class DispatchToExperts(Executor):
+    """Dispatches the incoming prompt to all expert agent executors (fan-out)."""
+
+    @handler
+    async def dispatch(self, prompt: str, ctx: WorkflowContext[AgentExecutorRequest]) -> None:
+        # Wrap the incoming prompt as a user message for each expert and request a response.
+        initial_message = ChatMessage(Role.USER, text=prompt)
+        await ctx.send_message(AgentExecutorRequest(messages=[initial_message], should_respond=True))
+
+
+@dataclass
+class AggregatedInsights:
+    """Structured output from the aggregator."""
+
+    research: str
+    marketing: str
+    legal: str
+
+
+class AggregateInsights(Executor):
+    """Aggregates expert agent responses into a single consolidated result (fan-in)."""
+
+    @handler
+    async def aggregate(self, results: list[AgentExecutorResponse], ctx: WorkflowContext[Never, str]) -> None:
+        # Map responses to text by executor id for a simple, predictable demo.
+        by_id: dict[str, str] = {}
+        for r in results:
+            # AgentExecutorResponse.agent_response.text contains concatenated assistant text
+            by_id[r.executor_id] = r.agent_response.text
+
+        research_text = by_id.get("researcher", "")
+        marketing_text = by_id.get("marketer", "")
+        legal_text = by_id.get("legal", "")
+
+        aggregated = AggregatedInsights(
+            research=research_text,
+            marketing=marketing_text,
+            legal=legal_text,
+        )
+
+        # Provide a readable, consolidated string as the final workflow result.
+        consolidated = (
+            "Consolidated Insights\n"
+            "====================\n\n"
+            f"Research Findings:\n{aggregated.research}\n\n"
+            f"Marketing Angle:\n{aggregated.marketing}\n\n"
+            f"Legal/Compliance Notes:\n{aggregated.legal}\n"
+        )
+
+        await ctx.yield_output(consolidated)
+
+
+def create_researcher_agent() -> ChatAgent:
+    """Creates a research domain expert agent."""
+    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+        instructions=(
+            "You're an expert market and product researcher. Given a prompt, provide concise, factual insights,"
+            " opportunities, and risks."
+        ),
+        name="researcher",
+    )
+
+
+def create_marketer_agent() -> ChatAgent:
+    """Creates a marketing domain expert agent."""
+    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+        instructions=(
+            "You're a creative marketing strategist. Craft compelling value propositions and target messaging"
+            " aligned to the prompt."
+        ),
+        name="marketer",
+    )
+
+
+def create_legal_agent() -> ChatAgent:
+    """Creates a legal domain expert agent."""
+    return AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
+        instructions=(
+            "You're a cautious legal/compliance reviewer. Highlight constraints, disclaimers, and policy concerns"
+            " based on the prompt."
+        ),
+        name="legal",
+    )
+
+
+async def main() -> None:
+    """Build and run the concurrent workflow with visualization."""
+
+    # Build a simple fan-out/fan-in workflow
+    workflow = (
+        WorkflowBuilder()
+        .register_agent(create_researcher_agent, name="researcher")
+        .register_agent(create_marketer_agent, name="marketer")
+        .register_agent(create_legal_agent, name="legal")
+        .register_executor(lambda: DispatchToExperts(id="dispatcher"), name="dispatcher")
+        .register_executor(lambda: AggregateInsights(id="aggregator"), name="aggregator")
+        .set_start_executor("dispatcher")
+        .add_fan_out_edges("dispatcher", ["researcher", "marketer", "legal"])
+        .add_fan_in_edges(["researcher", "marketer", "legal"], "aggregator")
+        .build()
+    )
+
+    # Generate workflow visualization
+    print("Generating workflow visualization...")
+    viz = WorkflowViz(workflow)
+    # Print out the mermaid string.
+    print("Mermaid string: \n=======")
+    print(viz.to_mermaid())
+    print("=======")
+    # Print out the DiGraph string with internal executors.
+    print("DiGraph string: \n=======")
+    print(viz.to_digraph(include_internal_executors=True))
+    print("=======")
+
+    # Export the DiGraph visualization as SVG.
+    svg_file = viz.export(format="svg")
+    print(f"SVG file saved to: {svg_file}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())