From 3fe6ff7600a9a1c5ab1a917457cb28cdd31fe3cb Mon Sep 17 00:00:00 2001
From: LI <2484593937@qq.com>
Date: Mon, 26 Oct 2026 23:03:52 +0800
Subject: [PATCH] Python: Correct HandoffBuilder output selection documentation

---
 .../agent_framework_orchestrations/_handoff.py             | 6 +++---
 .../tests/test_orchestration_intermediate_vs_terminal.py   | 7 ++++---
 2 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/python/packages/orchestrations/agent_framework_orchestrations/_handoff.py b/python/packages/orchestrations/agent_framework_orchestrations/_handoff.py
index 6b8e243b558..a7b84253c0a 100644
--- a/python/packages/orchestrations/agent_framework_orchestrations/_handoff.py
+++ b/python/packages/orchestrations/agent_framework_orchestrations/_handoff.py
@@ -657,15 +657,15 @@ class HandoffBuilder:
     tool injection, and middleware — capabilities only available on ``Agent``.
 
     Outputs:
-    Each agent's response surfaces as a workflow `output` event as it speaks; there is no
+    By default, each agent's response surfaces as a workflow `output` event as it speaks; there is no
     synthetic terminal event. Consumers iterating events see per-agent ``AgentResponse`` (or
     ``AgentResponseUpdate`` while streaming) in conversation order. The workflow returns to
     idle once the termination condition is met (or the user terminates an interactive run).
 
     Note:
     1. Agents in handoff workflows must be ``Agent`` instances and support local tool calls.
-    2. Because each agent's response is itself Workflow Output, handoff has no separate
-       "intermediate outputs" channel — every per-agent response is the primary output.
+    2. Use ``output_from`` and ``intermediate_output_from`` to select participants for Workflow Output
+       and Intermediate Output. Unselected participant outputs are hidden.
     """
 
     def __init__(
diff --git a/python/packages/orchestrations/tests/test_orchestration_intermediate_vs_terminal.py b/python/packages/orchestrations/tests/test_orchestration_intermediate_vs_terminal.py
index ece85161958..5172089a652 100644
--- a/python/packages/orchestrations/tests/test_orchestration_intermediate_vs_terminal.py
+++ b/python/packages/orchestrations/tests/test_orchestration_intermediate_vs_terminal.py
@@ -446,9 +446,10 @@ async def test_group_chat_intermediate_output_from_surface_as_intermediate() ->
 
 
 def test_handoff_builder_designates_every_participant_as_output() -> None:
-    """Handoff has no intermediate channel — every participant's reply is a primary
-    output. The builder must designate all participants in the workflow's
-    output designation so each per-agent yield surfaces as type='output'.
+    """By default, every Handoff participant's reply is Workflow Output.
+
+    The builder must designate all participants so each per-agent yield
+    surfaces as type='output'.
 
     Structural assertion (vs end-to-end) because Handoff agents require a full
     chat-client/middleware stack that we don't want to reproduce in this contract test.