Python: Literal handler annotations crash workflows at delivery (is_instance_of has no Literal case)

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

🤖 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_of at line 223 when target_type is Literal[...]; its origin reaches isinstance(data, Literal) and raises TypeError. Executor.can_handle() and _find_handler() trigger this during handler routing. Minimal repro: assert is_instance_of("a", Literal["a", "b"]) under Python 3.12.

Failing test: python/packages/core/tests/workflow/test_typing_utils.py::test_literal_types
Files examined: python/packages/core/agent_framework/_workflows/_typing_utils.py, python/packages/core/agent_framework/_workflows/_executor.py, python/packages/core/tests/workflow/test_typing_utils.py, python/packages/core/pyproject.toml
Tests run: test_typing_utils.py (65 passed baseline), test_literal_types on Python 3.12.3 and 3.13.15 (failed)
Current version: 1.18.0

Navigation Menu

Repository navigation

Python: Literal handler annotations crash workflows at delivery (is_instance_of has no Literal case) #8350

Description

Reproduction

Expected behavior

Environment

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Python: Literal handler annotations crash workflows at delivery (is_instance_of has no Literal case) #8350

Description

Description

Reproduction

Expected behavior

Environment

Activity

github-actions commented on Sep 14, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions