Python: (samples): adopt AzureOpenAIResponsesClient, reorganize orchestration examples, and fix workflow/orchestration bugs (#3873)

* adopt AzureOpenAIResponsesClient, reorganize orchestration examples, and fix workflow/orchestration bugs

* Updates

* add comment

python/samples/getting_started/orchestrations/handoff/handoff_autonomous.py

@@ -0,0 +1,157 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import logging
+import os
+from typing import cast
+
+from agent_framework import (
+    Agent,
+    AgentResponseUpdate,
+    Message,
+    resolve_agent_id,
+)
+from agent_framework.azure import AzureOpenAIResponsesClient
+from agent_framework.orchestrations import HandoffBuilder
+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:
+    - AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint.
+    - `az login` (Azure CLI authentication)
+    - Environment variables for AzureOpenAIResponsesClient (AZURE_AI_MODEL_DEPLOYMENT_NAME)
+
+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(
+    client: AzureOpenAIResponsesClient,
+) -> tuple[Agent, Agent, Agent]:
+    """Create coordinator and specialists for autonomous iteration."""
+    coordinator = 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 = 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",
+    )
+
+    summary_agent = 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
+
+
+async def main() -> None:
+    """Run an autonomous handoff workflow with specialist iteration enabled."""
+    client = AzureOpenAIResponsesClient(
+        project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+        deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+        credential=AzureCliCredential(),
+    )
+    coordinator, research_agent, summary_agent = create_agents(client)
+
+    # Build the workflow with autonomous mode
+    # In autonomous mode, agents continue iterating until they invoke a handoff tool
+    # termination_condition: Terminate after coordinator provides 5 assistant responses
+    workflow = (
+        HandoffBuilder(
+            name="autonomous_iteration_handoff",
+            participants=[coordinator, research_agent, summary_agent],
+            termination_condition=lambda conv: (
+                sum(1 for msg in conv if msg.author_name == "coordinator" and msg.role == "assistant") >= 5
+            ),
+        )
+        .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,
+            }
+        )
+        .build()
+    )
+
+    request = "Perform a comprehensive research on Microsoft Agent Framework."
+    print("Request:", request)
+
+    last_response_id: str | None = None
+    async for event in workflow.run(request, stream=True):
+        if event.type == "handoff_sent":
+            print(f"\nHandoff Event: from {event.data.source} to {event.data.target}\n")
+        elif event.type == "output":
+            data = event.data
+            if isinstance(data, AgentResponseUpdate):
+                if not data.text:
+                    # Skip updates that don't have text content
+                    # These can be tool calls or other non-text events
+                    continue
+                rid = data.response_id
+                if rid != last_response_id:
+                    if last_response_id is not None:
+                        print("\n")
+                    print(f"{data.author_name}:", end=" ", flush=True)
+                    last_response_id = rid
+                print(data.text, end="", flush=True)
+            elif event.type == "output":
+                # The output of the handoff workflow is a collection of chat messages from all participants
+                outputs = cast(list[Message], event.data)
+                print("\n" + "=" * 80)
+                print("\nFinal Conversation Transcript:\n")
+                for message in outputs:
+                    print(f"{message.author_name or message.role}: {message.text}\n")
+
+    """
+    Expected behavior:
+        - 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/orchestrations/handoff/handoff_simple.py

@@ -0,0 +1,302 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+from typing import Annotated, cast
+
+from agent_framework import (
+    Agent,
+    AgentResponse,
+    Message,
+    WorkflowEvent,
+    WorkflowRunState,
+    tool,
+)
+from agent_framework.azure import AzureOpenAIResponsesClient
+from agent_framework.orchestrations import HandoffAgentUserRequest, HandoffBuilder
+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:
+    - AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint.
+    - `az login` (Azure CLI authentication)
+    - Environment variables configured for AzureOpenAIResponsesClient (AZURE_AI_MODEL_DEPLOYMENT_NAME)
+
+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
+"""
+
+
+# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
+# See:
+# samples/getting_started/tools/function_tool_with_approval.py
+# samples/getting_started/tools/function_tool_with_approval_and_threads.py.
+@tool(approval_mode="never_require")
+def process_refund(order_number: Annotated[str, "Order number to process refund for"]) -> str:
+    """Simulated function to process a refund for a given order number."""
+    return f"Refund processed successfully for order {order_number}."
+
+
+@tool(approval_mode="never_require")
+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."
+
+
+@tool(approval_mode="never_require")
+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(client: AzureOpenAIResponsesClient) -> tuple[Agent, Agent, Agent, Agent]:
+    """Create and configure the triage and specialist agents.
+
+    Args:
+        client: The AzureOpenAIResponsesClient 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 = 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 = 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 = 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 = 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[WorkflowEvent[HandoffAgentUserRequest]]:
+    """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 request_info events for response handling
+
+    Args:
+        events: List of WorkflowEvent to process
+
+    Returns:
+        List of WorkflowEvent[HandoffAgentUserRequest] representing pending user input requests
+    """
+    requests: list[WorkflowEvent[HandoffAgentUserRequest]] = []
+
+    for event in events:
+        if event.type == "handoff_sent":
+            # handoff_sent event: Indicates a handoff has been initiated
+            print(f"\n[Handoff from {event.data.source} to {event.data.target} initiated.]")
+        elif event.type == "status" and event.state in {
+            WorkflowRunState.IDLE,
+            WorkflowRunState.IDLE_WITH_PENDING_REQUESTS,
+        }:
+            # Status event: Indicates workflow state changes
+            print(f"\n[Workflow Status] {event.state}")
+        elif event.type == "output":
+            # Output event: Contains contents generated by the workflow
+            data = event.data
+            if isinstance(data, AgentResponse):
+                for message in data.messages:
+                    if not message.text:
+                        # Skip messages without text (e.g., tool calls)
+                        continue
+                    speaker = message.author_name or message.role
+                    print(f"- {speaker}: {message.text}")
+            elif event.type == "output":
+                # The output of the handoff workflow is a collection of chat messages from all participants
+                conversation = cast(list[Message], event.data)
+                if isinstance(conversation, list):
+                    print("\n=== Final Conversation Snapshot ===")
+                    for message in conversation:
+                        speaker = message.author_name or message.role
+                        print(f"- {speaker}: {message.text or [content.type for content in message.contents]}")
+                    print("===================================")
+        elif event.type == "request_info" and isinstance(event.data, HandoffAgentUserRequest):
+            _print_handoff_agent_user_request(event.data.agent_response)
+            requests.append(cast(WorkflowEvent[HandoffAgentUserRequest], 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
+        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
+    client = AzureOpenAIResponsesClient(
+        project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+        deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+        credential=AzureCliCredential(),
+    )
+
+    # Create all agents: triage + specialists
+    triage, refund, order, support = create_agents(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
+    # - 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],
+            # 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.
+            termination_condition=lambda conversation: (
+                len(conversation) > 0 and "welcome" in conversation[-1].text.lower()
+            ),
+        )
+        .with_start_agent(triage)
+        .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=True) 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 = workflow.run(initial_message, stream=True)
+    pending_requests = _handle_events([event async for event in 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 run(responses=...) to get events from the workflow, allowing us to
+        # display agent responses and handle new requests as they arrive
+        events = await workflow.run(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/orchestrations/handoff/handoff_with_code_interpreter_file.py

@@ -0,0 +1,186 @@
+# 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 workflow events.
+
+Verifies GitHub issue #2718: files generated by code interpreter in
+HandoffBuilder workflows can be properly retrieved.
+
+Prerequisites:
+    - AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint.
+    - `az login` (Azure CLI authentication)
+    - AZURE_AI_MODEL_DEPLOYMENT_NAME
+"""
+
+import asyncio
+import os
+from collections.abc import AsyncIterable
+from typing import cast
+
+from agent_framework import (
+    AgentResponseUpdate,
+    Message,
+    WorkflowEvent,
+    WorkflowRunState,
+)
+from agent_framework.azure import AzureOpenAIResponsesClient
+from agent_framework.orchestrations import HandoffAgentUserRequest, HandoffBuilder
+from azure.identity import AzureCliCredential
+
+
+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[WorkflowEvent[HandoffAgentUserRequest]], list[str]]:
+    """Process workflow events and extract file IDs and pending requests.
+
+    Returns:
+        Tuple of (pending_requests, file_ids_found)
+    """
+
+    requests: list[WorkflowEvent[HandoffAgentUserRequest]] = []
+    file_ids: list[str] = []
+
+    for event in events:
+        if event.type == "handoff_sent":
+            print(f"\n[Handoff from {event.data.source} to {event.data.target} initiated.]")
+        elif event.type == "status" and event.state in {
+            WorkflowRunState.IDLE,
+            WorkflowRunState.IDLE_WITH_PENDING_REQUESTS,
+        }:
+            print(f"[status] {event.state}")
+        elif event.type == "request_info" and isinstance(event.data, HandoffAgentUserRequest):
+            requests.append(cast(WorkflowEvent[HandoffAgentUserRequest], event))
+        elif event.type == "output":
+            data = event.data
+            if isinstance(data, AgentResponseUpdate):
+                for content in data.contents:
+                    if content.type == "hosted_file":
+                        file_ids.append(content.file_id)  # type: ignore
+                        print(f"[Found HostedFileContent: file_id={content.file_id}]")
+                    elif content.type == "text" and content.annotations:
+                        for annotation in content.annotations:
+                            file_id = annotation["file_id"]  # type: ignore
+                            file_ids.append(file_id)
+                            print(f"[Found file annotation: file_id={file_id}]")
+            elif isinstance(data, list):
+                conversation = cast(list[Message], data)
+                if isinstance(conversation, list):
+                    print("\n=== Final Conversation Snapshot ===")
+                    for message in conversation:
+                        speaker = message.author_name or message.role
+                        print(f"- {speaker}: {message.text or [content.type for content in message.contents]}")
+                    print("===================================")
+
+    return requests, file_ids
+
+
+async def main() -> None:
+    """Run a simple handoff workflow with code interpreter file generation."""
+    print("=== Handoff Workflow with Code Interpreter File Generation ===\n")
+
+    client = AzureOpenAIResponsesClient(
+        project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+        deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+        credential=AzureCliCredential(),
+    )
+
+    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_interpreter_tool = client.get_code_interpreter_tool()
+
+    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=[code_interpreter_tool],
+    )
+
+    workflow = (
+        HandoffBuilder(
+            termination_condition=lambda conv: sum(1 for msg in conv if msg.role == "user") >= 2,
+        )
+        .participants([triage, code_specialist])
+        .with_start_agent(triage)
+        .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(user_inputs[0], stream=True))
+    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.run(stream=True, responses=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/orchestrations/handoff/handoff_with_tool_approval_checkpoint_resume.py

@@ -0,0 +1,236 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from agent_framework import (
+    Agent,
+    Content,
+    FileCheckpointStorage,
+    Workflow,
+    tool,
+)
+from agent_framework.azure import AzureOpenAIResponsesClient
+from agent_framework.orchestrations import HandoffAgentUserRequest, HandoffBuilder
+from azure.identity import AzureCliCredential
+
+"""
+Sample: Handoff Workflow with Tool Approvals + Checkpoint Resume
+
+Demonstrates resuming a handoff workflow from a checkpoint while handling both
+HandoffAgentUserRequest prompts and function approval request Content 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: Restore checkpoint, inspect pending requests, then provide responses.
+6. Workflow continues from the saved state.
+
+Pattern:
+- workflow.run(checkpoint_id=..., stream=True) to restore checkpoint and discover pending requests.
+- workflow.run(stream=True, responses=responses) to supply human replies and approvals.
+  (Two steps are needed here because the sample must inspect request types before building responses.
+  When response payloads are already known, use the single-call form:
+  workflow.run(stream=True, checkpoint_id=..., responses=responses).)
+
+Prerequisites:
+- AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint.
+- Azure CLI authentication (az login).
+- Environment variables configured for AzureOpenAIResponsesClient.
+"""
+
+CHECKPOINT_DIR = Path(__file__).parent / "tmp" / "handoff_checkpoints"
+CHECKPOINT_DIR.mkdir(parents=True, exist_ok=True)
+
+
+@tool(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: AzureOpenAIResponsesClient) -> tuple[Agent, Agent, Agent]:
+    """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) -> Workflow:
+    """Build the handoff workflow with checkpointing enabled."""
+
+    client = AzureOpenAIResponsesClient(
+        project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+        deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+        credential=AzureCliCredential(),
+    )
+    triage, refund, order = create_agents(client)
+
+    # checkpoint_storage: Enable checkpointing for resume
+    # termination_condition: Terminate after 5 user messages for this demo
+    return (
+        HandoffBuilder(
+            name="checkpoint_handoff_demo",
+            participants=[triage, refund, order],
+            checkpoint_storage=checkpoint_storage,
+            termination_condition=lambda conv: sum(1 for msg in conv if msg.role == "user") >= 5,
+        )
+        .with_start_agent(triage)
+        .build()
+    )
+
+
+def print_handoff_agent_user_request(request: HandoffAgentUserRequest, request_id: str) -> None:
+    """Log pending handoff request details for debugging."""
+    print(f"\n{'=' * 60}")
+    print("User input needed")
+    print(f"Request ID: {request_id}")
+    print(f"Awaiting agent: {request.agent_response.agent_id}")
+
+    response = request.agent_response
+    if not response.messages:
+        print("(No agent messages)")
+        return
+
+    for message in response.messages:
+        if not message.text:
+            continue
+        speaker = message.author_name or message.role
+        print(f"{speaker}: {message.text}")
+
+    print(f"{'=' * 60}\n")
+
+
+def print_function_approval_request(request: Content, request_id: str) -> None:
+    """Log pending tool approval details for debugging."""
+    args = request.function_call.parse_arguments() or {}  # type: ignore
+    print(f"\n{'=' * 60}")
+    print("Tool approval required")
+    print(f"Request ID: {request_id}")
+    print(f"Function: {request.function_call.name}")  # type: ignore
+    print(f"Arguments:\n{json.dumps(args, indent=2)}")
+    print(f"{'=' * 60}\n")
+
+
+async def main() -> None:
+    """
+    Demonstrate the checkpoint-based pause/resume pattern for handoff workflows.
+
+    This sample shows:
+    1. Starting a workflow and getting a HandoffAgentUserRequest
+    2. Pausing (checkpoint is saved automatically)
+    3. Resuming from checkpoint with a user response or tool approval
+    4. Continuing the conversation until completion
+    """
+    # 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)
+
+    # 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.",
+    ]
+
+    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
+    results = await workflow.run(message=initial_request)
+    request_events = results.get_request_info_events()
+    if not request_events:
+        print("Workflow completed without needing user input")
+        return
+
+    print("=" * 60)
+    print("WORKFLOW PAUSED with pending requests")
+    print("=" * 60)
+
+    # Phase 2: Running until no more user input is needed
+    # This creates a new workflow instance to simulate a fresh process start,
+    # but points it to the same checkpoint storage
+    while request_events:
+        print("=" * 60)
+        print("Simulating process restart...")
+        print("=" * 60)
+
+        workflow = create_workflow(checkpoint_storage=storage)
+
+        responses: dict[str, Any] = {}
+        for request_event in request_events:
+            print(f"Pending request ID: {request_event.request_id}, Type: {type(request_event.data)}")
+            if isinstance(request_event.data, HandoffAgentUserRequest):
+                print_handoff_agent_user_request(request_event.data, request_event.request_id)
+                response = handoff_responses.pop(0)
+                print(f"Responding with: {response}")
+                responses[request_event.request_id] = HandoffAgentUserRequest.create_response(response)
+            elif isinstance(request_event.data, Content) and request_event.data.type == "function_approval_request":
+                print_function_approval_request(request_event.data, request_event.request_id)
+                print("Approving tool call...")
+                responses[request_event.request_id] = request_event.data.to_function_approval_response(approved=True)
+            else:
+                # This sample only expects HandoffAgentUserRequest and function approval requests
+                raise ValueError(f"Unsupported request type: {type(request_event.data)}")
+
+        checkpoint = await storage.get_latest(workflow_name=workflow.name)
+        if not checkpoint:
+            raise RuntimeError("No checkpoints found.")
+        checkpoint_id = checkpoint.checkpoint_id
+
+        results = await workflow.run(responses=responses, checkpoint_id=checkpoint_id)
+        request_events = results.get_request_info_events()
+
+    print("\n" + "=" * 60)
+    print("DEMO COMPLETE")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/orchestrations/handoff/handoff_workflow_as_agent.py

@@ -0,0 +1,227 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import os
+from typing import Annotated
+
+from agent_framework import (
+    Agent,
+    AgentResponse,
+    Content,
+    Message,
+    WorkflowAgent,
+    tool,
+)
+from agent_framework.azure import AzureOpenAIResponsesClient
+from agent_framework.orchestrations import HandoffAgentUserRequest, HandoffBuilder
+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:
+    - AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint.
+    - `az login` (Azure CLI authentication)
+    - Environment variables configured for AzureOpenAIResponsesClient (AZURE_AI_MODEL_DEPLOYMENT_NAME)
+
+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
+"""
+
+
+# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
+# See:
+# samples/getting_started/tools/function_tool_with_approval.py
+# samples/getting_started/tools/function_tool_with_approval_and_threads.py.
+@tool(approval_mode="never_require")
+def process_refund(order_number: Annotated[str, "Order number to process refund for"]) -> str:
+    """Simulated function to process a refund for a given order number."""
+    return f"Refund processed successfully for order {order_number}."
+
+
+@tool(approval_mode="never_require")
+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."
+
+
+@tool(approval_mode="never_require")
+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(client: AzureOpenAIResponsesClient) -> tuple[Agent, Agent, Agent, Agent]:
+    """Create and configure the triage and specialist agents.
+
+    Args:
+        client: The AzureOpenAIResponsesClient 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 = 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 = 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 = 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 = 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}: {message.text}")
+        for content in message.contents:
+            if content.type == "function_call":
+                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
+    client = AzureOpenAIResponsesClient(
+        project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+        deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+        credential=AzureCliCredential(),
+    )
+
+    # Create all agents: triage + specialists
+    triage, refund, order, support = create_agents(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
+    # - 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],
+            # 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.
+            termination_condition=lambda conversation: (
+                len(conversation) > 0 and "welcome" in conversation[-1].text.lower()
+            ),
+        )
+        .with_start_agent(triage)
+        .build()
+        .as_agent()  # Convert workflow to agent interface
+    )
+
+    # 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:
+        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 = [
+            Content.from_function_result(call_id=req_id, result=response) for req_id, response in responses.items()
+        ]
+        response = await agent.run(Message("tool", function_results))
+        pending_requests = handle_response_and_requests(response)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())