Python: Docs: Update for intermediate vs terminal workflow/orchestration outputs (PR #5623)

[moonbox3]

Context

PR #5623 (merged 2026-05-19) reshapes how workflows and orchestrations distinguish terminal answers from observational/progress emissions, renames the relevant builder kwargs, and adds new accessors. The docs at microsoft/semantic-kernel (agent-framework/ path) need a refresh to match.

This issue is scoped to docs only. No code changes.

PR: #5623

Summary of what changed in code

1. New event discriminator. WorkflowEvent.type == "intermediate" joins "output" (terminal). Legacy "data" is now a deprecated alias for "intermediate".
2. Build-time per-executor designation. WorkflowBuilder(final_output_from=[...], intermediate_output_from=[...]). Designation is fixed at build time. ctx.yield_output(...) has no per-emission flag, and an executor cannot vary the label per yield.
3. New accessor. WorkflowRunResult.get_intermediate_outputs() alongside get_outputs().
4. workflow.as_agent() boundary. Now forwards both output and intermediate events (explicit allowlist AGENT_FORWARDED_EVENT_TYPES). Intermediates render as text_reasoning content; existing .text still returns only the terminal answer.
5. WorkflowExecutor (sub-workflow embedding). Child intermediate emissions now bubble up through the parent's event stream, attributed to the WorkflowExecutor's own id (preserves encapsulation), and keep the intermediate label regardless of how the parent designates the WorkflowExecutor.
6. Builder kwarg renames:
   • Core (agent_framework): output_executors -> final_output_from, intermediate_executors -> intermediate_output_from. Old names still accepted with DeprecationWarning. Supplying both old and new raises TypeError. Serialized form (Workflow.to_dict()) intentionally keeps the legacy wire keys output_executors / intermediate_executors for checkpoint compat.
   • Orchestrations (agent_framework_orchestrations): output_participants -> final_output_from, intermediate_participants -> intermediate_output_from. Clean break, no shim (pre-1.0 package).
7. Orchestration default-final + intermediate interaction. HandoffBuilder defaults final_output_from to every participant; SequentialBuilder defaults to the last participant. Supplying intermediate_output_from=[X] now implicitly demotes X out of the default-final set (previously raised an overlap error).
8. New canonical sample: python/samples/03-workflows/control-flow/intermediate_vs_terminal_outputs.py walks explicit designation, streaming consumption, WorkflowRunResult accessors, as_agent() translation, and sub-workflow embedding.

Docs files to update

Repo: microsoft/semantic-kernel, path: agent-framework/.

File	What to change
workflows/events.md	Document the "intermediate" discriminator alongside "output". Mark "data" as a deprecated alias. Show how to filter on each type from a streaming run.
workflows/executors.md	Add a section on per-executor designation via WorkflowBuilder(final_output_from=[...], intermediate_output_from=[...]). State the build-time invariant: ctx.yield_output has no per-emission flag, designation does not vary per yield.
workflows/as-agents.md	Document that .as_agent() now forwards both output and intermediate events. Intermediates render as text_reasoning content; .text still returns only the terminal answer.
workflows/advanced/sub-workflows.md	Update the Output Behavior section: child intermediate emissions pipe through the parent stream, attributed to the embedding WorkflowExecutor id, and retain the intermediate label regardless of how the parent designates the WorkflowExecutor.
workflows/advanced/agent-executor.md	Document WorkflowRunResult.get_intermediate_outputs() next to existing get_outputs() usage.
workflows/functional.md	Same: add get_intermediate_outputs() next to get_outputs().
workflows/declarative.md	Same: add get_intermediate_outputs() next to get_outputs().
workflows/orchestrations/handoff.md	Document the default: final_output_from defaults to all participants. Show that intermediate_output_from=[X] implicitly demotes X from the default-final set (no overlap error). Use the new kwarg names throughout.
workflows/orchestrations/sequential.md	Same pattern: default is last participant; intermediate designation demotes from the default. Use the new kwarg names.
workflows/orchestrations/magentic.md	Replace any remaining intermediate_outputs=True style references with the new builder-time designation model (final_output_from, intermediate_output_from).
workflows/orchestrations/concurrent.md and workflows/orchestrations/group-chat.md	Sweep for output_participants / intermediate_participants and rename to final_output_from / intermediate_output_from. (No deprecation shim in orchestrations.)
workflows/orchestrations/index.md	If it summarizes the builder kwargs, update the names.
integrations/ag-ui/workflows.md	Where it discusses workflow_output custom events, clarify that both terminal and intermediate outputs flow through, and that intermediates surface as text_reasoning content on the agent boundary.

Renames to sweep across all docs

• output_executors -> final_output_from (core; old name deprecated)
• intermediate_executors -> intermediate_output_from (core; old name deprecated)
• output_participants -> final_output_from (orchestrations; clean break)
• intermediate_participants -> intermediate_output_from (orchestrations; clean break)

Things to call out explicitly in the prose

• Per-executor / per-participant designation is build-time. There is no ctx.yield_intermediate(...) API; the same ctx.yield_output(...) call is labeled based on the builder's designation list.
• Workflow.to_dict() keeps the legacy wire keys output_executors / intermediate_executors for checkpoint compatibility. This asymmetry is intentional. If checkpoint format is documented anywhere, do not "fix" it.
• For orchestrations, intermediate_output_from is usable on its own and implicitly demotes listed participants from the default-final set. The earlier overlap-rejection behavior was a bug.

Reference material for the docs agent

• PR: Python: Improve the handling of intermediate outputs for workflows and orchestrations #5623
• Canonical sample: python/samples/03-workflows/control-flow/intermediate_vs_terminal_outputs.py
• Orchestrations sample sweep: python/samples/03-workflows/orchestrations/*.py (already updated to the new kwarg names; use as authoritative examples)
• Docstrings on ctx.yield_output, WorkflowEvent.output, WorkflowEvent.intermediate carry the per-executor invariant.

Out of scope

• Code changes in microsoft/agent-framework.
• Migrating any checkpoint payloads.
• Adding a ctx.yield_intermediate API or any per-emission labeling.

[moonbox3]

Complete.