Python: Adding support for nested workflows by alliscode · Pull Request #460 · microsoft/agent-framework

Ben Thomas (alliscode) · 2025-08-20T21:30:50Z

Add Sub-Workflows Support to Agent Framework

Summary

This PR introduces hierarchical workflow composition through sub-workflows, enabling workflows to execute other
workflows as executors within their execution graph. Sub-workflows can make external requests that are
automatically routed to parent workflows for interception and handling.

Key Features

Hierarchical Workflow Composition: WorkflowExecutor class enables embedding workflows as executors within
other workflows
Request Interception: Parent workflows can intercept sub-workflow requests using the @intercepts_request
decorator
Automatic Message Routing: SubWorkflowRequestInfo messages are automatically routed between parent and
sub-workflows
External Request Handling: Seamless integration with existing RequestInfoExecutor for external data
requests
Type-Safe Response Correlation: RequestResponse[TRequest, TResponse] pattern with automatic correlation
tracking

Implementation Details

Core Components

WorkflowExecutor: Wraps a workflow to make it behave as an executor, enabling hierarchical composition
SubWorkflowRequestInfo/SubWorkflowResponse: Message types for routing requests and responses between
workflow layers
@intercepts_request decorator: Allows parent workflows to intercept and handle specific request types from
sub-workflows
RequestResponse pattern: Type-safe response handling with .handled() and .forward() methods

Message Flow

Sub-Workflow → SubWorkflowRequestInfo → Parent Workflow Interceptor
↓ (if not intercepted)
RequestInfoExecutor → External Handler
↓
SubWorkflowResponse → Sub-Workflow

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
I didn't break anyone 😄

…oExecutor, going to make a change to remove that restrivtion.

…b-workflows.

Copilot

Pull Request Overview

This PR introduces hierarchical workflow composition through sub-workflows, enabling workflows to execute other workflows as executors within their execution graph. The implementation includes support for external request interception, where parent workflows can intercept and handle sub-workflow requests before they reach external services.

Key changes:

Sub-workflow execution: New WorkflowExecutor class wraps workflows to make them behave as executors
Request interception: @intercepts_request decorator allows parent workflows to conditionally handle or forward requests from sub-workflows
Message routing infrastructure: Automatic routing between parent and sub-workflows via SubWorkflowRequestInfo and SubWorkflowResponse message types

Reviewed Changes

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

Show a summary per file

File	Description
`subflow_design.md`	Comprehensive design document analyzing 6 implementation approaches for sub-workflows
`python/samples/getting_started/workflow/`	Three sample files demonstrating basic sub-workflows, request interception, and simple composition patterns
`python/packages/workflow/tests/`	Unit tests covering sub-workflow functionality, request interception, and edge cases
`python/packages/workflow/examples/`	Complete working example showing email validation with domain checking
`agent_framework_workflow/_executor.py`	Core implementation of `WorkflowExecutor`, request interception decorators, and message types
`agent_framework_workflow/_runner.py`	Message routing logic for handling sub-workflow requests and responses
`agent_framework_workflow/_workflow.py`	Workflow modifications to support RequestInfoExecutor discovery
`agent_framework_workflow/_validation.py`	Validation updates for single-executor workflows and interceptor output types
`docs/design/sub_workflows_guide.md`	Comprehensive user guide with examples and best practices

Comments suppressed due to low confidence (2)

python/packages/workflow/agent_framework_workflow/_executor.py:149

This assignment inside the loop will overwrite the value on each iteration. It should be moved outside the loop: move self.expected_result_count = len(emails) before the for loop.

                # Check additional condition

python/packages/workflow/agent_framework_workflow/_executor.py:140

This field declaration without initialization will cause AttributeError when accessed before being set. Initialize it with a default value: self.expected_result_count: int = 0

                if hasattr(request.data, "__class__") and request.data.__class__.__name__ == request_type:

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Eduard van Valkenburg (eavanvalkenburg) · 2025-08-21T02:23:07Z

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/workflow/agent_framework_workflow
_executor.py	338	58	82%	98, 119, 137, 139, 145, 163, 169, 182, 212, 224, 235, 237–238, 314–315, 324, 328, 386, 542, 548, 561, 563–565, 568, 572, 575, 648–652, 657, 659–662, 666–668, 670, 674, 676–677, 782, 851, 901–902, 905–908, 928, 956–957, 960, 965, 968
_runner.py	224	34	84%	94–96, 98, 149, 208, 230–231, 271–273, 288–292, 296, 300–301, 322–323, 335–336, 347–349, 353, 360–362, 367–368, 397, 416
_typing_utils.py	31	10	67%	18, 30, 38–40, 66, 68, 74–75, 78
_validation.py	306	29	90%	102, 146, 190, 201–202, 207, 229, 236, 331–332, 341, 400, 402, 472, 475, 533, 537, 646–647, 672, 674, 681–682, 685–686, 690–693
_workflow.py	199	34	82%	57, 151, 215, 224–225, 237, 251, 331–333, 366, 386–387, 389–391, 406–408, 416–417, 426–432, 437, 439, 554–556, 558
TOTAL	5085	695	86%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
629	40 💤	0 ❌	0 🔥	12.112s ⏱️

