Python: Add explicit input, output, and workflow_output parameters to @handler, @executor and request_info

[Evan Mattson (moonbox3)]

Motivation and Context

• Add optional input, output, and workflow_output 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.

[Mark Wallace (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, 365, 368, 475, 480, 490, 649
_function_executor.py	73	5	93%	112, 139, 145, 151, 168
_magentic.py	614	91	85%	69–78, 83, 87–98, 263, 274, 278, 298, 359, 368, 370, 412, 429, 438–439, 441–443, 445, 456, 598, 600, 640, 688, 724–726, 728, 736–739, 743–746, 789, 816–819, 910, 916, 922, 961, 999, 1028, 1045, 1056, 1110–1111, 1115–1117, 1141, 1162–1163, 1176, 1192, 1214, 1262–1263, 1301–1302, 1458, 1467, 1470, 1475, 1871, 1913, 1928, 1957
_orchestrator_helpers.py	21	2	90%	90–91
_request_info_mixin.py	107	5	95%	62, 99, 335, 342, 349
_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	16335	1984	87%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
3811	221 💤	0 ❌	0 🔥	1m 6s ⏱️

[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

[Tao Chen (TaoChenOSU)]

Should we also update response_handler in this PR?

[Evan Mattson (moonbox3)]

Should we also update response_handler in this PR?

Yes will add now.

[Eduard van Valkenburg (eavanvalkenburg)]

one question, but overall looks good