microsoft-agents-hosting-core 0.6.0.dev15__tar.gz

microsoft_agents_hosting_core-0.6.0.dev15/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.6.0.dev15/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: microsoft-agents-hosting-core
+Version: 0.6.0.dev15
+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.6.0.dev15
+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.6.0.dev15/microsoft_agents/hosting/core/__init__.py

@@ -0,0 +1,157 @@
+from .activity_handler import ActivityHandler
+from .agent import Agent
+from .card_factory import CardFactory
+from .channel_adapter import ChannelAdapter
+from .channel_api_handler_protocol import ChannelApiHandlerProtocol
+from .channel_service_adapter import ChannelServiceAdapter
+from .channel_service_client_factory_base import ChannelServiceClientFactoryBase
+from .message_factory import MessageFactory
+from .middleware_set import Middleware
+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._routes import _Route, _RouteList, RouteRank
+from .app.typing_indicator import TypingIndicator
+
+# App Auth
+from .app.oauth import (
+    Authorization,
+    AuthHandler,
+    AgenticUserAuthorization,
+)
+
+# App State
+from .app.state.conversation_state import ConversationState
+from .app.state.state import State, state
+from .app.state.temp_state import TempState
+from .app.state.turn_state import TurnState
+
+# Authorization
+from .authorization.access_token_provider_base import AccessTokenProviderBase
+from .authorization.authentication_constants import AuthenticationConstants
+from .authorization.anonymous_token_provider import AnonymousTokenProvider
+from .authorization.connections import Connections
+from .authorization.agent_auth_configuration import AgentAuthConfiguration
+from .authorization.claims_identity import ClaimsIdentity
+from .authorization.jwt_token_validator import JwtTokenValidator
+from .authorization.auth_types import AuthTypes
+
+# Client API
+from .client.agent_conversation_reference import AgentConversationReference
+from .client.channel_factory_protocol import ChannelFactoryProtocol
+from .client.channel_host_protocol import ChannelHostProtocol
+from .client.channel_info_protocol import ChannelInfoProtocol
+from .client.channel_protocol import ChannelProtocol
+from .client.channels_configuration import (
+    ChannelsConfiguration,
+    ChannelHostConfiguration,
+    ChannelInfo,
+)
+from .client.configuration_channel_host import ConfigurationChannelHost
+from .client.conversation_constants import ConversationConstants
+from .client.conversation_id_factory_options import ConversationIdFactoryOptions
+from .client.conversation_id_factory_protocol import ConversationIdFactoryProtocol
+from .client.conversation_id_factory import ConversationIdFactory
+from .client.http_agent_channel_factory import HttpAgentChannelFactory
+from .client.http_agent_channel import HttpAgentChannel
+
+# Connector API
+from .connector import (
+    ConnectorClient,
+    UserTokenClient,
+    UserTokenClientBase,
+    TeamsConnectorClient,
+    ConnectorClientBase,
+    get_product_info,
+)
+
+# State management
+from .state.agent_state import AgentState
+from .state.state_property_accessor import StatePropertyAccessor
+from .state.user_state import UserState
+
+# Storage
+from .storage.store_item import StoreItem
+from .storage import Storage
+from .storage.memory_storage import MemoryStorage
+
+# Error Resources
+from .errors import error_resources, ErrorMessage, ErrorResources
+
+
+# Define the package's public interface
+__all__ = [
+    "ActivityHandler",
+    "Agent",
+    "CardFactory",
+    "ChannelAdapter",
+    "ChannelApiHandlerProtocol",
+    "ChannelServiceAdapter",
+    "ChannelServiceClientFactoryBase",
+    "MessageFactory",
+    "Middleware",
+    "RestChannelServiceClientFactory",
+    "TurnContext",
+    "AgentApplication",
+    "ApplicationError",
+    "ApplicationOptions",
+    "InputFile",
+    "InputFileDownloader",
+    "Query",
+    "Route",
+    "RouteHandler",
+    "TypingIndicator",
+    "ConversationState",
+    "state",
+    "State",
+    "TurnState",
+    "TempState",
+    "Authorization",
+    "AuthHandler",
+    "AccessTokenProviderBase",
+    "AuthenticationConstants",
+    "AnonymousTokenProvider",
+    "Connections",
+    "AgentAuthConfiguration",
+    "ClaimsIdentity",
+    "JwtTokenValidator",
+    "AgentConversationReference",
+    "ChannelFactoryProtocol",
+    "ChannelHostProtocol",
+    "ChannelInfoProtocol",
+    "ChannelProtocol",
+    "ChannelsConfiguration",
+    "ChannelHostConfiguration",
+    "ChannelInfo",
+    "ConfigurationChannelHost",
+    "ConversationConstants",
+    "ConversationIdFactoryOptions",
+    "ConversationIdFactoryProtocol",
+    "ConversationIdFactory",
+    "HttpAgentChannelFactory",
+    "HttpAgentChannel",
+    "ConnectorClient",
+    "UserTokenClient",
+    "UserTokenClientBase",
+    "TeamsConnectorClient",
+    "ConnectorClientBase",
+    "get_product_info",
+    "AgentState",
+    "StatePropertyAccessor",
+    "UserState",
+    "StoreItem",
+    "Storage",
+    "MemoryStorage",
+    "AgenticUserAuthorization",
+    "Authorization",
+    "error_resources",
+    "ErrorMessage",
+    "ErrorResources",
+]

