Python: Add workflow composition via add_workflow() API

[moonbox3]

Motivation and Context

• Implements WorkflowBuilder.add_workflow() for composing high-level orchestration patterns (ConcurrentBuilder, SequentialBuilder) with simple logical IDs
• Adds _to_builder() to ConcurrentBuilder and SequentialBuilder (and others) for extracting internal graph structure
• Enables logical ID resolution in add_edge() and set_start_executor() (e.g., add_edge("analysis", "summary") automatically wires exit to entry points)
• Enhances type validation to fall back to workflow_output_types when output_types is empty, supporting composed workflows with terminal executors

Example

analysis = ConcurrentBuilder().participants([agent1, agent2])
summary = SequentialBuilder().participants([summarizer])

workflow = (
    WorkflowBuilder()
    .add_workflow(analysis, id="analysis")
    .add_workflow(summary, id="summary")
    .add_edge("analysis", "summary")  # Resolves to analysis/aggregator -> summary/input-conversation
    .set_start_executor("analysis")
    .build()
)

Design decisions located in attached design doc.

Note on other builders:

_to_builder() has not been added to GroupChatBuilder, HandoffBuilder, or MagenticBuilder yet. These builders have more complex internal structures where entry/exit points are less straightforward. We want to validate the API design with ConcurrentBuilder and SequentialBuilder first before extending to these patterns. This is tracked as Phase 3 in the design doc.

Description

• Addresses Workflow add additional steps after build #1795
• Supersedes Python: [DRAFT] workflow composibility design #2366

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework/_workflows
_concurrent.py	193	29	84%	53, 62–63, 71–72, 91–92, 97, 102, 127, 132, 137–138, 144, 166, 176, 183, 354, 357, 385, 441, 453, 492, 494–495, 497, 520, 524, 538
_edge.py	251	37	85%	41, 63–64, 66, 161, 191, 428, 437, 465–466, 471, 475–480, 482–484, 609, 742, 749–751, 798, 826, 852, 906, 920, 958–962, 964, 971
_executor.py	155	9	94%	209, 338, 353, 355, 368, 371, 479, 484, 494
_sequential.py	113	13	88%	74, 168, 188, 199, 205, 242, 244–245, 247, 270, 274, 288, 295
_validation.py	147	6	95%	85, 132, 153, 252, 333, 336
_workflow_builder.py	373	72	80%	276, 616, 718, 837, 840, 845, 848–850, 857, 860–864, 866, 928, 1006, 1009, 1069–1070, 1266–1270, 1272, 1275, 1298, 1300–1303, 1305, 1307, 1311–1312, 1337–1339, 1344–1345, 1349–1350, 1354–1358, 1360–1361, 1365–1366, 1371–1372, 1394, 1398, 1444, 1457–1464, 1466, 1469, 1471–1473, 1481
TOTAL	17608	2706	84%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
3173	213 💤	0 ❌	0 🔥	1m 5s ⏱️

[Copilot]

Pull request overview

This PR implements workflow composition via a new add_workflow() API that enables combining high-level orchestration patterns (ConcurrentBuilder, SequentialBuilder) with simple logical IDs. This addresses issue #1795 by allowing users to extend and compose high-level builders without writing custom orchestrator executors.

Changes:

• Added add_workflow() method to WorkflowBuilder for composing orchestration patterns
• Implemented logical ID resolution in edge methods (add_edge(), set_start_executor()) to automatically wire entry/exit points
• Enhanced type validation to support terminal executors using yield_output() in composed workflows

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
python/packages/core/agent_framework/_workflows/_workflow_builder.py	Implements core add_workflow() method with logical ID resolution, prefixing logic, and workflow mapping tracking
python/packages/core/agent_framework/_workflows/_concurrent.py	Adds _to_builder() method to extract internal WorkflowBuilder structure for composition
python/packages/core/agent_framework/_workflows/_sequential.py	Adds _to_builder() method to extract internal WorkflowBuilder structure for composition
python/packages/core/agent_framework/_workflows/_executor.py	Adds _clone_with_id() method for creating executor copies with prefixed IDs during composition
python/packages/core/agent_framework/_workflows/_edge.py	Adds _with_prefix() method to all edge group types for ID prefixing during composition
python/packages/core/agent_framework/_workflows/_validation.py	Enhances type validation to fall back to workflow_output_types when connecting terminal executors
python/packages/core/tests/workflow/test_workflow_composition.py	Comprehensive unit tests covering composition functionality, ID resolution, and edge cases
python/samples/getting_started/workflows/composition/workflow_composition.py	Demonstrates API usage with two examples: simple composition and pre/post-processing
docs/decisions/00XX-workflow-composability.md	Detailed design document explaining motivation, API design, alternatives considered, and implementation phases

[dmytrostruk]

nit: Don't forget to update document number instead of 00XX.

[dmytrostruk]

nit: I think this section is unnecessary, but feel free to decide.

[dmytrostruk]

nit: Maybe worth type alias.