microsoft-agents-hosting-core 0.10.0.dev6__tar.gz → 0.10.0.dev8__tar.gz

{microsoft_agents_hosting_core-0.10.0.dev6/microsoft_agents_hosting_core.egg-info → microsoft_agents_hosting_core-0.10.0.dev8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: microsoft-agents-hosting-core
-Version: 0.10.0.dev6
+Version: 0.10.0.dev8
 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.10.0.dev6
+Requires-Dist: microsoft-agents-activity==0.10.0.dev8
 Requires-Dist: pyjwt>=2.10.1
 Requires-Dist: isodate>=0.6.1
 Requires-Dist: azure-core>=1.30.0

microsoft_agents_hosting_core-0.10.0.dev8/VERSION.txt

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

{microsoft_agents_hosting_core-0.10.0.dev6 → microsoft_agents_hosting_core-0.10.0.dev8}/microsoft_agents/hosting/core/app/__init__.py

@@ -11,7 +11,7 @@ from .app_options import ApplicationOptions
 from .input_file import InputFile, InputFileDownloader
 from .query import Query
 from ._routes import _RouteList, _Route, RouteRank
-from .typing_indicator import TypingIndicator
+from .typing_indicator import TypingChannelStrategy, TypingIndicator, TypingOptions
 from ._type_defs import RouteHandler, RouteSelector, StateT
 
 # Auth
@@ -46,7 +46,9 @@ __all__ = [
     "Query",
     "Route",
     "RouteHandler",
+    "TypingChannelStrategy",
     "TypingIndicator",
+    "TypingOptions",
     "StatePropertyAccessor",
     "ConversationState",
     "state",

{microsoft_agents_hosting_core-0.10.0.dev6 → microsoft_agents_hosting_core-0.10.0.dev8}/microsoft_agents/hosting/core/app/agent_application.py

@@ -5,6 +5,7 @@ Licensed under the MIT License.
 
 from __future__ import annotations
 import logging
+from contextlib import nullcontext
 from copy import copy
 from functools import partial
 
@@ -697,62 +698,69 @@ class AgentApplication(Agent, Generic[StateT]):
         await self._start_long_running_call(context, self._on_turn)
 
     async def _on_turn(self, context: TurnContext):
-        typing = None
         try:
             with spans.AppOnTurn(context) as on_turn_span:
-                if context.activity.type != ActivityTypes.typing:
-                    if self._options.start_typing_timer:
-                        typing = TypingIndicator(context)
-                        typing.start()
-
-                self._remove_mentions(context)
-
-                logger.debug("Initializing turn state")
-                turn_state = await self._initialize_state(context)
-                if (
-                    context.activity.type == ActivityTypes.message
-                    or context.activity.type == ActivityTypes.invoke
-                ):
+                use_typing = (
+                    self._options.start_typing_timer
+                    and context.activity.type != ActivityTypes.typing
+                )
+                typing_context = (
+                    TypingIndicator(
+                        context,
+                        typing_options=self._options.typing,
+                    )
+                    if use_typing
+                    else nullcontext()
+                )
 
-                    (
-                        auth_intercepts,
-                        continuation_activity,
-                    ) = await self._auth._on_turn_auth_intercept(context, turn_state)
-                    if auth_intercepts:
-                        if continuation_activity:
-                            new_context = copy(context)
-                            new_context.activity = continuation_activity
-                            logger.info(
-                                "Resending continuation activity %s",
-                                continuation_activity.text,
-                            )
-                            await self.on_turn(new_context)
-                            await turn_state.save(context)
+                async with typing_context:
+                    self._remove_mentions(context)
+
+                    logger.debug("Initializing turn state")
+                    turn_state = await self._initialize_state(context)
+                    if context.activity.type in [
+                        ActivityTypes.message,
+                        ActivityTypes.invoke,
+                    ]:
+
+                        (
+                            auth_intercepts,
+                            continuation_activity,
+                        ) = await self._auth._on_turn_auth_intercept(
+                            context, turn_state
+                        )
+                        if auth_intercepts:
+                            if continuation_activity:
+                                new_context = copy(context)
+                                new_context.activity = continuation_activity
+                                logger.info(
+                                    "Resending continuation activity %s",
+                                    continuation_activity.text,
+                                )
+                                await self.on_turn(new_context)
+                                await turn_state.save(context)
+                            return
+
+                    logger.debug("Running before turn middleware")
+                    if not await self._run_before_turn_middleware(context, turn_state):
                         return
 
-                logger.debug("Running before turn middleware")
-                if not await self._run_before_turn_middleware(context, turn_state):
-                    return
+                    logger.debug("Running file downloads")
+                    await self._handle_file_downloads(context, turn_state)
 
-                logger.debug("Running file downloads")
-                await self._handle_file_downloads(context, turn_state)
+                    logger.debug("Running activity handlers")
+                    await self._on_activity(context, turn_state, on_turn_span)
 
-                logger.debug("Running activity handlers")
-                await self._on_activity(context, turn_state, on_turn_span)
-
-                logger.debug("Running after turn middleware")
-                if await self._run_after_turn_middleware(context, turn_state):
-                    await turn_state.save(context)
-                return
+                    logger.debug("Running after turn middleware")
+                    if await self._run_after_turn_middleware(context, turn_state):
+                        await turn_state.save(context)
+                    return
         except ApplicationError as err:
             logger.error(
                 f"An application error occurred in the AgentApplication: {err}",
                 exc_info=True,
             )
             await self._on_error(context, err)
-        finally:
-            if typing:
-                typing.stop()
 
     def _remove_mentions(self, context: TurnContext):
         if (

{microsoft_agents_hosting_core-0.10.0.dev6 → microsoft_agents_hosting_core-0.10.0.dev8}/microsoft_agents/hosting/core/app/app_options.py

@@ -13,6 +13,7 @@ from microsoft_agents.hosting.core.app.oauth import AuthHandler
 from microsoft_agents.hosting.core.storage import Storage
 
 # from .auth import AuthOptions
+from .typing_indicator import TypingOptions
 from .input_file import InputFileDownloader
 from ..channel_service_adapter import ChannelServiceAdapter
 
@@ -62,6 +63,13 @@ class ApplicationOptions:
     the request. Defaults to true.
     """
 
+    typing: Optional[TypingOptions] = None
+    """
+    Optional. Typing indicator timing options. Controls initial delay, interval,
+    and per-channel strategies. If not provided, defaults are used when
+    ``start_typing_timer`` is true.
+    """
+
     long_running_messages: bool = False
     """
     Optional. If true, the bot supports long running messages that can take longer then the 10 - 15

{microsoft_agents_hosting_core-0.10.0.dev6 → microsoft_agents_hosting_core-0.10.0.dev8}/microsoft_agents/hosting/core/app/proactive/proactive.py

@@ -16,6 +16,7 @@ from microsoft_agents.hosting.core.storage import Storage
 from .conversation import Conversation
 from .create_conversation_options import CreateConversationOptions
 from .proactive_options import ProactiveOptions
+from .telemetry import spans
 
 if TYPE_CHECKING:
     from microsoft_agents.hosting.core.turn_context import TurnContext
@@ -95,7 +96,7 @@ class Proactive(Generic[StateT]):
 
     async def store_conversation(
         self,
-        context_or_conversation: "TurnContext | Conversation",
+        context_or_conversation: TurnContext | Conversation,
     ) -> None:
         """
         Persist a :class:`~microsoft_agents.hosting.core.app.proactive.conversation.Conversation`
@@ -120,10 +121,13 @@ class Proactive(Generic[StateT]):
         else:
             conversation = context_or_conversation
 
-        conversation.validate()
-        key = self._storage_key(conversation.conversation_reference.conversation.id)
-        logger.debug("Storing conversation with key: %s", key)
-        await self._storage.write({key: conversation})
+        with spans.ProactiveStoreConversation(
+            conversation.conversation_reference.conversation.id
+        ):
+            conversation.validate()
+            key = self._storage_key(conversation.conversation_reference.conversation.id)
+            logger.debug("Storing conversation with key: %s", key)
+            await self._storage.write({key: conversation})
 
     async def get_conversation(self, conversation_id: str) -> Optional[Conversation]:
         """
@@ -136,9 +140,12 @@ class Proactive(Generic[StateT]):
             or ``None`` if not found.
         :rtype: Optional[:class:`~microsoft_agents.hosting.core.app.proactive.conversation.Conversation`]
         """
-        key = self._storage_key(conversation_id)
-        results = await self._storage.read([key], target_cls=Conversation)
-        return results.get(key)
+        with spans.ProactiveGetConversation(conversation_id) as span:
+            key = self._storage_key(conversation_id)
+            results = await self._storage.read([key], target_cls=Conversation)
+            conversation = results.get(key)
+            span.share(found=conversation is not None)
+            return conversation
 
     async def delete_conversation(self, conversation_id: str) -> None:
         """
@@ -147,9 +154,10 @@ class Proactive(Generic[StateT]):
         :param conversation_id: The conversation ID to delete.
         :type conversation_id: str
         """
-        key = self._storage_key(conversation_id)
-        logger.debug("Deleting conversation with key: %s", key)
-        await self._storage.delete([key])
+        with spans.ProactiveDeleteConversation(conversation_id):
+            key = self._storage_key(conversation_id)
+            logger.debug("Deleting conversation with key: %s", key)
+            await self._storage.delete([key])
 
     # ------------------------------------------------------------------
     # Send a single activity
@@ -181,7 +189,9 @@ class Proactive(Generic[StateT]):
             conversation is not found in storage.
         """
         conversation = await self._resolve_conversation(conversation_id_or_conversation)
-        return await Proactive._send_activity_impl(adapter, conversation, activity)
+        conversation_id = conversation.conversation_reference.conversation.id
+        with spans.ProactiveSendActivity(conversation_id, activity):
+            return await Proactive._send_activity_impl(adapter, conversation, activity)
 
     @staticmethod
     async def _send_activity_impl(
@@ -252,6 +262,7 @@ class Proactive(Generic[StateT]):
             :attr:`~ProactiveOptions.fail_on_unsigned_in_connections` is ``True``.
         """
         conversation = await self._resolve_conversation(conversation_id_or_conversation)
+        conversation_id = conversation.conversation_reference.conversation.id
 
         captured_exc: Optional[BaseException] = None
         claims = Conversation.identity_from_claims(conversation.claims)
@@ -267,10 +278,14 @@ class Proactive(Generic[StateT]):
             except Exception as exc:  # noqa: BLE001
                 captured_exc = exc
 
-        await adapter.continue_conversation_with_claims(claims, continuation, _callback)
+        with spans.ProactiveContinueConversation(conversation_id, continuation):
 
-        if captured_exc is not None:
-            raise captured_exc
+            await adapter.continue_conversation_with_claims(
+                claims, continuation, _callback
+            )
+
+            if captured_exc is not None:
+                raise captured_exc
 
     # ------------------------------------------------------------------
     # Create a new conversation
@@ -303,40 +318,42 @@ class Proactive(Generic[StateT]):
         new_conversation: Optional[Conversation] = None
         captured_exc: Optional[BaseException] = None
 
-        audience = options.audience or options.identity.get_token_audience()
+        with spans.ProactiveCreateConversation(options):
 
-        async def _callback(context: "TurnContext") -> None:
-            nonlocal new_conversation, captured_exc
-            try:
-                reference = context.activity.get_conversation_reference()
-                new_conversation = Conversation(
-                    claims=options.identity,
-                    conversation_reference=reference,
-                )
+            audience = options.audience or options.identity.get_token_audience()
 
-                if options.store_conversation:
-                    await self.store_conversation(new_conversation)
-
-                if handler is not None:
-                    state = await self._load_state(context)
-                    await handler(context, state)
-                    await state.save(context)
-            except Exception as exc:  # noqa: BLE001
-                captured_exc = exc
+            async def _callback(context: "TurnContext") -> None:
+                nonlocal new_conversation, captured_exc
+                try:
+                    reference = context.activity.get_conversation_reference()
+                    new_conversation = Conversation(
+                        claims=options.identity,
+                        conversation_reference=reference,
+                    )
 
-        await adapter.create_conversation(
-            options.identity.get_app_id() or "",
-            options.channel_id,
-            options.service_url,
-            audience,
-            options.parameters,
-            _callback,
-        )
+                    if options.store_conversation:
+                        await self.store_conversation(new_conversation)
+
+                    if handler is not None:
+                        state = await self._load_state(context)
+                        await handler(context, state)
+                        await state.save(context)
+                except Exception as exc:  # noqa: BLE001
+                    captured_exc = exc
+
+            await adapter.create_conversation(
+                options.identity.get_app_id() or "",
+                options.channel_id,
+                options.service_url,
+                audience,
+                options.parameters,
+                _callback,
+            )
 
-        if captured_exc is not None:
-            raise captured_exc
+            if captured_exc is not None:
+                raise captured_exc
 
-        return new_conversation
+            return new_conversation
 
     # ------------------------------------------------------------------
     # Internal helpers

microsoft_agents_hosting_core-0.10.0.dev8/microsoft_agents/hosting/core/app/proactive/telemetry/constants.py

@@ -0,0 +1,9 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+SPAN_STORE_CONVERSATION = "agents.proactive.store_conversation"
+SPAN_GET_CONVERSATION = "agents.proactive.get_conversation"
+SPAN_DELETE_CONVERSATION = "agents.proactive.delete_conversation"
+SPAN_SEND_ACTIVITY = "agents.proactive.send_activity"
+SPAN_CONTINUE_CONVERSATION = "agents.proactive.continue_conversation"
+SPAN_CREATE_CONVERSATION = "agents.proactive.create_conversation"

microsoft_agents_hosting_core-0.10.0.dev8/microsoft_agents/hosting/core/app/proactive/telemetry/spans.py

@@ -0,0 +1,142 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+from microsoft_agents.activity import Activity
+from microsoft_agents.hosting.core.telemetry import (
+    AttributeMap,
+    attributes,
+    SimpleSpanWrapper,
+)
+from . import constants
+from ..create_conversation_options import CreateConversationOptions
+
+
+class ProactiveStoreConversation(SimpleSpanWrapper):
+    """Span for storing a conversation reference in proactive scenarios, starting from when the store operation is initiated until it is completed. This span can be used to correlate telemetry related to storing conversation references in proactive scenarios."""
+
+    def __init__(self, conversation_id: str):
+        """Initializes the ProactiveStoreConversation SpanWrapper.
+
+        :param conversation_id: The ID of the conversation being stored, used to extract attributes for the span
+        """
+        super().__init__(constants.SPAN_STORE_CONVERSATION)
+        self._conversation_id = conversation_id
+
+    def _get_attributes(self) -> AttributeMap:
+        return {
+            attributes.CONVERSATION_ID: self._conversation_id or attributes.UNKNOWN,
+        }
+
+
+class ProactiveGetConversation(SimpleSpanWrapper):
+    """Span for getting a conversation reference in proactive scenarios."""
+
+    def __init__(self, conversation_id: str):
+        """Initializes the ProactiveGetConversation SpanWrapper.
+
+        :param conversation_id: The ID of the conversation being retrieved, used to extract attributes for the span
+        """
+        super().__init__(constants.SPAN_GET_CONVERSATION)
+        self._conversation_id = conversation_id
+        self._found: bool | None = None
+
+    def _get_attributes(self) -> AttributeMap:
+        return {
+            attributes.CONVERSATION_ID: self._conversation_id or attributes.UNKNOWN,
+            attributes.CONVERSATION_FOUND: (
+                self._found if self._found is not None else attributes.UNKNOWN
+            ),
+        }
+
+    def share(self, found: bool) -> None:
+        """Records to the span whether the conversation being retrieved was found.
+
+        :param found: Whether the conversation being retrieved was found
+        """
+        self._found = found
+
+
+class ProactiveDeleteConversation(SimpleSpanWrapper):
+    """Span for deleting a conversation reference in proactive scenarios, starting from when the delete operation is initiated until it is completed. This span can be used to correlate telemetry related to deleting conversation references in proactive scenarios."""
+
+    def __init__(self, conversation_id: str):
+        """Initializes the ProactiveDeleteConversation SpanWrapper.
+
+        :param conversation_id: The ID of the conversation being deleted, used to extract attributes for the span
+        """
+        super().__init__(constants.SPAN_DELETE_CONVERSATION)
+        self._conversation_id = conversation_id
+
+    def _get_attributes(self) -> AttributeMap:
+        return {
+            attributes.CONVERSATION_ID: self._conversation_id or attributes.UNKNOWN,
+        }
+
+
+class ProactiveSendActivity(SimpleSpanWrapper):
+    """Span for sending an activity in proactive scenarios, starting from when the send operation is initiated until it is completed. This span can be used to correlate telemetry related to sending activities in proactive scenarios."""
+
+    def __init__(self, conversation_id: str, activity: Activity):
+        """Initializes the ProactiveSendActivity SpanWrapper.
+
+        :param conversation_id: The ID of the conversation the activity is being sent to, used to extract attributes for the span
+        :param activity: The activity being sent, used to extract attributes for the span
+        """
+        super().__init__(constants.SPAN_SEND_ACTIVITY)
+        self._conversation_id = conversation_id
+        self._activity = activity
+
+    def _get_attributes(self) -> AttributeMap:
+        return {
+            attributes.CONVERSATION_ID: self._conversation_id or attributes.UNKNOWN,
+            attributes.ACTIVITY_TYPE: self._activity.type or attributes.UNKNOWN,
+            attributes.ACTIVITY_CHANNEL_ID: self._activity.channel_id
+            or attributes.UNKNOWN,
+        }
+
+
+class ProactiveContinueConversation(SimpleSpanWrapper):
+    """Span for continuing a conversation in proactive scenarios, starting from when the continue operation is initiated until it is completed. This span can be used to correlate telemetry related to continuing conversations in proactive scenarios."""
+
+    def __init__(self, conversation_id: str, activity: Activity):
+        """Initializes the ProactiveContinueConversation SpanWrapper.
+
+        :param conversation_id: The ID of the conversation being continued, used to extract attributes for the span
+        :param activity: The activity being sent, used to extract attributes for the span
+        """
+        super().__init__(constants.SPAN_CONTINUE_CONVERSATION)
+        self._conversation_id = conversation_id
+        self._activity = activity
+
+    def _get_attributes(self) -> AttributeMap:
+        return {
+            attributes.CONVERSATION_ID: self._conversation_id or attributes.UNKNOWN,
+            attributes.ACTIVITY_TYPE: self._activity.type or attributes.UNKNOWN,
+            attributes.ACTIVITY_CHANNEL_ID: self._activity.channel_id
+            or attributes.UNKNOWN,
+        }
+
+
+class ProactiveCreateConversation(SimpleSpanWrapper):
+    """Span for creating a conversation in proactive scenarios, starting from when the create operation is initiated until it is completed. This span can be used to correlate telemetry related to creating conversations in proactive scenarios."""
+
+    def __init__(self, options: CreateConversationOptions):
+        """Initializes the ProactiveCreateConversation SpanWrapper.
+
+        :param options: The options used to create the conversation, used to extract attributes for the span
+        """
+        super().__init__(constants.SPAN_CREATE_CONVERSATION)
+        self._channel_id = options.channel_id
+        self._members_count: str | int = (
+            len(options.parameters.members)
+            if options.parameters and options.parameters.members
+            else attributes.UNKNOWN
+        )
+
+    def _get_attributes(self) -> AttributeMap:
+        return {
+            attributes.ACTIVITY_CHANNEL_ID: self._channel_id,
+            attributes.MEMBERS_COUNT: self._members_count,
+        }