microsoft_agents_hosting_core-0.6.0.dev15/microsoft_agents/hosting/core/_oauth/__init__.py

@@ -0,0 +1,15 @@
+# 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
+
+__all__ = [
+    "_FlowState",
+    "_FlowStateTag",
+    "_FlowErrorTag",
+    "_FlowResponse",
+    "_FlowStorageClient",
+    "_OAuthFlow",
+]

microsoft_agents_hosting_core-0.6.0.dev15/microsoft_agents/hosting/core/_oauth/_flow_state.py

@@ -0,0 +1,81 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Optional
+
+from pydantic import BaseModel
+
+from microsoft_agents.activity import Activity
+
+from ..storage import StoreItem
+
+
+class _FlowStateTag(Enum):
+    """Represents the top-level state of an OAuthFlow
+
+    For instance, a flow can arrive at an error, but its
+    broader state may still be CONTINUE if the flow can
+    still progress
+    """
+
+    BEGIN = "begin"
+    CONTINUE = "continue"
+    NOT_STARTED = "not_started"
+    FAILURE = "failure"
+    COMPLETE = "complete"
+
+
+class _FlowErrorTag(Enum):
+    """Represents the various error states that can occur during an OAuthFlow"""
+
+    NONE = "none"
+    MAGIC_FORMAT = "magic_format"
+    MAGIC_CODE_INCORRECT = "magic_code_incorrect"
+    OTHER = "other"
+
+
+class _FlowState(BaseModel, StoreItem):
+    """Represents the state of an OAuthFlow"""
+
+    channel_id: str = ""
+    user_id: str = ""
+    ms_app_id: str = ""
+    connection: str = ""
+    auth_handler_id: str = ""
+
+    expiration: float = 0
+    continuation_activity: Optional[Activity] = None
+    attempts_remaining: int = 0
+    tag: _FlowStateTag = _FlowStateTag.NOT_STARTED
+
+    def store_item_to_json(self) -> dict:
+        return self.model_dump(mode="json", exclude_unset=True, by_alias=True)
+
+    @staticmethod
+    def from_json_to_store_item(json_data: dict) -> _FlowState:
+        return _FlowState.model_validate(json_data)
+
+    def is_expired(self) -> bool:
+        return datetime.now(timezone.utc).timestamp() >= self.expiration
+
+    def reached_max_attempts(self) -> bool:
+        return self.attempts_remaining <= 0
+
+    def is_active(self) -> bool:
+        return (
+            not self.is_expired()
+            and not self.reached_max_attempts()
+            and self.tag in [_FlowStateTag.BEGIN, _FlowStateTag.CONTINUE]
+        )
+
+    def refresh(self):
+        if (
+            self.tag
+            in [_FlowStateTag.BEGIN, _FlowStateTag.CONTINUE, _FlowStateTag.COMPLETE]
+            and self.is_expired()
+        ):
+            self.tag = _FlowStateTag.NOT_STARTED

