microsoft-agents-hosting-core 0.9.0.dev10__tar.gz → 0.10.0.dev0__tar.gz

{microsoft_agents_hosting_core-0.9.0.dev10/microsoft_agents_hosting_core.egg-info → microsoft_agents_hosting_core-0.10.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: microsoft-agents-hosting-core
-Version: 0.9.0.dev10
+Version: 0.10.0.dev0
 Summary: Core library for Microsoft Agents
 Author: Microsoft Corporation
 License-Expression: MIT
@@ -15,7 +15,7 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: microsoft-agents-activity==0.9.0.dev10
+Requires-Dist: microsoft-agents-activity==0.10.0.dev0
 Requires-Dist: pyjwt>=2.10.1
 Requires-Dist: isodate>=0.6.1
 Requires-Dist: azure-core>=1.30.0
@@ -43,6 +43,15 @@ This library is part of the **Microsoft 365 Agents SDK for Python** - a comprehe
     <th style="width:20%">Date</th>
     <th style="width:60%">Release Notes</th>
   </tr>
+  <tr>
+    <td>0.9.0</td>
+    <td>2026-04-15</td>
+    <td>
+      <a href="https://github.com/microsoft/Agents-for-python/blob/main/changelog.md#microsoft-365-agents-sdk-for-python---release-notes-v090">
+        0.9.0 Release Notes
+      </a>
+    </td>
+  </tr>
   <tr>
     <td>0.8.0</td>
     <td>2026-02-23</td>

microsoft_agents_hosting_core-0.10.0.dev0/VERSION.txt

@@ -0,0 +1 @@
+0.10.0.dev0

{microsoft_agents_hosting_core-0.9.0.dev10 → microsoft_agents_hosting_core-0.10.0.dev0}/microsoft_agents/hosting/core/app/__init__.py

@@ -21,6 +21,16 @@ from .oauth import (
     AgenticUserAuthorization,
 )
 
+# Proactive
+from .proactive import (
+    Conversation,
+    ConversationBuilder,
+    ConversationReferenceBuilder,
+    CreateConversationOptions,
+    Proactive,
+    ProactiveOptions,
+)
+
 # App State
 from .state.conversation_state import ConversationState
 from .state.state import State, StatePropertyAccessor, state
@@ -47,4 +57,11 @@ __all__ = [
     "Authorization",
     "AuthHandler",
     "AgenticUserAuthorization",
+    # Proactive
+    "Conversation",
+    "ConversationBuilder",
+    "ConversationReferenceBuilder",
+    "CreateConversationOptions",
+    "Proactive",
+    "ProactiveOptions",
 ]

{microsoft_agents_hosting_core-0.9.0.dev10 → microsoft_agents_hosting_core-0.10.0.dev0}/microsoft_agents/hosting/core/app/agent_application.py

@@ -45,6 +45,7 @@ from .telemetry import spans
 
 from ._type_defs import RouteHandler, RouteSelector
 from ._routes import _RouteList, _Route, RouteRank, _agentic_selector
+from .proactive import Proactive, ProactiveOptions
 
 logger = logging.getLogger(__name__)
 
@@ -69,6 +70,7 @@ class AgentApplication(Agent, Generic[StateT]):
     _options: ApplicationOptions
     _adapter: Optional[ChannelServiceAdapter] = None
     _auth: Optional[Authorization] = None
+    _proactive: Optional[Proactive] = None
     _internal_before_turn: list[Callable[[TurnContext, StateT], Awaitable[bool]]] = []
     _internal_after_turn: list[Callable[[TurnContext, StateT], Awaitable[bool]]] = []
     _route_list: _RouteList[StateT] = _RouteList[StateT]()
@@ -147,6 +149,12 @@ class AgentApplication(Agent, Generic[StateT]):
             or partial(TurnState.with_storage, self._options.storage)
         )
 
+        if options.proactive:
+            proactive_opts = copy(options.proactive)
+            if not proactive_opts.storage:
+                proactive_opts.storage = self._options.storage
+            self._proactive = Proactive(self, proactive_opts)
+
         # TODO: decide how to initialize the Authorization (params vs options vs kwargs)
         if authorization:
             self._auth = authorization
