Python: Fix executor handler type resolution when using from __future__ import annotations

[moonbox3]

Motivation and Context

When from __future__ import annotations is used (standard in Python 3.12+), all annotations become strings instead of resolved types. This causes _validate_handler_signature to fail because it compares string annotations against actual types, breaking @handler decorator validation in executors.

Fixes #3898

Description

The root cause is that inspect.Parameter.annotation returns raw string annotations when from __future__ import annotations is active, but the validation logic expected resolved type objects. The fix uses typing.get_type_hints(func) to eagerly resolve stringified annotations back to their actual types before performing type checks on the ctx and message parameters. A new test module with from __future__ import annotations enabled at the module level verifies that handler registration works correctly with stringified annotations across multiple scenarios.

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.

---

Note: PR autogenerated by moonbox3's agent

[moonbox3]

Automated Code Review

Reviewers: 3 | Confidence: 85%

✓ Correctness

This diff correctly fixes handling of PEP 563 stringified annotations (from from __future__ import annotations) by using typing.get_type_hints() to resolve forward references. The implementation properly falls back to inspect.Parameter.annotation when a parameter name isn't found in the resolved hints, and the test coverage is solid across key scenarios. No correctness issues found.

✓ Security Reliability

The change correctly uses typing.get_type_hints() to resolve stringified annotations from from __future__ import annotations. There are no security issues—while get_type_hints() internally evaluates string annotations, these originate from developer-authored source code, not untrusted input. The main reliability concern is that get_type_hints() can raise NameError (or other exceptions) when forward references cannot be resolved, and there is no error handling around the call, which could produce confusing tracebacks during handler registration.

✓ Test Coverage

The new test file covers the main happy paths for future annotations (multi-arg, single-arg, complex types, bare context), which is good. However, there are two notable gaps: (1) the skip_message_annotation code path (when @handler(input=..., output=...) is used) was also changed to use resolved type hints but has no corresponding future-annotations test, and (2) the bare-context test only asserts handler registration without verifying that output_types and workflow_output_types are correctly empty, making it weaker than the other tests.

Suggestions

• Consider wrapping typing.get_type_hints(func) in a try/except for NameError (unresolvable forward references) to provide a more user-friendly error message pointing to the handler and the unresolvable annotation, rather than letting the raw NameError propagate.
• Consider wrapping typing.get_type_hints(func) in a try/except to catch NameError or Exception, falling back to raw inspect annotations and/or raising a more descriptive ValueError that mentions the handler name and hints at the unresolvable type. This would improve the developer experience when a forward reference cannot be resolved at registration time.
• Add a test for @handler(input=MyTypeA, output=MyTypeB) with from __future__ import annotations to cover the skip_message_annotation branch that was also modified in _validate_handler_signature.
• Strengthen the bare-context test to assert on output_types and workflow_output_types, consistent with the other tests in the suite.
• Consider adding a test for union-type context annotations (e.g., WorkflowContext[MyTypeA | MyTypeB, MyTypeC]) with future annotations, since union handling is a common source of edge-case bugs with stringified annotations.

---

Automated review by moonbox3's agents

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework/_workflows
_executor.py	183	10	94%	211, 335, 337, 346, 366, 369, 476, 481, 491, 650
TOTAL	22222	2758	87%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
4714	247 💤	0 ❌	0 🔥	1m 18s ⏱️

[Copilot]

Pull request overview

This PR fixes a bug where the @handler decorator in Python Executor classes fails when from __future__ import annotations is used (which becomes standard in Python 3.12+). The issue occurs because stringified annotations need to be resolved to actual type objects before validation, but the original code expected resolved types directly from inspect.Parameter.annotation.

Changes:

• Added typing.get_type_hints() call to resolve stringified annotations before type validation in _validate_handler_signature()
• Updated message type and context annotation resolution to use resolved type hints with proper fallback
• Added comprehensive test suite to verify the fix works across different annotation patterns

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
python/packages/core/agent_framework/_workflows/_executor.py	Fixed _validate_handler_signature() to resolve stringified annotations using typing.get_type_hints() before validation, matching the pattern already used in FunctionExecutor
python/packages/core/tests/workflow/test_executor_future.py	Added new test module with from __future__ import annotations to verify handler decorator works correctly with stringified annotations across multiple scenarios (two type args, single type arg, complex types, bare context)