Python: Improve the handling of intermediate outputs for workflows and orchestrations (#5623)

* Improve the handling of intermediate outputs for workflows and orchestrations

* Address PR review feedback on intermediate output forwarding

- Switch workflow.as_agent() forwarding to an explicit allowlist of {output,
  intermediate, data, request_info} so orchestration-internal events
  (group_chat, handoff_sent, magentic_orchestrator) stay inside the workflow
  instead of leaking into agent responses via str(data) coercion.
- Stop raising on intermediate AgentResponseUpdate in non-streaming run();
  surface the partial as a Message with text_reasoning content. The defensive
  raise still applies to terminal output events, where Update payloads would
  corrupt message ordering.
- Extend the DevUI workflow-event mapper so intermediate yields wrapping
  plain strings, Messages, and list[Message] render as visible output items
  instead of generic completed-trace events.
- Add orchestration coverage for GroupChat, Handoff, and Magentic builders
  (default vs intermediate_outputs=True; structural where end-to-end is heavy).

* Lift output-designation policy into a value type

Replace the ``Workflow._output_executors`` list and the
``RunnerContext.should_label_as_intermediate`` Protocol method with a single
immutable ``OutputDesignation`` value type owned by ``Workflow``. Thread the
designation as a parameter through the existing call chain (Runner ->
EdgeRunner -> Executor -> WorkflowContext) so ``yield_output`` consults the
threaded snapshot directly rather than calling back into the runner context.

Removes the ``InProcRunnerContext._workflow`` back-reference and the
``WorkflowBuilder.build()`` assignment that wired it up. Adds the public
predicate ``Workflow.is_terminal_executor(executor_id)`` for external
observers; ``OutputDesignation`` itself stays package-internal.

Key decisions
- ``OutputDesignation.designated`` is ``frozenset[str] | None`` -- ``None``
  preserves legacy "every yield is type='output'" behavior, any frozenset
  (including empty) opts into strict mode. The ``DeprecationWarning`` for
  legacy mode at build time is unchanged.
- ``output_designation`` is an optional parameter on ``Runner``,
  ``EdgeRunner.send_message``, ``EdgeRunner._execute_on_target``,
  ``Executor.execute``, ``Executor._create_context_for_handler``, and
  ``WorkflowContext.__init__``. Each defaults to legacy ``OutputDesignation()``
  so direct callers (Azure Functions ``CapturingRunnerContext``,
  ``test_runner`` recording fixtures) keep working without ceremony.
- The workflow-level filter in ``_run_core`` reads ``self._output_designation``
  live, preserving today's semantics where mutating the designation after
  build still affects subsequent runs (used by two existing tests).
- ``Workflow.to_dict()`` continues to emit ``"output_executors":
  list[str] | None`` (sorted from the frozenset). Checkpoint format unchanged.

Files changed
- _workflow.py: add ``OutputDesignation`` dataclass; replace
  ``_output_executors`` with ``_output_designation``; add
  ``is_terminal_executor``; delete ``_should_yield_output_event``.
- _runner_context.py: drop ``should_label_as_intermediate`` Protocol method
  and ``InProcRunnerContext`` impl; drop ``_workflow`` back-reference.
- _workflow_builder.py: remove ``context._workflow = workflow`` assignment.
- _runner.py, _edge_runner.py, _executor.py, _workflow_context.py: thread
  ``output_designation`` parameter through the call chain.
- tests/workflow/test_output_designation.py (new): three-state coverage of
  the value type plus the public predicate delegation.
- tests/workflow/test_workflow_builder.py, test_validation.py,
  test_workflow.py, test_runner.py and
  orchestrations/tests/test_orchestration_intermediate_vs_terminal.py:
  switch probes from ``_output_executors`` set checks to
  ``get_output_executors`` / ``is_terminal_executor``; update two
  post-build mutation tests to set ``_output_designation`` instead.

Verification
- core/tests/workflow/, orchestrations/tests/, azurefunctions/tests/:
  1119 passed, 42 skipped, 2 xfailed.
- ``uv run poe lint``: clean.
- ``uv run poe typing``: only the pre-existing
  ``_AGENT_FORWARDED_EVENT_TYPES`` pyright warning from 394bcd607 remains.

Notes for next iteration
- The builder's own ``_output_executors`` attribute (``list[Executor |
  SupportsAgentRun]``) is intentionally untouched; the issue scoped the
  rename to the workflow attribute.
- Adjacent review candidates (twin ``WorkflowAgent`` translators,
  ``_AGENT_FORWARDED_EVENT_TYPES`` kind classifier,
  ``_event_origin_context`` ContextVar removal, ``WorkflowEvent`` ADT
  split, legacy-mode removal) remain out of scope.

* Add explicit workflow output designation

Key decisions

- Extend the internal OutputDesignation value type from terminal-only membership to output/intermediate/hidden classification. Legacy mode remains outputs=None, so workflows built without output_executors or intermediate_executors still label every yield_output as type='output'.

- WorkflowBuilder now accepts intermediate_executors. Providing either designation enters explicit mode; output executors emit output, intermediate executors emit intermediate, and unlisted yield_output payloads are hidden from caller-facing events while remaining in executor_completed data.

- Empty explicit designation, duplicate entries, overlaps, unknown executors, and designated executors without workflow output annotations fail build validation. Existing orchestration builders pass intermediate-capable participants through intermediate_executors to preserve current intermediate_outputs behavior until participant-oriented designation lands.

Files changed

