Looking at this generated documentation: https://learn.microsoft.com/en-us/python/api/microsoft-agents-a365-notifications/microsoft_agents_a365.notifications.agentnotification?view=agent365-sdk-python-latest
There are several places where links to related classes are broken. For example, the return type data for the on_email method should contain links to the types. But actually, the type value looks like this:
Callable[[Callable[[xref:microsoft_agents_a365.notifications.agent_notification.TContext, xref:microsoft_agents_a365.notifications.agent_notification.TState, AgentNotificationActivity], Awaitable[None]]], Callable[[TurnContext, TurnState], Awaitable[None]]]
These docs are generated using DocFx, and I have reason to believe that the docs would generated correctly in the code was written differently. The following is the analysis I got:
The root cause is a code issue, not a doc generator bug. Here's what's happening:
The problem chain:
AgentHandler (line 43) is defined as a generic type alias using two TypeVars:
TContext = TypeVar("TContext", bound=TurnContext)
TState = TypeVar("TState", bound=TurnState)
AgentHandler = Callable[[TContext, TState, AgentNotificationActivity], Awaitable[None]]
When on_email's return type references AgentHandler, the doc generator correctly expands it to its full form — and that expansion contains TContext and TState. Those are TypeVars, not concrete classes, so DocFx can't resolve them as cross-references. The warning is accurate.
Why this is a code problem:
The on_email method (and all the on_* convenience methods) don't actually need generic TypeVars in their signatures. They always deal with concrete TurnContext and TurnState. Using AgentHandler here is conceptually imprecise — it implies the caller could pass a handler typed to a subclass of TurnContext, but the route handler returned is always typed to the concrete base types.
The fix:
Replace AgentHandler in the return types of all on_* methods with an inline version using the concrete bound types. In agent_notification.py:225, change from:
-> Callable[[AgentHandler], Callable[[TurnContext, TurnState], Awaitable[None]]]:
...to:
-> Callable[[Callable[[TurnContext, TurnState, AgentNotificationActivity], Awaitable[None]]], Callable[[TurnContext, TurnState], Awaitable[None]]]:
This substitutes TContext → TurnContext and TState → TurnState (their declared bounds), which are real importable classes that DocFx can cross-reference. The same change applies to on_word, on_excel, on_powerpoint, on_lifecycle, on_user_created, on_user_workload_onboarding, and on_user_deleted.
Note that AgentHandler itself can stay as-is — it's legitimately generic for use in user code where someone might subclass TurnContext. The issue is only in the return type annotations of the decorator methods.
Please consider applying these changes for a better implementation that will allow the docs to be generated in a clean way.
Looking at this generated documentation: https://learn.microsoft.com/en-us/python/api/microsoft-agents-a365-notifications/microsoft_agents_a365.notifications.agentnotification?view=agent365-sdk-python-latest
There are several places where links to related classes are broken. For example, the return type data for the on_email method should contain links to the types. But actually, the type value looks like this:
These docs are generated using DocFx, and I have reason to believe that the docs would generated correctly in the code was written differently. The following is the analysis I got:
The root cause is a code issue, not a doc generator bug. Here's what's happening:
The problem chain:
AgentHandler (line 43) is defined as a generic type alias using two TypeVars:
TContext = TypeVar("TContext", bound=TurnContext)
TState = TypeVar("TState", bound=TurnState)
AgentHandler = Callable[[TContext, TState, AgentNotificationActivity], Awaitable[None]]
When on_email's return type references AgentHandler, the doc generator correctly expands it to its full form — and that expansion contains TContext and TState. Those are TypeVars, not concrete classes, so DocFx can't resolve them as cross-references. The warning is accurate.
Why this is a code problem:
The on_email method (and all the on_* convenience methods) don't actually need generic TypeVars in their signatures. They always deal with concrete TurnContext and TurnState. Using AgentHandler here is conceptually imprecise — it implies the caller could pass a handler typed to a subclass of TurnContext, but the route handler returned is always typed to the concrete base types.
The fix:
Replace AgentHandler in the return types of all on_* methods with an inline version using the concrete bound types. In agent_notification.py:225, change from:
-> Callable[[AgentHandler], Callable[[TurnContext, TurnState], Awaitable[None]]]:
...to:
-> Callable[[Callable[[TurnContext, TurnState, AgentNotificationActivity], Awaitable[None]]], Callable[[TurnContext, TurnState], Awaitable[None]]]:
This substitutes TContext → TurnContext and TState → TurnState (their declared bounds), which are real importable classes that DocFx can cross-reference. The same change applies to on_word, on_excel, on_powerpoint, on_lifecycle, on_user_created, on_user_workload_onboarding, and on_user_deleted.
Note that AgentHandler itself can stay as-is — it's legitimately generic for use in user code where someone might subclass TurnContext. The issue is only in the return type annotations of the decorator methods.
Please consider applying these changes for a better implementation that will allow the docs to be generated in a clean way.