microsoft-teams-api 2.0.16__tar.gz → 2.1.0a2__tar.gz

{microsoft_teams_api-2.0.16 → microsoft_teams_api-2.1.0a2}/PKG-INFO

@@ -1,14 +1,15 @@
 Metadata-Version: 2.5
 Name: microsoft-teams-api
-Version: 2.0.16
+Version: 2.1.0a2
 Summary: API package for Microsoft Teams
 Project-URL: Homepage, https://github.com/microsoft/teams.py/tree/main/packages/api/src/microsoft/teams/api
 Author-email: Microsoft <TeamsAISDKFeedback@microsoft.com>
 License-Expression: MIT
 Keywords: agents,ai,bot,microsoft,teams
 Requires-Python: <4.0,>=3.11
-Requires-Dist: microsoft-teams-cards>=2.0.16
-Requires-Dist: microsoft-teams-common>=2.0.16
+Requires-Dist: microsoft-teams-cards>=2.1.0a2
+Requires-Dist: microsoft-teams-common>=2.1.0a2
+Requires-Dist: opentelemetry-api>=1.41.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: pyjwt[crypto]>=2.12.0
 Description-Content-Type: text/markdown

{microsoft_teams_api-2.0.16 → microsoft_teams_api-2.1.0a2}/pyproject.toml

