Python: Add explicit input_type and output_type parameters to @handler and @executor decorators

[moonbox3]

Motivation and Context

• Add optional input_type, output_type, and workflow_output_type parameters to @handler and @executor decorators
• Explicit types take precedence over introspection from function signatures
• Support union types via both str | int and Union[str, int] syntax
• Add normalize_type_to_list utility for converting union types to lists

Example

# You can specify all three types explicitly:
@handler(input_type=str, output_type=int, workflow_output_type=bool)
async def handle_full(self, message, ctx) -> None:
    await ctx.send_message(42)      # int - matches output_type
    await ctx.yield_output(True)    # bool - matches workflow_output_type

# Or for function executors:
@executor(input_type=str, output_type=int, workflow_output_type=bool)
async def process(message, ctx):
    await ctx.send_message(42)
    await ctx.yield_output(True)

Description

See above.

• Closes Python: Add type handling to @handler and @executor decorators #3538

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
_agent_executor.py	171	23	86%	95, 117, 151, 167–168, 219–220, 222–223, 255–257, 265–267, 277–279, 281, 285, 289, 293–294
_executor.py	173	10	94%	212, 334, 336, 345, 371, 374, 481, 486, 496, 654
_function_executor.py	73	5	93%	116, 143, 149, 155, 172
_request_info_mixin.py	78	5	93%	55, 100, 221, 228, 235
_typing_utils.py	124	28	77%	141, 165, 244, 246–247, 256, 258, 265, 267, 287, 289, 291, 296–303, 306–307, 309–313, 315
_validation.py	146	6	95%	86, 133, 154, 248, 329, 332
_workflow.py	248	17	93%	89, 259–261, 263–264, 282, 310, 411, 688, 722, 727, 730, 749–751, 816
_workflow_context.py	177	24	86%	63–64, 72, 76, 90, 166, 191, 309, 428, 471–473, 475, 477–478, 480–481, 490–492, 494–496, 498
_workflow_executor.py	173	43	75%	96, 445, 456, 468–471, 474–476, 479–480, 482, 485–487, 490–494, 498–499, 508, 513, 547, 573–578, 581, 584, 592, 597, 608, 618, 622, 628, 632, 642, 646
TOTAL	16305	2026	87%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
3777	221 💤	0 ❌	0 🔥	1m 9s ⏱️

[Copilot]

Pull request overview

This pull request adds explicit input_type and output_type parameters to the @handler and @executor decorators in the Python workflow framework. These optional parameters allow developers to specify types explicitly instead of relying on type introspection from function signatures, with explicit types taking precedence over introspected types. The feature supports union types via both str | int and Union[str, int] syntax.

Changes:

• Added normalize_type_to_list utility function to convert union types to lists
• Enhanced @handler and @executor decorators with optional input_type and output_type parameters
• Modified signature validation functions to support skipping message annotation when explicit types are provided
• Added comprehensive test coverage for explicit type parameters
• Updated sample code to demonstrate the new feature

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
python/packages/core/agent_framework/_workflows/_typing_utils.py	Added normalize_type_to_list utility function for handling union types; changed logger import pattern
python/packages/core/agent_framework/_workflows/_executor.py	Enhanced @handler decorator with input_type and output_type parameters; updated handler validation logic; refactored exception handling in _discover_handlers
python/packages/core/agent_framework/_workflows/_function_executor.py	Enhanced @executor decorator and FunctionExecutor class with explicit type parameters; updated function validation logic
python/packages/core/tests/workflow/test_typing_utils.py	Added comprehensive tests for normalize_type_to_list function covering single types, union types, and optional types
python/packages/core/tests/workflow/test_executor.py	Added comprehensive test suite for @handler with explicit types, covering precedence, union types, and partial specifications
python/packages/core/tests/workflow/test_function_executor.py	Added comprehensive test suite for @executor with explicit types, covering various edge cases and usage patterns
python/samples/getting_started/workflows/_start-here/step1_executors_and_edges.py	Added documentation and example demonstrating explicit type parameters with a new ExclamationAdder executor