Repository navigation
Python: Literal handler annotations crash workflows at delivery (is_instance_of has no Literal case) #8350
Description
Description
is_instance_of() in agent_framework/_workflows/_typing_utils.py has no Literal case. Executor.can_handle() / _find_handler() call it directly on every message delivery, so a handler registered with a Literal message annotation (which @handler registration and the builder type validation both accept) crashes the workflow on first message:
TypeError: typing.Literal cannot be used with isinstance()
The sibling helper _matches_annotation() in the same file already implements the intended Literal semantics, so the two validators disagree.
Reproduction
from typing import Literal
from agent_framework._workflows._typing_utils import is_instance_of
Msg = Literal["a", "b"]
is_instance_of("a", Msg)
# TypeError: typing.Literal cannot be used with isinstance()Any @handler with Literal["a","b"] message annotation hits this at delivery time.
Expected behavior
is_instance_of("a", Msg) is True / is_instance_of("c", Msg) is False, matching _matches_annotation(), so Literal-annotated handlers work end to end.
Environment
agent-framework python main, Python 3.12
Metadata
Metadata
Labels
Type
Projects
- Status
Activity
github-actions commentedon Sep 14, 2026
🤖 Automated triage reproduction notes (agent-authored — trust but verify)
Agent analysis
The defect reproduces in
python/packages/core/agent_framework/_workflows/_typing_utils.py::is_instance_ofat line 223 whentarget_typeisLiteral[...]; its origin reachesisinstance(data, Literal)and raisesTypeError.Executor.can_handle()and_find_handler()trigger this during handler routing. Minimal repro: assertis_instance_of("a", Literal["a", "b"])under Python 3.12.python/packages/core/tests/workflow/test_typing_utils.py::test_literal_types1.18.0