- packages/core/agent_framework/_workflows/_workflow.py, _workflow_builder.py, _workflow_context.py, _validation.py, _events.py

- packages/core/tests/workflow/test_output_designation.py, test_output_executors_contract.py, test_strict_mode_event_labeling.py, test_validation.py, test_workflow.py, test_workflow_agent_intermediate.py

- packages/orchestrations/agent_framework_orchestrations/_sequential.py, _concurrent.py, _group_chat.py, _magentic.py

- packages/core/AGENTS.md

Verification

- uv run pytest packages/core/tests/workflow packages/orchestrations/tests packages/devui/tests/devui/test_mapper.py -q

- uv run pytest packages/azurefunctions/tests -q

- uv run poe lint

- uv run poe typing fails only on pre-existing packages/core/agent_framework/_workflows/_agent.py _AGENT_FORWARDED_EVENT_TYPES private-use pyright error.

Notes for next iteration

- issues/03-core-workflow-explicit-designation.md was moved to issues/done but issues/ remains untracked and intentionally excluded from this commit.

- Slice 4 should tighten workflow.as_agent() mapping for hidden emissions and streaming-only update payloads; Slice 5 should replace orchestration intermediate_outputs with participant-oriented designation.

* Tighten workflow-as-agent output mapping

Key decisions

- Treat AgentResponseUpdate as a streaming-only payload across the workflow.as_agent() adapter, so non-streaming agent runs now reject both terminal output and intermediate workflow events carrying updates.
- Keep streaming classification behavior explicit: terminal update payloads remain normal text content, while intermediate update payloads are rewritten to text_reasoning content.
- Add explicit-mode coverage proving hidden yield_output emissions do not appear in non-streaming AgentResponse messages or streaming AgentResponseUpdate chunks.

Files changed

- packages/core/agent_framework/_workflows/_agent.py
- packages/core/tests/workflow/test_workflow_agent_intermediate.py

Verification

- uv run pytest packages/core/tests/workflow/test_workflow_agent_intermediate.py -q
- uv run pytest packages/core/tests/workflow/test_workflow_agent.py packages/core/tests/workflow/test_workflow_agent_intermediate.py -q
- uv run pytest packages/core/tests/workflow packages/orchestrations/tests packages/devui/tests/devui/test_mapper.py -q
- uv run poe lint
- uv run poe typing fails only on the pre-existing packages/core/agent_framework/_workflows/_agent.py _AGENT_FORWARDED_EVENT_TYPES private-use pyright error.

Blockers or notes for next iteration

- issues/04-workflow-as-agent-output-mapping.md was moved to issues/done/ but issues/ remains untracked and intentionally excluded from this commit.
- Slice 5 should replace orchestration intermediate_outputs with participant-oriented designation.

* Add orchestration participant output designation

Key decisions

- Replace orchestration intermediate_outputs with participant-oriented output_participants and intermediate_participants across Sequential, Concurrent, GroupChat, Magentic, and Handoff builders.
- Keep synthetic final executors terminal by default for Concurrent, GroupChat, and Magentic; keep Sequential's final participant terminal by default; keep Handoff participants terminal by default.
- Centralize participant designation validation for empty explicit designation, duplicates, overlaps, and unknown participants, then map validated participants to workflow output/intermediate executors.

Files changed

- packages/orchestrations/agent_framework_orchestrations/_participant_designation.py
- packages/orchestrations/agent_framework_orchestrations/_sequential.py
- packages/orchestrations/agent_framework_orchestrations/_concurrent.py
- packages/orchestrations/agent_framework_orchestrations/_group_chat.py
- packages/orchestrations/agent_framework_orchestrations/_magentic.py
- packages/orchestrations/agent_framework_orchestrations/_handoff.py
- packages/orchestrations/tests/test_orchestration_intermediate_vs_terminal.py
- packages/orchestrations/tests/test_magentic.py

Blockers or notes for next iteration

- issues/05-orchestration-participant-designation.md was moved to issues/done/ but issues/ remains untracked and intentionally excluded from this commit.
- Slice 7 should migrate samples and docs away from intermediate_outputs to the new participant designation API.
- uv run poe typing still fails only on the pre-existing packages/core/agent_framework/_workflows/_agent.py _AGENT_FORWARDED_EVENT_TYPES private-use pyright error.

* Migrate samples to explicit output designation

Key decisions

- Replace sample usage of the removed orchestration intermediate_outputs boolean with participant-oriented intermediate_participants designation.
- Update raw workflow guidance to show output_executors together with intermediate_executors, and document that unlisted yields are hidden in explicit designation mode.
- Keep orchestration final outputs terminal while streaming designated participant responses as intermediate progress, including workflow.as_agent() samples where intermediates map to text_reasoning content.
- Refresh workflow and orchestration README guidance plus the changelog reference so public docs no longer point users at intermediate_outputs.

Files changed

- CHANGELOG.md
- packages/orchestrations/README.md
- samples/README.md
- samples/03-workflows/README.md
- samples/03-workflows/control-flow/intermediate_vs_terminal_outputs.py
- samples/03-workflows/orchestrations/README.md
- samples/03-workflows/orchestrations/group_chat_agent_manager.py
- samples/03-workflows/orchestrations/group_chat_philosophical_debate.py
- samples/03-workflows/orchestrations/group_chat_simple_selector.py
- samples/03-workflows/orchestrations/magentic.py
- samples/03-workflows/orchestrations/magentic_human_plan_review.py
- samples/03-workflows/orchestrations/sequential_chain_only_agent_responses.py
- samples/03-workflows/agents/group_chat_workflow_as_agent.py
- samples/03-workflows/agents/magentic_workflow_as_agent.py
- samples/03-workflows/agents/sequential_workflow_as_agent.py
- samples/semantic-kernel-migration/orchestrations/group_chat.py
- samples/semantic-kernel-migration/orchestrations/magentic.py

