chore: import upstream snapshot with attribution

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

@@ -0,0 +1,249 @@
+# 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
+    Agent,
+    AgentExecutor,
+    AgentExecutorRequest,  # Input message bundle for an AgentExecutor
+    AgentExecutorResponse,
+    Message,
+    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.foundry import FoundryChatClient
+from agent_framework.openai import OpenAIChatOptions  # Thin client wrapper for Azure OpenAI chat models
+from azure.identity import AzureCliCredential  # Uses your az CLI login for credentials
+from dotenv import load_dotenv
+from pydantic import BaseModel  # Structured outputs for safer parsing
+from typing_extensions import Never
+
+# Load environment variables from .env file
+load_dotenv()
+
+"""
+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:
+- FOUNDRY_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint.
+- 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 FoundryChatClient. You should be logged in with Azure CLI (AzureCliCredential)
+and have the Foundry V2 Project 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 Message and forwards it as a new request.
+    detection = DetectionResult.model_validate_json(response.agent_response.text)
+    user_msg = Message("user", contents=[detection.email_content])
+    await ctx.send_message(AgentExecutorRequest(messages=[user_msg], should_respond=True))
+
+
+def create_spam_detector_agent() -> Agent:
+    """Helper to create a spam detection agent."""
+    # AzureCliCredential uses your current az login. This avoids embedding secrets in code.
+    return Agent(
+        client=FoundryChatClient(
+            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+            model=os.environ["FOUNDRY_MODEL"],
+            credential=AzureCliCredential(),
+        ),
+        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=OpenAIChatOptions[Any](response_format=DetectionResult),
+    )
+
+
+def create_email_assistant_agent() -> Agent:
+    """Helper to create an email assistant agent."""
+    # AzureCliCredential uses your current az login. This avoids embedding secrets in code.
+    return Agent(
+        client=FoundryChatClient(
+            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+            model=os.environ["FOUNDRY_MODEL"],
+            credential=AzureCliCredential(),
+        ),
+        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=OpenAIChatOptions[Any](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.
+    spam_detection_agent = AgentExecutor(create_spam_detector_agent())
+    email_assistant_agent = AgentExecutor(create_email_assistant_agent())
+
+    workflow = (
+        WorkflowBuilder(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, handle_email_response)
+        # Spam path: send to spam handler
+        .add_edge(spam_detection_agent, handle_spam_classifier_response, 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")  # noqa: ASYNC240
+
+    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=[Message("user", contents=[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/03-workflows/control-flow/intermediate_vs_terminal_outputs.py

@@ -0,0 +1,158 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import (
+    Message,
+    WorkflowBuilder,
+    WorkflowContext,
+    WorkflowExecutor,
+    executor,
+)
+from typing_extensions import Never
+
+"""
+Sample: Workflow Output vs Intermediate Output labeling
+
+What this sample shows
+- How ``WorkflowBuilder(output_from=[...])`` designates which executors emit
+  Workflow Output.
+- How ``WorkflowBuilder(intermediate_output_from=[...])`` designates which executor
+  yields surface as Intermediate Output (``type='intermediate'`` events).
+- How unlisted executor yields are hidden from caller-facing output/intermediate
+  events in explicit designation mode.
+- How the same workflow wrapped via ``workflow.as_agent()`` translates intermediate
+  events to ``text_reasoning`` content so existing ``.text`` accessors keep
+  returning Workflow Output only.
+- How a sub-workflow embedded via ``WorkflowExecutor`` bubbles its intermediate
+  emissions up through the parent's event stream, attributed to the
+  ``WorkflowExecutor`` id rather than the child's internal executor ids.
+
+The output selection contract:
+- Compatibility mode: when neither ``output_from`` nor ``intermediate_output_from``
+  is provided, every ``yield_output`` produces Workflow Output and a deprecation
+  warning points to explicit selection.
+- Explicit selection mode: provide either ``output_from`` or
+  ``intermediate_output_from``. Executors selected by ``output_from`` emit Workflow Output
+  (``type='output'`` events); executors selected by ``intermediate_output_from`` emit
+  Intermediate Output (``type='intermediate'`` events); unselected executor yields are
+  hidden from the stream and ``WorkflowRunResult`` output accessors.
+- Validation: explicit selections must not both be empty; duplicate executor entries,
+  overlap between Workflow Output and Intermediate Output, unknown executors, invalid
+  literals, and selected executors without workflow output types are rejected.
+
+Prerequisites
+- No external services required.
+"""
+
+
+@executor(id="planner")
+async def planner(messages: list[Message], ctx: WorkflowContext[list[Message], str]) -> None:
+    """Intermediate step: emits a visible progress note, then forwards."""
+    prompt = messages[0].text if messages else ""
+    await ctx.yield_output(f"plan: starting work on '{prompt}'")
+    await ctx.send_message(messages)
+
+
+@executor(id="researcher")
+async def researcher(messages: list[Message], ctx: WorkflowContext[list[Message], str]) -> None:
+    """Intermediate step: emits visible progress, then forwards."""
+    prompt = messages[0].text if messages else ""
+    await ctx.yield_output(f"research: gathering data for '{prompt}'")
+    await ctx.send_message(messages)
+
+
+@executor(id="answerer")
+async def answerer(messages: list[Message], ctx: WorkflowContext[Never, str]) -> None:
+    """Designated Workflow Output: emits the workflow's answer."""
+    prompt = messages[0].text if messages else ""
+    await ctx.yield_output(f"final answer to '{prompt}': 42")
+
+
+async def main() -> None:
+    # Build with explicit Workflow Output and Intermediate Output selections.
+    # `answerer` produces type='output' events; planner and researcher produce
+    # visible type='intermediate' events.
+    workflow = (
+        WorkflowBuilder(
+            start_executor=planner,
+            output_from=[answerer],
+            intermediate_output_from=[planner, researcher],
+        )
+        .add_edge(planner, researcher)
+        .add_edge(researcher, answerer)
+        .build()
+    )
+
+    initial = [Message(role="user", contents=["life, the universe, and everything"])]
+
+    print("=== Streaming events (workflow.run(stream=True)) ===")
+    async for event in workflow.run(initial, stream=True):
+        if event.type == "intermediate":
+            print(f"  [intermediate] {event.executor_id}: {event.data}")
+        elif event.type == "output":
+            print(f"  [output]       {event.executor_id}: {event.data}")
+
+    # WorkflowRunResult.get_outputs() filters to type='output' events, so it
+    # only returns the selected Workflow Output yield.
+    print("\n=== Non-streaming run().get_outputs() ===")
+    result = await workflow.run(initial)
+    print(f"  outputs: {result.get_outputs()}")
+
+    # When the same workflow is wrapped via as_agent(), intermediate events
+    # surface as ``text_reasoning`` content; Workflow Output surfaces as
+    # ``text`` content. Existing callers reading ``response.text`` get only
+    # the selected Workflow Output because ``.text`` filters to text content.
+    print("\n=== workflow.as_agent() -- intermediate -> text_reasoning content ===")
+    agent = workflow.as_agent("planner-agent")
+    response = await agent.run("life, the universe, and everything")
+    print(f"  response.text (Workflow Output only): {response.text!r}")
+    reasoning = " | ".join(
+        c.text for m in response.messages for c in m.contents if c.type == "text_reasoning" and c.text is not None
+    )
+    print(f"  reasoning content (intermediates): {reasoning!r}")
+
+    # Embed the same workflow as a node inside a larger workflow via WorkflowExecutor.
+    # Child intermediate emissions are forwarded to the parent's event stream with the
+    # WorkflowExecutor's id as the source, so outer callers don't have to know the
+    # child's internal executor layout. The 'intermediate' label is preserved across
+    # the boundary regardless of how the parent designates the WorkflowExecutor.
+    print("\n=== Embedding as a sub-workflow -- intermediates bubble up ===")
+    sub = WorkflowExecutor(workflow, id="sub")
+
+    @executor(id="parent_sink")
+    async def parent_sink(message: str, ctx: WorkflowContext[Never, str]) -> None:
+        await ctx.yield_output(message)
+
+    parent_workflow = WorkflowBuilder(start_executor=sub, output_from=[parent_sink]).add_edge(sub, parent_sink).build()
+
+    async for event in parent_workflow.run(initial, stream=True):
+        if event.type == "intermediate":
+            print(f"  [intermediate] {event.executor_id}: {event.data}")
+        elif event.type == "output":
+            print(f"  [output]       {event.executor_id}: {event.data}")
+
+    """
+    Sample output:
+
+    === Streaming events (workflow.run(stream=True)) ===
+      [intermediate] planner: plan: starting work on 'life, the universe, and everything'
+      [intermediate] researcher: research: gathering data for 'life, the universe, and everything'
+      [output]       answerer: final answer to 'life, the universe, and everything': 42
+
+    === Non-streaming run().get_outputs() ===
+      outputs: ["final answer to 'life, the universe, and everything': 42"]
+
+    === workflow.as_agent() -- intermediate -> text_reasoning content ===
+      response.text (Workflow Output only): "final answer to 'life, the universe, and everything': 42"
+      reasoning content (intermediates): "plan: starting work on ... | research: gathering data for ..."
+
+    === Embedding as a sub-workflow -- intermediates bubble up ===
+      [intermediate] sub: plan: starting work on 'life, the universe, and everything'
+      [intermediate] sub: research: gathering data for 'life, the universe, and everything'
+      [output]       parent_sink: final answer to 'life, the universe, and everything': 42
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,318 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Step 06b — Multi-Selection Edge Group sample."""
+
+import asyncio
+import os
+from dataclasses import dataclass
+from typing import Any, Literal
+from uuid import uuid4
+
+from agent_framework import (
+    Agent,
+    AgentExecutor,
+    AgentExecutorRequest,
+    AgentExecutorResponse,
+    AgentResponseUpdate,
+    Message,
+    WorkflowBuilder,
+    WorkflowContext,
+    WorkflowEvent,
+    executor,
+)
+from agent_framework.foundry import FoundryChatClient
+from agent_framework.openai import OpenAIChatOptions
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+from pydantic import BaseModel
+from typing_extensions import Never
+
+# Load environment variables from .env file
+load_dotenv()
+
+"""
+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 workflow 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:
+- FOUNDRY_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint.
+- Familiarity with WorkflowBuilder, executors, edges, and events.
+- Understanding of multi-selection edge groups and how their selection function maps to target ids.
+- Experience with workflow state 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)
+    ctx.set_state(f"{EMAIL_STATE_PREFIX}{new_email.email_id}", new_email)
+    ctx.set_state(CURRENT_EMAIL_ID_KEY, new_email.email_id)
+
+    await ctx.send_message(
+        AgentExecutorRequest(messages=[Message("user", contents=[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 = ctx.get_state(CURRENT_EMAIL_ID_KEY)
+    email: Email = ctx.get_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 = ctx.get_state(f"{EMAIL_STATE_PREFIX}{analysis.email_id}")
+    await ctx.send_message(
+        AgentExecutorRequest(messages=[Message("user", contents=[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 = ctx.get_state(f"{EMAIL_STATE_PREFIX}{analysis.email_id}")
+    await ctx.send_message(
+        AgentExecutorRequest(messages=[Message("user", contents=[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 = ctx.get_state(CURRENT_EMAIL_ID_KEY)
+    email: Email = ctx.get_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 = ctx.get_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(type="database_event", data=f"Email {analysis.email_id} saved to database."))  # type: ignore
+
+
+def create_email_analysis_agent() -> Agent:
+    """Creates the email analysis agent."""
+    return Agent(
+        client=FoundryChatClient(
+            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+            model=os.environ["FOUNDRY_MODEL"],
+            credential=AzureCliCredential(),
+        ),
+        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=OpenAIChatOptions[Any](response_format=AnalysisResultAgent),
+    )
+
+
+def create_email_assistant_agent() -> Agent:
+    """Creates the email assistant agent."""
+    return Agent(
+        client=FoundryChatClient(
+            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+            model=os.environ["FOUNDRY_MODEL"],
+            credential=AzureCliCredential(),
+        ),
+        instructions=("You are an email assistant that helps users draft responses to emails with professionalism."),
+        name="email_assistant_agent",
+        default_options=OpenAIChatOptions[Any](response_format=EmailResponse),
+    )
+
+
+def create_email_summary_agent() -> Agent:
+    """Creates the email summary agent."""
+    return Agent(
+        client=FoundryChatClient(
+            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+            model=os.environ["FOUNDRY_MODEL"],
+            credential=AzureCliCredential(),
+        ),
+        instructions=("You are an assistant that helps users summarize emails."),
+        name="email_summary_agent",
+        default_options=OpenAIChatOptions[Any](response_format=EmailSummaryModel),
+    )
+
+
+async def main() -> None:
+    # Build the workflow
+    email_analysis_agent = AgentExecutor(create_email_analysis_agent())
+    email_assistant_agent = AgentExecutor(create_email_assistant_agent())
+    email_summary_agent = AgentExecutor(create_email_summary_agent())
+
+    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 = (
+        WorkflowBuilder(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(email, stream=True):
+        if isinstance(event, DatabaseEvent):
+            print(f"{event}")
+        elif event.type == "output":
+            if isinstance(event.data, AgentResponseUpdate):
+                # Agent executors stream token-level updates. Skip these to keep sample
+                # output focused on final workflow results.
+                continue
+            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/03-workflows/control-flow/sequential_executors.py

@@ -0,0 +1,85 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from typing import cast
+
+from agent_framework import (
+    Executor,
+    WorkflowBuilder,
+    WorkflowContext,
+    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 streaming run 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.
+    upper_case_executor = UpperCaseExecutor(id="upper_case_executor")
+    reverse_text_executor = ReverseTextExecutor(id="reverse_text_executor")
+
+    workflow = (
+        WorkflowBuilder(start_executor=upper_case_executor).add_edge(upper_case_executor, reverse_text_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("hello world", stream=True):
+        print(f"Event: {event}")
+        if event.type == "output":
+            outputs.append(cast(str, event.data))
+
+    if outputs:
+        print(f"Workflow outputs: {outputs}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,80 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import WorkflowBuilder, WorkflowContext, 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 a streaming run.
+
+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 executor_invoked events (type='executor_invoked') and
+executor_completed events (type='executor_completed') 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(start_executor=to_upper_case).add_edge(to_upper_case, reverse_text).build()
+
+    # Step 2: Run the workflow and stream events in real time.
+    async for event in workflow.run("hello world", stream=True):
+        # You will see executor invoke and completion events as the workflow progresses.
+        print(f"Event: {event}")
+        if event.type == "output":
+            print(f"Workflow completed with result: {event.data}")
+
+    """
+    Sample Output:
+
+    Event: executor_invoked event (type='executor_invoked', executor_id=upper_case_executor)
+    Event: executor_completed event (type='executor_completed', executor_id=upper_case_executor)
+    Event: executor_invoked event (type='executor_invoked', executor_id=reverse_text_executor)
+    Event: executor_completed event (type='executor_completed', executor_id=reverse_text_executor)
+    Event: output event (type='output', data='DLROW OLLEH', executor_id=reverse_text_executor)
+    Workflow completed with result: DLROW OLLEH
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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

