Python: Improve error message when TypeVar is used in handler registration

[ogkranthi]

Summary

• Adds early detection of unresolved TypeVar instances during handler/executor registration, surfacing a clear ValueError with actionable guidance instead of a confusing TypeCompatibilityError at edge validation time
• Covers @handler, @executor, and WorkflowContext[T] type argument validation (both direct and union members)

Fixes #4547

Changes

• _executor.py — TypeVar check in @handler decorator for both explicit type params and introspected annotation paths
• _function_executor.py — TypeVar check in FunctionExecutor.__init__ for both explicit and introspected paths
• _workflow_context.py — TypeVar check in validate_workflow_context_annotation for direct type args and union members

Test plan

• Verify @handler(input=SomeTypeVar) raises ValueError with actionable message
• Verify handler with TypeVar annotation (introspection path) raises ValueError
• Verify @executor(input=SomeTypeVar) raises ValueError
• Verify WorkflowContext[SomeTypeVar] raises ValueError
• Verify concrete types continue to work without regression
• Existing test suite passes

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework/_workflows
_executor.py	188	12	93%	211, 335, 337, 346, 366, 369, 476, 481, 491, 632, 664, 671
_function_executor.py	78	7	91%	104, 125, 132, 160, 166, 172, 189
_workflow_context.py	162	20	87%	57–58, 66, 70, 74–77, 79–81, 83–85, 160, 181, 194, 202, 313, 432
TOTAL	22696	2570	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
4938	20 💤	0 ❌	0 🔥	1m 18s ⏱️

[Copilot]

Pull request overview

Adds earlier, more actionable validation errors when unresolved TypeVar objects are used in workflow handler/executor registration, aiming to fail fast (during registration) rather than later during workflow edge/type validation.

Changes:

• Add TypeVar detection in @handler registration for both explicit decorator parameters and introspected annotations.
• Add TypeVar detection in FunctionExecutor registration for both explicit decorator parameters and introspected annotations.
• Add TypeVar detection in WorkflowContext[...] generic argument validation, including union members.

Reviewed changes

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

File	Description
python/packages/core/agent_framework/_workflows/_workflow_context.py	Adds early TypeVar checks for WorkflowContext type arguments (direct + union members) to raise clearer ValueErrors.
python/packages/core/agent_framework/_workflows/_function_executor.py	Adds early TypeVar checks for @executor registration (explicit params + introspected message type).
python/packages/core/agent_framework/_workflows/_executor.py	Adds early TypeVar checks for @handler registration (explicit params + introspected message type).

---

You can also share your feedback on Copilot code review. Take the survey.

[ogkranthi]

@copilot open a new pull request to apply changes based on the comments in this thread