microsoft_agents_hosting_core-0.6.0.dev15/microsoft_agents/hosting/core/_oauth/_flow_storage_client.py

@@ -0,0 +1,93 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from typing import Optional
+
+from ..storage import Storage
+from ._flow_state import _FlowState
+
+
+class _DummyCache(Storage):
+
+    async def read(self, keys: list[str], **kwargs) -> dict[str, _FlowState]:
+        return {}
+
+    async def write(self, changes: dict[str, _FlowState]) -> None:
+        pass
+
+    async def delete(self, keys: list[str]) -> None:
+        pass
+
+
+# this could be generalized. Ideas:
+# - CachedStorage class for two-tier storage
+# - Namespaced/PrefixedStorage class for namespacing keying
+# not generally thread or async safe (operations are not atomic)
+class _FlowStorageClient:
+    """Wrapper around Storage that manages sign-in state specific to each user and channel.
+
+    Uses the activity's channel_id and from.id to create a key prefix for storage operations.
+    """
+
+    def __init__(
+        self,
+        channel_id: str,
+        user_id: str,
+        storage: Storage,
+        cache_class: Optional[type[Storage]] = None,
+    ):
+        """
+        Args:
+            channel_id: used to create the prefix
+            user_id: used to create the prefix
+            storage: the backing storage
+            cache_class: the cache class to use (defaults to DummyCache, which performs no caching).
+                This cache's lifetime is tied to the FlowStorageClient instance.
+        """
+
+        if not user_id or not channel_id:
+            raise ValueError(
+                "FlowStorageClient.__init__(): channel_id and user_id must be set."
+            )
+
+        self._base_key = f"auth/{channel_id}/{user_id}/"
+        self._storage = storage
+        if cache_class is None:
+            cache_class = _DummyCache
+        self._cache = cache_class()
+
+    @property
+    def base_key(self) -> str:
+        """Returns the prefix used for flow state storage isolation."""
+        return self._base_key
+
+    def key(self, auth_handler_id: str) -> str:
+        """Creates a storage key for a specific sign-in handler."""
+        return f"{self._base_key}{auth_handler_id}"
+
+    async def read(self, auth_handler_id: str) -> Optional[_FlowState]:
+        """Reads the flow state for a specific authentication handler."""
+        key: str = self.key(auth_handler_id)
+        data = await self._cache.read([key], target_cls=_FlowState)
+        if key not in data:
+            data = await self._storage.read([key], target_cls=_FlowState)
+            if key not in data:
+                return None
+            await self._cache.write({key: data[key]})
+        return _FlowState.model_validate(data.get(key))
+
+    async def write(self, value: _FlowState) -> None:
+        """Saves the flow state for a specific authentication handler."""
+        key: str = self.key(value.auth_handler_id)
+        cached_state = await self._cache.read([key], target_cls=_FlowState)
+        if not cached_state or cached_state != value:
+            await self._cache.write({key: value})
+            await self._storage.write({key: value})
+
+    async def delete(self, auth_handler_id: str) -> None:
+        """Deletes the flow state for a specific authentication handler."""
+        key: str = self.key(auth_handler_id)
+        cached_state = await self._cache.read([key], target_cls=_FlowState)
+        if cached_state:
+            await self._cache.delete([key])
+        await self._storage.delete([key])