@@ -0,0 +1,173 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+from enum import Enum
+
+from agent_framework import (
+    Agent,
+    AgentExecutor,
+    AgentExecutorRequest,
+    AgentExecutorResponse,
+    AgentResponseUpdate,
+    Executor,
+    Message,
+    WorkflowBuilder,
+    WorkflowContext,
+    handler,
+)
+from agent_framework.foundry import FoundryChatClient
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+"""
+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:
+- FOUNDRY_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint.
+- FOUNDRY_MODEL must be set to your Azure OpenAI model deployment name.
+- 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=[Message("user", contents=[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() -> Agent:
+    """Create a judge agent that evaluates guesses."""
+    return Agent(
+        client=FoundryChatClient(
+            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+            model=os.environ["FOUNDRY_MODEL"],
+            credential=AzureCliCredential(),
+        ),
+        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.
+    guess_number = GuessNumberExecutor((1, 100), "guess_number")
+    judge_agent = AgentExecutor(create_judge_agent())
+    submit_judge = SubmitToJudgeAgent(judge_agent_id="judge_agent", target=30)
+    parse_judge = ParseJudgeResponse(id="parse_judge")
+
+    workflow = (
+        WorkflowBuilder(start_executor=guess_number)
+        .add_edge(guess_number, submit_judge)
+        .add_edge(submit_judge, judge_agent)
+        .add_edge(judge_agent, parse_judge)
+        .add_edge(parse_judge, guess_number)
+        .build()
+    )
+
+    # Step 2: Run the workflow with concise streaming output.
+    iterations = 0
+    async for event in workflow.run(NumberSignal.INIT, stream=True):
+        if event.type == "executor_completed" and event.executor_id == "guess_number":
+            iterations += 1
+        elif event.type == "output":
+            if isinstance(event.data, AgentResponseUpdate):
+                # Agent executor streams token-level updates; skip to avoid noisy logs.
+                continue
+            print(f"Workflow output: {event.data}")
+
+    # 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/03-workflows/control-flow/switch_case_edge_group.py

@@ -0,0 +1,241 @@
+# 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
+    Agent,
+    AgentExecutor,
+    AgentExecutorRequest,  # Message bundle sent to an AgentExecutor
+    AgentExecutorResponse,  # Result returned by an AgentExecutor
+    Case,
+    Default,  # Default branch when no cases match
+    Message,
+    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.foundry import FoundryChatClient
+from agent_framework.openai import OpenAIChatOptions  # Thin client for Azure OpenAI chat models
+from azure.identity import AzureCliCredential  # Uses your az CLI login for credentials
+from dotenv import load_dotenv
+from pydantic import BaseModel  # Structured outputs with validation
+from typing_extensions import Never
+
+# Load environment variables from .env file
+load_dotenv()
+
+"""
+Sample: Switch-Case Edge Group with an explicit Uncertain branch.
+
+The workflow stores a single email in workflow 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 workflow 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:
+- FOUNDRY_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint.
+- 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 FoundryChatClient, 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 workflow 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)
+    ctx.set_state(f"{EMAIL_STATE_PREFIX}{new_email.email_id}", new_email)
+    ctx.set_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=[Message("user", contents=[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 = ctx.get_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 workflow state using the id carried in DetectionResult.
+    email: Email = ctx.get_state(f"{EMAIL_STATE_PREFIX}{detection.email_id}")
+    await ctx.send_message(
+        AgentExecutorRequest(messages=[Message("user", contents=[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 = ctx.get_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() -> Agent:
+    """Create and return the spam detection agent."""
+    return Agent(
+        client=FoundryChatClient(
+            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+            model=os.environ["FOUNDRY_MODEL"],
+            credential=AzureCliCredential(),
+        ),
+        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=OpenAIChatOptions[Any](response_format=DetectionResultAgent),
+    )
+
+
+def create_email_assistant_agent() -> Agent:
+    """Create and return the email assistant agent."""
+    return Agent(
+        client=FoundryChatClient(
+            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+            model=os.environ["FOUNDRY_MODEL"],
+            credential=AzureCliCredential(),
+        ),
+        instructions=("You are an email assistant that helps users draft responses to emails with professionalism."),
+        name="email_assistant_agent",
+        default_options=OpenAIChatOptions[Any](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.
+    spam_detection_agent = AgentExecutor(create_spam_detection_agent())
+    email_assistant_agent = AgentExecutor(create_email_assistant_agent())
+
+    workflow = (
+        WorkflowBuilder(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/03-workflows/control-flow/workflow_cancellation.py

@@ -0,0 +1,94 @@
+# 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() stream=True and stream=False. 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(start_executor=step1).add_edge(step1, step2).add_edge(step2, step3).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.ensure_future(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())