Fix handoff workflow context management and improve AG-UI demo (#5136)

python/samples/03-workflows/agents/handoff_workflow_as_agent.py

@@ -80,6 +80,7 @@ def create_agents(client: FoundryChatClient) -> tuple[Agent, Agent, Agent, Agent
             "based on the problem described."
         ),
         name="triage_agent",
+        require_per_service_call_history_persistence=True,
     )
 
     # Refund specialist: Handles refund requests
@@ -89,6 +90,7 @@ def create_agents(client: FoundryChatClient) -> tuple[Agent, Agent, Agent, Agent
         name="refund_agent",
         # In a real application, an agent can have multiple tools; here we keep it simple
         tools=[process_refund],
+        require_per_service_call_history_persistence=True,
     )
 
     # Order/shipping specialist: Resolves delivery issues
@@ -98,6 +100,7 @@ def create_agents(client: FoundryChatClient) -> tuple[Agent, Agent, Agent, Agent
         name="order_agent",
         # In a real application, an agent can have multiple tools; here we keep it simple
         tools=[check_order_status],
+        require_per_service_call_history_persistence=True,
     )
 
     # Return specialist: Handles return requests
@@ -107,6 +110,7 @@ def create_agents(client: FoundryChatClient) -> tuple[Agent, Agent, Agent, Agent
         name="return_agent",
         # In a real application, an agent can have multiple tools; here we keep it simple
         tools=[process_return],
+        require_per_service_call_history_persistence=True,
     )
 
     return triage_agent, refund_agent, order_agent, return_agent

python/samples/03-workflows/orchestrations/README.md

@@ -85,6 +85,8 @@ from agent_framework.orchestrations import (
 
 **Handoff workflow tip**: Handoff workflows maintain the full conversation history including any `Message.additional_properties` emitted by your agents. This ensures routing metadata remains intact across all agent transitions. For specialist-to-specialist handoffs, use `.add_handoff(source, targets)` to configure which agents can route to which others with a fluent, type-safe API.
 
+**Handoff `require_per_service_call_history_persistence`**: All agents in a handoff workflow **must** set `require_per_service_call_history_persistence=True`. `HandoffBuilder.build()` will raise a `ValueError` if any participant is missing this flag. This is required because handoff middleware short-circuits tool calls via `MiddlewareTermination`, and without per-service-call history persistence, local history would store tool results the service never received, causing mismatches on subsequent turns.
+
 **Sequential orchestration note**: Sequential orchestration uses a few small adapter nodes for plumbing:
 - `input-conversation` normalizes input to `list[Message]`
 - `to-conversation:<participant>` converts agent responses into the shared conversation

python/samples/03-workflows/orchestrations/handoff_autonomous.py

@@ -53,6 +53,7 @@ def create_agents(
             "Assign the two tasks to the appropriate specialists, one after the other."
         ),
         name="coordinator",
+        require_per_service_call_history_persistence=True,
     )
 
     research_agent = Agent(
@@ -66,6 +67,7 @@ def create_agents(
             "coordinator. Keep each individual response focused on one aspect."
         ),
         name="research_agent",
+        require_per_service_call_history_persistence=True,
     )
 
     summary_agent = Agent(
@@ -75,6 +77,7 @@ def create_agents(
             "control to the coordinator."
         ),
         name="summary_agent",
+        require_per_service_call_history_persistence=True,
     )
 
     return coordinator, research_agent, summary_agent

python/samples/03-workflows/orchestrations/handoff_simple.py

@@ -77,6 +77,7 @@ def create_agents(client: FoundryChatClient) -> tuple[Agent, Agent, Agent, Agent
             "based on the problem described."
         ),
         name="triage_agent",
+        require_per_service_call_history_persistence=True,
     )
 
     # Refund specialist: Handles refund requests
@@ -86,6 +87,7 @@ def create_agents(client: FoundryChatClient) -> tuple[Agent, Agent, Agent, Agent
         name="refund_agent",
         # In a real application, an agent can have multiple tools; here we keep it simple
         tools=[process_refund],
+        require_per_service_call_history_persistence=True,
     )
 
     # Order/shipping specialist: Resolves delivery issues
@@ -95,6 +97,7 @@ def create_agents(client: FoundryChatClient) -> tuple[Agent, Agent, Agent, Agent
         name="order_agent",
         # In a real application, an agent can have multiple tools; here we keep it simple
         tools=[check_order_status],
+        require_per_service_call_history_persistence=True,
     )
 
     # Return specialist: Handles return requests
@@ -104,6 +107,7 @@ def create_agents(client: FoundryChatClient) -> tuple[Agent, Agent, Agent, Agent
         name="return_agent",
         # In a real application, an agent can have multiple tools; here we keep it simple
         tools=[process_return],
+        require_per_service_call_history_persistence=True,
     )
 
     return triage_agent, refund_agent, order_agent, return_agent

python/samples/03-workflows/orchestrations/handoff_with_code_interpreter_file.py

@@ -105,6 +105,7 @@ async def main() -> None:
             "When the user asks to create or generate files, hand off to code_specialist "
             "by calling handoff_to_code_specialist."
         ),
+        require_per_service_call_history_persistence=True,
     )
 
     code_interpreter_tool = client.get_code_interpreter_tool()
@@ -117,6 +118,7 @@ async def main() -> None:
             "and create files when requested. Always save files to /mnt/data/ directory."
         ),
         tools=[code_interpreter_tool],
+        require_per_service_call_history_persistence=True,
     )
 
     workflow = (

python/samples/03-workflows/orchestrations/handoff_with_tool_approval_checkpoint_resume.py

@@ -71,6 +71,7 @@ def create_agents(client: FoundryChatClient) -> tuple[Agent, Agent, Agent]:
             "if they need refund help or order tracking. Use handoff_to_refund_agent or "
             "handoff_to_order_agent to transfer them."
         ),
+        require_per_service_call_history_persistence=True,
     )
 
     refund = Agent(
@@ -83,6 +84,7 @@ def create_agents(client: FoundryChatClient) -> tuple[Agent, Agent, Agent]:
             "to record the request before continuing."
         ),
         tools=[submit_refund],
+        require_per_service_call_history_persistence=True,
     )
 
     order = Agent(
@@ -92,6 +94,7 @@ def create_agents(client: FoundryChatClient) -> tuple[Agent, Agent, Agent]:
             "You are an order tracking specialist. Help customers track their orders. "
             "Ask for order numbers and provide shipping updates."
         ),
+        require_per_service_call_history_persistence=True,
     )
 
     return triage, refund, order