What causes "Return type not found" in microsoft/autogen?

Use a concrete, imported return type: -> None for fire-and-forget handlers, or -> MyResponse.

microsoft/autogen · error · AssertionError

Return type not found

Error message

Return type not found

What it means

Companion check to the previous two: the closure's return annotation must resolve via get_types() to concrete types. A declared-but-unresolvable return annotation (forward reference that fails, None-producing annotation shapes) triggers AssertionError('Return type not found') after the 'return' key existence check passed.

Source

Thrown at python/packages/autogen-core/src/autogen_core/_closure_agent.py:49

        raise AssertionError("Closure must have 4 arguments")

    message_arg_name = args[1]

    type_hints = get_type_hints(closure)

    if "return" not in type_hints:
        raise AssertionError("return not found in function signature")

    # Get the type of the message parameter
    target_types = get_types(type_hints[message_arg_name])
    if target_types is None:
        raise AssertionError("Message type not found")

    # print(type_hints)
    return_types = get_types(type_hints["return"])

    if return_types is None:
        raise AssertionError("Return type not found")

    return target_types


class ClosureContext(Protocol):
    @property
    def id(self) -> AgentId: ...

    async def send_message(
        self,
        message: Any,
        recipient: AgentId,
        *,
        cancellation_token: CancellationToken | None = None,
        message_id: str | None = None,
    ) -> Any: ...

    async def publish_message(

View on GitHub (pinned to 027ecf0a37)

Solutions

Use a concrete, imported return type: -> None for fire-and-forget handlers, or -> MyResponse.
If avoiding circular imports, move shared message types into a separate module both sides import.
Verify get_type_hints(handler) resolves in a REPL before constructing the ClosureAgent.

Example fix

# before
async def handler(agent, message: Msg, ctx) -> "Resp":  # Resp not resolvable
    ...

# after
from myapp.types import Resp
async def handler(agent: ClosureContext, message: Msg, ctx: MessageContext) -> Resp:
    ...

Defensive patterns

Strategy: validation

Validate before calling

from typing import get_type_hints

hints = get_type_hints(my_closure)
assert hints.get("return") is not None, "return annotation must resolve to a concrete type"

Prevention

Return concrete imported types from closures (None is fine for fire-and-forget).
Resolve circular imports by moving message/response types to a shared module.
Verify with typing.get_type_hints(closure) in a REPL before wiring into a runtime.

When it happens

Trigger: async def handler(...) -> "SomeUnimportedType"; returning generics whose hints get_types cannot reduce; annotations referencing names deleted or shadowed at ClosureAgent construction time.

Common situations: Return types declared with quoted forward references to avoid circular imports; refactoring that renames the response type without updating the string annotation.

Related errors

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/32f40d6b547ee089. Report an issue: GitHub.