microsoft-agents-activity 0.5.0.dev5__py3-none-any.whl → 0.5.0.dev10__py3-none-any.whl

microsoft_agents/activity/__init__.py

@@ -1,3 +1,6 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
 from .agents_model import AgentsModel
 from .action_types import ActionTypes
 from .activity import Activity
@@ -17,6 +20,8 @@ from .card_action import CardAction
 from .card_image import CardImage
 from .channels import Channels
 from .channel_account import ChannelAccount
+from ._channel_id_field_mixin import _ChannelIdFieldMixin
+from .channel_id import ChannelId
 from .conversation_account import ConversationAccount
 from .conversation_members import ConversationMembers
 from .conversation_parameters import ConversationParameters
@@ -26,6 +31,7 @@ from .conversations_result import ConversationsResult
 from .expected_replies import ExpectedReplies
 from .entity import (
     Entity,
+    EntityTypes,
     AIEntity,
     ClientCitation,
     ClientCitationAppearance,
@@ -36,6 +42,7 @@ from .entity import (
     SensitivityPattern,
     GeoCoordinates,
     Place,
+    ProductInfo,
     Thing,
 )
 from .error import Error
@@ -115,6 +122,8 @@ __all__ = [
     "CardImage",
     "Channels",
     "ChannelAccount",
+    "ChannelId",
+    "_ChannelIdFieldMixin",
     "ConversationAccount",
     "ConversationMembers",
     "ConversationParameters",
@@ -145,6 +154,7 @@ __all__ = [
     "OAuthCard",
     "PagedMembersResult",
     "Place",
+    "ProductInfo",
     "ReceiptCard",
     "ReceiptItem",
     "ResourceResponse",

microsoft_agents/activity/_channel_id_field_mixin.py

@@ -0,0 +1,96 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+import logging
+from typing import Optional, Any
+
+from pydantic import (
+    ModelWrapValidatorHandler,
+    SerializerFunctionWrapHandler,
+    computed_field,
+    model_validator,
+    model_serializer,
+)
+
+from .channel_id import ChannelId
+
+logger = logging.getLogger(__name__)
+
+
+# can be generalized in the future, if needed
+class _ChannelIdFieldMixin:
+    """A mixin to add a computed field channel_id of type ChannelId to a Pydantic model."""
+
+    _channel_id: Optional[ChannelId] = None
+
+    # required to define the setter below
+    @computed_field(return_type=Optional[ChannelId], alias="channelId")
+    @property
+    def channel_id(self) -> Optional[ChannelId]:
+        """Gets the _channel_id field"""
+        return self._channel_id
+
+    # necessary for backward compatibility
+    # previously, channel_id was directly assigned with strings
+    @channel_id.setter
+    def channel_id(self, value: Any):
+        """Sets the channel_id after validating it as a ChannelId model."""
+        if isinstance(value, ChannelId):
+            self._channel_id = value
+        elif isinstance(value, str):
+            self._channel_id = ChannelId(value)
+        else:
+            raise ValueError(
+                f"Invalid type for channel_id: {type(value)}. "
+                "Expected ChannelId or str."
+            )
+
+    def _set_validated_channel_id(self, data: Any) -> None:
+        """Sets the channel_id after validating it as a ChannelId model."""
+        if "channelId" in data:
+            self.channel_id = data["channelId"]
+        elif "channel_id" in data:
+            self.channel_id = data["channel_id"]
+
+    @model_validator(mode="wrap")
+    @classmethod
+    def _validate_channel_id(
+        cls, data: Any, handler: ModelWrapValidatorHandler
+    ) -> _ChannelIdFieldMixin:
+        """Validate the _channel_id field after model initialization.
+
+        :return: The model instance itself.
+        """
+        try:
+            model = handler(data)
+            model._set_validated_channel_id(data)
+            return model
+        except Exception:
+            logging.error("Model %s failed to validate with data %s", cls, data)
+            raise
+
+    def _remove_serialized_unset_channel_id(
+        self, serialized: dict[str, object]
+    ) -> None:
+        """Remove the _channel_id field if it is not set."""
+        if not self._channel_id:
+            if "channelId" in serialized:
+                del serialized["channelId"]
+            elif "channel_id" in serialized:
+                del serialized["channel_id"]
+
+    @model_serializer(mode="wrap")
+    def _serialize_channel_id(
+        self, handler: SerializerFunctionWrapHandler
+    ) -> dict[str, object]:
+        """Serialize the model using Pydantic's standard serialization.
+
+        :param handler: The serialization handler provided by Pydantic.
+        :return: A dictionary representing the serialized model.
+        """
+        serialized = handler(self)
+        if self:  # serialization can be called with None
+            self._remove_serialized_unset_channel_id(serialized)
+        return serialized

microsoft_agents/activity/activity.py

@@ -1,10 +1,24 @@
 # Copyright (c) Microsoft Corporation. All rights reserved.
 # Licensed under the MIT License.
 
+from __future__ import annotations
+
+import logging
 from copy import copy
 from datetime import datetime, timezone
-from typing import Optional
-from pydantic import Field, SerializeAsAny
+from typing import Optional, Any
+
+from pydantic import (
+    Field,
+    SerializeAsAny,
+    model_serializer,
+    model_validator,
+    SerializerFunctionWrapHandler,
+    ModelWrapValidatorHandler,
+    computed_field,
+    ValidationError,
+)
+
 from .activity_types import ActivityTypes
 from .channel_account import ChannelAccount
 from .conversation_account import ConversationAccount
@@ -14,9 +28,11 @@ from .suggested_actions import SuggestedActions
 from .attachment import Attachment
 from .entity import (
     Entity,
+    EntityTypes,
     Mention,
     AIEntity,
     ClientCitation,
+    ProductInfo,
     SensitivityUsageInfo,
 )
 from .conversation_reference import ConversationReference
@@ -24,12 +40,16 @@ from .text_highlight import TextHighlight
 from .semantic_action import SemanticAction
 from .agents_model import AgentsModel
 from .role_types import RoleTypes
+from ._channel_id_field_mixin import _ChannelIdFieldMixin
+from .channel_id import ChannelId
 from ._model_utils import pick_model, SkipNone
 from ._type_aliases import NonEmptyString
 
+logger = logging.getLogger(__name__)
+
 
 # TODO: A2A Agent 2 is responding with None as id, had to mark it as optional (investigate)
-class Activity(AgentsModel):
+class Activity(AgentsModel, _ChannelIdFieldMixin):
     """An Activity is the basic communication type for the protocol.
 
     :param type: Contains the activity type. Possible values include:
@@ -50,8 +70,8 @@ class Activity(AgentsModel):
     :type local_timezone: str
     :param service_url: Contains the URL that specifies the channel's service endpoint. Set by the channel.
     :type service_url: str
-    :param channel_id: Contains an ID that uniquely identifies the channel. Set by the channel.
-    :type channel_id: str
+    :param channel_id: Contains an ID that uniquely identifies the channel (and possibly the sub-channel). Set by the channel.
+    :type channel_id: ~microsoft_agents.activity.ChannelId
     :param from_property: Identifies the sender of the message.
     :type from_property: ~microsoft_agents.activity.ChannelAccount
     :param conversation: Identifies the conversation to which the activity belongs.
@@ -136,7 +156,6 @@ class Activity(AgentsModel):
     local_timestamp: datetime = None
     local_timezone: NonEmptyString = None
     service_url: NonEmptyString = None
-    channel_id: NonEmptyString = None
     from_property: ChannelAccount = Field(None, alias="from")
     conversation: ConversationAccount = None
     recipient: ChannelAccount = None
@@ -173,6 +192,92 @@ class Activity(AgentsModel):
     semantic_action: SemanticAction = None
     caller_id: NonEmptyString = None
 
+    @model_validator(mode="wrap")
+    @classmethod
+    def _validate_channel_id(
+        cls, data: Any, handler: ModelWrapValidatorHandler[Activity]
+    ) -> Activity:
+        """Validate the Activity, ensuring consistency between channel_id.sub_channel and productInfo entity.
+
+        :param data: The input data to validate.
+        :param handler: The validation handler provided by Pydantic.
+        :return: The validated Activity instance.
+        """
+        try:
+            # run Pydantic's standard validation first
+            activity = handler(data)
+
+            # needed to assign to a computed field
+            # needed because we override the mixin validator
+            activity._set_validated_channel_id(data)
+
+            # sync sub_channel with productInfo entity
+            product_info = activity.get_product_info_entity()
+            if product_info and activity.channel_id:
+                if (
+                    activity.channel_id.sub_channel
+                    and activity.channel_id.sub_channel != product_info.id
+                ):
+                    raise Exception(
+                        "Conflict between channel_id.sub_channel and productInfo entity"
+                    )
+                activity.channel_id = ChannelId(
+                    channel=activity.channel_id.channel,
+                    sub_channel=product_info.id,
+                )
+
+            return activity
+        except ValidationError as exc:
+            logger.error("Validation error for Activity: %s", exc, exc_info=True)
+            raise
+
+    @model_serializer(mode="wrap")
+    def _serialize_sub_channel_data(
+        self, handler: SerializerFunctionWrapHandler
+    ) -> dict[str, object]:
+        """Serialize the Activity, ensuring consistency between channel_id.sub_channel and productInfo entity.
+
+        :param handler: The serialization handler provided by Pydantic.
+        :return: A dictionary representing the serialized Activity.
+        """
+
+        # run Pydantic's standard serialization first
+        serialized = handler(self)
+        if not self:  # serialization can be called with None
+            return serialized
+
+        # find the ProductInfo entity
+        product_info = None
+        for i, entity in enumerate(serialized.get("entities") or []):
+            if entity.get("type", "") == EntityTypes.PRODUCT_INFO:
+                product_info = entity
+                break
+
+        # maintain consistency between ProductInfo entity and sub channel
+        if self.channel_id and self.channel_id.sub_channel:
+            if product_info and product_info.get("id") != self.channel_id.sub_channel:
+                raise Exception(
+                    "Conflict between channel_id.sub_channel and productInfo entity"
+                )
+            elif not product_info:
+                if not serialized.get("entities"):
+                    serialized["entities"] = []
+                serialized["entities"].append(
+                    {
+                        "type": EntityTypes.PRODUCT_INFO,
+                        "id": self.channel_id.sub_channel,
+                    }
+                )
+        elif product_info:  # remove productInfo entity if sub_channel is not set
+            del serialized["entities"][i]
+            if not serialized["entities"]:  # after removal above, list may be empty
+                del serialized["entities"]
+
+        # necessary due to computed_field serialization
+        self._remove_serialized_unset_channel_id(serialized)
+
+        return serialized
+
     def apply_conversation_reference(
         self, reference: ConversationReference, is_incoming: bool = False
     ):
@@ -531,6 +636,14 @@ class Activity(AgentsModel):
             service_url=self.service_url,
         )
 
+    def get_product_info_entity(self) -> Optional[ProductInfo]:
+        if not self.entities:
+            return None
+        target = EntityTypes.PRODUCT_INFO.lower()
+        # validated entities can be Entity, and that prevents us from
+        # making assumptions about the casing of the 'type' attribute
+        return next(filter(lambda e: e.type.lower() == target, self.entities), None)
+
     def get_mentions(self) -> list[Mention]:
         """
         Resolves the mentions from the entities of this activity.
@@ -543,7 +656,7 @@ class Activity(AgentsModel):
         """
         if not self.entities:
             return []
-        return [x for x in self.entities if x.type.lower() == "mention"]
+        return [x for x in self.entities if x.type.lower() == EntityTypes.MENTION]
 
     def get_reply_conversation_reference(
         self, reply: ResourceResponse

microsoft_agents/activity/channel_id.py

@@ -0,0 +1,95 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+from typing import Optional, Any
+
+from pydantic_core import CoreSchema, core_schema
+from pydantic import GetCoreSchemaHandler
+
+
+class ChannelId(str):
+    """A ChannelId represents a channel and optional sub-channel in the format 'channel:sub_channel'."""
+
+    def __init__(
+        self,
+        value: Optional[str] = None,
+        *,
+        channel: Optional[str] = None,
+        sub_channel: Optional[str] = None,
+    ) -> None:
+        """Initialize a ChannelId instance.
+
+        :param value: The full channel ID string in the format 'channel:sub_channel'. Must be provided if channel is not provided.
+        :param channel: The main channel string. Must be provided if value is not provided.
+        :param sub_channel: The sub-channel string.
+        :raises ValueError: If the input parameters are invalid. value and channel cannot both be provided.
+        """
+        super().__init__()
+        if not channel:
+            split = self.strip().split(":", 1)
+            self._channel = split[0].strip()
+            self._sub_channel = split[1].strip() if len(split) == 2 else None
+        else:
+            self._channel = channel
+            self._sub_channel = sub_channel
+
+    def __new__(
+        cls,
+        value: Optional[str] = None,
+        *,
+        channel: Optional[str] = None,
+        sub_channel: Optional[str] = None,
+    ) -> ChannelId:
+        """Create a new ChannelId instance.
+
+        :param value: The full channel ID string in the format 'channel:sub_channel'. Must be provided if channel is not provided.
+        :param channel: The main channel string. Must be provided if value is not provided. Must not contain ':', as it delimits channels and sub channels.
+        :param sub_channel: The sub-channel string.
+        :return: A new ChannelId instance.
+        :raises ValueError: If the input parameters are invalid. value and channel cannot both be provided.
+        """
+        if isinstance(value, str):
+            if channel or sub_channel:
+                raise ValueError(
+                    "If value is provided, channel and sub_channel must be None"
+                )
+
+            value = value.strip()
+            if value:
+                return str.__new__(cls, value)
+            raise TypeError("value must be a non empty string if provided")
+        else:
+            if (
+                not isinstance(channel, str)
+                or len(channel.strip()) == 0
+                or ":" in channel
+            ):
+                raise TypeError(
+                    "channel must be a non empty string, and must not contain the ':' character"
+                )
+            if sub_channel is not None and (not isinstance(sub_channel, str)):
+                raise TypeError("sub_channel must be a string if provided")
+            channel = channel.strip()
+            sub_channel = sub_channel.strip() if sub_channel else None
+            if sub_channel:
+                return str.__new__(cls, f"{channel}:{sub_channel}")
+            return str.__new__(cls, channel)
+
+    @property
+    def channel(self) -> str:
+        """The main channel, e.g. 'email' in 'email:work'."""
+        return self._channel  # type: ignore[return-value]
+
+    @property
+    def sub_channel(self) -> Optional[str]:
+        """The sub-channel, e.g. 'work' in 'email:work'. May be None."""
+        return self._sub_channel
+
+    # https://docs.pydantic.dev/dev/concepts/types/#customizing-validation-with-__get_pydantic_core_schema__
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls, source_type: Any, handler: GetCoreSchemaHandler
+    ) -> CoreSchema:
+        return core_schema.no_info_after_validator_function(cls, handler(str))

microsoft_agents/activity/conversation_reference.py

@@ -1,20 +1,27 @@
 # Copyright (c) Microsoft Corporation. All rights reserved.
 # Licensed under the MIT License.
 
+from __future__ import annotations
+
 from uuid import uuid4 as uuid
 from typing import Optional
+import logging
 
 from pydantic import Field
 
 from .channel_account import ChannelAccount
+from ._channel_id_field_mixin import _ChannelIdFieldMixin
+from .channel_id import ChannelId
 from .conversation_account import ConversationAccount
 from .agents_model import AgentsModel
 from ._type_aliases import NonEmptyString
 from .activity_types import ActivityTypes
 from .activity_event_names import ActivityEventNames
 
+logger = logging.getLogger(__name__)
+
 
-class ConversationReference(AgentsModel):
+class ConversationReference(AgentsModel, _ChannelIdFieldMixin):
     """An object relating to a particular point in a conversation.
 
     :param activity_id: (Optional) ID of the activity to refer to
@@ -26,7 +33,7 @@ class ConversationReference(AgentsModel):
     :param conversation: Conversation reference
     :type conversation: ~microsoft_agents.activity.ConversationAccount
     :param channel_id: Channel ID
-    :type channel_id: str
+    :type channel_id: ~microsoft_agents.activity.ChannelId
     :param locale: A locale name for the contents of the text field.
         The locale name is a combination of an ISO 639 two- or three-letter
         culture code associated with a language and an ISO 3166 two-letter
@@ -43,7 +50,6 @@ class ConversationReference(AgentsModel):
     user: Optional[ChannelAccount] = None
     agent: ChannelAccount = Field(None, alias="bot")
     conversation: ConversationAccount
-    channel_id: NonEmptyString
     locale: Optional[NonEmptyString] = None
     service_url: NonEmptyString = None
 

microsoft_agents/activity/entity/__init__.py

@@ -1,5 +1,9 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
 from .mention import Mention
 from .entity import Entity
+from .entity_types import EntityTypes
 from .ai_entity import (
     ClientCitation,
     ClientCitationAppearance,
@@ -11,10 +15,12 @@ from .ai_entity import (
 )
 from .geo_coordinates import GeoCoordinates
 from .place import Place
+from .product_info import ProductInfo
 from .thing import Thing
 
 __all__ = [
     "Entity",
+    "EntityTypes",
     "AIEntity",
     "ClientCitation",
     "ClientCitationAppearance",
@@ -25,5 +31,6 @@ __all__ = [
     "SensitivityPattern",
     "GeoCoordinates",
     "Place",
+    "ProductInfo",
     "Thing",
 ]

microsoft_agents/activity/entity/entity.py

@@ -1,14 +1,12 @@
 # Copyright (c) Microsoft Corporation. All rights reserved.
 # Licensed under the MIT License.
 
-from typing import Any, Optional
-from enum import Enum
+from typing import Any
 
 from pydantic import model_serializer, model_validator
 from pydantic.alias_generators import to_camel, to_snake
 
 from ..agents_model import AgentsModel, ConfigDict
-from .._type_aliases import NonEmptyString
 
 
 class Entity(AgentsModel):

microsoft_agents/activity/entity/entity_types.py

@@ -0,0 +1,14 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from enum import Enum
+
+
+class EntityTypes(str, Enum):
+    """Well-known enumeration of entity types."""
+
+    GEO_COORDINATES = "GeoCoordinates"
+    MENTION = "mention"
+    PLACE = "Place"
+    THING = "Thing"
+    PRODUCT_INFO = "ProductInfo"

microsoft_agents/activity/entity/geo_coordinates.py

@@ -1,11 +1,14 @@
 # Copyright (c) Microsoft Corporation. All rights reserved.
 # Licensed under the MIT License.
 
-from ..agents_model import AgentsModel
+from typing import Literal
+
 from .._type_aliases import NonEmptyString
+from .entity import Entity
+from .entity_types import EntityTypes
 
 
-class GeoCoordinates(AgentsModel):
+class GeoCoordinates(Entity):
     """GeoCoordinates (entity type: "https://schema.org/GeoCoordinates").
 
     :param elevation: Elevation of the location [WGS
@@ -26,5 +29,5 @@ class GeoCoordinates(AgentsModel):
     elevation: float = None
     latitude: float = None
     longitude: float = None
-    type: NonEmptyString = None
+    type: Literal[EntityTypes.GEO_COORDINATES] = EntityTypes.GEO_COORDINATES
     name: NonEmptyString = None

microsoft_agents/activity/entity/mention.py

@@ -5,7 +5,7 @@ from typing import Literal
 
 from ..channel_account import ChannelAccount
 from .entity import Entity
-from .._type_aliases import NonEmptyString
+from .entity_types import EntityTypes
 
 
 class Mention(Entity):
@@ -21,4 +21,4 @@ class Mention(Entity):
 
     mentioned: ChannelAccount = None
     text: str = None
-    type: Literal["mention"] = "mention"
+    type: Literal[EntityTypes.MENTION] = EntityTypes.MENTION

microsoft_agents/activity/entity/place.py

@@ -1,11 +1,14 @@
 # Copyright (c) Microsoft Corporation. All rights reserved.
 # Licensed under the MIT License.
 
-from ..agents_model import AgentsModel
+from typing import Literal
+
 from .._type_aliases import NonEmptyString
+from .entity import Entity
+from .entity_types import EntityTypes
 
 
-class Place(AgentsModel):
+class Place(Entity):
     """Place (entity type: "https://schema.org/Place").
 
     :param address: Address of the place (may be `string` or complex object of
@@ -26,5 +29,5 @@ class Place(AgentsModel):
     address: object = None
     geo: object = None
     has_map: object = None
-    type: NonEmptyString = None
+    type: Literal[EntityTypes.PLACE] = EntityTypes.PLACE
     name: NonEmptyString = None

microsoft_agents/activity/entity/product_info.py

@@ -0,0 +1,20 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from typing import Literal
+
+from .entity import Entity
+from .entity_types import EntityTypes
+
+
+class ProductInfo(Entity):
+    """Product information (entity type: "productInfo").
+
+    :param type: The type of the entity, always "productInfo".
+    :type type: str
+    :param id: The unique identifier for the product.
+    :type id: str
+    """
+
+    type: Literal[EntityTypes.PRODUCT_INFO] = EntityTypes.PRODUCT_INFO
+    id: str = None

microsoft_agents/activity/entity/thing.py

@@ -1,11 +1,14 @@
 # Copyright (c) Microsoft Corporation. All rights reserved.
 # Licensed under the MIT License.
 
-from ..agents_model import AgentsModel
+from typing import Literal
+
 from .._type_aliases import NonEmptyString
+from .entity import Entity
+from .entity_types import EntityTypes
 
 
-class Thing(AgentsModel):
+class Thing(Entity):
     """Thing (entity type: "https://schema.org/Thing").
 
     :param type: The type of the thing
@@ -14,5 +17,5 @@ class Thing(AgentsModel):
     :type name: str
     """
 
-    type: NonEmptyString = None
+    type: Literal[EntityTypes.THING] = EntityTypes.THING
     name: NonEmptyString = None

microsoft_agents_activity-0.5.0.dev10.dist-info/METADATA

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: microsoft-agents-activity
+Version: 0.5.0.dev10
+Summary: A protocol library for Microsoft Agents
+Author: Microsoft Corporation
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/microsoft/Agents
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.10.4
+Dynamic: license-file
+
+# Microsoft Agents Activity
+
+[![PyPI version](https://img.shields.io/pypi/v/microsoft-agents-activity)](https://pypi.org/project/microsoft-agents-activity/)
+
+Core types and schemas for building conversational AI agents that work across Microsoft 365 platforms like Teams, Copilot Studio, and Webchat.
+
+# What is this?
+
+This library is part of the **Microsoft 365 Agents SDK for Python** - a comprehensive framework for building enterprise-grade conversational AI agents. The SDK enables developers to create intelligent agents that work across multiple platforms including Microsoft Teams, M365 Copilot, Copilot Studio, and web chat, with support for third-party integrations like Slack, Facebook Messenger, and Twilio.
+
+## Packages Overview
+
+We offer the following PyPI packages to create conversational experiences based on Agents:
+
+| Package Name | PyPI Version | Description |
+|--------------|-------------|-------------|
+| `microsoft-agents-activity` | [![PyPI](https://img.shields.io/pypi/v/microsoft-agents-activity)](https://pypi.org/project/microsoft-agents-activity/) | Types and validators implementing the Activity protocol spec. |
+| `microsoft-agents-hosting-core` | [![PyPI](https://img.shields.io/pypi/v/microsoft-agents-hosting-core)](https://pypi.org/project/microsoft-agents-hosting-core/) | Core library for Microsoft Agents hosting. |
+| `microsoft-agents-hosting-aiohttp` | [![PyPI](https://img.shields.io/pypi/v/microsoft-agents-hosting-aiohttp)](https://pypi.org/project/microsoft-agents-hosting-aiohttp/) | Configures aiohttp to run the Agent. |
+| `microsoft-agents-hosting-teams` | [![PyPI](https://img.shields.io/pypi/v/microsoft-agents-hosting-teams)](https://pypi.org/project/microsoft-agents-hosting-teams/) | Provides classes to host an Agent for Teams. |
+| `microsoft-agents-storage-blob` | [![PyPI](https://img.shields.io/pypi/v/microsoft-agents-storage-blob)](https://pypi.org/project/microsoft-agents-storage-blob/) | Extension to use Azure Blob as storage. |
+| `microsoft-agents-storage-cosmos` | [![PyPI](https://img.shields.io/pypi/v/microsoft-agents-storage-cosmos)](https://pypi.org/project/microsoft-agents-storage-cosmos/) | Extension to use CosmosDB as storage. |
+| `microsoft-agents-authentication-msal` | [![PyPI](https://img.shields.io/pypi/v/microsoft-agents-authentication-msal)](https://pypi.org/project/microsoft-agents-authentication-msal/) | MSAL-based authentication for Microsoft Agents. |
+
+Additionally we provide a Copilot Studio Client, to interact with Agents created in CopilotStudio:
+
+| Package Name | PyPI Version | Description |
+|--------------|-------------|-------------|
+| `microsoft-agents-copilotstudio-client` | [![PyPI](https://img.shields.io/pypi/v/microsoft-agents-copilotstudio-client)](https://pypi.org/project/microsoft-agents-copilotstudio-client/) | Direct to Engine client to interact with Agents created in CopilotStudio |
+
+## Architecture
+
+The SDK follows a modular architecture:
+- **Activity Layer**: Protocol definitions for cross-platform messaging
+- **Hosting Layer**: Core agent lifecycle, middleware, and web hosting
+- **Storage Layer**: Persistent state management with Azure backends
+- **Authentication Layer**: Secure identity and token management
+- **Integration Layer**: Platform-specific adapters (Teams, Copilot Studio)
+
+## Installation
+
+```bash
+pip install microsoft-agents-activity
+```
+
+## Quick Start
+Code below taken from the [Quick Start](https://github.com/microsoft/Agents/tree/main/samples/python/quickstart) sample.
+```python
+@AGENT_APP.conversation_update("membersAdded")
+async def on_members_added(context: TurnContext, _state: TurnState):
+    await context.send_activity(
+        "Welcome to the empty agent! "
+        "This agent is designed to be a starting point for your own agent development."
+    )
+    return True
+
+
+@AGENT_APP.message(re.compile(r"^hello$"))
+async def on_hello(context: TurnContext, _state: TurnState):
+    await context.send_activity("Hello!")
+
+
+@AGENT_APP.activity("message")
+async def on_message(context: TurnContext, _state: TurnState):
+    await context.send_activity(f"you said: {context.activity.text}")
+```
+
+## Common Use Cases
+
+### Rich Messages with Cards
+Code below taken from the [Cards](https://github.com/microsoft/Agents/tree/main/samples/python/cards) sample.
+
+
+```python
+    @staticmethod
+    async def send_animation_card(context: TurnContext):
+        card = CardFactory.animation_card(
+            AnimationCard(
+                title="Microsoft Agents Framework",
+                image=ThumbnailUrl(
+                    url="https://i.giphy.com/Ki55RUbOV5njy.gif", alt="Cute Robot"
+                ),
+                media=[MediaUrl(url="https://i.giphy.com/Ki55RUbOV5njy.gif")],
+                subtitle="Animation Card",
+                text="This is an example of an animation card using a gif.",
+                aspect="16:9",
+                duration="PT2M",
+            )
+        )
+        await CardMessages.send_activity(context, card)
+
+    @staticmethod
+    async def send_activity(context: TurnContext, card: Attachment):
+        activity = Activity(type=ActivityTypes.message, attachments=[card])
+        await context.send_activity(activity)
+```
+
+## Activity Types
+
+The library supports different types of communication:
+
+- **Message** - Regular chat messages with text, cards, attachments
+- **Typing** - Show typing indicators  
+- **ConversationUpdate** - People joining/leaving chats
+- **Event** - Custom events and notifications
+- **Invoke** - Direct function calls
+- **EndOfConversation** - End chat sessions
+
+## Key Features
+
+✅ **Type-safe** - Built with Pydantic for automatic validation  
+✅ **Rich content** - Support for cards, images, videos, and interactive elements  
+✅ **Teams ready** - Full Microsoft Teams integration  
+✅ **Cross-platform** - Works across all Microsoft 365 chat platforms  
+✅ **Migration friendly** - Easy upgrade from Bot Framework  
+
+# Quick Links
+
+- 📦 [All SDK Packages on PyPI](https://pypi.org/search/?q=microsoft-agents)
+- 📖 [Complete Documentation](https://aka.ms/agents)
+- 💡 [Python Samples Repository](https://github.com/microsoft/Agents/tree/main/samples/python)
+- 🐛 [Report Issues](https://github.com/microsoft/Agents-for-python/issues)
+
+# Sample Applications
+Explore working examples in the [Python samples repository](https://github.com/microsoft/Agents/tree/main/samples/python):
+
+|Name|Description|README|
+|----|----|----|
+|Quickstart|Simplest agent|[Quickstart](https://github.com/microsoft/Agents/blob/main/samples/python/quickstart/README.md)|
+|Auto Sign In|Simple OAuth agent using Graph and GitHub|[auto-signin](https://github.com/microsoft/Agents/blob/main/samples/python/auto-signin/README.md)|
+|OBO Authorization|OBO flow to access a Copilot Studio Agent|[obo-authorization](https://github.com/microsoft/Agents/blob/main/samples/python/obo-authorization/README.md)|
+|Semantic Kernel Integration|A weather agent built with Semantic Kernel|[semantic-kernel-multiturn](https://github.com/microsoft/Agents/blob/main/samples/python/semantic-kernel-multiturn/README.md)|
+|Streaming Agent|Streams OpenAI responses|[azure-ai-streaming](https://github.com/microsoft/Agents/blob/main/samples/python/azureai-streaming/README.md)|
+|Copilot Studio Client|Console app to consume a Copilot Studio Agent|[copilotstudio-client](https://github.com/microsoft/Agents/blob/main/samples/python/copilotstudio-client/README.md)|
+|Cards Agent|Agent that uses rich cards to enhance conversation design |[cards](https://github.com/microsoft/Agents/blob/main/samples/python/cards/README.md)|

{microsoft_agents_activity-0.5.0.dev5.dist-info → microsoft_agents_activity-0.5.0.dev10.dist-info}/RECORD

@@ -1,9 +1,10 @@
-microsoft_agents/activity/__init__.py,sha256=YOcBqmggcRMTr1JGEswCBMENn_CW2crgsGQY1dr2Elo,6093
+microsoft_agents/activity/__init__.py,sha256=BYUTF2A_YEw5Ql_hPS7MLBGEsmvey6vrMGh9hpsB7EA,6378
+microsoft_agents/activity/_channel_id_field_mixin.py,sha256=pFMfbN5EVrhO-7mFE-_8kT3yZ1zS6s9jyXoDGTLHT7g,3222
 microsoft_agents/activity/_load_configuration.py,sha256=ztmv1wOBDE9hUYPPzWexc-qi0eiBmxnay1skJpKVEcY,1125
 microsoft_agents/activity/_model_utils.py,sha256=gUAKCOl98jA9tt95o5G7LoMuHgROvrW6lY9s0CzQu6k,2004
 microsoft_agents/activity/_type_aliases.py,sha256=kP5tYxEKSgcgBT3bucdluVVxxopwrUaGqKL7X_TQ0Og,229
 microsoft_agents/activity/action_types.py,sha256=nslx3hvQAd120NPdXZXdprwdjj3I3d4MWXV1b-Igr_o,419
-microsoft_agents/activity/activity.py,sha256=hLtPg9-nt7o0M_jUzkiAw7EfNOlqkAbvvBEDDt-cjCA,28002
+microsoft_agents/activity/activity.py,sha256=fOzNz7wVmgWcbEt2nomXEezshwmiNYQEo64z9kUJM2c,32377
 microsoft_agents/activity/activity_event_names.py,sha256=dmtE1w50nnemTC_s1QG7IqTbnocpiczK_CG31JpgoJ4,254
 microsoft_agents/activity/activity_importance.py,sha256=cRIlyz8EjmztPmfcgdqZ6Csp6Vp2rQhXt4ZWIDXdt_s,212
 microsoft_agents/activity/activity_types.py,sha256=dm4vTVSoa-8_aPY_kZuU6C_FWQAURgZRassR1o8o9qQ,762
@@ -24,12 +25,13 @@ microsoft_agents/activity/card_action.py,sha256=-c9VLUNVrRx1wYCSiCueZRvWOO5nWOA6
 microsoft_agents/activity/card_image.py,sha256=2DCOErbmGm8dRhJrYhxDweQgH0ys-5_cRISxgJ7hx9k,640
 microsoft_agents/activity/channel_account.py,sha256=2M5K1NJl1GTttYNI65OQBvxLcgGzx9B7bJhjdTHRsgo,1217
 microsoft_agents/activity/channel_adapter_protocol.py,sha256=CQU9FhsR5UCzRib8DJVj9DO0131QB9Kn5euhHRKGCf4,2135
+microsoft_agents/activity/channel_id.py,sha256=m59mGBfHQ5g3AdK2p_kMxIm9pC--okgOz3wopTmxFMs,3814
 microsoft_agents/activity/channels.py,sha256=UC5MDF5C4PbW29rJhtXzfjA-4y4VqPXi1nK8oCmHM0o,4560
 microsoft_agents/activity/contact_relation_update_action_types.py,sha256=6RIJbnVmr8agTPYYw84xTH9rx88QE0dvMbNwC0cpcG0,208
 microsoft_agents/activity/conversation_account.py,sha256=fOU9PgxnH8NsHIZDiESU22Ph3oEE0PMnLbKYuz3vgYA,1536
 microsoft_agents/activity/conversation_members.py,sha256=6-kBKO3W7rtpG1sbhKX5T6FDBDlQDzXdIIpjQALw1K4,552
 microsoft_agents/activity/conversation_parameters.py,sha256=JwsoZeml90q8W_ngYBao218-q1FIMSAbIf3yUXz3yAg,1475
-microsoft_agents/activity/conversation_reference.py,sha256=1Iyx4JeaZOWZvbLS0L1yYwnwRKZASzOASrFXYhyLqEo,2452
+microsoft_agents/activity/conversation_reference.py,sha256=hcWDW8oi18KDX4HCcMfEOcsa9IJgj-_ymXPbg49LGsY,2657
 microsoft_agents/activity/conversation_resource_response.py,sha256=du_lE0AFPo_PEWj2a5gilsYFD8wfDidPh9LmUHQJVyA,652
 microsoft_agents/activity/conversation_update_types.py,sha256=l57bE-oXKEYyrTLPmcYCioZD_VSfXQLUl9l29Pkw_7w,568
 microsoft_agents/activity/conversations_result.py,sha256=GK_l5ou-veMnM7eQgiTQ1eUnf52KKEi6okUzf_ybeNc,617
@@ -78,13 +80,15 @@ microsoft_agents/activity/token_status.py,sha256=o3pGTKRjuqEndRWClMe91Cmox6cW8aD
 microsoft_agents/activity/transcript.py,sha256=vV0p-JEt62UPp3D4gmz1Fn1vq45vpjc01x2p5iCzKsw,423
 microsoft_agents/activity/turn_context_protocol.py,sha256=S1lJi_pT-o3w0RNB9p4WDiOEL7SHBf_gojRfY9CBwF4,1787
 microsoft_agents/activity/video_card.py,sha256=6ZYvTYCsIsACbR3KJBhfwFJ1GTYbjKJWvBsqw0pyyWA,2048
-microsoft_agents/activity/entity/__init__.py,sha256=WqUL3e79ifcn8UhHVIHcSqQ6MHaEEyGgKi3v65-jQls,617
+microsoft_agents/activity/entity/__init__.py,sha256=nq9ySwflvNeFWKxZmvb4XenYwB_ATDbeOikkk860UfY,826
 microsoft_agents/activity/entity/ai_entity.py,sha256=VOjU9Y6m68vkiKUHnqG5XmNPRu4KCSKmd0XPDCJ6B0s,3280
-microsoft_agents/activity/entity/entity.py,sha256=AyAigxMH1M966G7gn6BHgjztuaKJLZcdJ5WfyJZsn6A,1180
-microsoft_agents/activity/entity/geo_coordinates.py,sha256=N-90kqHX1I04U4rju5WVPMiVaV4EGMfS0bs5C4sX6qM,986
-microsoft_agents/activity/entity/mention.py,sha256=1OEmnzNJ9me5dbVwCxjFLFwmj1Ubc9-kDQHuBiuC2Ks,699
-microsoft_agents/activity/entity/place.py,sha256=SskI7KzQ8YHCAahOUYDdKnMxWNgLCc76kzPl-DcHfJk,921
-microsoft_agents/activity/entity/thing.py,sha256=r2LTZ1Ytp8oau56FaWgniNEszn-TWTP-U-lNb3lS-Mo,453
+microsoft_agents/activity/entity/entity.py,sha256=FmJ23emzoEiV66JjpkOwCQoJReFB_5whihj3PFdRtKk,1105
+microsoft_agents/activity/entity/entity_types.py,sha256=_oqG6O2Ds0BHmY65KN_elaXly6rporMmUYcaWEjqi3s,336
+microsoft_agents/activity/entity/geo_coordinates.py,sha256=xLc8SGGmjmJL3m-ionTicC_rL4x09_0hWa28Ed5JKLs,1080
+microsoft_agents/activity/entity/mention.py,sha256=Gpjy4o7_5EQ1flkADPMzJw6nOU92uzf5Gt54Rj7Oi-c,714
+microsoft_agents/activity/entity/place.py,sha256=uw-YUdbhkgawjor92vZwz7qmdcSIVDhYG0L5CphfFrI,995
+microsoft_agents/activity/entity/product_info.py,sha256=bFacwylgKbLuebM5zVpMyud32SCvH6_pJ4n6_wWYMdg,529
+microsoft_agents/activity/entity/thing.py,sha256=u-uWCHgZrrjh_d7pje1GszNmiDfLRKbM26PJnel8Ye8,527
 microsoft_agents/activity/teams/__init__.py,sha256=pdcnd_Ud92Eox_fHSgm1kwzwFmG8LVeatF9MRI8IaVY,8532
 microsoft_agents/activity/teams/app_based_link_query.py,sha256=-2uuPbyElN0DbU5R_mTJ_o7jphBNFr1ZFlLeziXuxn0,462
 microsoft_agents/activity/teams/batch_failed_entries_response.py,sha256=Q6Mgbdu_OdFGEKmaMu3jr71BSfwNtAgCMLyDSrfLf7I,439
@@ -192,8 +196,8 @@ microsoft_agents/activity/teams/teams_member.py,sha256=vRcLRHy6wTfH7DP6k6QbrKkOR
 microsoft_agents/activity/teams/teams_paged_members_result.py,sha256=cG4eKHjA0u1EMioC2ErVpydnoPJrtTDcdhdzYET9xto,555
 microsoft_agents/activity/teams/tenant_info.py,sha256=h8OxMd6LD5lWVj_LK2ut8z7SB0I7Gx74W1wwEiYOzXk,296
 microsoft_agents/activity/teams/user_meeting_details.py,sha256=tvk2CWYf7Bo-DhK8NSojhanJDXEOGVrKXxJDca03CAo,467
-microsoft_agents_activity-0.5.0.dev5.dist-info/licenses/LICENSE,sha256=ws_MuBL-SCEBqPBFl9_FqZkaaydIJmxHrJG2parhU4M,1141
-microsoft_agents_activity-0.5.0.dev5.dist-info/METADATA,sha256=wDn9lOzwvLHG2YadGcmwxWIn989eF5e2lWimTdPUGck,430
-microsoft_agents_activity-0.5.0.dev5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-microsoft_agents_activity-0.5.0.dev5.dist-info/top_level.txt,sha256=lWKcT4v6fTA_NgsuHdNvuMjSrkiBMXohn64ApY7Xi8A,17
-microsoft_agents_activity-0.5.0.dev5.dist-info/RECORD,,
+microsoft_agents_activity-0.5.0.dev10.dist-info/licenses/LICENSE,sha256=ws_MuBL-SCEBqPBFl9_FqZkaaydIJmxHrJG2parhU4M,1141
+microsoft_agents_activity-0.5.0.dev10.dist-info/METADATA,sha256=p9kymyEI4VhcE2XdeZJsbUVe0v4aDMmVBKMQNPKkXHU,8071
+microsoft_agents_activity-0.5.0.dev10.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+microsoft_agents_activity-0.5.0.dev10.dist-info/top_level.txt,sha256=lWKcT4v6fTA_NgsuHdNvuMjSrkiBMXohn64ApY7Xi8A,17
+microsoft_agents_activity-0.5.0.dev10.dist-info/RECORD,,

microsoft_agents_activity-0.5.0.dev5.dist-info/METADATA

@@ -1,13 +0,0 @@
-Metadata-Version: 2.4
-Name: microsoft-agents-activity
-Version: 0.5.0.dev5
-Summary: A protocol library for Microsoft Agents
-Author: Microsoft Corporation
-License-Expression: MIT
-Project-URL: Homepage, https://github.com/microsoft/Agents
-Classifier: Programming Language :: Python :: 3
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.9
-License-File: LICENSE
-Requires-Dist: pydantic>=2.10.4
-Dynamic: license-file