Co-authored-by: Eric Zhu <ekzhu@users.noreply.github.com>

…a subflow with multiple requests in a single super step.

Eric Zhu (ekzhu)

I will clean up and resolve the conflicts.

Eric Zhu (ekzhu) · 2025-08-23T03:11:49Z

I noticed it currently doesn't automatically forward sub-workflow's request info event externally when there is no interceptor or request info executor in the parent workflow. I added a warning for this. What is the reason for not automatically surface the sub workflow's RequestInfoEvent?

agent-framework/python/packages/workflow/agent_framework_workflow/_runner.py

Lines 205 to 211 in c1a4088

    
           logger.warning( 
        
               f"Sub-workflow request of type '{sub_request.data.__class__.__name__}' " 
        
               f"from sub-workflow '{sub_request.sub_workflow_id}' could not be handled: " 
        
               f"no RequestInfoExecutor found in the workflow. Add a RequestInfoExecutor " 
        
               f"to handle external requests or add an @intercepts_request handler." 
        
           )

* Adding design documents and data flow descriptions for sub-workflows * Updating docs. * Sub-workflow implementation microsoft#1. Stuck because of singleton RequestInfoExecutor, going to make a change to remove that restrivtion. * Removed the singleton restriction on RequestInfoExecutor so enable sub-workflows. * Scenarios seem to be working. * Sample improved. * going to have intern add generic response wrappers. * Wrapped responses working. * Non-hardcoded routing is working. * Sample showing external approved and not approved. * Cleaning up. * Updating some samples and user guide. * Removing old design doc. * Cleaning up. * Adding python-package-setup.md back. * Update python/packages/workflow/agent_framework_workflow/_executor.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update python/packages/workflow/agent_framework_workflow/_validation.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Removing prints. * Fixing lint and type issues. * Fixing lint and type issues. * Update python/packages/workflow/agent_framework_workflow/_executor.py Co-authored-by: Eric Zhu <ekzhu@users.noreply.github.com> * Adding type hints to intercepts decorator. * Removing unused files. * Fixing issue with sample 5 groupchat with hil. * Removing redundent samples. * Updates to ensure no conflicting request interceptors and to support a subflow with multiple requests in a single super step. * Fixing pypi errors. * clean up samples * update samples to make it more clear * warning for unhandled request info from sub workflow * add logger info --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Eric Zhu <ekzhu@users.noreply.github.com>

Ben Thomas (alliscode) added 15 commits August 15, 2025 15:56

Adding design documents and data flow descriptions for sub-workflows

bb9d06b

Updating docs.

c1d50b1

Sub-workflow implementation #1. Stuck because of singleton RequestInf…

bd23068

…oExecutor, going to make a change to remove that restrivtion.

Removed the singleton restriction on RequestInfoExecutor so enable su…

5955c9a

…b-workflows.

Scenarios seem to be working.

eb8723b

Sample improved.

09d5da6

going to have intern add generic response wrappers.

64383d7

Wrapped responses working.

2d02fc2

Non-hardcoded routing is working.

89d2bc5

Sample showing external approved and not approved.

7fee8ba

Cleaning up.

ecd3e5e

Updating some samples and user guide.

bb02c82

Removing old design doc.

78cebba

Cleaning up.

be677ee

Merging from main

e9fd564

Copilot AI review requested due to automatic review settings August 20, 2025 21:30

Eduard van Valkenburg (eavanvalkenburg) added documentation Usage: [Issues, PRs], Target: documentation in the code base and learn docs python Usage: [Issues, PRs], Target: Python labels Aug 20, 2025

Ben Thomas (alliscode) changed the title ~~bentho/sub workflows~~ Adding support for nested workflows Aug 20, 2025