@@ -216,6 +224,26 @@ class AgentApplication(Agent, Generic[StateT]):
         """
         return self._options
 
+    @property
+    def proactive(self) -> Proactive:
+        """
+        The application's proactive messaging manager.
+
+        :return: The proactive messaging manager.
+        :rtype: :class:`microsoft_agents.hosting.core.app.proactive.proactive.Proactive`
+        :raises ApplicationError: If proactive options were not configured.
+        """
+        if not self._proactive:
+            logger.error(
+                "AgentApplication.proactive(): proactive options are not configured.",
+                stack_info=True,
+            )
+            raise ApplicationError("""
+                The `AgentApplication.proactive` property is unavailable because
+                no ProactiveOptions were configured in ApplicationOptions.
+                """)
+        return self._proactive
+
     def add_route(
         self,
         selector: RouteSelector,

{microsoft_agents_hosting_core-0.9.0.dev10 → microsoft_agents_hosting_core-0.10.0.dev0}/microsoft_agents/hosting/core/app/app_options.py

@@ -17,6 +17,7 @@ from .input_file import InputFileDownloader
 from ..channel_service_adapter import ChannelServiceAdapter
 
 from .state.turn_state import TurnState
+from .proactive.proactive_options import ProactiveOptions
 
 # from .teams_adapter import TeamsAdapter
 
@@ -89,3 +90,10 @@ class ApplicationOptions:
     Optional. Authorization handler for OAuth flows.
     If not provided, no OAuth flows will be supported.
     """
+
+    proactive: Optional[ProactiveOptions] = None
+    """
+    Optional. Options for the proactive messaging subsystem.
+    When set, :attr:`AgentApplication.proactive` is available for storing
+    conversations and initiating proactive turns.
+    """

{microsoft_agents_hosting_core-0.9.0.dev10 → microsoft_agents_hosting_core-0.10.0.dev0}/microsoft_agents/hosting/core/app/oauth/telemetry/constants.py

@@ -3,5 +3,5 @@
 
 AGENTIC_TOKEN = "agents.authorization.agentic_token"
 AZURE_BOT_TOKEN = "agents.authorization.azure_bot_token"
-AZURE_BOT_SIGN_OUT = "agents.authorization.azure_bot_sign_out"
-AZURE_BOT_SIGN_IN = "agents.authorization.azure_bot_sign_in"
+AZURE_BOT_SIGN_OUT = "agents.authorization.azure_bot_signout"
+AZURE_BOT_SIGN_IN = "agents.authorization.azure_bot_signin"

microsoft_agents_hosting_core-0.10.0.dev0/microsoft_agents/hosting/core/app/proactive/__init__.py

@@ -0,0 +1,20 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from .conversation import Conversation
+from .conversation_builder import ConversationBuilder
+from .conversation_reference_builder import ConversationReferenceBuilder
+from .create_conversation_options import CreateConversationOptions
+from .proactive import Proactive
+from .proactive_options import ProactiveOptions
+
+__all__ = [
+    "Conversation",
+    "ConversationBuilder",
+    "ConversationReferenceBuilder",
+    "CreateConversationOptions",
+    "Proactive",
+    "ProactiveOptions",
+]

microsoft_agents_hosting_core-0.10.0.dev0/microsoft_agents/hosting/core/app/proactive/conversation.py