@@ -11,6 +11,7 @@ authors = [
 ]
 requires-python = ">=3.11,<4.0"
 dependencies = [
+    "opentelemetry-api>=1.41.0",
     "pydantic>=2.0.0",
     "microsoft-teams-common",
     "microsoft-teams-cards",

{microsoft_teams_api-2.0.16 → microsoft_teams_api-2.1.0a2}/src/microsoft_teams/api/__init__.py

@@ -5,10 +5,11 @@ Licensed under the MIT License.
 
 import logging
 
-from . import activities, auth, clients, models
+from . import activities, auth, clients, diagnostics, models
 from .activities import *  # noqa: F403
 from .auth import *  # noqa: F403
 from .clients import *  # noqa: F403
+from .diagnostics import *  # noqa: F403
 from .models import *  # noqa: F403
 
 logging.getLogger(__name__).addHandler(logging.NullHandler())
@@ -18,4 +19,5 @@ __all__: list[str] = []
 __all__.extend(activities.__all__)
 __all__.extend(auth.__all__)
 __all__.extend(clients.__all__)
+__all__.extend(diagnostics.__all__)
 __all__.extend(models.__all__)

microsoft_teams_api-2.1.0a2/src/microsoft_teams/api/activities/event/__init__.py

@@ -0,0 +1,83 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from typing import Annotated, Union
+
+from pydantic import Field
+
+from .agent_lifecycle import (
+    AgenticUserDeletedActivity,
+    AgenticUserDeletedValue,
+    AgenticUserDisabledActivity,
+    AgenticUserDisabledValue,
+    AgenticUserEnabledActivity,
+    AgenticUserEnabledValue,
+    AgenticUserIdentityCreatedActivity,
+    AgenticUserIdentityCreatedValue,
+    AgenticUserIdentityUpdatedActivity,
+    AgenticUserIdentityUpdatedValue,
+    AgenticUserManagerUpdatedActivity,
+    AgenticUserManagerUpdatedValue,
+    AgenticUserUndeletedActivity,
+    AgenticUserUndeletedValue,
+    AgenticUserWorkloadOnboardingUpdatedActivity,
+    AgenticUserWorkloadOnboardingUpdatedValue,
+    AgentLifecycleEventActivity,
+    AgentLifecycleEventActivityBase,
+    AgentLifecycleManager,
+    AgentLifecycleManagerRef,
+    AgentLifecycleUpdatedProperty,
+    AgentLifecycleValueBase,
+)
+from .meeting_end import MeetingEndEventActivity
+from .meeting_participant import MeetingParticipantEventActivity
+from .meeting_participant_join import MeetingParticipantJoinEventActivity
+from .meeting_participant_leave import MeetingParticipantLeaveEventActivity
+from .meeting_start import MeetingStartEventActivity
+from .read_reciept import ReadReceiptEventActivity
+
+EventActivity = Annotated[
+    Union[
+        ReadReceiptEventActivity,
+        MeetingStartEventActivity,
+        MeetingEndEventActivity,
+        MeetingParticipantJoinEventActivity,
+        MeetingParticipantLeaveEventActivity,
+        AgentLifecycleEventActivity,
+    ],
+    Field(discriminator="name"),
+]
+
+__all__ = [
+    "MeetingEndEventActivity",
+    "MeetingStartEventActivity",
+    "MeetingParticipantEventActivity",
+    "MeetingParticipantJoinEventActivity",
+    "MeetingParticipantLeaveEventActivity",
+    "ReadReceiptEventActivity",
+    "EventActivity",
+    "AgentLifecycleEventActivity",
+    "AgentLifecycleEventActivityBase",
+    "AgenticUserIdentityCreatedActivity",
+    "AgenticUserIdentityUpdatedActivity",
+    "AgenticUserManagerUpdatedActivity",
+    "AgenticUserEnabledActivity",
+    "AgenticUserDisabledActivity",
+    "AgenticUserDeletedActivity",
+    "AgenticUserUndeletedActivity",
+    "AgenticUserWorkloadOnboardingUpdatedActivity",
+    "AgentLifecycleManager",
+    "AgentLifecycleManagerRef",
+    "AgentLifecycleUpdatedProperty",
+    "AgentLifecycleValueBase",
+    "AgenticUserIdentityCreatedValue",
+    "AgenticUserIdentityUpdatedValue",
+    "AgenticUserManagerUpdatedValue",
+    "AgenticUserEnabledValue",
+    "AgenticUserDisabledValue",
+    "AgenticUserDeletedValue",
+    "AgenticUserUndeletedValue",
+    "AgenticUserWorkloadOnboardingUpdatedValue",
+]

microsoft_teams_api-2.1.0a2/src/microsoft_teams/api/activities/event/agent_lifecycle/__init__.py

@@ -0,0 +1,56 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from .activity import (
+    AgenticUserDeletedActivity,
+    AgenticUserDisabledActivity,
+    AgenticUserEnabledActivity,
+    AgenticUserIdentityCreatedActivity,
+    AgenticUserIdentityUpdatedActivity,
+    AgenticUserManagerUpdatedActivity,
+    AgenticUserUndeletedActivity,
+    AgenticUserWorkloadOnboardingUpdatedActivity,
+    AgentLifecycleEventActivity,
+    AgentLifecycleEventActivityBase,
+)
+from .value import (
+    AgenticUserDeletedValue,
+    AgenticUserDisabledValue,
+    AgenticUserEnabledValue,
+    AgenticUserIdentityCreatedValue,
+    AgenticUserIdentityUpdatedValue,
+    AgenticUserManagerUpdatedValue,
+    AgenticUserUndeletedValue,
+    AgenticUserWorkloadOnboardingUpdatedValue,
+    AgentLifecycleManager,
+    AgentLifecycleManagerRef,
+    AgentLifecycleUpdatedProperty,
+    AgentLifecycleValueBase,
+)
+
+__all__ = [
+    "AgentLifecycleEventActivity",
+    "AgentLifecycleEventActivityBase",
+    "AgenticUserIdentityCreatedActivity",
+    "AgenticUserIdentityUpdatedActivity",
+    "AgenticUserManagerUpdatedActivity",
+    "AgenticUserEnabledActivity",
+    "AgenticUserDisabledActivity",
+    "AgenticUserDeletedActivity",
+    "AgenticUserUndeletedActivity",
+    "AgenticUserWorkloadOnboardingUpdatedActivity",
+    "AgentLifecycleManager",
+    "AgentLifecycleManagerRef",
+    "AgentLifecycleUpdatedProperty",
+    "AgentLifecycleValueBase",
+    "AgenticUserIdentityCreatedValue",
+    "AgenticUserIdentityUpdatedValue",
+    "AgenticUserManagerUpdatedValue",
+    "AgenticUserEnabledValue",
+    "AgenticUserDisabledValue",
+    "AgenticUserDeletedValue",
+    "AgenticUserUndeletedValue",
+    "AgenticUserWorkloadOnboardingUpdatedValue",
+]

microsoft_teams_api-2.1.0a2/src/microsoft_teams/api/activities/event/agent_lifecycle/activity.py

@@ -0,0 +1,119 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from typing import Annotated, Literal, Union
+
+from pydantic import Field
+
+from ....models import ActivityBase, CustomBaseModel
+from .value import (
+    AgenticUserDeletedValue,
+    AgenticUserDisabledValue,
+    AgenticUserEnabledValue,
+    AgenticUserIdentityCreatedValue,
+    AgenticUserIdentityUpdatedValue,
+    AgenticUserManagerUpdatedValue,
+    AgenticUserUndeletedValue,
+    AgenticUserWorkloadOnboardingUpdatedValue,
+)
+
+
+class AgentLifecycleEventActivityBase(ActivityBase, CustomBaseModel):
+    """Base for Agent 365 ``agentLifecycle`` event activities.
+
+    These activities arrive from the ``System`` user on the ``agents`` channel with
+    ``type == "event"`` and ``name == "agentLifecycle"``. The ``value_type`` field
+    names the variant and ``value`` carries the typed payload.
+    """
+
+    type: Literal["event"] = "event"
+
+    name: Literal["agentLifecycle"] = "agentLifecycle"
+    """The name of the operation associated with an event activity."""
+
+
+class AgenticUserIdentityCreatedActivity(AgentLifecycleEventActivityBase):
+    """Fired when an agentic user identity is created."""
+
+    value_type: Literal["AgenticUserIdentityCreated"] = "AgenticUserIdentityCreated"
+    value: AgenticUserIdentityCreatedValue
+
+
+class AgenticUserIdentityUpdatedActivity(AgentLifecycleEventActivityBase):
+    """Fired when an agentic user identity property changes."""
+
+    value_type: Literal["AgenticUserIdentityUpdated"] = "AgenticUserIdentityUpdated"
+    value: AgenticUserIdentityUpdatedValue
+
+
+class AgenticUserManagerUpdatedActivity(AgentLifecycleEventActivityBase):
+    """Fired when an agentic user's manager changes."""
+
+    value_type: Literal["AgenticUserManagerUpdated"] = "AgenticUserManagerUpdated"
+    value: AgenticUserManagerUpdatedValue
+
+
+class AgenticUserEnabledActivity(AgentLifecycleEventActivityBase):
+    """Fired when an agentic user is enabled."""
+
+    value_type: Literal["AgenticUserEnabled"] = "AgenticUserEnabled"
+    value: AgenticUserEnabledValue
+
+
+class AgenticUserDisabledActivity(AgentLifecycleEventActivityBase):
+    """Fired when an agentic user is disabled."""
+
+    value_type: Literal["AgenticUserDisabled"] = "AgenticUserDisabled"
+    value: AgenticUserDisabledValue
+
+
+class AgenticUserDeletedActivity(AgentLifecycleEventActivityBase):
+    """Fired when an agentic user is deleted."""
+
+    value_type: Literal["AgenticUserDeleted"] = "AgenticUserDeleted"
+    value: AgenticUserDeletedValue
+
+
+class AgenticUserUndeletedActivity(AgentLifecycleEventActivityBase):
+    """Fired when a previously deleted agentic user is restored."""
+
+    value_type: Literal["AgenticUserUndeleted"] = "AgenticUserUndeleted"
+    value: AgenticUserUndeletedValue
+
+
+class AgenticUserWorkloadOnboardingUpdatedActivity(AgentLifecycleEventActivityBase):
+    """Fired when a workload onboarding state changes for an agentic user."""
+
+    value_type: Literal["AgenticUserWorkloadOnboardingUpdated"] = "AgenticUserWorkloadOnboardingUpdated"
+    value: AgenticUserWorkloadOnboardingUpdatedValue
+
+
+AgentLifecycleEventActivity = Annotated[
+    Union[
+        AgenticUserIdentityCreatedActivity,
+        AgenticUserIdentityUpdatedActivity,
+        AgenticUserManagerUpdatedActivity,
+        AgenticUserEnabledActivity,
+        AgenticUserDisabledActivity,
+        AgenticUserDeletedActivity,
+        AgenticUserUndeletedActivity,
+        AgenticUserWorkloadOnboardingUpdatedActivity,
+    ],
+    Field(discriminator="value_type"),
+]
+"""Union of all Agent 365 ``agentLifecycle`` event activities, discriminated by ``valueType``."""
+
+__all__ = [
+    "AgentLifecycleEventActivityBase",
+    "AgenticUserIdentityCreatedActivity",
+    "AgenticUserIdentityUpdatedActivity",
+    "AgenticUserManagerUpdatedActivity",
+    "AgenticUserEnabledActivity",
+    "AgenticUserDisabledActivity",
+    "AgenticUserDeletedActivity",
+    "AgenticUserUndeletedActivity",
+    "AgenticUserWorkloadOnboardingUpdatedActivity",
+    "AgentLifecycleEventActivity",
+]

microsoft_teams_api-2.1.0a2/src/microsoft_teams/api/activities/event/agent_lifecycle/value.py

@@ -0,0 +1,157 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from datetime import datetime
+from typing import Literal, Optional
+
+from pydantic import Field
+
+from ....models import CustomBaseModel
+
+
+class AgentLifecycleManager(CustomBaseModel):
+    """Manager profile carried by the ``AgenticUserIdentityCreated`` service event."""
+
+    user_id: Optional[str] = None
+    """The Entra object ID of the manager."""
+
+    email: Optional[str] = None
+    """The manager's email address."""
+
+    display_name: Optional[str] = None
+    """The manager's display name."""
+
+
+class AgentLifecycleManagerRef(CustomBaseModel):
+    """Manager reference carried by the ``AgenticUserManagerUpdated`` event."""
+
+    manager_id: Optional[str] = None
+    """The Entra object ID of the manager."""
+
+
+class AgentLifecycleUpdatedProperty(CustomBaseModel):
+    """A single property change carried by the ``AgenticUserIdentityUpdated`` service event."""
+
+    property_name: str
+    """The name of the property that changed (e.g. ``Mail``, ``Alias``, ``UserPrincipalName``)."""
+
+    property_value: Optional[str] = None
+    """The new value of the property."""
+
+
+class AgentLifecycleValueBase(CustomBaseModel):
+    """Fields shared by every agentLifecycle event payload."""
+
+    tenant_id: Optional[str] = None
+    """The tenant the agentic user belongs to."""
+
+    agentic_user_id: Optional[str] = Field(
+        default=None,
+        validation_alias="agenticUserId",
+        serialization_alias="agenticUserId",
+    )
+    """The Agent ID user-shaped identity object ID."""
+
+    agentic_app_instance_id: Optional[str] = Field(
+        default=None,
+        validation_alias="agenticAppInstanceId",
+        serialization_alias="agenticAppInstanceId",
+    )
+    """The service-owned agentic app instance ID."""
+
+    agent_identity_blueprint_id: Optional[str] = Field(
+        default=None,
+        validation_alias="agentIdentityBlueprintId",
+        serialization_alias="agentIdentityBlueprintId",
+    )
+    """The service-owned agent identity blueprint ID."""
+
+    version: Optional[int] = None
+    """Monotonic version of the agentic user state, when provided by the service."""
+
+
+class AgenticUserIdentityCreatedValue(AgentLifecycleValueBase):
+    """Payload for the ``agenticUserIdentityCreated`` event."""
+
+    event_type: Literal["agenticUserIdentityCreated"] = "agenticUserIdentityCreated"
+
+    manager: Optional[AgentLifecycleManager] = None
+    """The manager assigned to the agentic user at creation."""
+
+    expiration_date_time: Optional[datetime] = None
+    """When the agentic user identity expires."""
+
+
+class AgenticUserIdentityUpdatedValue(AgentLifecycleValueBase):
+    """Payload for the ``agenticUserIdentityUpdated`` event."""
+
+    event_type: Literal["agenticUserIdentityUpdated"] = "agenticUserIdentityUpdated"
+
+    updated_property: AgentLifecycleUpdatedProperty
+    """The property that changed."""
+
+
+class AgenticUserManagerUpdatedValue(AgentLifecycleValueBase):
+    """Payload for the ``agenticUserManagerUpdated`` event."""
+
+    event_type: Literal["agenticUserManagerUpdated"] = "agenticUserManagerUpdated"
+
+    manager: Optional[AgentLifecycleManagerRef] = None
+    """The new manager reference. Absent when the manager was removed."""
+
+
+class AgenticUserEnabledValue(AgentLifecycleValueBase):
+    """Payload for the ``agenticUserEnabled`` event."""
+
+    event_type: Literal["agenticUserEnabled"] = "agenticUserEnabled"
+
+
+class AgenticUserDisabledValue(AgentLifecycleValueBase):
+    """Payload for the ``agenticUserDisabled`` event."""
+
+    event_type: Literal["agenticUserDisabled"] = "agenticUserDisabled"
+
+
+class AgenticUserDeletedValue(AgentLifecycleValueBase):
+    """Payload for the ``agenticUserDeleted`` event."""
+
+    event_type: Literal["agenticUserDeleted"] = "agenticUserDeleted"
+
+    deletion_reason: Optional[str] = None
+    """The reason the agentic user was deleted (e.g. ``UserSoftDelete``, ``UserHardDelete``)."""
+
+
+class AgenticUserUndeletedValue(AgentLifecycleValueBase):
+    """Payload for the ``agenticUserUndeleted`` event."""
+
+    event_type: Literal["agenticUserUndeleted"] = "agenticUserUndeleted"
+
+
+class AgenticUserWorkloadOnboardingUpdatedValue(AgentLifecycleValueBase):
+    """Payload for the ``agenticUserWorkloadOnboardingUpdated`` event."""
+
+    event_type: Literal["agenticUserWorkloadOnboardingUpdated"] = "agenticUserWorkloadOnboardingUpdated"
+
+    workload_name: Optional[str] = None
+    """The workload being onboarded (e.g. ``Teams``)."""
+
+    workload_onboarding_state: Optional[str] = None
+    """The onboarding state for the workload (e.g. ``succeeded``)."""
+
+
+__all__ = [
+    "AgentLifecycleManager",
+    "AgentLifecycleManagerRef",
+    "AgentLifecycleUpdatedProperty",
+    "AgentLifecycleValueBase",
+    "AgenticUserIdentityCreatedValue",
+    "AgenticUserIdentityUpdatedValue",
+    "AgenticUserManagerUpdatedValue",
+    "AgenticUserEnabledValue",
+    "AgenticUserDisabledValue",
+    "AgenticUserDeletedValue",
+    "AgenticUserUndeletedValue",
+    "AgenticUserWorkloadOnboardingUpdatedValue",
+]

{microsoft_teams_api-2.0.16 → microsoft_teams_api-2.1.0a2}/src/microsoft_teams/api/activities/message/message.py

@@ -316,6 +316,8 @@ class MessageActivityInput(_MessageBase, ActivityInputBase):
             self.channel_data.stream_id = self.id
         if hasattr(self.channel_data, "stream_type"):
             self.channel_data.stream_type = "final"
+        if hasattr(self.channel_data, "stream_sequence"):
+            self.channel_data.stream_sequence = None
 
         # Add stream info entity
         stream_entity = StreamInfoEntity(type="streaminfo", stream_id=self.id, stream_type="final")

{microsoft_teams_api-2.0.16 → microsoft_teams_api-2.1.0a2}/src/microsoft_teams/api/auth/__init__.py

@@ -10,11 +10,18 @@ from .cloud_environment import (
 )
 from .cloud_environment import from_name as config_from_cloud_name
 from .credentials import (
+    AgenticAppTokenProviderProtocol,
+    AgenticUserTokenProviderProtocol,
+    BasicTokenProvider,
     ClientCredentials,
     Credentials,
     FederatedIdentityCredentials,
     ManagedIdentityCredentials,
     TokenCredentials,
+    TokenProvider,
+    TokenProviderProtocol,
+    TokenResult,
+    TokenValue,
 )
 from .json_web_token import JsonWebToken, JsonWebTokenPayload
 from .token import TokenProtocol
@@ -23,12 +30,19 @@ __all__ = [
     "CallerIds",
     "CallerType",
     "CloudEnvironment",
+    "AgenticAppTokenProviderProtocol",
+    "AgenticUserTokenProviderProtocol",
+    "BasicTokenProvider",
     "ClientCredentials",
     "config_from_cloud_name",
     "Credentials",
     "FederatedIdentityCredentials",
     "ManagedIdentityCredentials",
     "TokenCredentials",
+    "TokenProvider",
+    "TokenProviderProtocol",
+    "TokenResult",
+    "TokenValue",
     "TokenProtocol",
     "JsonWebToken",
     "JsonWebTokenPayload",

{microsoft_teams_api-2.0.16 → microsoft_teams_api-2.1.0a2}/src/microsoft_teams/api/auth/cloud_environment.py

@@ -21,6 +21,8 @@ class CloudEnvironment:
     """The default multi-tenant login tenant (e.g. "botframework.com")."""
     bot_scope: str
     """The Bot Framework OAuth scope (e.g. "https://api.botframework.com/.default")."""
+    agent_bot_scope: str
+    """The Teams Bot API scope for Agent ID user-token calls."""
     token_service_url: str
     """The Bot Framework token service base URL (e.g. "https://token.botframework.com")."""
     openid_metadata_url: str
@@ -35,6 +37,7 @@ PUBLIC = CloudEnvironment(
     login_endpoint="https://login.microsoftonline.com",
     login_tenant="botframework.com",
     bot_scope="https://api.botframework.com/.default",
+    agent_bot_scope="https://botapi.skype.com/.default",
     token_service_url="https://token.botframework.com",
     openid_metadata_url="https://login.botframework.com/v1/.well-known/openidconfiguration",
     token_issuer="https://api.botframework.com",
@@ -46,6 +49,8 @@ US_GOV = CloudEnvironment(
     login_endpoint="https://login.microsoftonline.us",
     login_tenant="MicrosoftServices.onmicrosoft.us",
     bot_scope="https://api.botframework.us/.default",
+    # TODO: confirm Agent ID Bot API scope for this cloud before enabling sovereign Agent ID scenarios.
+    agent_bot_scope="https://botapi.skype.com/.default",
     token_service_url="https://tokengcch.botframework.azure.us",
     openid_metadata_url="https://login.botframework.azure.us/v1/.well-known/openidconfiguration",
     token_issuer="https://api.botframework.us",
@@ -57,6 +62,8 @@ US_GOV_DOD = CloudEnvironment(
     login_endpoint="https://login.microsoftonline.us",
     login_tenant="MicrosoftServices.onmicrosoft.us",
     bot_scope="https://api.botframework.us/.default",
+    # TODO: confirm Agent ID Bot API scope for this cloud before enabling sovereign Agent ID scenarios.
+    agent_bot_scope="https://botapi.skype.com/.default",
     token_service_url="https://apiDoD.botframework.azure.us",
     openid_metadata_url="https://login.botframework.azure.us/v1/.well-known/openidconfiguration",
     token_issuer="https://api.botframework.us",
@@ -68,6 +75,8 @@ CHINA = CloudEnvironment(
     login_endpoint="https://login.partner.microsoftonline.cn",
     login_tenant="microsoftservices.partner.onmschina.cn",
     bot_scope="https://api.botframework.azure.cn/.default",
+    # TODO: confirm Agent ID Bot API scope for this cloud before enabling China cloud Agent ID scenarios.
+    agent_bot_scope="https://botapi.skype.com/.default",
     token_service_url="https://token.botframework.azure.cn",
     openid_metadata_url="https://login.botframework.azure.cn/v1/.well-known/openidconfiguration",
     token_issuer="https://api.botframework.azure.cn",

{microsoft_teams_api-2.0.16 → microsoft_teams_api-2.1.0a2}/src/microsoft_teams/api/auth/credentials.py

@@ -3,9 +3,54 @@ Copyright (c) Microsoft Corporation. All rights reserved.
 Licensed under the MIT License.
 """
 
-from typing import Awaitable, Callable, Literal, Optional, Union
+from typing import Awaitable, Callable, Literal, Optional, Protocol, TypeAlias, Union, runtime_checkable
 
 from ..models import CustomBaseModel
+from .token import TokenProtocol
+
+TokenScope: TypeAlias = Union[str, list[str]]
+TokenValue: TypeAlias = Union[str, TokenProtocol, None]
+TokenResult: TypeAlias = Union[TokenValue, Awaitable[TokenValue]]
+BasicTokenProvider: TypeAlias = Callable[[TokenScope, Optional[str]], TokenResult]
+
+
+@runtime_checkable
+class TokenProviderProtocol(Protocol):
+    """Named token capabilities for apps that need more than app-only tokens."""
+
+    def get_app_token(
+        self,
+        scope: str,
+        tenant_id: Optional[str],
+    ) -> TokenResult: ...
+
+
+@runtime_checkable
+class AgenticUserTokenProviderProtocol(TokenProviderProtocol, Protocol):
+    """Optional named capability for acquiring agentic user-scoped tokens."""
+
+    def get_agentic_user_token(
+        self,
+        scope: str,
+        agentic_app_id: str,
+        agentic_user_id: str,
+        tenant_id: Optional[str],
+    ) -> TokenResult: ...
+
+
+@runtime_checkable
+class AgenticAppTokenProviderProtocol(TokenProviderProtocol, Protocol):
+    """Optional named capability for acquiring agentic app-scoped tokens."""
+
+    def get_agentic_app_token(
+        self,
+        scope: str,
+        agentic_app_id: str,
+        tenant_id: Optional[str],
+    ) -> TokenResult: ...
+
+
+TokenProvider: TypeAlias = Union[BasicTokenProvider, TokenProviderProtocol]
 
 
 class ClientCredentials(CustomBaseModel):
@@ -36,10 +81,9 @@ class TokenCredentials(CustomBaseModel):
     """
     The tenant ID.
     """
-    # (scope: string | string[], tenantId?: string) => string | Promise<string>
-    token: Callable[[Union[str, list[str]], Optional[str]], Union[str, Awaitable[str]]]
+    token: TokenProvider
     """
-    The token function.
+    A callable for app-only tokens, or a named token provider for app-only and agentic grants.
     """
 
 

{microsoft_teams_api-2.0.16 → microsoft_teams_api-2.1.0a2}/src/microsoft_teams/api/clients/__init__.py

@@ -4,7 +4,12 @@ Licensed under the MIT License.
 """
 
 from . import bot, conversation, meeting, reaction, team, user
-from .api_client import ApiClient
+from .api_client import (
+    AGENTIC_IDENTITY_CLEAR,
+    AgenticIdentityClear,
+    AgenticIdentityScope,
+    ApiClient,
+)
 from .api_client_settings import ApiClientSettings, merge_api_client_settings
 from .bot import *  # noqa: F403
 from .conversation import *  # noqa: F403
@@ -17,6 +22,9 @@ from .user import *  # noqa: F403
 __all__: list[str] = [
     "ApiClient",
     "ApiClientSettings",
+    "AGENTIC_IDENTITY_CLEAR",
+    "AgenticIdentityClear",
+    "AgenticIdentityScope",
     "merge_api_client_settings",
 ]
 __all__.extend(bot.__all__)