chore: import upstream snapshot with attribution

python/samples/semantic-kernel-migration/orchestrations/handoff.py

@@ -0,0 +1,311 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#     "agent-framework-openai",
+#     "agent-framework-orchestrations",
+#     "semantic-kernel",
+# ]
+# ///
+# Run with any PEP 723 compatible runner, e.g.:
+#   uv run samples/semantic-kernel-migration/orchestrations/handoff.py
+
+# Copyright (c) Microsoft. All rights reserved.
+"""Side-by-side handoff orchestrations for Semantic Kernel and Agent Framework."""
+
+import asyncio
+from collections.abc import AsyncIterable, Callable, Iterator, Sequence
+
+from agent_framework import (
+    Agent,
+    Message,
+    WorkflowEvent,
+)
+from agent_framework.openai import OpenAIChatCompletionClient
+from agent_framework.orchestrations import HandoffAgentUserRequest, HandoffBuilder
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+from semantic_kernel.agents import Agent as SKAgent
+from semantic_kernel.agents import ChatCompletionAgent, HandoffOrchestration, OrchestrationHandoffs
+from semantic_kernel.agents.runtime import InProcessRuntime
+from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion
+from semantic_kernel.contents import (
+    AuthorRole,
+    ChatMessageContent,
+    FunctionCallContent,
+    FunctionResultContent,
+    StreamingChatMessageContent,
+)
+from semantic_kernel.functions import kernel_function
+
+# Load environment variables from .env file
+load_dotenv()
+
+CUSTOMER_PROMPT = "I need help with order 12345. I want a replacement and need to know when it will arrive."
+SCRIPTED_RESPONSES = [
+    "The item arrived damaged. I'd like a replacement shipped to the same address.",
+    "Great! Can you confirm the shipping cost won't be charged again?",
+    "Thanks for confirming!",
+]
+
+
+######################################################################
+# Semantic Kernel orchestration path
+######################################################################
+
+
+class OrderStatusPlugin:
+    @kernel_function
+    def check_order_status(self, order_id: str) -> str:
+        return f"Order {order_id} is shipped and will arrive in 2-3 days."
+
+
+class OrderRefundPlugin:
+    @kernel_function
+    def process_refund(self, order_id: str, reason: str) -> str:
+        return f"Refund for order {order_id} has been processed successfully (reason: {reason})."
+
+
+class OrderReturnPlugin:
+    @kernel_function
+    def process_return(self, order_id: str, reason: str) -> str:
+        return f"Return for order {order_id} has been processed successfully (reason: {reason})."
+
+
+def build_semantic_kernel_agents() -> tuple[list[SKAgent], OrchestrationHandoffs]:
+    credential = AzureCliCredential()
+
+    triage = ChatCompletionAgent(
+        name="TriageAgent",
+        description="Customer support triage specialist.",
+        instructions="Greet the customer, collect intent, and hand off to the right specialist.",
+        service=AzureChatCompletion(credential=credential),
+    )
+    refund = ChatCompletionAgent(
+        name="RefundAgent",
+        description="Handles refunds.",
+        instructions="Process refund requests.",
+        service=AzureChatCompletion(credential=credential),
+        plugins=[OrderRefundPlugin()],
+    )
+    order_status = ChatCompletionAgent(
+        name="OrderStatusAgent",
+        description="Looks up order status.",
+        instructions="Provide shipping timelines and tracking information.",
+        service=AzureChatCompletion(credential=credential),
+        plugins=[OrderStatusPlugin()],
+    )
+    order_return = ChatCompletionAgent(
+        name="OrderReturnAgent",
+        description="Handles returns.",
+        instructions="Coordinate order returns.",
+        service=AzureChatCompletion(credential=credential),
+        plugins=[OrderReturnPlugin()],
+    )
+
+    handoffs = (
+        OrchestrationHandoffs()
+        .add_many(
+            source_agent=triage.name,
+            target_agents={
+                refund.name: "Route refund-related requests here.",
+                order_status.name: "Route shipping questions here.",
+                order_return.name: "Route return-related requests here.",
+            },
+        )
+        .add(refund.name, triage.name, "Return to triage for non-refund issues.")
+        .add(order_status.name, triage.name, "Return to triage for non-status issues.")
+        .add(order_return.name, triage.name, "Return to triage for non-return issues.")
+    )
+
+    return [triage, refund, order_status, order_return], handoffs
+
+
+_sk_new_message = True
+
+
+def _sk_streaming_callback(message: StreamingChatMessageContent, is_final: bool) -> None:
+    """Display SK agent messages as they stream."""
+
+    global _sk_new_message
+    if _sk_new_message:
+        print(f"{message.name}: ", end="", flush=True)
+        _sk_new_message = False
+
+    if message.content:
+        print(message.content, end="", flush=True)
+
+    for item in message.items:
+        if isinstance(item, FunctionCallContent):
+            print(f"[tool call: {item.name}({item.arguments})]", end="", flush=True)
+        if isinstance(item, FunctionResultContent):
+            print(f"[tool result: {item.result}]", end="", flush=True)
+
+    if is_final:
+        print()
+        _sk_new_message = True
+
+
+def _make_sk_human_responder(script: Iterator[str]) -> Callable[[], ChatMessageContent]:
+    def _responder() -> ChatMessageContent:
+        try:
+            user_text = next(script)
+        except StopIteration:
+            user_text = "Thanks, that's all."
+        print(f"[User]: {user_text}")
+        return ChatMessageContent(role=AuthorRole.USER, content=user_text)
+
+    return _responder
+
+
+async def run_semantic_kernel_example(initial_task: str, scripted_responses: Sequence[str]) -> str:
+    agents, handoffs = build_semantic_kernel_agents()
+    response_iter = iter(scripted_responses)
+
+    orchestration = HandoffOrchestration(
+        members=agents,
+        handoffs=handoffs,
+        streaming_agent_response_callback=_sk_streaming_callback,
+        human_response_function=_make_sk_human_responder(response_iter),
+    )
+
+    runtime = InProcessRuntime()
+    runtime.start()
+
+    try:
+        orchestration_result = await orchestration.invoke(task=initial_task, runtime=runtime)
+        final_message = await orchestration_result.get(timeout=30)
+        if isinstance(final_message, ChatMessageContent):
+            return final_message.content or ""
+        return str(final_message)
+    finally:
+        await runtime.stop_when_idle()
+
+
+######################################################################
+# Agent Framework orchestration path
+######################################################################
+
+
+def _create_af_agents(client: OpenAIChatCompletionClient):
+    triage = Agent(
+        client=client,
+        name="triage_agent",
+        instructions=(
+            "You are a customer support triage agent. Route requests:\n"
+            "- handoff_to_refund_agent for refunds\n"
+            "- handoff_to_order_status_agent for shipping/timeline questions\n"
+            "- handoff_to_order_return_agent for returns"
+        ),
+        require_per_service_call_history_persistence=True,
+    )
+    refund = Agent(
+        client=client,
+        name="refund_agent",
+        instructions=(
+            "Handle refunds. Ask for order id and reason. If shipping info is needed, hand off to order_status_agent."
+        ),
+        require_per_service_call_history_persistence=True,
+    )
+    status = Agent(
+        client=client,
+        name="order_status_agent",
+        instructions=(
+            "Provide order status, tracking, and timelines. If billing questions appear, hand off to refund_agent."
+        ),
+        require_per_service_call_history_persistence=True,
+    )
+    returns = Agent(
+        client=client,
+        name="order_return_agent",
+        instructions=(
+            "Coordinate returns, confirm addresses, and summarize next steps. Hand off to triage_agent if unsure."
+        ),
+        require_per_service_call_history_persistence=True,
+    )
+    return triage, refund, status, returns
+
+
+async def _drain_events(stream: AsyncIterable[WorkflowEvent]) -> list[WorkflowEvent]:
+    return [event async for event in stream]
+
+
+def _collect_handoff_requests(events: list[WorkflowEvent]) -> list[WorkflowEvent]:
+    requests: list[WorkflowEvent] = []
+    for event in events:
+        if event.type == "request_info" and isinstance(event.data, HandoffAgentUserRequest):
+            requests.append(event)
+    return requests
+
+
+def _extract_final_conversation(events: list[WorkflowEvent]) -> list[Message]:
+    for event in events:
+        if event.type == "output":
+            return event.data
+    return []
+
+
+async def run_agent_framework_example(initial_task: str, scripted_responses: Sequence[str]) -> str:
+    client = OpenAIChatCompletionClient(credential=AzureCliCredential())
+    triage, refund, status, returns = _create_af_agents(client)
+
+    workflow = (
+        HandoffBuilder(
+            name="sk_af_handoff_migration",
+            participants=[triage, refund, status, returns],
+            termination_condition=lambda conv: sum(1 for m in conv if m.role == "user") >= 4,
+        )
+        .with_start_agent(triage)
+        .add_handoff(triage, [refund, status, returns])
+        .add_handoff(refund, [status, triage])
+        .add_handoff(status, [refund, triage])
+        .add_handoff(returns, [triage])
+        .build()
+    )
+
+    events = await _drain_events(workflow.run(initial_task, stream=True))
+    pending = _collect_handoff_requests(events)
+    scripted_iter = iter(scripted_responses)
+
+    final_events = events
+    while pending:
+        try:
+            user_reply = next(scripted_iter)
+        except StopIteration:
+            user_reply = "Thanks, that's all."
+        responses = {request.request_id: [Message(role="user", contents=[user_reply])] for request in pending}
+        final_events = await _drain_events(workflow.run(stream=True, responses=responses))
+        pending = _collect_handoff_requests(final_events)
+
+    conversation = _extract_final_conversation(final_events)
+    if not conversation:
+        return ""
+
+    # Render final transcript succinctly.
+    lines: list[str] = []
+    for message in conversation:
+        text = message.text or ""
+        if not text.strip():
+            continue
+        speaker = message.author_name or message.role
+        lines.append(f"{speaker}: {text}")
+    return "\n".join(lines)
+
+
+######################################################################
+# Console entry point
+######################################################################
+
+
+async def main() -> None:
+    print("===== Agent Framework Handoff =====")
+    af_transcript = await run_agent_framework_example(CUSTOMER_PROMPT, SCRIPTED_RESPONSES)
+    print(af_transcript or "No output produced.")
+    print()
+
+    print("===== Semantic Kernel Handoff =====")
+    sk_result = await run_semantic_kernel_example(CUSTOMER_PROMPT, SCRIPTED_RESPONSES)
+    print(sk_result or "No output produced.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())