github-actions Bot changed the title ~~Adding support for nested workflows~~ Python: bentho/sub workflows Aug 20, 2025

Copilot AI reviewed Aug 20, 2025

View reviewed changes

Comment thread python/packages/workflow/agent_framework_workflow/_workflow_context.py Outdated

Comment thread python/packages/workflow/agent_framework_workflow/_validation.py Outdated

Comment thread python/packages/workflow/agent_framework_workflow/_executor.py Outdated

Ben Thomas (alliscode) and others added 4 commits August 20, 2025 14:35

Adding python-package-setup.md back.

e267374

Update python/packages/workflow/agent_framework_workflow/_executor.py

f466a0e

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update python/packages/workflow/agent_framework_workflow/_validation.py

51aebb8

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Removing prints.

f54c1e8

Eric Zhu (ekzhu) reviewed Aug 21, 2025

View reviewed changes

Ben Thomas (alliscode) added 2 commits August 20, 2025 18:49

Fixing lint and type issues.

dd84e38

Fixing lint and type issues.

ff09a5c

Ben Thomas (alliscode) changed the title ~~Python: bentho/sub workflows~~ Python: Adding support for nested workflows Aug 21, 2025

Ben Thomas (alliscode) and others added 11 commits August 21, 2025 10:02

Merging from updates in main.

2210550

Update python/packages/workflow/agent_framework_workflow/_executor.py

3ee8f93

Co-authored-by: Eric Zhu <ekzhu@users.noreply.github.com>

Adding type hints to intercepts decorator.

cc21378

Adding type hints to intercepts decorator.

73f7887

Removing unused files.

3eb8a8e

Fixing issue with sample 5 groupchat with hil.

1f9fc0f

Removing redundent samples.

367b188

Merge branch 'main' into bentho/sub-workflows

39edc97

Updates to ensure no conflicting request interceptors and to support …

9958add

…a subflow with multiple requests in a single super step.

Merge branch 'main' into bentho/sub-workflows

e85a692

Fixing pypi errors.

2c1c531

Eric Zhu (ekzhu) approved these changes Aug 22, 2025

View reviewed changes

Eric Zhu (ekzhu) reviewed Aug 22, 2025

View reviewed changes

Jacob Alber (lokitoth) approved these changes Aug 22, 2025

View reviewed changes

Eric Zhu (ekzhu) added 3 commits August 22, 2025 17:31

Merge branch 'main' into bentho/sub-workflows

cef4cab

clean up samples

fbcba5e

update samples to make it more clear

dd4632c

Eric Zhu (ekzhu) enabled auto-merge August 23, 2025 02:50

Eric Zhu (ekzhu) disabled auto-merge August 23, 2025 02:50

warning for unhandled request info from sub workflow

c1a4088

Eric Zhu (ekzhu) enabled auto-merge August 23, 2025 03:12

Eric Zhu (ekzhu) disabled auto-merge August 23, 2025 03:13

add logger info

c6f9ea0

Eric Zhu (ekzhu) enabled auto-merge August 23, 2025 03:19

Eric Zhu (ekzhu) added this pull request to the merge queue Aug 23, 2025

Merged via the queue into main with commit b0b3fd1 Aug 23, 2025

Chris (crickman) deleted the bentho/sub-workflows branch August 26, 2025 20:23

Navigation Menu

Repository navigation

Python: Adding support for nested workflows - #460

Python: Adding support for nested workflows#460
Eric Zhu (ekzhu) merged 37 commits into
mainfrom
bentho/sub-workflows

Ben Thomas (alliscode) commented Aug 20, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Eduard van Valkenburg (eavanvalkenburg) commented Aug 21, 2025 •

edited

Loading

Uh oh!

Eric Zhu (ekzhu) left a comment

Uh oh!

Eric Zhu (ekzhu) commented Aug 23, 2025 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

Ben Thomas (alliscode) commented Aug 20, 2025

Add Sub-Workflows Support to Agent Framework

Summary

Key Features

Implementation Details

Core Components

Message Flow

Contribution Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Eduard van Valkenburg (eavanvalkenburg) commented Aug 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Python Unit Test Overview

Uh oh!

Eric Zhu (ekzhu) left a comment

Choose a reason for hiding this comment

Uh oh!

Eric Zhu (ekzhu) commented Aug 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Eduard van Valkenburg (eavanvalkenburg) commented Aug 21, 2025 •

edited

Loading

Eric Zhu (ekzhu) commented Aug 23, 2025 •

edited

Loading