microsoft-agents-hosting-core 0.4.0.dev18__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.dev18 → 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.dev18 → 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.dev18 → microsoft_agents_hosting_core-0.5.0}/microsoft_agents/hosting/core/activity_handler.py

@@ -38,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
 
@@ -143,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::
@@ -176,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
@@ -195,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
@@ -216,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
 
@@ -260,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
@@ -285,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`
 
@@ -382,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
@@ -395,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"):
@@ -412,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
@@ -425,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
@@ -439,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
 
@@ -456,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 (
@@ -492,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
         """
@@ -508,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.dev18 → microsoft_agents_hosting_core-0.5.0}/microsoft_agents/hosting/core/app/agent_application.py

@@ -83,8 +83,16 @@ class AgentApplication(Agent, Generic[StateT]):
     ) -> None:
         """
         Creates a new AgentApplication instance.
+
+        :param options: Configuration options for the application.
+        :type options: Optional[:class:`microsoft_agents.hosting.core.app.app_options.ApplicationOptions`]
+        :param connection_manager: OAuth connection manager.
+        :type connection_manager: Optional[:class:`microsoft_agents.hosting.core.authorization.Connections`]
+        :param authorization: Authorization manager for handling authentication flows.
+        :type authorization: Optional[:class:`microsoft_agents.hosting.core.app.oauth.Authorization`]
+        :param kwargs: Additional configuration parameters.
+        :type kwargs: Any
         """
-        self.typing = TypingIndicator()
         self._route_list = _RouteList[StateT]()
 
         configuration = kwargs
@@ -161,6 +169,10 @@ class AgentApplication(Agent, Generic[StateT]):
     def adapter(self) -> ChannelServiceAdapter:
         """
         The bot's adapter.
+
+        :return: The channel service adapter for the bot.
+        :rtype: :class:`microsoft_agents.hosting.core.channel_service_adapter.ChannelServiceAdapter`
+        :raises ApplicationError: If the adapter is not configured.
         """
 
         if not self._adapter:
@@ -181,6 +193,10 @@ class AgentApplication(Agent, Generic[StateT]):
     def auth(self) -> Authorization:
         """
         The application's authentication manager
+
+        :return: The authentication manager for handling OAuth flows.
+        :rtype: :class:`microsoft_agents.hosting.core.app.oauth.Authorization`
+        :raises ApplicationError: If authentication is not configured.
         """
         if not self._auth:
             logger.error(
@@ -200,6 +216,9 @@ class AgentApplication(Agent, Generic[StateT]):
     def options(self) -> ApplicationOptions:
         """
         The application's configured options.
+
+        :return: The configuration options for the application.
+        :rtype: :class:`microsoft_agents.hosting.core.app.app_options.ApplicationOptions`
         """
         return self._options
 
@@ -217,18 +236,18 @@ class AgentApplication(Agent, Generic[StateT]):
         Routes are ordered by: is_agentic, is_invoke, rank (lower is higher priority), in that order.
 
         :param selector: A function that takes a TurnContext and returns a boolean indicating whether the route should be selected.
-        :type selector: RouteSelector
+        :type selector: :class:`microsoft_agents.hosting.core.app._type_defs.RouteSelector`
         :param handler: A function that takes a TurnContext and a TurnState and returns an Awaitable.
-        :type handler: RouteHandler[StateT]
+        :type handler: :class:`microsoft_agents.hosting.core.app._type_defs.RouteHandler`[StateT]
         :param is_invoke: Whether the route is for an invoke activity, defaults to False
-        :type is_invoke: bool, optional
+        :type is_invoke: bool, Optional
         :param is_agentic: Whether the route is for an agentic request, defaults to False. For agentic requests
             the selector will include a new check for `context.activity.is_agentic_request()`.
-        :type is_agentic: bool, optional
+        :type is_agentic: bool, Optional
         :param rank: The rank of the route, defaults to RouteRank.DEFAULT
-        :type rank: RouteRank, optional
+        :type rank: :class:`microsoft_agents.hosting.core.app._routes.RouteRank`, Optional
         :param auth_handlers: A list of authentication handler IDs to use for this route, defaults to None
-        :type auth_handlers: Optional[list[str]], optional
+        :type auth_handlers: Optional[list[str]], Optional
         :raises ApplicationError: If the selector or handler are not valid.
         """
         if not selector or not handler:
@@ -639,9 +658,12 @@ 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:
             if context.activity.type != ActivityTypes.typing:
-                await self._start_typing(context)
+                if self._options.start_typing_timer:
+                    typing = TypingIndicator()
+                    await typing.start(context)
 
             self._remove_mentions(context)
 
@@ -689,11 +711,8 @@ class AgentApplication(Agent, Generic[StateT]):
             )
             await self._on_error(context, err)
         finally:
-            self.typing.stop()
-
-    async def _start_typing(self, context: TurnContext):
-        if self._options.start_typing_timer:
-            await self.typing.start(context)
+            if typing:
+                await typing.stop()
 
     def _remove_mentions(self, context: TurnContext):
         if (
@@ -706,6 +725,11 @@ class AgentApplication(Agent, Generic[StateT]):
     def parse_env_vars_configuration(vars: dict[str, Any]) -> dict:
         """
         Parses environment variables and returns a dictionary with the relevant configuration.
+
+        :param vars: Dictionary of environment variable names and values.
+        :type vars: dict[str, Any]
+        :return: Parsed configuration dictionary with nested structure.
+        :rtype: dict
         """
         result = {}
         for key, value in vars.items():

microsoft_agents_hosting_core-0.5.0/microsoft_agents/hosting/core/app/input_file.py

@@ -0,0 +1,49 @@
+"""
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the MIT License.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import List, Optional
+
+from microsoft_agents.hosting.core import TurnContext
+
+
+@dataclass
+class InputFile:
+    """A file sent by the user to the bot.
+
+    :param content: The downloaded content of the file.
+    :type content: bytes
+    :param content_type: The content type of the file.
+    :type content_type: str
+    :param content_url: Optional. URL to the content of the file.
+    :type content_url: Optional[str]
+    """
+
+    content: bytes
+    content_type: str
+    content_url: Optional[str]
+
+
+class InputFileDownloader(ABC):
+    """
+    Abstract base class for a plugin responsible for downloading files provided by the user.
+
+    Implementations should download any files referenced by the incoming activity and return a
+    list of :class:`InputFile` instances representing the downloaded content.
+    """
+
+    @abstractmethod
+    async def download_files(self, context: TurnContext) -> List[InputFile]:
+        """
+        Download any files referenced by the incoming activity for the current turn.
+
+        :param context: The turn context for the current request.
+        :type context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
+        :return: A list of downloaded :class:`InputFile` objects.
+        :rtype: list[:class:`microsoft_agents.hosting.core.app.input_file.InputFile`]
+        """