Blockers or notes for next iteration

- issues/07-samples-and-docs-explicit-output-designation.md was moved to issues/done/ but issues/ remains untracked and intentionally excluded from this commit.
- issues/06-devui-intermediate-event-rendering.md remains present and appears already satisfied by existing DevUI mapper/tests from the prior implementation slice.
- PRD-explicit-workflow-output-designation.md remains untracked and intentionally excluded from this commit.

* Render DevUI intermediate workflow outputs

Key decisions

- Preserve workflow output designation metadata on visible DevUI output messages and text deltas so intermediate/data emissions remain distinguishable from terminal output.
- Render intermediate workflow message items in the execution timeline using executor metadata, while excluding them from the final workflow result aggregation.
- Keep terminal output message rendering unchanged and retain legacy data events on the intermediate compatibility path.

Files changed

- packages/devui/agent_framework_devui/_mapper.py
- packages/devui/frontend/src/components/features/workflow/execution-timeline.tsx
- packages/devui/frontend/src/components/features/workflow/workflow-view.tsx
- packages/devui/frontend/src/types/openai.ts
- packages/devui/tests/devui/test_mapper.py

Blockers or notes for next iteration

- issues/06-devui-intermediate-event-rendering.md was moved to issues/done/ but issues/ remains untracked and intentionally excluded from this commit.
- PRD-explicit-workflow-output-designation.md remains untracked and intentionally excluded from this commit.
- uv run poe typing still fails only on the pre-existing packages/core/agent_framework/_workflows/_agent.py _AGENT_FORWARDED_EVENT_TYPES private-use pyright error.

* Fix mypy

* Clarify orchestration participant output config

* Rename participant output kwargs for clarity

output_participants -> final_output_from, intermediate_participants ->
intermediate_output_from. The old names read like categories of
participant; the new names make it clear the kwarg designates which
participants' outputs surface as final vs. intermediate events.

* Rename core workflow output kwargs with deprecation shim

Adds final_output_from / intermediate_output_from as canonical kwargs on
Workflow and WorkflowBuilder. Old output_executors / intermediate_executors
kwargs continue to work but emit DeprecationWarning via a shared coalesce
helper that also rejects supplying both. Wire-format keys in to_dict()
stay as output_executors / intermediate_executors so checkpoint
compatibility is preserved.

Internal call sites in orchestrations and samples updated to the new
names so users following sample code learn the canonical vocabulary;
legacy callers still work with a one-shot warning.

* Suppress pyright reportPrivateUsage on cross-module sentinel import

* Update docstrings

* Propagate sub-workflow intermediate outputs, fix handoff/sequential intermediate-only designation, and shore up tests, sample, and docstrings around the intermediate output contract.

* Add canonical workflow output_from selection

