Improved Teams support with microsoft-agents-hosting-msteams package

.azdo/ci-pr.yaml

@@ -73,10 +73,10 @@ steps:
     python -m pip install ./dist/microsoft_agents_copilotstudio_client*.whl
     python -m pip install ./dist/microsoft_agents_hosting_aiohttp*.whl
     python -m pip install ./dist/microsoft_agents_hosting_dialogs*.whl
-    if python -c "import sys; sys.exit(0 if sys.version_info >= (3, 12) else 1)"; then
-      python -m pip install ./dist/microsoft_agents_hosting_teams*.whl
+    if python -c "import sys; sys.exit(0 if sys.version_info >= (3, 11) else 1)"; then
+      python -m pip install ./dist/microsoft_agents_hosting_msteams*.whl
     else
-      echo "Skipping microsoft_agents_hosting_teams: requires Python 3.12+"
+      echo "Skipping microsoft_agents_hosting_msteams: requires Python 3.11+"
     fi
     python -m pip install ./dist/microsoft_agents_hosting_slack*.whl
     python -m pip install ./dist/microsoft_agents_storage_blob*.whl

.github/workflows/python-package.yml

@@ -62,10 +62,10 @@ jobs:
         python -m pip install ./dist/microsoft_agents_copilotstudio_client*.whl
         python -m pip install ./dist/microsoft_agents_hosting_aiohttp*.whl
         python -m pip install ./dist/microsoft_agents_hosting_dialogs*.whl
-        if python -c "import sys; sys.exit(0 if sys.version_info >= (3, 12) else 1)"; then
-          python -m pip install ./dist/microsoft_agents_hosting_teams*.whl
+        if python -c "import sys; sys.exit(0 if sys.version_info >= (3, 11) else 1)"; then
+          python -m pip install ./dist/microsoft_agents_hosting_msteams*.whl
         else
-          echo "Skipping microsoft_agents_hosting_teams: requires Python 3.12+"
+          echo "Skipping microsoft_agents_hosting_msteams: requires Python 3.11+"
         fi
         python -m pip install ./dist/microsoft_agents_hosting_slack*.whl
         python -m pip install ./dist/microsoft_agents_storage_blob*.whl

libraries/microsoft-agents-activity/microsoft_agents/activity/__init__.py

@@ -45,6 +45,8 @@
     ProductInfo,
     Thing,
     StreamInfo,
+    ActivityTreatment,
+    ActivityTreatmentTypes,
 )
 from .error import Error
 from .error_response import ErrorResponse
@@ -199,5 +201,7 @@
     "load_configuration_from_env",
     "ChannelAdapterProtocol",
     "TurnContextProtocol",
+    "ActivityTreatment",
+    "ActivityTreatmentTypes",
     "TokenOrSignInResourceResponse",
 ]

libraries/microsoft-agents-activity/microsoft_agents/activity/entity/__init__.py

@@ -1,6 +1,7 @@
 # Copyright (c) Microsoft Corporation. All rights reserved.
 # Licensed under the MIT License.
 
+from .activity_treatment import ActivityTreatment, ActivityTreatmentTypes
 from .mention import Mention
 from .entity import Entity
 from .entity_types import EntityTypes
@@ -35,4 +36,6 @@
     "Place",
     "ProductInfo",
     "Thing",
+    "ActivityTreatment",
+    "ActivityTreatmentTypes",
 ]

libraries/microsoft-agents-activity/microsoft_agents/activity/entity/activity_treatment.py

@@ -0,0 +1,27 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from enum import Enum
+from typing import Literal
+
+from .entity import Entity
+from .entity_types import EntityTypes
+
+
+class ActivityTreatmentTypes(str, Enum):
+    """Well-known enumeration of activity treatment types."""
+
+    TARGETED = "targeted"
+
+
+class ActivityTreatment(Entity):
+    """Activity treatment information (entity type: "activityTreatment").
+
+    :param treatment: The type of treatment
+    :type treatment: ~microsoft_agents.activity.ActivityTreatmentTypes
+    :param type: Type of this entity (RFC 3987 IRI)
+    :type type: str
+    """
+
+    type: Literal[EntityTypes.ACTIVITY_TREATMENT] = EntityTypes.ACTIVITY_TREATMENT
+    treatment: ActivityTreatmentTypes

libraries/microsoft-agents-activity/microsoft_agents/activity/entity/entity_types.py

@@ -7,6 +7,7 @@
 class EntityTypes(str, Enum):
     """Well-known enumeration of entity types."""
 
+    ACTIVITY_TREATMENT = "activityTreatment"
     GEO_COORDINATES = "GeoCoordinates"
     MENTION = "mention"
     PLACE = "Place"

libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/_type_defs.py

@@ -13,3 +13,9 @@
 
 class RouteHandler(Protocol[StateT]):
     def __call__(self, context: TurnContext, state: StateT, /) -> Awaitable[None]: ...
+
+
+class HandoffHandler(Protocol[StateT]):
+    def __call__(
+        self, context: TurnContext, state: StateT, handoff_data: str
+    ) -> Awaitable[None]: ...

libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/agent_application.py

@@ -43,7 +43,11 @@
 from .typing_indicator import TypingIndicator
 from .telemetry import spans
 
-from ._type_defs import RouteHandler, RouteSelector
+from ._type_defs import (
+    RouteHandler,
+    HandoffHandler,
+    RouteSelector,
+)
 from ._routes import _RouteList, _Route, RouteRank, _agentic_selector
 from .proactive import Proactive, ProactiveOptions
 
@@ -69,7 +73,7 @@ class AgentApplication(Agent, Generic[StateT]):
 
     _options: ApplicationOptions
     _adapter: Optional[ChannelServiceAdapter] = None
-    _auth: Optional[Authorization] = None
+    _auth: Authorization
     _proactive: Optional[Proactive] = None
     _internal_before_turn: list[Callable[[TurnContext, StateT], Awaitable[bool]]]
     _internal_after_turn: list[Callable[[TurnContext, StateT], Awaitable[bool]]]
@@ -614,11 +618,11 @@ def __call(func: RouteHandler[StateT]) -> RouteHandler[StateT]:
     @overload
     def handoff(
         self,
-        func: Callable[[TurnContext, StateT, str], Awaitable[None]],
+        func: HandoffHandler[StateT],
         *,
         auth_handlers: Optional[list[str]] = None,
         **kwargs,
-    ) -> Callable[[TurnContext, StateT, str], Awaitable[None]]: ...
+    ) -> HandoffHandler[StateT]: ...
 
     @overload
     def handoff(
@@ -627,21 +631,21 @@ def handoff(
         auth_handlers: Optional[list[str]] = None,
         **kwargs: Any,
     ) -> Callable[
-        [Callable[[TurnContext, StateT, str], Awaitable[None]]],
-        Callable[[TurnContext, StateT, str], Awaitable[None]],
+        [HandoffHandler[StateT]],
+        HandoffHandler[StateT],
     ]: ...
 
     def handoff(
         self,
-        func: Optional[Callable[[TurnContext, StateT, str], Awaitable[None]]] = None,
+        func: Optional[HandoffHandler[StateT]] = None,
         *,
         auth_handlers: Optional[list[str]] = None,
         **kwargs,
     ) -> (
-        Callable[[TurnContext, StateT, str], Awaitable[None]]
+        HandoffHandler[StateT]
         | Callable[
-            [Callable[[TurnContext, StateT, str], Awaitable[None]]],
-            Callable[[TurnContext, StateT, str], Awaitable[None]],
+            [HandoffHandler[StateT]],
+            HandoffHandler[StateT],
         ]
     ):
         """
@@ -655,7 +659,7 @@ async def on_handoff(context: TurnContext, state: TurnState, continuation: str):
                     print(continuation)
 
         :param func: Optional handler to register directly without using decorator syntax.
-        :type func: Optional[Callable[[TurnContext, StateT, str], Awaitable[None]]]
+        :type func: Optional[HandoffHandler[StateT]]
         :param auth_handlers: Optional list of authorization handler IDs for the route.
         :type auth_handlers: Optional[list[str]]
         :param kwargs: Additional route configuration passed to :meth:`microsoft_agents.hosting.core.AgentApplication.add_route`.
@@ -668,8 +672,8 @@ def __selector(context: TurnContext) -> bool:
             )
 
         def __call(
-            func: Callable[[TurnContext, StateT, str], Awaitable[None]],
-        ) -> Callable[[TurnContext, StateT, str], Awaitable[None]]:
+            func: HandoffHandler[StateT],
+        ) -> HandoffHandler[StateT]:
             async def __handler(context: TurnContext, state: StateT):
                 if (
                     isinstance(context.activity.value, dict)

libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/app_options.py

@@ -10,6 +10,7 @@
 from typing import Callable, Optional
 
 from microsoft_agents.hosting.core.app.oauth import AuthHandler
+from microsoft_agents.hosting.core.authorization import Connections
 from microsoft_agents.hosting.core.storage import Storage
 
 # from .auth import AuthOptions

libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/turn_context.py

@@ -27,6 +27,8 @@ class TurnContext(TurnContextProtocol):
     # Same constant as in the BF Adapter, duplicating here to avoid circular dependency
     _INVOKE_RESPONSE_KEY = "TurnContext.InvokeResponse"
 
+    _activity: Activity
+
     def __init__(
         self,
         adapter_or_context,
@@ -43,7 +45,7 @@ def __init__(
             self._identity = adapter_or_context.identity
         else:
             self.adapter = adapter_or_context
-            self._activity = request
+            self._activity = request  # exception thrown if None further down
             self.responses: list[Activity] = []
             self._services: dict = {}
             self._on_send_activities: Callable[
@@ -60,7 +62,7 @@ def __init__(
 
         if self.adapter is None:
             raise TypeError("TurnContext must be instantiated with an adapter.")
-        if self.activity is None:
+        if self._activity is None:
             raise TypeError(
                 "TurnContext must be instantiated with a request parameter of type Activity."
             )
@@ -83,7 +85,7 @@ def copy_to(self, context: "TurnContext") -> None:
         """
         for attribute in [
             "adapter",
-            "activity",
+            "_activity",
             "_responded",
             "_services",
             "_on_send_activities",
@@ -187,7 +189,7 @@ async def send_activity(
         activity_or_text: Activity | str,
         speak: str | None = None,
         input_hint: str | None = None,
-    ) -> ResourceResponse | None:
+    ) -> ResourceResponse:
         """
         Sends a single activity or message to the user.
         :param activity_or_text:
@@ -203,7 +205,7 @@ async def send_activity(
                 activity_or_text.speak = speak
 
         result = await self.send_activities([activity_or_text])
-        return result[0] if result else None
+        return result[0] if result else ResourceResponse()
 
     async def send_activities(
         self, activities: list[Activity]

libraries/microsoft-agents-hosting-msteams/microsoft_agents/hosting/msteams/__init__.py

@@ -0,0 +1,39 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+"""Microsoft 365 Agents SDK -- Microsoft Teams hosting extension.
+
+This package layers Teams-specific functionality on top of an
+:class:`~microsoft_agents.hosting.core.AgentApplication`. Its entry point is
+:class:`TeamsAgentExtension`, which exposes namespaced route registration for
+Teams events (channels, teams, meetings, messages, message extensions, task
+modules, configuration, and file consent). It also provides the Teams-aware
+:class:`TeamsTurnContext` and :class:`TeamsActivity` helpers.
+"""
+
+from .teams_agent_extension import TeamsAgentExtension
+from .channel import Channel
+from .config import Config
+from .file_consent import FileConsent
+from .meeting import Meeting
+from .message import Message
+from .message_extension import MessageExtension
+from .task_module import TaskModule
+from .team import Team
+
+from .teams_activity import TeamsActivity
+from .teams_turn_context import TeamsTurnContext
+
+__all__ = [
+    "TeamsAgentExtension",
+    "Channel",
+    "Config",
+    "FileConsent",
+    "Meeting",
+    "Message",
+    "MessageExtension",
+    "TaskModule",
+    "Team",
+    "TeamsActivity",
+    "TeamsTurnContext",
+]

libraries/microsoft-agents-hosting-msteams/microsoft_agents/hosting/msteams/_graph.py

@@ -0,0 +1,86 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+"""Microsoft Graph client integration for the Teams hosting layer.
+
+Builds a :class:`msgraph.GraphServiceClient` whose requests are authenticated
+with tokens obtained from the agent's configured authorization, so handlers can
+call Microsoft Graph on behalf of the current turn.
+"""
+
+from typing import Any
+
+from kiota_abstractions.request_information import RequestInformation
+from kiota_abstractions.authentication import AuthenticationProvider
+
+from msgraph import GraphServiceClient, GraphRequestAdapter
+
+from microsoft_agents.hosting.core import (
+    AgentApplication,
+    TurnContext,
+)
+
+
+class _SDKAuthenticationProvider(AuthenticationProvider):
+    """Kiota authentication provider backed by the agent's authorization.
+
+    Acquires an access token for the current turn via
+    :meth:`AgentApplication.auth.get_token` and attaches it to outgoing Graph
+    requests as a bearer token.
+    """
+
+    def __init__(
+        self,
+        app: AgentApplication,
+        context: TurnContext,
+        handler_name: str | None = None,
+    ):
+        """Capture the context needed to resolve a token at request time.
+
+        :param app: The agent application whose authorization issues tokens.
+        :param context: The current turn context.
+        :param handler_name: The auth handler name used to acquire the token.
+        """
+        self._app = app
+        self._context = context
+        self._handler_name = handler_name
+
+    async def authenticate_request(
+        self,
+        request: RequestInformation,
+        additional_authentication_context: dict[str, Any] | None = None,
+    ) -> None:
+        """Attach a bearer token to the outgoing Graph request.
+
+        :param request: The request to authenticate.
+        :param additional_authentication_context: Optional Kiota authentication
+            context; unused but accepted to satisfy the provider interface.
+        """
+        if additional_authentication_context is None:
+            additional_authentication_context = {}
+
+        token_response = await self._app.auth.get_token(
+            self._context, self._handler_name
+        )
+        if token_response:
+            request.headers["Authorization"] = f"Bearer {token_response.token}"
+
+
+def _create_graph_service_client(
+    app: AgentApplication,
+    context: TurnContext,
+    handler_name: str | None = None,
+) -> GraphServiceClient:
+    """Create a Graph client authenticated for the current turn.
+
+    :param app: The agent application whose authorization issues tokens.
+    :param context: The current turn context.
+    :param handler_name: Optional auth handler name used to acquire the token.
+    :return: A :class:`GraphServiceClient` that authenticates each request via
+        the agent's authorization.
+    """
+    return GraphServiceClient(
+        request_adapter=GraphRequestAdapter(
+            _SDKAuthenticationProvider(app, context, handler_name)
+        )
+    )