microsoft-agents-hosting-core 0.4.0.dev16__tar.gz → 0.5.0__tar.gz

microsoft_agents_hosting_core-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

microsoft_agents_hosting_core-0.5.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: microsoft-agents-hosting-core
+Version: 0.5.0
+Summary: Core library for Microsoft Agents
+Author: Microsoft Corporation
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/microsoft/Agents
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: microsoft-agents-activity==0.5.0
+Requires-Dist: pyjwt>=2.10.1
+Requires-Dist: isodate>=0.6.1
+Requires-Dist: azure-core>=1.30.0
+Requires-Dist: python-dotenv>=1.1.1
+Dynamic: license-file
+Dynamic: requires-dist
+
+# Microsoft Agents Hosting Core
+
+[![PyPI version](https://img.shields.io/pypi/v/microsoft-agents-hosting-core)](https://pypi.org/project/microsoft-agents-hosting-core/)
+
+The core hosting library for Microsoft 365 Agents SDK. This library provides the fundamental building blocks for creating conversational AI agents, including activity processing, state management, authentication, and channel communication.
+
+This is the heart of the Microsoft 365 Agents SDK - think of it as the engine that powers your conversational agents. It handles the complex orchestration of conversations, manages state across turns, and provides the infrastructure needed to build production-ready agents that work across Microsoft 365 platforms.
+
+# 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.
+
+## Release Notes
+<table style="width:100%">
+  <tr>
+    <th style="width:20%">Version</th>
+    <th style="width:20%">Date</th>
+    <th style="width:60%">Release Notes</th>
+  </tr>
+  <tr>
+    <td>0.5.0</td>
+    <td>2025-10-22</td>
+    <td>
+      <a href="https://github.com/microsoft/Agents-for-python/blob/main/changelog.md">
+        0.5.0 Release Notes
+      </a>
+    </td>
+  </tr>
+</table>
+
+## 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 |
+
+
+## Installation
+
+```bash
+pip install microsoft-agents-hosting-core
+```
+## Simple Echo Agent
+See the [Quickstart sample](https://github.com/microsoft/Agents/tree/main/samples/python/quickstart) for full working code.
+
+```python
+agents_sdk_config = load_configuration_from_env(environ)
+
+STORAGE = MemoryStorage()
+CONNECTION_MANAGER = MsalConnectionManager(**agents_sdk_config)
+ADAPTER = CloudAdapter(connection_manager=CONNECTION_MANAGER)
+AUTHORIZATION = Authorization(STORAGE, CONNECTION_MANAGER, **agents_sdk_config)
+
+AGENT_APP = AgentApplication[TurnState](
+    storage=STORAGE, adapter=ADAPTER, authorization=AUTHORIZATION, **agents_sdk_config
+)
+
+@AGENT_APP.activity("message")
+async def on_message(context: TurnContext, state: TurnState):
+    await context.send_activity(f"You said: {context.activity.text}")
+
+...
+
+start_server(
+    agent_application=AGENT_APP,
+    auth_configuration=CONNECTION_MANAGER.get_default_connection_configuration(),
+)
+```
+
+## Core Concepts
+
+### AgentApplication vs ActivityHandler
+
+**AgentApplication** - Modern, fluent API for building agents:
+- Decorator-based routing (`@agent_app.activity("message")`)
+- Built-in state management and middleware
+- AI-ready with authorization support
+- Type-safe with generics
+
+**ActivityHandler** - Traditional inheritance-based approach:
+- Override methods for different activity types
+- More familiar to Bot Framework developers
+- Lower-level control over activity processing
+
+### Route-based Message Handling
+
+```python
+@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}")
+```
+
+### Error Handling
+
+```python
+@AGENT_APP.error
+async def on_error(context: TurnContext, error: Exception):
+    # NOTE: In production environment, you should consider logging this to Azure
+    #       application insights.
+    print(f"\n [on_turn_error] unhandled error: {error}", file=sys.stderr)
+    traceback.print_exc()
+
+    # Send a message to the user
+    await context.send_activity("The bot encountered an error or bug.")
+```
+
+
+## Key Classes Reference
+
+### Core Classes
+- **`AgentApplication`** - Main application class with fluent API
+- **`ActivityHandler`** - Base class for inheritance-based agents
+- **`TurnContext`** - Context for each conversation turn
+- **`TurnState`** - State management across conversation turns
+
+### State Management
+- **`ConversationState`** - Conversation-scoped state
+- **`UserState`** - User-scoped state across conversations
+- **`TempState`** - Temporary state for current turn
+- **`MemoryStorage`** - In-memory storage (development)
+
+### Messaging
+- **`MessageFactory`** - Create different types of messages
+- **`CardFactory`** - Create rich card attachments
+- **`InputFile`** - Handle file attachments
+
+### Authorization
+- **`Authorization`** - Authentication and authorization manager
+- **`ClaimsIdentity`** - User identity and claims
+
+# 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
+
+|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_hosting_core-0.4.0.dev16 → microsoft_agents_hosting_core-0.5.0}/microsoft_agents/hosting/core/__init__.py

@@ -11,12 +11,13 @@ from .rest_channel_service_client_factory import RestChannelServiceClientFactory
 from .turn_context import TurnContext
 
 # Application Style
+from .app._type_defs import RouteHandler, RouteSelector, StateT
 from .app.agent_application import AgentApplication
 from .app.app_error import ApplicationError
 from .app.app_options import ApplicationOptions
 from .app.input_file import InputFile, InputFileDownloader
 from .app.query import Query
-from .app.route import Route, RouteHandler
+from .app._routes import _Route, _RouteList, RouteRank
 from .app.typing_indicator import TypingIndicator
 
 # App Auth

{microsoft_agents_hosting_core-0.4.0.dev16 → microsoft_agents_hosting_core-0.5.0}/microsoft_agents/hosting/core/_oauth/__init__.py

@@ -1,3 +1,6 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
 from ._flow_state import _FlowState, _FlowStateTag, _FlowErrorTag
 from ._flow_storage_client import _FlowStorageClient
 from ._oauth_flow import _OAuthFlow, _FlowResponse

{microsoft_agents_hosting_core-0.4.0.dev16 → microsoft_agents_hosting_core-0.5.0}/microsoft_agents/hosting/core/_oauth/_flow_state.py

@@ -3,7 +3,7 @@
 
 from __future__ import annotations
 
-from datetime import datetime
+from datetime import datetime, timezone
 from enum import Enum
 from typing import Optional
 
@@ -60,7 +60,7 @@ class _FlowState(BaseModel, StoreItem):
         return _FlowState.model_validate(json_data)
 
     def is_expired(self) -> bool:
-        return datetime.now().timestamp() >= self.expiration
+        return datetime.now(timezone.utc).timestamp() >= self.expiration
 
     def reached_max_attempts(self) -> bool:
         return self.attempts_remaining <= 0

{microsoft_agents_hosting_core-0.4.0.dev16 → microsoft_agents_hosting_core-0.5.0}/microsoft_agents/hosting/core/_oauth/_oauth_flow.py

@@ -6,7 +6,7 @@ from __future__ import annotations
 import logging
 
 from pydantic import BaseModel
-from datetime import datetime
+from datetime import datetime, timezone
 from typing import Optional
 
 from microsoft_agents.activity import (
@@ -30,7 +30,6 @@ class _FlowResponse(BaseModel):
     flow_error_tag: _FlowErrorTag = _FlowErrorTag.NONE
     token_response: Optional[TokenResponse] = None
     sign_in_resource: Optional[SignInResource] = None
-    continuation_activity: Optional[Activity] = None
 
 
 class _OAuthFlow:
@@ -112,7 +111,7 @@ class _OAuthFlow:
         """Get the user token based on the context.
 
         Args:
-            magic_code (str, optional): Defaults to None. The magic code for user authentication.
+            magic_code (str, Optional): Defaults to None. The magic code for user authentication.
 
         Returns:
             TokenResponse
@@ -137,7 +136,7 @@ class _OAuthFlow:
         if token_response:
             logger.info("User token obtained successfully: %s", token_response)
             self._flow_state.expiration = (
-                datetime.now().timestamp() + self._default_flow_duration
+                datetime.now(timezone.utc).timestamp() + self._default_flow_duration
             )
             self._flow_state.tag = _FlowStateTag.COMPLETE
 
@@ -183,20 +182,8 @@ class _OAuthFlow:
         Notes:
             The flow state is reset if a token is not obtained from cache.
         """
-        token_response = await self.get_user_token()
-        if token_response:
-            return _FlowResponse(
-                flow_state=self._flow_state, token_response=token_response
-            )
 
         logger.debug("Starting new OAuth flow")
-        self._flow_state.tag = _FlowStateTag.BEGIN
-        self._flow_state.expiration = (
-            datetime.now().timestamp() + self._default_flow_duration
-        )
-
-        self._flow_state.attempts_remaining = self._max_attempts
-        self._flow_state.continuation_activity = activity.model_copy()
 
         token_exchange_state = TokenExchangeState(
             connection_name=self._abs_oauth_connection_name,
@@ -205,16 +192,33 @@ class _OAuthFlow:
             ms_app_id=self._ms_app_id,
         )
 
-        sign_in_resource = (
-            await self._user_token_client.agent_sign_in.get_sign_in_resource(
-                state=token_exchange_state.get_encoded_state()
+        res = await self._user_token_client.user_token._get_token_or_sign_in_resource(
+            activity.from_property.id,
+            self._abs_oauth_connection_name,
+            activity.channel_id,
+            token_exchange_state.get_encoded_state(),
+        )
+
+        if res.token_response:
+            logger.info("Skipping flow, user token obtained.")
+            self._flow_state.tag = _FlowStateTag.COMPLETE
+            self._flow_state.expiration = (
+                datetime.now(timezone.utc).timestamp() + self._default_flow_duration
+            )
+            return _FlowResponse(
+                flow_state=self._flow_state, token_response=res.token_response
             )
+
+        self._flow_state.tag = _FlowStateTag.BEGIN
+        self._flow_state.expiration = (
+            datetime.now(timezone.utc).timestamp() + self._default_flow_duration
         )
+        self._flow_state.attempts_remaining = self._max_attempts
 
-        logger.debug("Sign-in resource obtained successfully: %s", sign_in_resource)
+        logger.debug("Sign-in resource obtained successfully: %s", res.sign_in_resource)
 
         return _FlowResponse(
-            flow_state=self._flow_state, sign_in_resource=sign_in_resource
+            flow_state=self._flow_state, sign_in_resource=res.sign_in_resource
         )
 
     async def _continue_from_message(
@@ -299,7 +303,7 @@ class _OAuthFlow:
         else:
             self._flow_state.tag = _FlowStateTag.COMPLETE
             self._flow_state.expiration = (
-                datetime.now().timestamp() + self._default_flow_duration
+                datetime.now(timezone.utc).timestamp() + self._default_flow_duration
             )
             logger.debug(
                 "OAuth flow completed successfully, got TokenResponse: %s",
@@ -310,7 +314,6 @@ class _OAuthFlow:
             flow_state=self._flow_state.model_copy(),
             flow_error_tag=flow_error_tag,
             token_response=token_response,
-            continuation_activity=self._flow_state.continuation_activity,
         )
 
     async def begin_or_continue_flow(self, activity: Activity) -> _FlowResponse:

{microsoft_agents_hosting_core-0.4.0.dev16 → microsoft_agents_hosting_core-0.5.0}/microsoft_agents/hosting/core/activity_handler.py

@@ -1,5 +1,6 @@
 # Copyright (c) Microsoft Corporation. All rights reserved.
 # Licensed under the MIT License.
+
 from __future__ import annotations
 from http import HTTPStatus
 from pydantic import BaseModel
@@ -37,7 +38,7 @@ class ActivityHandler(Agent):
         in order to process an inbound :class:`microsoft_agents.activity.Activity`.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
 
         :returns: A task that represents the work queued to execute
 
@@ -142,7 +143,7 @@ class ActivityHandler(Agent):
         :meth:`on_turn()` is used.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :returns: A task that represents the work queued to execute
 
         .. remarks::
@@ -175,7 +176,7 @@ class ActivityHandler(Agent):
 
         :param members_added: A list of all the members added to the conversation, as described by the
         conversation update activity
-        :type members_added: list[ChannelAccount]
+        :type members_added: list[:class:`microsoft_agents.activity.ChannelAccount`]
         :param turn_context: The context object for this turn
         :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :returns: A task that represents the work queued to execute
@@ -194,9 +195,9 @@ class ActivityHandler(Agent):
         Override this method in a derived class to provide logic for when members other than the agent leave
         the conversation.  You can add your agent's good-bye logic.
 
-        :param members_added: A list of all the members removed from the conversation, as described by the
+        :param members_removed: A list of all the members removed from the conversation, as described by the
         conversation update activity
-        :type members_added: list[ChannelAccount]
+        :type members_removed: list[:class:`microsoft_agents.activity.ChannelAccount`]
         :param turn_context: The context object for this turn
         :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :returns: A task that represents the work queued to execute
@@ -215,7 +216,7 @@ class ActivityHandler(Agent):
         :meth:`on_turn()` is used.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
 
         :returns: A task that represents the work queued to execute
 
@@ -259,7 +260,7 @@ class ActivityHandler(Agent):
         are added to the conversation.
 
         :param message_reactions: The list of reactions added
-        :type message_reactions: list[MessageReaction]
+        :type message_reactions: list[:class:`microsoft_agents.activity.MessageReaction`]
         :param turn_context: The context object for this turn
         :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :returns: A task that represents the work queued to execute
@@ -284,7 +285,7 @@ class ActivityHandler(Agent):
         are removed from the conversation.
 
         :param message_reactions: The list of reactions removed
-        :type message_reactions: list[MessageReaction]
+        :type message_reactions: list[:class:`microsoft_agents.activity.MessageReaction`]
         :param turn_context: The context object for this turn
         :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
 
@@ -381,7 +382,7 @@ class ActivityHandler(Agent):
         ActivityTypes.typing activities, such as the conversational logic.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :returns: A task that represents the work queued to execute
         """
         return
@@ -394,7 +395,7 @@ class ActivityHandler(Agent):
         ActivityTypes.InstallationUpdate activities.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :returns: A task that represents the work queued to execute
         """
         if turn_context.activity.action in ("add", "add-upgrade"):
@@ -411,7 +412,7 @@ class ActivityHandler(Agent):
         ActivityTypes.InstallationUpdate activities with 'action' set to 'add'.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :returns: A task that represents the work queued to execute
         """
         return
@@ -424,7 +425,7 @@ class ActivityHandler(Agent):
         ActivityTypes.InstallationUpdate activities with 'action' set to 'remove'.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :returns: A task that represents the work queued to execute
         """
         return
@@ -438,7 +439,7 @@ class ActivityHandler(Agent):
         If overridden, this method could potentially respond to any of the other activity types.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
 
         :returns: A task that represents the work queued to execute
 
@@ -455,9 +456,10 @@ class ActivityHandler(Agent):
         Registers an activity event handler for the _invoke_ event, emitted for every incoming event activity.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
 
         :returns: A task that represents the work queued to execute
+        :rtype: Optional[:class:`microsoft_agents.activity.InvokeResponse`]
         """
         try:
             if (
@@ -491,7 +493,7 @@ class ActivityHandler(Agent):
         By default, this method does nothing.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
 
         :returns: A task that represents the work queued to execute
         """
@@ -507,10 +509,11 @@ class ActivityHandler(Agent):
         calls this method.
 
         :param turn_context: A context object for this turn.
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :param invoke_value: A string-typed object from the incoming activity's value.
-        :type invoke_value: :class:`microsoft_agents.activity.adaptive_card_invoke_value.AdaptiveCardInvokeValue`
+        :type invoke_value: :class:`microsoft_agents.activity.AdaptiveCardInvokeValue`
         :return: The HealthCheckResponse object
+        :rtype: :class:`microsoft_agents.activity.AdaptiveCardInvokeResponse`
         """
         raise _InvokeResponseException(HTTPStatus.NOT_IMPLEMENTED)
 

{microsoft_agents_hosting_core-0.4.0.dev16 → microsoft_agents_hosting_core-0.5.0}/microsoft_agents/hosting/core/app/__init__.py

@@ -10,8 +10,9 @@ from .app_error import ApplicationError
 from .app_options import ApplicationOptions
 from .input_file import InputFile, InputFileDownloader
 from .query import Query
-from .route import Route, RouteHandler
+from ._routes import _RouteList, _Route, RouteRank
 from .typing_indicator import TypingIndicator
+from ._type_defs import RouteHandler, RouteSelector, StateT
 
 # Auth
 from .oauth import (

microsoft_agents_hosting_core-0.5.0/microsoft_agents/hosting/core/app/_routes/__init__.py

@@ -0,0 +1,13 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from ._route_list import _RouteList
+from ._route import _Route, _agentic_selector
+from .route_rank import RouteRank
+
+__all__ = [
+    "_RouteList",
+    "_Route",
+    "RouteRank",
+    "_agentic_selector",
+]

microsoft_agents_hosting_core-0.5.0/microsoft_agents/hosting/core/app/_routes/_route.py

@@ -0,0 +1,89 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+from typing import Generic, Optional, TypeVar
+
+from ...turn_context import TurnContext
+from .._type_defs import RouteHandler, RouteSelector
+from ..state.turn_state import TurnState
+from .route_rank import RouteRank
+
+
+def _agentic_selector(selector: RouteSelector) -> RouteSelector:
+    def wrapped_selector(context: TurnContext) -> bool:
+        return context.activity.is_agentic_request() and selector(context)
+
+    return wrapped_selector
+
+
+StateT = TypeVar("StateT", bound=TurnState)
+
+
+class _Route(Generic[StateT]):
+    selector: RouteSelector
+    handler: RouteHandler[StateT]
+    _is_invoke: bool
+    _rank: int
+    auth_handlers: list[str]
+    _is_agentic: bool
+
+    def __init__(
+        self,
+        selector: RouteSelector,
+        handler: RouteHandler[StateT],
+        is_invoke: bool = False,
+        rank: int = RouteRank.DEFAULT,
+        auth_handlers: Optional[list[str]] = None,
+        is_agentic: bool = False,
+        **kwargs,
+    ) -> None:
+
+        if rank < 0 or rank > RouteRank.LAST:
+            raise ValueError(
+                "Route rank must be between 0 and RouteRank.LAST (inclusive)"
+            )
+
+        self.selector = selector
+        self.handler = handler
+        self._is_invoke = is_invoke
+        self._rank = int(rank)  # conversion from RouteRank IntEnum if necessary
+        self._is_agentic = is_agentic
+        self.auth_handlers = auth_handlers or []
+
+    @property
+    def is_invoke(self) -> bool:
+        return self._is_invoke
+
+    @property
+    def rank(self) -> int:
+        return self._rank
+
+    @property
+    def is_agentic(self) -> bool:
+        return self._is_agentic
+
+    @property
+    def priority(self) -> list[int]:
+        """Lower "values" indicate higher priority.
+
+        Priority is determined by:
+        1. Whether the route is for an invoke activity (0) or not (1).
+        2. Whether the route is agentic (0) or not (1).
+        3. The rank of the route (lower numbers indicate higher priority).
+
+        In that order. If both are invokes, the agentic one has higher priority.
+        If both are agentic and invokes, then the rank determines priority.
+
+        priority is represented as a list of three integers for easy lexicographic comparison.
+        """
+        return [
+            0 if self._is_invoke else 1,
+            0 if self._is_agentic else 1,
+            self._rank,
+        ]
+
+    def __lt__(self, other: _Route) -> bool:
+        # built-in list ordering is a lexicographic comparison in Python
+        return self.priority < other.priority

microsoft_agents_hosting_core-0.5.0/microsoft_agents/hosting/core/app/_routes/_route_list.py

@@ -0,0 +1,32 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+import heapq
+from typing import Generic, TypeVar
+
+from ..state.turn_state import TurnState
+from ._route import _Route
+
+StateT = TypeVar("StateT", bound=TurnState)
+
+
+class _RouteList(Generic[StateT]):
+    _routes: list[_Route[StateT]]
+
+    def __init__(
+        self,
+    ) -> None:
+        # a min-heap where lower "values" indicate higher priority
+        self._routes = []
+
+    def add_route(self, route: _Route[StateT]) -> None:
+        """Adds a route to the list."""
+        heapq.heappush(self._routes, route)
+
+    def __iter__(self):
+        # sorted will return a new list, leaving the heap intact
+        # returning an iterator over the previous list would expose
+        # internal details
+        return iter(sorted(self._routes))