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

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/.

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.