@@ -0,0 +1,152 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+from typing import Optional, TYPE_CHECKING
+
+from microsoft_agents.activity import ConversationReference
+from microsoft_agents.hosting.core.authorization import ClaimsIdentity
+from microsoft_agents.hosting.core.storage.store_item import StoreItem
+
+if TYPE_CHECKING:
+    from microsoft_agents.hosting.core.turn_context import TurnContext
+    from microsoft_agents.hosting.core.channel_adapter import ChannelAdapter
+
+# JWT claim keys that are persisted alongside a ConversationReference.
+_PERSISTED_CLAIM_KEYS = frozenset({"aud", "azp", "appid", "idtyp", "ver", "iss", "tid"})
+
+
+class Conversation(StoreItem):
+    """
+    Bundles a :class:`~microsoft_agents.activity.ConversationReference` together
+    with a filtered set of JWT claims so that a proactive continuation can be
+    performed without holding onto the full :class:`~microsoft_agents.hosting.core.authorization.ClaimsIdentity`.
+
+    Instances are typically created via
+    :meth:`~microsoft_agents.hosting.core.app.proactive.conversation_builder.ConversationBuilder`
+    or via :meth:`from_turn_context`.
+
+    :param claims: Filtered JWT claims (``aud``, ``azp``, ``appid``, ``idtyp``,
+        ``ver``, ``iss``, ``tid``).  May be a raw ``dict`` or a
+        :class:`~microsoft_agents.hosting.core.authorization.ClaimsIdentity`.
+    :type claims: dict[str, str] or ClaimsIdentity
+    :param conversation_reference: The conversation reference.
+    :type conversation_reference: :class:`~microsoft_agents.activity.ConversationReference`
+    """
+
+    def __init__(
+        self,
+        claims: "dict[str, str] | ClaimsIdentity",
+        conversation_reference: ConversationReference,
+    ) -> None:
+        if isinstance(claims, ClaimsIdentity):
+            self.claims: dict[str, str] = Conversation.claims_from_identity(claims)
+        else:
+            self.claims = {
+                k: v for k, v in claims.items() if k in _PERSISTED_CLAIM_KEYS
+            }
+        self.conversation_reference: ConversationReference = conversation_reference
+
+    # ------------------------------------------------------------------
+    # Factory helpers
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def from_turn_context(cls, context: "TurnContext") -> "Conversation":
+        """
+        Create a :class:`Conversation` from the current turn context.
+
+        :param context: The active turn context.
+        :type context: :class:`~microsoft_agents.hosting.core.turn_context.TurnContext`
+        :return: A new :class:`Conversation` capturing the current turn's identity
+            and conversation reference.
+        :rtype: :class:`Conversation`
+        """
+        from microsoft_agents.hosting.core.channel_adapter import ChannelAdapter
+
+        identity: Optional[ClaimsIdentity] = context.turn_state.get(
+            ChannelAdapter.AGENT_IDENTITY_KEY
+        )
+        reference = context.activity.get_conversation_reference()
+        return cls(identity or {}, reference)
+
+    # ------------------------------------------------------------------
+    # Claims helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def claims_from_identity(identity: ClaimsIdentity) -> "dict[str, str]":
+        """
+        Return the subset of claims from *identity* that are relevant for proactive
+        messaging (``aud``, ``azp``, ``appid``, ``idtyp``, ``ver``, ``iss``, ``tid``).
+
+        :param identity: The full claims identity.
+        :type identity: :class:`~microsoft_agents.hosting.core.authorization.ClaimsIdentity`
+        :return: Filtered claims dictionary.
+        :rtype: dict[str, str]
+        """
+        return {k: v for k, v in identity.claims.items() if k in _PERSISTED_CLAIM_KEYS}
+
+    @staticmethod
+    def identity_from_claims(claims: "dict[str, str]") -> ClaimsIdentity:
+        """
+        Reconstruct a :class:`~microsoft_agents.hosting.core.authorization.ClaimsIdentity`
+        from a previously persisted claims dict.
+
+        :param claims: Filtered claims dictionary (as produced by :meth:`claims_from_identity`).
+        :type claims: dict[str, str]
+        :return: Reconstituted claims identity.
+        :rtype: :class:`~microsoft_agents.hosting.core.authorization.ClaimsIdentity`
+        """
+        return ClaimsIdentity(claims=dict(claims), is_authenticated=True)
+
+    # ------------------------------------------------------------------
+    # Validation
+    # ------------------------------------------------------------------
+
+    def validate(self) -> None:
+        """
+        Raise :exc:`ValueError` if required fields are missing.
+
+        :raises ValueError: If ``conversation_reference``, its nested
+            ``conversation``, or ``service_url`` are absent.
+        """
+        if not self.conversation_reference:
+            raise ValueError("Conversation.conversation_reference is required.")
+        if not self.conversation_reference.conversation:
+            raise ValueError(
+                "Conversation.conversation_reference.conversation is required."
+            )
+        if not self.conversation_reference.conversation.id:
+            raise ValueError(
+                "Conversation.conversation_reference.conversation.id is required."
+            )
+        if not self.conversation_reference.service_url:
+            raise ValueError(
+                "Conversation.conversation_reference.service_url is required."
+            )
+
+    # ------------------------------------------------------------------
+    # StoreItem serialization
+    # ------------------------------------------------------------------
+
+    def store_item_to_json(self) -> dict:
+        return {
+            "claims": self.claims,
+            "conversation_reference": self.conversation_reference.model_dump(
+                mode="json", by_alias=True, exclude_unset=True
+            ),
+        }
+
+    @staticmethod
+    def from_json_to_store_item(json_data: dict) -> "Conversation":
+        reference = ConversationReference.model_validate(
+            json_data.get("conversation_reference", {})
+        )
+        return Conversation(
+            claims=json_data.get("claims", {}),
+            conversation_reference=reference,
+        )