Key decisions:\n- Make output_from the canonical workflow-output allow-list and keep output_executors/final_output_from as deprecated compatibility aliases.\n- Treat empty output_from/intermediate_output_from lists as explicit selections and keep validation responsible for empty, duplicate, overlap, and unknown selections.\n- Remove the branch-only public intermediate_executors WorkflowBuilder kwarg while preserving legacy wire keys in to_dict().\n\nFiles changed:\n- packages/core/agent_framework/_workflows/_workflow.py\n- packages/core/agent_framework/_workflows/_workflow_builder.py\n- packages/core/agent_framework/_workflows/_workflow_context.py\n- packages/core/agent_framework/_workflows/_agent.py\n- packages/core/agent_framework/_workflows/_agent_executor.py\n- packages/core/tests/workflow/* output-selection coverage updates\n- packages/core/AGENTS.md\n- issues/done/001-canonical-list-based-output-selection.md\n\nBlockers/notes:\n- Orchestration builders still pass final_output_from internally; follow-up issue 004 should migrate them to output_from.\n- Legacy omitted-selection behavior and explicit all/all_other literals are left for issues 002 and 003.

* Add explicit all workflow output selection

Key decisions:
- Treat output_from='all' as an explicit workflow-output selection sentinel and expand it at build time to executors with declared workflow output types.
- Keep omitted output selections in legacy all-output mode with a deprecation warning that names output_from and intermediate_output_from and points to output_from='all'.
- Reject intermediate_output_from='all' at construction because the all-output literal is output-only for this issue.

Files changed:
- packages/core/agent_framework/_workflows/_workflow_builder.py
- packages/core/tests/workflow/test_output_executors_contract.py
- issues/done/002-explicit-all-output-and-legacy-migration.md

Blockers/notes:
- all_other intermediate-output selection remains for issue 003.
- Workflow-as-agent/orchestration parity remains for issue 004.

* Add all-other intermediate output selection

Key decisions:
- Treat intermediate_output_from='all_other' as an explicit intermediate-output selection sentinel and expand it at build time after the workflow graph is complete.
- Expand all_other to output-capable executors not selected by output_from; omitted or empty output_from selects no workflow outputs, while output_from='all' leaves an empty intermediate selection.
- Keep output_from='all_other' invalid so all_other remains intermediate-output-only and runtime classification still receives concrete executor-id sets.

Files changed:
- packages/core/agent_framework/_workflows/_workflow_builder.py
- packages/core/tests/workflow/test_output_executors_contract.py
- issues/done/003-all-other-intermediate-output-selection.md

Blockers/notes:
- Workflow-as-agent and orchestration parity remains for issue 004.
- Full documentation updates remain for issue 005.

* Add orchestration output selection parity

Key decisions:
- Expose output_from on sequential, concurrent, group chat, handoff, and magentic builders while keeping final_output_from as a deprecated compatibility alias.
- Resolve orchestration participant selections through the same explicit rules as workflows: output_from='all', intermediate_output_from='all_other', hidden unselected participant payloads, and overlap/duplicate/unknown/invalid-literal validation.
- Continue preserving documented orchestration defaults by always designating each pattern's terminal internal executor where applicable.

Files changed:
- packages/orchestrations/agent_framework_orchestrations/_participant_output_config.py
- packages/orchestrations/agent_framework_orchestrations/_sequential.py
- packages/orchestrations/agent_framework_orchestrations/_concurrent.py
- packages/orchestrations/agent_framework_orchestrations/_group_chat.py
- packages/orchestrations/agent_framework_orchestrations/_handoff.py
- packages/orchestrations/agent_framework_orchestrations/_magentic.py
- packages/orchestrations/agent_framework_orchestrations/_orchestration_request_info.py
- packages/orchestrations/tests/test_orchestration_intermediate_vs_terminal.py
- issues/done/004-workflow-as-agent-and-orchestration-parity.md

Blockers/notes:
- Full documentation and sample migration wording remains for issue 005.
- Existing tests that intentionally use final_output_from now emit the new deprecation warning.

* Document workflow output selection contract

Key decisions:
- Use Workflow Output and Intermediate Output as the developer-facing terms for selected caller-facing emissions.
- Document output_from and intermediate_output_from as the canonical API, with output_from as an allow-list and unselected payloads hidden unless explicitly selected as intermediate.
- Add scenario and invalid-selection tables for workflow and orchestration docs, including legacy omission warnings, output_from='all', intermediate_output_from='all_other', list selections, invalid literals, overlap, duplicates, unknown selections, and empty explicit selections.
- Migrate samples away from final_output_from and output_executors except where compatibility aliases are explicitly documented.

Files changed:
- packages/core/AGENTS.md
- packages/orchestrations/README.md
- packages/orchestrations/agent_framework_orchestrations/_handoff.py
- packages/orchestrations/agent_framework_orchestrations/_sequential.py
- samples/03-workflows/README.md
- samples/03-workflows/control-flow/intermediate_vs_terminal_outputs.py
- samples/03-workflows/human-in-the-loop/agents_with_approval_requests.py
- samples/03-workflows/orchestrations/README.md
- samples/04-hosting/foundry-hosted-agents/responses/05_workflows/main.py
- scripts/sample_validation/create_dynamic_workflow_executor.py
- issues/done/005-document-output-selection-contract.md

Blockers/notes:
- Direct full Ruff on scripts/sample_validation/create_dynamic_workflow_executor.py still reports pre-existing docstring/print/line-length issues outside this docs migration; syntax-focused checks for changed files pass.
- No remaining AFK issue files are present under issues/.

* Latest updates

* Typing fixes

* Cleanup

python/samples/03-workflows/README.md

@@ -89,6 +89,7 @@ Write workflows as plain Python async functions — no graph concepts, no execut
 | Multi-Selection Edge Group | [control-flow/multi_selection_edge_group.py](./control-flow/multi_selection_edge_group.py) | Select one or many targets dynamically (subset fan-out) |
 | Simple Loop                | [control-flow/simple_loop.py](./control-flow/simple_loop.py)                               | Feedback loop where an agent judges ABOVE/BELOW/MATCHED |
 | Workflow Cancellation      | [control-flow/workflow_cancellation.py](./control-flow/workflow_cancellation.py)           | Cancel a running workflow using asyncio tasks           |
+| Workflow and Intermediate Outputs | [control-flow/intermediate_vs_terminal_outputs.py](./control-flow/intermediate_vs_terminal_outputs.py) | Select Workflow Output and Intermediate Output executors; hide unselected yields; map Intermediate Output events to `text_reasoning` content via `as_agent` |
 
 ### human-in-the-loop
 
@@ -118,6 +119,43 @@ For additional observability samples in Agent Framework, see the [observability
 Orchestration-focused samples (Sequential, Concurrent, Handoff, GroupChat, Magentic), including builder-based
 `workflow.as_agent(...)` variants, are documented in the [orchestrations](./orchestrations/README.md) directory.
 
+### output selection
+
+Workflow Output selection controls which `ctx.yield_output(...)` calls are visible to callers as `type='output'`
+events and through `WorkflowRunResult.get_outputs()`. The core rule is that `output_from` is an allow-list for
+Workflow Output, not a routing rule for every other executor output. Unselected executor payloads are hidden unless
+`intermediate_output_from` explicitly selects them as Intermediate Output.
+
+Use `output_from` and `intermediate_output_from` as the canonical API:
+
+| Selection | Workflow Output | Intermediate Output | Hidden payloads |
+| --- | --- | --- | --- |
+| Omit both selections | Every executor `yield_output`; emits a deprecation warning | None | None |
+| `output_from="all"` | Every executor `yield_output`; no warning | None | None |
+| `output_from=[answerer]` | Only `answerer` | None | All other executor payloads |
+| `output_from=[answerer], intermediate_output_from="all_other"` | Only `answerer` | Every output-capable executor not selected by `output_from` | None |
+| `intermediate_output_from="all_other"` | None | Every output-capable executor | None |
+| `output_from=[], intermediate_output_from="all_other"` | None | Every output-capable executor | None |
+| `output_from=[answerer], intermediate_output_from=[planner, researcher]` | Only `answerer` | `planner` and `researcher` | Any other executor payloads |
+
+Invalid selections fail at construction or build time:
+
+| Invalid selection | Why it fails |
+| --- | --- |
+| `output_from="all_other"` | `"all_other"` is only valid for `intermediate_output_from` |
+| `intermediate_output_from="all"` | `"all"` is only valid for `output_from` |
+| The same executor in both selections | One payload cannot be both Workflow Output and Intermediate Output |
+| Duplicate executor selections | Duplicates are treated as configuration errors |
+| Unknown executor selections | Typos and missing participants are rejected |
+| `output_from=[], intermediate_output_from=[]` | Both explicit selections are empty |
+
+Compatibility aliases such as `output_executors` emit deprecation warnings where supported. New samples and
+applications should use `output_from` and `intermediate_output_from`.
+
+When a workflow is wrapped with `workflow.as_agent()`, Workflow Output becomes normal agent text content. Intermediate
+Output becomes `text_reasoning` content, so `AgentResponse.text` remains focused on the caller-facing answer while
+callers can still inspect progress or supporting work from the response messages.
+
 ### parallelism
 
 | Sample                               | File                                                                                                         | Concepts                                                             |
@@ -174,7 +212,7 @@ 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
-- "complete" publishes the final output event (type='output')
+- "complete" publishes the Workflow Output event (`type='output'`)
   These may appear in event streams (executor_invoked/executor_completed). They're analogous to
   concurrent’s dispatcher and aggregator and can be ignored if you only care about agent activity.
 

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

@@ -54,11 +54,11 @@ async def main() -> None:
         credential=AzureCliCredential(),
     )
 
-    # intermediate_outputs=True: Enable intermediate outputs to observe the conversation as it unfolds
-    # (Intermediate outputs will be emitted as WorkflowOutputEvent events)
+    # Mark participant responses as intermediate so workflow.as_agent() maps
+    # them to text_reasoning content while the final answer remains normal text.
     workflow = GroupChatBuilder(
         participants=[researcher, writer],
-        intermediate_outputs=True,
+        intermediate_output_from=[researcher, writer],
         orchestrator_agent=Agent(
             client=_orch_client,
             name="Orchestrator",

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

@@ -72,11 +72,11 @@ async def main() -> None:
 
     print("\nBuilding Magentic Workflow...")
 
-    # intermediate_outputs=True: Enable intermediate outputs to observe the conversation as it unfolds
-    # (Intermediate outputs will be emitted as WorkflowOutputEvent events)
+    # Mark participant responses as intermediate so workflow.as_agent() maps
+    # them to text_reasoning content while the final answer remains normal text.
     workflow = MagenticBuilder(
         participants=[researcher_agent, coder_agent],
-        intermediate_outputs=True,
+        intermediate_output_from=[researcher_agent, coder_agent],
         manager_agent=manager_agent,
         max_round_count=10,
         max_stall_count=3,

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

@@ -77,9 +77,9 @@ async def main() -> None:
 
     Note:
     `workflow.as_agent()` returns ONLY the final agent's response (the "answer") — the prior agents' work
-    is not included in the response. To observe intermediate agents while running as an agent, build with
-    `SequentialBuilder(participants=[...], intermediate_outputs=True)`; the intermediate replies are then
-    surfaced as `data` events and merged into the AgentResponse.
+    is not included in the response. To preserve earlier participant replies while running as an agent, build with
+    `SequentialBuilder(participants=[...], intermediate_output_from=[writer])`; intermediate workflow events become
+    `text_reasoning` content on the AgentResponse, while `.text` remains terminal-output only.
     """
 
 

python/samples/03-workflows/control-flow/intermediate_vs_terminal_outputs.py

@@ -0,0 +1,156 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import (
+    Message,
+    WorkflowBuilder,
+    WorkflowContext,
+    WorkflowExecutor,
+    executor,
+)
+from typing_extensions import Never
+
+"""
+Sample: Workflow Output vs Intermediate Output labeling
+
+What this sample shows
+- How ``WorkflowBuilder(output_from=[...])`` designates which executors emit
+  Workflow Output.
+- How ``WorkflowBuilder(intermediate_output_from=[...])`` designates which executor
+  yields surface as Intermediate Output (``type='intermediate'`` events).
+- How unlisted executor yields are hidden from caller-facing output/intermediate
+  events in explicit designation mode.
+- How the same workflow wrapped via ``workflow.as_agent()`` translates intermediate
+  events to ``text_reasoning`` content so existing ``.text`` accessors keep
+  returning Workflow Output only.
+- How a sub-workflow embedded via ``WorkflowExecutor`` bubbles its intermediate
+  emissions up through the parent's event stream, attributed to the
+  ``WorkflowExecutor`` id rather than the child's internal executor ids.
+
+The output selection contract:
+- Compatibility mode: when neither ``output_from`` nor ``intermediate_output_from``
+  is provided, every ``yield_output`` produces Workflow Output and a deprecation
+  warning points to explicit selection.
+- Explicit selection mode: provide either ``output_from`` or
+  ``intermediate_output_from``. Executors selected by ``output_from`` emit Workflow Output
+  (``type='output'`` events); executors selected by ``intermediate_output_from`` emit
+  Intermediate Output (``type='intermediate'`` events); unselected executor yields are
+  hidden from the stream and ``WorkflowRunResult`` output accessors.
+- Validation: explicit selections must not both be empty; duplicate executor entries,
+  overlap between Workflow Output and Intermediate Output, unknown executors, invalid
+  literals, and selected executors without workflow output types are rejected.
+
+Prerequisites
+- No external services required.
+"""
+
+
+@executor(id="planner")
+async def planner(messages: list[Message], ctx: WorkflowContext[list[Message], str]) -> None:
+    """Intermediate step: emits a visible progress note, then forwards."""
+    prompt = messages[0].text if messages else ""
+    await ctx.yield_output(f"plan: starting work on '{prompt}'")
+    await ctx.send_message(messages)
+
+
+@executor(id="researcher")
+async def researcher(messages: list[Message], ctx: WorkflowContext[list[Message], str]) -> None:
+    """Intermediate step: emits visible progress, then forwards."""
+    prompt = messages[0].text if messages else ""
+    await ctx.yield_output(f"research: gathering data for '{prompt}'")
+    await ctx.send_message(messages)
+
+
+@executor(id="answerer")
+async def answerer(messages: list[Message], ctx: WorkflowContext[Never, str]) -> None:
+    """Designated Workflow Output: emits the workflow's answer."""
+    prompt = messages[0].text if messages else ""
+    await ctx.yield_output(f"final answer to '{prompt}': 42")
+
+
+async def main() -> None:
+    # Build with explicit Workflow Output and Intermediate Output selections.
+    # `answerer` produces type='output' events; planner and researcher produce
+    # visible type='intermediate' events.
+    workflow = (
+        WorkflowBuilder(
+            start_executor=planner,
+            output_from=[answerer],
+            intermediate_output_from=[planner, researcher],
+        )
+        .add_edge(planner, researcher)
+        .add_edge(researcher, answerer)
+        .build()
+    )
+
+    initial = [Message(role="user", contents=["life, the universe, and everything"])]
+
+    print("=== Streaming events (workflow.run(stream=True)) ===")
+    async for event in workflow.run(initial, stream=True):
+        if event.type == "intermediate":
+            print(f"  [intermediate] {event.executor_id}: {event.data}")
+        elif event.type == "output":
+            print(f"  [output]       {event.executor_id}: {event.data}")
+
+    # WorkflowRunResult.get_outputs() filters to type='output' events, so it
+    # only returns the selected Workflow Output yield.
+    print("\n=== Non-streaming run().get_outputs() ===")
+    result = await workflow.run(initial)
+    print(f"  outputs: {result.get_outputs()}")
+
+    # When the same workflow is wrapped via as_agent(), intermediate events
+    # surface as ``text_reasoning`` content; Workflow Output surfaces as
+    # ``text`` content. Existing callers reading ``response.text`` get only
+    # the selected Workflow Output because ``.text`` filters to text content.
+    print("\n=== workflow.as_agent() -- intermediate -> text_reasoning content ===")
+    agent = workflow.as_agent("planner-agent")
+    response = await agent.run("life, the universe, and everything")
+    print(f"  response.text (Workflow Output only): {response.text!r}")
+    reasoning = " | ".join(c.text for m in response.messages for c in m.contents if c.type == "text_reasoning")
+    print(f"  reasoning content (intermediates): {reasoning!r}")
+
+    # Embed the same workflow as a node inside a larger workflow via WorkflowExecutor.
+    # Child intermediate emissions are forwarded to the parent's event stream with the
+    # WorkflowExecutor's id as the source, so outer callers don't have to know the
+    # child's internal executor layout. The 'intermediate' label is preserved across
+    # the boundary regardless of how the parent designates the WorkflowExecutor.
+    print("\n=== Embedding as a sub-workflow -- intermediates bubble up ===")
+    sub = WorkflowExecutor(workflow, id="sub")
+
+    @executor(id="parent_sink")
+    async def parent_sink(message: str, ctx: WorkflowContext[Never, str]) -> None:
+        await ctx.yield_output(message)
+
+    parent_workflow = WorkflowBuilder(start_executor=sub, output_from=[parent_sink]).add_edge(sub, parent_sink).build()
+
+    async for event in parent_workflow.run(initial, stream=True):
+        if event.type == "intermediate":
+            print(f"  [intermediate] {event.executor_id}: {event.data}")
+        elif event.type == "output":
+            print(f"  [output]       {event.executor_id}: {event.data}")
+
+    """
+    Sample output:
+
+    === Streaming events (workflow.run(stream=True)) ===
+      [intermediate] planner: plan: starting work on 'life, the universe, and everything'
+      [intermediate] researcher: research: gathering data for 'life, the universe, and everything'
+      [output]       answerer: final answer to 'life, the universe, and everything': 42
+
+    === Non-streaming run().get_outputs() ===
+      outputs: ["final answer to 'life, the universe, and everything': 42"]
+
+    === workflow.as_agent() -- intermediate -> text_reasoning content ===
+      response.text (Workflow Output only): "final answer to 'life, the universe, and everything': 42"
+      reasoning content (intermediates): "plan: starting work on ... | research: gathering data for ..."
+
+    === Embedding as a sub-workflow -- intermediates bubble up ===
+      [intermediate] sub: plan: starting work on 'life, the universe, and everything'
+      [intermediate] sub: research: gathering data for 'life, the universe, and everything'
+      [output]       parent_sink: final answer to 'life, the universe, and everything': 42
+    """
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/03-workflows/human-in-the-loop/agents_with_approval_requests.py

@@ -248,7 +248,7 @@ async def main() -> None:
 
     # Build the workflow
     workflow = (
-        WorkflowBuilder(start_executor=email_processor, output_executors=[conclude_workflow])
+        WorkflowBuilder(start_executor=email_processor, output_from=[conclude_workflow])
         .add_edge(email_processor, email_writer_agent)
         .add_edge(email_writer_agent, conclude_workflow)
         .build()

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

@@ -81,6 +81,41 @@ from agent_framework.orchestrations import (
 
 ## Tips
 
+**Participant output selection**: Orchestration builders use participant-oriented names for Workflow Output selection.
+Use `output_from=[...]` when participant responses should be Workflow Output (`type='output'` events), and
+`intermediate_output_from=[...]` when participant responses should be Intermediate Output (`type='intermediate'`
+events). `output_from` is an allow-list for Workflow Output, not a routing rule for every other participant output.
+Unselected participant responses are hidden unless `intermediate_output_from` selects them.
+
+| Selection | Workflow Output | Intermediate Output | Hidden payloads |
+| --- | --- | --- | --- |
+| Omit both selections | Builder default Workflow Output contract | None | Builder-specific non-output participant payloads |
+| `output_from="all"` | Every output-capable participant | None | None |
+| `output_from=[writer]` | Only `writer` | None | All other participant payloads |
+| `output_from=[writer], intermediate_output_from="all_other"` | Only `writer` | Every output-capable participant not selected by `output_from` | None |
+| `intermediate_output_from="all_other"` | None, except builder-internal default output executors where applicable | Every output-capable participant | Builder-internal plumbing payloads |
+| `output_from=[], intermediate_output_from="all_other"` | None, except builder-internal default output executors where applicable | Every output-capable participant | Builder-internal plumbing payloads |
+| `output_from=[writer], intermediate_output_from=[researcher, reviewer]` | Only `writer` | `researcher` and `reviewer` | Any other participant payloads |
+
+Invalid selections fail at construction or build time:
+
+| Invalid selection | Why it fails |
+| --- | --- |
+| `output_from="all_other"` | `"all_other"` is only valid for `intermediate_output_from` |
+| `intermediate_output_from="all"` | `"all"` is only valid for `output_from` |
+| The same participant in both selections | One payload cannot be both Workflow Output and Intermediate Output |
+| Duplicate participant selections | Duplicates are treated as configuration errors |
+| Unknown participant selections | Typos and missing participants are rejected |
+| `output_from=[], intermediate_output_from=[]` | Both explicit selections are empty |
+
+By default, Sequential keeps the last participant as Workflow Output. Concurrent, GroupChat, and Magentic keep their
+synthetic aggregator/orchestrator/manager executors as Workflow Output, while participant responses stay hidden unless
+selected. Handoff keeps participants as Workflow Output by default.
+
+When an orchestration workflow is exposed via `workflow.as_agent()`, Workflow Output becomes normal text content in
+the `AgentResponse`; Intermediate Output becomes `text_reasoning` content. This preserves `.text` while making
+selected progress available for callers that inspect message contents.
+
 **Magentic checkpointing tip**: Treat `MagenticBuilder.participants` keys as stable identifiers. When resuming from a checkpoint, the rebuilt workflow must reuse the same participant names; otherwise the checkpoint cannot be applied and the run will fail fast.
 
 **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.
@@ -90,7 +125,7 @@ from agent_framework.orchestrations import (
 **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
-- `complete` publishes the final output event (type='output')
+- `complete` publishes the Workflow Output event (`type='output'`)
 
 These may appear in event streams (executor_invoked/executor_completed). They're analogous to concurrent's dispatcher and aggregator and can be ignored if you only care about agent activity.
 

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

@@ -78,13 +78,14 @@ async def main() -> None:
     # Build the group chat workflow
     # termination_condition: stop after 4 assistant messages
     # (The agent orchestrator will intelligently decide when to end before this limit but just in case)
-    # intermediate_outputs=True: Enable intermediate outputs to observe the conversation as it unfolds
-    # (Intermediate outputs will be emitted as WorkflowOutputEvent events)
+    # Mark participant responses as intermediate so the stream shows the
+    # conversation as it unfolds while the orchestrator's transcript remains the
+    # terminal workflow output.
     workflow = (
         GroupChatBuilder(
             participants=[researcher, writer],
             termination_condition=lambda messages: sum(1 for msg in messages if msg.role == "assistant") >= 4,
-            intermediate_outputs=True,
+            intermediate_output_from=[researcher, writer],
             orchestrator_agent=orchestrator_agent,
         )
         # Set a hard termination condition: stop after 4 assistant messages
@@ -102,7 +103,7 @@ async def main() -> None:
     # Keep track of the last response to format output nicely in streaming mode
     last_response_id: str | None = None
     async for event in workflow.run(task, stream=True):
-        if event.type == "output":
+        if event.type in ("intermediate", "output"):
             data = event.data
             if isinstance(data, AgentResponseUpdate):
                 rid = data.response_id

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

@@ -219,13 +219,16 @@ Share your perspective authentically. Feel free to:
     )
 
     # termination_condition: stop after 10 assistant messages
-    # intermediate_outputs=True: Enable intermediate outputs to observe the conversation as it unfolds
-    # (Intermediate outputs will be emitted as WorkflowOutputEvent events)
+    # Mark participant responses as intermediate so the stream shows the
+    # conversation as it unfolds while the orchestrator's transcript remains the
+    # terminal workflow output.
     workflow = (
         GroupChatBuilder(
             participants=[farmer, developer, teacher, activist, spiritual_leader, artist, immigrant, doctor],
             termination_condition=lambda messages: sum(1 for msg in messages if msg.role == "assistant") >= 10,
-            intermediate_outputs=True,
+            intermediate_output_from=[
+                "all",
+            ],
             orchestrator_agent=moderator,
         )
         .with_termination_condition(lambda messages: sum(1 for msg in messages if msg.role == "assistant") >= 10)
@@ -254,7 +257,7 @@ Share your perspective authentically. Feel free to:
     # Keep track of the last response to format output nicely in streaming mode
     last_response_id: str | None = None
     async for event in workflow.run(f"Please begin the discussion on: {topic}", stream=True):
-        if event.type == "output":
+        if event.type in ("intermediate", "output"):
             data = event.data
             if isinstance(data, AgentResponseUpdate):
                 rid = data.response_id

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

@@ -96,13 +96,14 @@ async def main() -> None:
     # This will end the conversation after the expert has spoken 2 times (one iteration loop)
     # Note: it's possible that the expert gets it right the first time and the other participants
     # have nothing to add, but for demo purposes we want to see at least one full round of interaction.
-    # intermediate_outputs=True: Enable intermediate outputs to observe the conversation as it unfolds
-    # (Intermediate outputs will be emitted as WorkflowOutputEvent events)
+    # Mark participant responses as intermediate so the stream shows the
+    # conversation as it unfolds while the orchestrator's transcript remains the
+    # terminal workflow output.
     workflow = (
         GroupChatBuilder(
             participants=[expert, verifier, clarifier, skeptic],
             termination_condition=lambda conversation: len(conversation) >= 6,
-            intermediate_outputs=True,
+            intermediate_output_from=[expert, verifier, clarifier, skeptic],
             selection_func=round_robin_selector,
         )
         # Set a hard termination condition: stop after 6 messages (user task + one full rounds + 1)
@@ -123,7 +124,7 @@ async def main() -> None:
     # Keep track of the last response to format output nicely in streaming mode
     last_response_id: str | None = None
     async for event in workflow.run(task, stream=True):
-        if event.type == "output":
+        if event.type in ("intermediate", "output"):
             data = event.data
             if isinstance(data, AgentResponseUpdate):
                 rid = data.response_id

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

@@ -88,11 +88,12 @@ async def main() -> None:
 
     print("\nBuilding Magentic Workflow...")
 
-    # intermediate_outputs=True: Enable intermediate outputs to observe the conversation as it unfolds
-    # (Intermediate outputs will be emitted as WorkflowOutputEvent events)
+    # Mark participant responses as intermediate so the stream shows the
+    # conversation as it unfolds while the manager's final answer remains the
+    # terminal workflow output.
     workflow = MagenticBuilder(
         participants=[researcher_agent, coder_agent],
-        intermediate_outputs=True,
+        intermediate_output_from=[researcher_agent, coder_agent],
         manager_agent=manager_agent,
         max_round_count=10,
         max_stall_count=3,
@@ -115,7 +116,7 @@ async def main() -> None:
     last_response_id: str | None = None
     output_event: WorkflowEvent | None = None
     async for event in workflow.run(task, stream=True):
-        if event.type == "output" and isinstance(event.data, AgentResponseUpdate):
+        if event.type in ("intermediate", "output") and isinstance(event.data, AgentResponseUpdate):
             response_id = event.data.response_id
             if response_id != last_response_id:
                 if last_response_id is not None:

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

@@ -55,7 +55,7 @@ async def process_event_stream(stream: AsyncIterable[WorkflowEvent]) -> dict[str
         if event.type == "request_info" and event.request_type is MagenticPlanReviewRequest:
             requests[event.request_id] = cast(MagenticPlanReviewRequest, event.data)
 
-        if event.type == "output":
+        if event.type in ("intermediate", "output"):
             data = event.data
             if isinstance(data, AgentResponseUpdate):
                 rid = data.response_id
@@ -129,13 +129,14 @@ async def main() -> None:
 
     print("\nBuilding Magentic Workflow with Human Plan Review...")
 
-    # enable_plan_review=True: Request human input for plan review
-    # intermediate_outputs=True: Enable intermediate outputs to observe the conversation as it unfolds
-    # (Intermediate outputs will be emitted as WorkflowOutputEvent events)
+    # enable_plan_review=True: Request human input for plan review.
+    # Mark participant responses as intermediate so the stream shows the
+    # conversation as it unfolds while the manager's final answer remains the
+    # terminal workflow output.
     workflow = MagenticBuilder(
         participants=[researcher_agent, analyst_agent],
         enable_plan_review=True,
-        intermediate_outputs=True,
+        intermediate_output_from=[researcher_agent, analyst_agent],
         manager_agent=manager_agent,
         max_round_count=10,
         max_stall_count=1,

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

@@ -66,13 +66,13 @@ async def main() -> None:
     workflow = SequentialBuilder(
         participants=[writer, translator, reviewer],
         chain_only_agent_responses=True,
-        intermediate_outputs=True,
+        intermediate_output_from=[writer, translator],
     ).build()
 
     # 3) Run and collect outputs
     last_agent: str | None = None
     async for event in workflow.run("Write a tagline for a budget-friendly eBike.", stream=True):
-        if event.type == "output" and isinstance(event.data, AgentResponseUpdate):
+        if event.type in ("intermediate", "output") and isinstance(event.data, AgentResponseUpdate):
             if event.data.author_name != last_agent:
                 last_agent = event.data.author_name
                 print()