Repository navigation
Python: [Bug]: @response_handler fails with postponed annotations #8327
Description
Description
The introspection mode of @response_handler reads raw values from inspect.signature(func). When a module uses from __future__ import annotations, valid request, response, and WorkflowContext[...] annotations are stored as strings, but the response-handler validation path does not resolve them before validating the context annotation.
This causes a valid executor definition to fail while the class body is being evaluated, so the executor cannot be imported or instantiated.
Reproduction
from __future__ import annotations
from agent_framework import Executor, WorkflowContext, handler, response_handler
class FutureAnnotationsExecutor(Executor):
@handler
async def handle(self, message: str, ctx: WorkflowContext) -> None:
pass
@response_handler
async def handle_response(
self, original_request: str, response: int, ctx: WorkflowContext[str]
) -> None:
passOn the current upstream main, defining the class raises:
ValueError: Response handler parameter 'ctx' must be annotated as WorkflowContext, WorkflowContext[T], or WorkflowContext[T, U], got WorkflowContext[str]
Expected behavior
The introspection path should resolve postponed annotations in the same way as the existing @handler path, then register the response handler with str as the request type, int as the response type, and str as the workflow output type.
Scope
This affects introspection mode only. Explicit @response_handler(request=..., response=...) parameters already resolve string references and should remain unchanged.
The corresponding @handler future-annotation behavior is covered by test_executor_future.py (issue #3898); this issue tracks the missing response-handler counterpart.
Metadata
Metadata
Labels
Type
Projects
- Status
Activity
github-actions commentedon Sep 12, 2026
🤖 Automated triage reproduction notes (agent-authored — trust but verify)
Agent analysis
The bug occurs in
python/packages/core/agent_framework/_workflows/_request_info_mixin.py::_validate_response_handler_signatureat lines 325-366. It is triggered when introspection-mode@response_handlerreceives postponed request, response, andWorkflowContextannotations, causing the raw context string to fail validation. Minimal repro: define the issue’s executor underfrom __future__ import annotations; class definition raises before instantiation.python/packages/core/tests/workflow/test_executor_future.py1.18.0he-yufeng commentedon Sep 13, 2026
The mechanism is exactly as analyzed: the
@handlerpath resolves postponed annotations throughtyping.get_type_hints, while_validate_response_handler_signaturereads rawinspect.signatureannotations, so underfrom __future__ import annotationsthe ctx string"WorkflowContext[str]"reachesvalidate_workflow_context_annotationunresolved and a valid executor definition raises during class evaluation.Fix mirrors the decorator's explicit-parameter path: resolve each annotation with the existing
resolve_type_annotationhelper againstfunc.__globals__, falling back to the raw annotation when resolution fails so registration failures stay diagnosable. Verified with the issue's repro (red before, green after) plus response-handler counterparts of thetest_executor_future.pycases.I have the patch ready and will open a PR shortly unless you'd rather take it yourself, Eduard van Valkenburg (@eavanvalkenburg).