Remove approval examples due to bug, refine handoff example

Author: pamelafox

README.md

@@ -229,7 +229,6 @@ You can run the examples in this repository by executing the scripts in the `exa
 | [workflow_hitl_checkpoint.py](examples/workflow_hitl_checkpoint.py) | Content review with `FileCheckpointStorage` — pause, exit process, and resume from checkpoint. |
 | [workflow_hitl_checkpoint_pg.py](examples/workflow_hitl_checkpoint_pg.py) | Same content review workflow with a custom `PostgresCheckpointStorage` backend. |
 | [workflow_hitl_handoff.py](examples/workflow_hitl_handoff.py) | Interactive handoff (no autonomous mode) — framework pauses for user input via `HandoffAgentUserRequest`. |
-| [workflow_hitl_handoff_approval.py](examples/workflow_hitl_handoff_approval.py) | Handoff with user input + tool approval combined in the same event loop. |
 | [workflow_hitl_magentic.py](examples/workflow_hitl_magentic.py) | Magentic orchestration with plan review — human can approve or revise the plan before execution. |
 | [agent_otel_aspire.py](examples/agent_otel_aspire.py) | An agent with OpenTelemetry tracing, metrics, and structured logs exported to the [Aspire Dashboard](https://aspire.dev/dashboard/standalone/). |
 | [agent_otel_appinsights.py](examples/agent_otel_appinsights.py) | An agent with OpenTelemetry tracing, metrics, and structured logs exported to [Azure Application Insights](https://learn.microsoft.com/azure/azure-monitor/app/app-insights-overview). Requires Azure provisioning via `azd provision`. |

examples/spanish/README.md

@@ -224,7 +224,6 @@ Puedes ejecutar los ejemplos en este repositorio ejecutando los scripts en el di
 | [workflow_hitl_checkpoint.py](workflow_hitl_checkpoint.py) | Revisión de contenido con `FileCheckpointStorage` — pausar, salir del proceso y reanudar desde checkpoint. |
 | [workflow_hitl_checkpoint_pg.py](workflow_hitl_checkpoint_pg.py) | Mismo workflow de revisión con un backend personalizado `PostgresCheckpointStorage`. |
 | [workflow_hitl_handoff.py](workflow_hitl_handoff.py) | Handoff interactivo (sin modo autónomo) — el framework pausa para entrada del usuario vía `HandoffAgentUserRequest`. |
-| [workflow_hitl_handoff_approval.py](workflow_hitl_handoff_approval.py) | Handoff con entrada de usuario + aprobación de herramientas combinados en el mismo bucle de eventos. |
 | [workflow_hitl_magentic.py](workflow_hitl_magentic.py) | Orquestación Magentic con revisión de plan — el humano puede aprobar o revisar el plan antes de la ejecución. |
 | [agent_otel_aspire.py](agent_otel_aspire.py) | Un agente con trazas, métricas y logs estructurados de OpenTelemetry exportados al [Aspire Dashboard](https://aspire.dev/dashboard/standalone/). |
 | [agent_otel_appinsights.py](agent_otel_appinsights.py) | Un agente con trazas, métricas y logs estructurados de OpenTelemetry exportados a [Azure Application Insights](https://learn.microsoft.com/azure/azure-monitor/app/app-insights-overview). Requiere aprovisionamiento de Azure con `azd provision`. |

examples/spanish/workflow_hitl_handoff.py

@@ -14,9 +14,9 @@
 import asyncio
 import os
 import sys
-from typing import Any
+from typing import Annotated, Any
 
-from agent_framework import Agent, AgentResponse, AgentResponseUpdate
+from agent_framework import Agent, AgentResponse, AgentResponseUpdate, tool
 from agent_framework.openai import OpenAIChatClient
 from agent_framework.orchestrations import HandoffAgentUserRequest, HandoffBuilder
 from azure.identity.aio import DefaultAzureCredential, get_bearer_token_provider
@@ -47,6 +47,18 @@
     )
 
 
+# --- Herramientas ---
+
+
+@tool
+def process_return(
+    order_number: Annotated[str, "The 3-digit order number"],
+    return_type: Annotated[str, "Either 'refund' or 'replacement'"],
+) -> str:
+    """Process a product return for the given order."""
+    return f"Return processed for order {order_number}: {return_type} approved. Confirmation email sent."
+
+
 # --- Agentes ---
 
 triage_agent = Agent(
@@ -56,6 +68,8 @@
         "Eres un agente de triaje de soporte al cliente. Saluda al cliente, entiende su problema "
         "y transfiere al especialista correcto: order_agent para consultas de pedidos, "
         "return_agent para devoluciones. No puedes manejar problemas específicos tú mismo — siempre transfiere. "
+        "Si un especialista acaba de terminar de ayudar, pregunta al cliente si necesita algo más "
+        "— NO reenvíes al mismo especialista. "
         "NO pidas información de contacto, correo electrónico ni número de teléfono. "
         "NO digas 'Adiós' hasta que el cliente confirme explícitamente que no tiene más preguntas."
     ),
@@ -65,7 +79,7 @@
     client=client,
     name="order_agent",
     instructions=(
-        "Te encargas de consultas sobre el estado de pedidos. Ayuda al cliente con su pedido. "
+        "Eres el especialista en seguimiento de pedidos. Ayuda al cliente a verificar el estado de su pedido. "
         "Cuando termines, transfiere de vuelta a triage_agent."
     ),
 )
@@ -74,10 +88,12 @@
     client=client,
     name="return_agent",
     instructions=(
-        "Te encargas de devoluciones de productos. Ayuda al cliente a iniciar una devolución. "
+        "Eres el especialista en devoluciones. Ayuda al cliente a iniciar una devolución. "
         "Los únicos datos que necesitas son el número de pedido (3 dígitos) y si quieren un reembolso o reemplazo. "
-        "Mantenlo simple y rápido. Cuando termines, transfiere de vuelta a triage_agent."
+        "Mantenlo simple y rápido. Una vez que el cliente confirme, llama a process_return para completar la devolución. "
+        "Después de procesar la devolución, transfiere de vuelta a triage_agent."
     ),
+    tools=[process_return],
 )
 
 
@@ -131,11 +147,9 @@ async def main() -> None:
             if isinstance(request_event.data, HandoffAgentUserRequest):
                 # Muestra la respuesta del agente
                 agent_response = request_event.data.agent_response
-                if agent_response.messages:
-                    for msg in agent_response.messages[-3:]:
-                        if msg.text:
-                            speaker = msg.author_name or msg.role
-                            print(f"🤖 {speaker}: {msg.text}")
+                for msg in agent_response.messages:
+                    if msg.text:
+                        print(f"🤖 {msg.author_name}: {msg.text}")
 
                 # Obtiene la entrada del usuario
                 user_input = input("\n👤 Tú: ").strip()

examples/spanish/workflow_hitl_handoff_approval.py

@@ -14,9 +14,9 @@
 import asyncio
 import os
 import sys
-from typing import Any
+from typing import Annotated, Any
 
-from agent_framework import Agent, AgentResponse, AgentResponseUpdate
+from agent_framework import Agent, AgentResponse, AgentResponseUpdate, tool
 from agent_framework.openai import OpenAIChatClient
 from agent_framework.orchestrations import HandoffAgentUserRequest, HandoffBuilder
 from azure.identity.aio import DefaultAzureCredential, get_bearer_token_provider
@@ -47,6 +47,18 @@
     )
 
 
+# --- Tools ---
+
+
+@tool
+def process_return(
+    order_number: Annotated[str, "The 3-digit order number"],
+    return_type: Annotated[str, "Either 'refund' or 'replacement'"],
+) -> str:
+    """Process a product return for the given order."""
+    return f"Return processed for order {order_number}: {return_type} approved. Confirmation email sent."
+
+
 # --- Agents ---
 
 triage_agent = Agent(
@@ -56,6 +68,8 @@
         "You are a customer-support triage agent. Greet the customer, understand their issue, "
         "and hand off to the right specialist: order_agent for order inquiries, "
         "return_agent for returns. You cannot handle specific issues yourself — always hand off. "
+        "If a specialist has just finished helping, ask the customer if there is anything else "
+        "they need help with — do NOT re-route to the same specialist. "
         "Do NOT ask for contact information, email, or phone number. "
         "Do NOT say 'Goodbye' until the customer explicitly confirms they have no more questions."
     ),
@@ -65,7 +79,7 @@
     client=client,
     name="order_agent",
     instructions=(
-        "You handle order status inquiries. Help the customer with their order. "
+        "You are the order tracking specialist. Help the customer check order status. "
         "When done, hand off back to triage_agent."
     ),
 )
@@ -74,18 +88,16 @@
     client=client,
     name="return_agent",
     instructions=(
-        "You handle product returns. Help the customer initiate a return. "
+        "You are the returns specialist. Help the customer initiate a return. "
         "The only details you need are the order number (3 digits) and whether they want a refund or replacement. "
-        "Keep it simple and fast. When done, hand off back to triage_agent."
+        "Keep it simple and fast. Once the customer confirms, call process_return to complete the return. "
+        "After the return is processed, hand off back to triage_agent."
     ),
+    tools=[process_return],
 )
 
 
-# --- Main ---
-
-
 # --- Workflow ---
-
 workflow = (
     HandoffBuilder(
         name="customer_support",
@@ -131,11 +143,9 @@ async def main() -> None:
             if isinstance(request_event.data, HandoffAgentUserRequest):
                 # Show agent's response
                 agent_response = request_event.data.agent_response
-                if agent_response.messages:
-                    for msg in agent_response.messages[-3:]:
-                        if msg.text:
-                            speaker = msg.author_name or msg.role
-                            print(f"🤖 {speaker}: {msg.text}")
+                for msg in agent_response.messages:
+                    if msg.text:
+                        print(f"🤖 {msg.author_name}: {msg.text}")
 
                 # Get user input
                 user_input = input("\n👤 You: ").strip()