microsoft-teams-m365extensions 2.1.0__tar.gz

microsoft_teams_m365extensions-2.1.0/.gitignore

@@ -0,0 +1,57 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+
+# Environments
+.env
+.env.*
+!.env.example
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# pytest-cov
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+.copilot-instructions.md
+
+# other
+.DS_STORE
+*.bak
+*~
+*.tmp
+
+ref/
+
+.env.claude/
+.claude/
+tmpclaude-*-cwd
+
+examples/**/.vscode/
+examples/**/appPackage/
+examples/**/infra/
+examples/**/teamsapp*
+examples/**/aad.manifest.json
+
+# Targeted-messages sample ships a manifest to demonstrate the slash-commands
+# opt-in fields (supportsTargetedMessages, commandLists[].triggers).
+!examples/targeted-messages/appPackage/
+!examples/targeted-messages/appPackage/manifest.json
+
+# Node (from tab)
+node_modules
+dist/
+build/

microsoft_teams_m365extensions-2.1.0/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.5
+Name: microsoft-teams-m365extensions
+Version: 2.1.0
+Summary: Extension package that embeds the Teams SDK inside an M365 Agents Application.
+Project-URL: Homepage, https://github.com/microsoft/teams.py/tree/main/packages/m365extensions/src/microsoft_teams/m365extensions
+Author-email: Microsoft <TeamsAISDKFeedback@microsoft.com>
+License-Expression: MIT
+Keywords: agents,ai,bot,m365,microsoft,teams
+Requires-Python: <4.0,>=3.11
+Requires-Dist: microsoft-agents-activity>=1.3.0
+Requires-Dist: microsoft-agents-hosting-core>=1.3.0
+Requires-Dist: microsoft-teams-api>=2.1.0
+Requires-Dist: microsoft-teams-apps>=2.1.0
+Description-Content-Type: text/markdown
+
+# Microsoft Teams M365 Extensions
+
+<p>
+    <a href="https://pypi.org/project/microsoft-teams-m365extensions" target="_blank">
+        <img src="https://img.shields.io/pypi/v/microsoft-teams-m365extensions" />
+    </a>
+    <a href="https://pypi.org/project/microsoft-teams-m365extensions" target="_blank">
+        <img src="https://img.shields.io/pypi/dw/microsoft-teams-m365extensions" />
+    </a>
+</p>
+
+This extension package bridges the [Microsoft Teams SDK for Python](https://github.com/microsoft/teams.py) into an [Agents SDK](https://github.com/microsoft/Agents) `AgentApplication`. It installs a middleware that routes Teams turns to a teams.py `App` while letting every other channel — and unmatched Teams turns — fall through to existing Agents SDK handlers.
+
+<a href="https://microsoft.github.io/teams-sdk" target="_blank">
+    <img src="https://img.shields.io/badge/📖 Getting Started-blue?style=for-the-badge" />
+</a>
+

microsoft_teams_m365extensions-2.1.0/README.md

@@ -0,0 +1,17 @@
+# Microsoft Teams M365 Extensions
+
+<p>
+    <a href="https://pypi.org/project/microsoft-teams-m365extensions" target="_blank">
+        <img src="https://img.shields.io/pypi/v/microsoft-teams-m365extensions" />
+    </a>
+    <a href="https://pypi.org/project/microsoft-teams-m365extensions" target="_blank">
+        <img src="https://img.shields.io/pypi/dw/microsoft-teams-m365extensions" />
+    </a>
+</p>
+
+This extension package bridges the [Microsoft Teams SDK for Python](https://github.com/microsoft/teams.py) into an [Agents SDK](https://github.com/microsoft/Agents) `AgentApplication`. It installs a middleware that routes Teams turns to a teams.py `App` while letting every other channel — and unmatched Teams turns — fall through to existing Agents SDK handlers.
+
+<a href="https://microsoft.github.io/teams-sdk" target="_blank">
+    <img src="https://img.shields.io/badge/📖 Getting Started-blue?style=for-the-badge" />
+</a>
+

microsoft_teams_m365extensions-2.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "microsoft-teams-m365extensions"
+dynamic = ["version"]
+description = "Extension package that embeds the Teams SDK inside an M365 Agents Application."
+readme = "README.md"
+repository = "https://github.com/microsoft/teams.py"
+keywords = ["microsoft", "teams", "ai", "bot", "agents", "m365"]
+license = "MIT"
+authors = [{ name = "Microsoft", email = "TeamsAISDKFeedback@microsoft.com" }]
+requires-python = ">=3.11,<4.0"
+dependencies = [
+    "microsoft-agents-activity>=1.3.0",
+    "microsoft-agents-hosting-core>=1.3.0",
+    "microsoft-teams-api",
+    "microsoft-teams-apps",
+]
+
+[project.urls]
+Homepage = "https://github.com/microsoft/teams.py/tree/main/packages/m365extensions/src/microsoft_teams/m365extensions"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.0",
+    "pytest-asyncio>=1.0.0",
+]
+
+[build-system]
+requires = ["hatchling", "hatch-teams-build"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "teams-build"
+
+[tool.hatch.metadata.hooks.teams-build]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/microsoft_teams", "src/microsoft"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src"]
+
+[tool.uv.sources]
+microsoft-teams-api = { workspace = true }
+microsoft-teams-apps = { workspace = true }

microsoft_teams_m365extensions-2.1.0/src/microsoft_teams/m365extensions/__init__.py

@@ -0,0 +1,17 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+from .credentials import make_agent_sdk_token_provider
+from .install import use_teams_sdk
+from .middleware import TeamsMiddleware, is_teams_channel
+
+__all__ = [
+    "TeamsMiddleware",
+    "is_teams_channel",
+    "make_agent_sdk_token_provider",
+    "use_teams_sdk",
+]

microsoft_teams_m365extensions-2.1.0/src/microsoft_teams/m365extensions/context.py

@@ -0,0 +1,15 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+
+from microsoft_agents.hosting.core.turn_context import TurnContext
+
+# Internal only: the middleware sets this for the duration of a teams.py-handled
+# turn so ``credentials._select_provider`` can pick the connection that matches
+# the inbound identity. It is deliberately not exposed as a public accessor.
+agent_sdk_context: ContextVar[TurnContext] = ContextVar("teams_sdk.agent_sdk_context")

microsoft_teams_m365extensions-2.1.0/src/microsoft_teams/m365extensions/credentials.py

@@ -0,0 +1,88 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+from typing import Any, Awaitable, Callable, Optional, Union
+
+from microsoft_agents.hosting.core.channel_adapter import ChannelAdapter
+
+from .context import agent_sdk_context
+
+logger = logging.getLogger(__name__)
+
+# Routing key used to select the connection that mints agentic tokens,
+# mirroring the Agents SDK's ``get_token_provider(identity, "agentic")``
+# convention (and the ``CONNECTIONSMAP ... SERVICEURL=agentic`` entry). When no
+# dedicated agentic connection is registered the lookup falls back to the
+# default connection, which is sufficient for the single-connection case.
+_AGENTIC_ROUTING_KEY = "agentic"
+
+
+def make_agent_sdk_token_provider(
+    connection_manager: Any,
+) -> Callable[..., Awaitable[str]]:
+    async def _token(
+        scope: Union[str, list[str]],
+        tenant_id: Optional[str] = None,
+        *,
+        agentic_identity: Optional[Any] = None,
+    ) -> str:
+        scopes = [scope] if isinstance(scope, str) else list(scope)
+
+        agentic_user_id = getattr(agentic_identity, "agentic_user_id", None)
+        if agentic_identity is not None and agentic_user_id:
+            provider = _select_provider(connection_manager, _AGENTIC_ROUTING_KEY)
+            token = await provider.get_agentic_user_token(
+                getattr(agentic_identity, "tenant_id", None) or tenant_id,
+                agentic_identity.agentic_app_id,
+                agentic_user_id,
+                scopes,
+            )
+            if not token:
+                raise RuntimeError(
+                    "Agents SDK connection returned no agentic user token; the "
+                    "connection must be an MSAL provider with agentic support."
+                )
+            return token
+
+        # Non-agentic path: outbound Bot Framework Service token. Strip
+        # ".default" off the first scope to derive the resource_url MSAL wants
+        # — '.default' is appended back internally.
+        first = scopes[0] if scopes else ""
+        resource_url = first[: -len("/.default")] if first.endswith("/.default") else first
+
+        provider = _select_provider(connection_manager, resource_url)
+        result = provider.get_access_token(resource_url, scopes)
+        if inspect.isawaitable(result):
+            result = await result
+        return result
+
+    return _token
+
+
+def _select_provider(connection_manager: Any, service_url: str) -> Any:
+    context = agent_sdk_context.get(None)
+    if context is None:
+        return connection_manager.get_default_connection()
+
+    claims_identity = context.turn_state.get(ChannelAdapter.AGENT_IDENTITY_KEY)
+    if claims_identity is None:
+        return connection_manager.get_default_connection()
+
+    target_url = service_url or (context.activity.service_url or "")
+    if not target_url:
+        return connection_manager.get_default_connection()
+
+    try:
+        return connection_manager.get_token_provider(claims_identity, target_url)
+    except Exception as exc:  # noqa: BLE001 — degrade gracefully on lookup failure
+        logger.debug(
+            "connection lookup failed (%s); using default connection",
+            exc,
+        )
+        return connection_manager.get_default_connection()

microsoft_teams_m365extensions-2.1.0/src/microsoft_teams/m365extensions/install.py

@@ -0,0 +1,38 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from microsoft_agents.hosting.core.app.agent_application import AgentApplication
+from microsoft_agents.hosting.core.authorization.connections import Connections
+from microsoft_agents.hosting.core.turn_context import TurnContext
+from microsoft_teams.apps import App
+
+from .credentials import make_agent_sdk_token_provider
+from .middleware import TeamsMiddleware
+
+
+def use_teams_sdk(
+    app: AgentApplication[Any],
+    connection_manager: Connections,
+    should_bypass_teams: Optional[Callable[[TurnContext], bool]] = None,
+    **teams_app_kwargs: Any,
+) -> App:
+    reserved = {"client_id", "tenant_id", "token"} & teams_app_kwargs.keys()
+    if reserved:
+        raise TypeError(f"use_teams_sdk owns {sorted(reserved)}; remove from teams_app_kwargs.")
+
+    auth = connection_manager.get_default_connection_configuration()
+    teams_app = App(
+        client_id=auth.CLIENT_ID,
+        tenant_id=auth.TENANT_ID,
+        token=make_agent_sdk_token_provider(connection_manager),
+        **teams_app_kwargs,
+    )
+
+    app.adapter.use(TeamsMiddleware(teams_app, should_bypass_teams))
+    return teams_app

microsoft_teams_m365extensions-2.1.0/src/microsoft_teams/m365extensions/middleware.py

@@ -0,0 +1,118 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable, Optional, cast
+
+from microsoft_agents.activity import Activity, ActivityTypes, InvokeResponse
+from microsoft_agents.hosting.core.middleware_set import Middleware
+from microsoft_agents.hosting.core.turn_context import TurnContext
+from microsoft_teams.api import ActivityTypeAdapter
+from microsoft_teams.apps import App
+from microsoft_teams.apps.events.types import ActivityEvent, CoreActivity
+
+from .context import agent_sdk_context
+from .token import TeamsToken
+
+TEAMS_CHANNEL_ID = "msteams"
+
+
+def is_teams_channel(activity: Activity) -> bool:
+    """True for Teams turns, including sub-channels like ``msteams:COPILOT``."""
+    channel_id: Optional[str] = activity.channel_id
+    if not channel_id:
+        return False
+
+    channel = getattr(channel_id, "channel", None)
+    if channel is None:
+        channel = str(channel_id).split(":", 1)[0]
+    return channel == TEAMS_CHANNEL_ID
+
+
+class TeamsMiddleware(Middleware):
+    def __init__(
+        self,
+        teams_app: App,
+        should_bypass_teams: Optional[Callable[[TurnContext], bool]] = None,
+    ) -> None:
+        self._teams_app = teams_app
+        self._should_bypass_teams = should_bypass_teams
+
+    async def on_turn(
+        self,
+        context: TurnContext,
+        logic: Callable[[TurnContext], Awaitable[None]],
+    ) -> None:
+        activity: Activity = context.activity
+        if not is_teams_channel(activity):
+            await logic(context)
+            return
+
+        # Idempotent — App tracks _initialized internally. Run on every Teams
+        # turn so AgentApplication handlers can safely call into TEAMS_APP
+        # (e.g. ``TEAMS_APP.send`` for proactive sends) even when no teams.py
+        # route matched this turn.
+        await self._teams_app.initialize()
+
+        if self._should_bypass_teams is not None and self._should_bypass_teams(context):
+            await logic(context)
+            return
+
+        core_activity = self._translate_inbound(activity)
+
+        if not self._teams_app.router.select_handlers(core_activity):
+            # No teams.py route matches; let AgentApplication try its handlers.
+            await logic(context)
+            return
+
+        event = ActivityEvent(
+            body=cast(CoreActivity, core_activity),
+            token=TeamsToken.from_activity(activity),
+        )
+
+        ctx_token = agent_sdk_context.set(context)
+        try:
+            invoke_response = await self._teams_app.activity_processor.process_activity(
+                plugins=self._teams_app.plugins, event=event
+            )
+        finally:
+            agent_sdk_context.reset(ctx_token)
+
+        if activity.type == ActivityTypes.invoke:
+            await self._propagate_invoke_response(context, invoke_response)
+
+    @staticmethod
+    def _translate_inbound(activity: Activity):
+        payload: str = activity.model_dump_json(by_alias=True, exclude_none=True)
+        return ActivityTypeAdapter.validate_json(payload)
+
+    @staticmethod
+    async def _propagate_invoke_response(context: TurnContext, invoke_response: object) -> None:
+        if invoke_response is None:
+            return
+
+        status: Any
+        body: Any
+        if isinstance(invoke_response, dict):
+            response = cast("dict[str, Any]", invoke_response)
+            status = response.get("status")
+            body = response.get("body")
+        else:
+            status = getattr(invoke_response, "status", None)
+            body = getattr(invoke_response, "body", None)
+
+        if status is None:
+            return
+
+        if hasattr(body, "model_dump"):
+            body = body.model_dump(mode="json", by_alias=True, exclude_none=True)
+
+        await context.send_activity(
+            Activity(
+                type=ActivityTypes.invoke_response,
+                value=InvokeResponse(status=status, body=body),
+            )
+        )

microsoft_teams_m365extensions-2.1.0/src/microsoft_teams/m365extensions/py.typed

@@ -0,0 +1 @@
+

microsoft_teams_m365extensions-2.1.0/src/microsoft_teams/m365extensions/token.py

@@ -0,0 +1,83 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Optional
+
+from microsoft_agents.activity import Activity
+from microsoft_teams.api.auth.caller import CallerIds, CallerType
+from microsoft_teams.api.auth.token import TokenProtocol
+
+
+class TeamsToken(TokenProtocol):
+    """A minimal TokenProtocol synthesized from an Agents SDK Activity."""
+
+    def __init__(
+        self,
+        *,
+        app_id: str,
+        tenant_id: Optional[str],
+        service_url: str,
+        app_display_name: Optional[str] = None,
+    ) -> None:
+        self._app_id = app_id
+        self._tenant_id = tenant_id
+        self._service_url = service_url.rstrip("/") if service_url else ""
+        self._app_display_name = app_display_name
+        # Synthetic expiration ~1h out so is_expired() reports False.
+        self._expiration_ms = int(time.time() * 1000) + 60 * 60 * 1000
+
+    @classmethod
+    def from_activity(cls, activity: Activity) -> "TeamsToken":
+        recipient = getattr(activity, "recipient", None)
+        conversation = getattr(activity, "conversation", None)
+        return cls(
+            app_id=getattr(recipient, "id", "") or "",
+            app_display_name=getattr(recipient, "name", None),
+            tenant_id=getattr(conversation, "tenant_id", None),
+            service_url=getattr(activity, "service_url", "") or "",
+        )
+
+    # ── TokenProtocol surface ──────────────────────────────────────────
+
+    @property
+    def app_id(self) -> str:
+        return self._app_id
+
+    @property
+    def app_display_name(self) -> Optional[str]:
+        return self._app_display_name
+
+    @property
+    def tenant_id(self) -> Optional[str]:
+        return self._tenant_id
+
+    @property
+    def service_url(self) -> str:
+        return self._service_url or "https://smba.trafficmanager.net/teams"
+
+    @property
+    def from_(self) -> CallerType:
+        return "bot" if self._app_id else "azure"
+
+    @property
+    def from_id(self) -> str:
+        if self.from_ == "bot":
+            return f"{CallerIds.BOT}:{self._app_id}"
+        return CallerIds.AZURE
+
+    @property
+    def expiration(self) -> Optional[int]:
+        return self._expiration_ms
+
+    def is_expired(self, buffer_ms: int = 5 * 60 * 1000) -> bool:
+        return self._expiration_ms < (time.time() * 1000) + buffer_ms
+
+    def __str__(self) -> str:
+        # No real JWT is forwarded; a tagged sentinel is more honest than '' and
+        # cannot be mistaken for a signable bearer.
+        return f"teams-sdk-synthetic://app/{self._app_id}"