microsoft_agents_hosting_core-0.10.0.dev0/microsoft_agents/hosting/core/app/proactive/conversation_builder.py

@@ -0,0 +1,237 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from microsoft_agents.activity import (
+    ChannelAccount,
+    Channels,
+    ConversationAccount,
+    ConversationReference,
+)
+from microsoft_agents.hosting.core.authorization import ClaimsIdentity
+
+from .conversation import Conversation
+from .conversation_reference_builder import _service_url_for_channel
+
+
+class ConversationBuilder:
+    """
+    Fluent builder for :class:`~microsoft_agents.hosting.core.app.proactive.conversation.Conversation`.
+
+    Typical usage — building from a minimal set of claims::
+
+        conversation = (
+            ConversationBuilder
+            .create("agent-app-id", "msteams", service_url="https://smba.trafficmanager.net/teams/")
+            .with_user("user-aad-oid", "User Display Name")
+            .with_conversation("19:thread-id@thread.v2")
+            .build()
+        )
+
+    Or from an existing :class:`~microsoft_agents.hosting.core.authorization.ClaimsIdentity`::
+
+        conversation = (
+            ConversationBuilder
+            .create_from_identity(claims_identity, "msteams")
+            .with_conversation("19:thread-id@thread.v2")
+            .build()
+        )
+    """
+
+    def __init__(self) -> None:
+        self._claims: dict[str, str] = {}
+        self._channel_id: Optional[str] = None
+        self._service_url: Optional[str] = None
+        self._agent_id: Optional[str] = None
+        self._agent_name: Optional[str] = None
+        self._user_id: Optional[str] = None
+        self._user_name: Optional[str] = None
+        self._conversation_id: Optional[str] = None
+        self._conversation_name: Optional[str] = None
+        self._tenant_id: Optional[str] = None
+        self._activity_id: Optional[str] = None
+
+    # ------------------------------------------------------------------
+    # Entry-point factories
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def create(
+        cls,
+        agent_client_id: str,
+        channel_id: str,
+        service_url: Optional[str] = None,
+        requestor_id: Optional[str] = None,
+    ) -> "ConversationBuilder":
+        """
+        Start building a :class:`~microsoft_agents.hosting.core.app.proactive.conversation.Conversation`
+        from a minimal set of claims.
+
+        :param agent_client_id: The agent's AAD application ID (becomes the ``aud``
+            claim and optionally the ``appid`` claim).
+        :type agent_client_id: str
+        :param channel_id: The channel identifier (e.g. ``"msteams"``).
+        :type channel_id: str
+        :param service_url: Override the service URL.  Defaults to the canonical
+            URL for *channel_id*.
+        :type service_url: Optional[str]
+        :param requestor_id: If provided, stored as the ``appid`` claim (useful
+            when the requestor differs from the audience).
+        :type requestor_id: Optional[str]
+        :return: A builder pre-populated with the supplied claims.
+        :rtype: :class:`ConversationBuilder`
+        """
+        builder = cls()
+        builder._channel_id = channel_id
+        builder._service_url = service_url or _service_url_for_channel(channel_id)
+        builder._claims["aud"] = agent_client_id
+        if requestor_id:
+            builder._claims["appid"] = requestor_id
+
+        # Set agent ID with Teams prefix if needed.
+        if channel_id == Channels.ms_teams or channel_id == "msteams":
+            builder._agent_id = f"28:{agent_client_id}"
+        else:
+            builder._agent_id = agent_client_id
+
+        return builder
+
+    @classmethod
+    def create_from_identity(
+        cls,
+        identity: ClaimsIdentity,
+        channel_id: str,
+        service_url: Optional[str] = None,
+    ) -> "ConversationBuilder":
+        """
+        Start building a :class:`~microsoft_agents.hosting.core.app.proactive.conversation.Conversation`
+        from a full :class:`~microsoft_agents.hosting.core.authorization.ClaimsIdentity`.
+
+        :param identity: The claims identity to extract claims from.
+        :type identity: :class:`~microsoft_agents.hosting.core.authorization.ClaimsIdentity`
+        :param channel_id: The channel identifier.
+        :type channel_id: str
+        :param service_url: Override the service URL.
+        :type service_url: Optional[str]
+        :return: A builder pre-populated with the identity's claims.
+        :rtype: :class:`ConversationBuilder`
+        """
+        builder = cls()
+        builder._channel_id = channel_id
+        builder._service_url = service_url or _service_url_for_channel(channel_id)
+        builder._claims = Conversation.claims_from_identity(identity)
+
+        app_id = identity.get_app_id()
+        if app_id:
+            if channel_id == Channels.ms_teams or channel_id == "msteams":
+                builder._agent_id = f"28:{app_id}"
+            else:
+                builder._agent_id = app_id
+
+        return builder
+
+    # ------------------------------------------------------------------
+    # Fluent setters
+    # ------------------------------------------------------------------
+
+    def with_user(
+        self,
+        user_id: str,
+        user_name: Optional[str] = None,
+    ) -> "ConversationBuilder":
+        """
+        Set the user account.
+
+        :param user_id: The user's channel account ID.
+        :type user_id: str
+        :param user_name: Optional display name.
+        :type user_name: Optional[str]
+        :return: ``self`` for chaining.
+        :rtype: :class:`ConversationBuilder`
+        """
+        self._user_id = user_id
+        self._user_name = user_name
+        return self
+
+    def with_conversation(
+        self,
+        conversation_id: str,
+        conversation_name: Optional[str] = None,
+        tenant_id: Optional[str] = None,
+    ) -> "ConversationBuilder":
+        """
+        Set the conversation account details.
+
+        :param conversation_id: The conversation ID.
+        :type conversation_id: str
+        :param conversation_name: Optional conversation name.
+        :type conversation_name: Optional[str]
+        :param tenant_id: Optional tenant ID.
+        :type tenant_id: Optional[str]
+        :return: ``self`` for chaining.
+        :rtype: :class:`ConversationBuilder`
+        """
+        self._conversation_id = conversation_id
+        self._conversation_name = conversation_name
+        self._tenant_id = tenant_id
+        return self
+
+    def with_activity_id(self, activity_id: str) -> "ConversationBuilder":
+        """
+        Set the activity ID on the underlying conversation reference.
+
+        :param activity_id: The activity ID.
+        :type activity_id: str
+        :return: ``self`` for chaining.
+        :rtype: :class:`ConversationBuilder`
+        """
+        self._activity_id = activity_id
+        return self
+
+    # ------------------------------------------------------------------
+    # Build
+    # ------------------------------------------------------------------
+
+    def build(self) -> Conversation:
+        """
+        Construct the :class:`~microsoft_agents.hosting.core.app.proactive.conversation.Conversation`.
+
+        :raises ValueError: If required fields (``channel_id``, ``conversation_id``) are missing.
+        :return: The built :class:`~microsoft_agents.hosting.core.app.proactive.conversation.Conversation`.
+        :rtype: :class:`~microsoft_agents.hosting.core.app.proactive.conversation.Conversation`
+        """
+        if not self._channel_id:
+            raise ValueError("ConversationBuilder: channel_id is required.")
+        if not self._conversation_id:
+            raise ValueError("ConversationBuilder: conversation_id is required.")
+
+        agent = (
+            ChannelAccount(id=self._agent_id, name=self._agent_name)
+            if self._agent_id
+            else None
+        )
+        user = (
+            ChannelAccount(id=self._user_id, name=self._user_name)
+            if self._user_id
+            else None
+        )
+
+        reference = ConversationReference(
+            channel_id=self._channel_id,
+            service_url=self._service_url or _service_url_for_channel(self._channel_id),
+            conversation=ConversationAccount(
+                id=self._conversation_id,
+                name=self._conversation_name,
+                tenant_id=self._tenant_id,
+            ),
+            bot=agent,
+            user=user,
+            activity_id=self._activity_id,
+        )
+
+        return Conversation(claims=self._claims, conversation_reference=reference)