microsoft-agents-a365-runtime 0.1.0__py3-none-any.whl

microsoft_agents_a365/runtime/__init__.py

@@ -0,0 +1,14 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from .environment_utils import get_observability_authentication_scope
+from .power_platform_api_discovery import ClusterCategory, PowerPlatformApiDiscovery
+from .utility import Utility
+
+__all__ = [
+    "get_observability_authentication_scope",
+    "PowerPlatformApiDiscovery",
+    "ClusterCategory",
+    "Utility",
+]
+
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)

microsoft_agents_a365/runtime/environment_utils.py

@@ -0,0 +1,56 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""
+Utility logic for environment-related operations.
+"""
+
+import os
+
+# Authentication scopes for different environments
+PROD_OBSERVABILITY_SCOPE = "https://api.powerplatform.com/.default"
+
+# Cluster categories for different environments
+PROD_OBSERVABILITY_CLUSTER_CATEGORY = "prod"
+
+# Default environment names
+PRODUCTION_ENVIRONMENT_NAME = "production"
+DEVELOPMENT_ENVIRONMENT_NAME = "Development"
+
+
+def get_observability_authentication_scope() -> list[str]:
+    """
+    Returns the scope for authenticating to the observability service based on the current environment.
+
+    Returns:
+        list[str]: The authentication scope for the current environment.
+    """
+    return [PROD_OBSERVABILITY_SCOPE]
+
+
+def is_development_environment() -> bool:
+    """
+    Returns True if the current environment is a development environment.
+
+    Returns:
+        bool: True if the current environment is development, False otherwise.
+    """
+    environment = _get_current_environment()
+    return environment.lower() == DEVELOPMENT_ENVIRONMENT_NAME.lower()
+
+
+def _get_current_environment() -> str:
+    """
+    Gets the current environment name.
+
+    Returns:
+        str: The current environment name.
+    """
+    # Check environment variables in order of precedence
+
+    # Check Python-specific environment variables
+    environment = os.getenv("PYTHON_ENVIRONMENT")
+    if environment:
+        return environment
+
+    # Default to Production
+    return PRODUCTION_ENVIRONMENT_NAME

microsoft_agents_a365/runtime/power_platform_api_discovery.py

@@ -0,0 +1,89 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import re
+from typing import Literal
+
+ClusterCategory = Literal[
+    "local",
+    "dev",
+    "test",
+    "preprod",
+    "firstrelease",
+    "prod",
+    "gov",
+    "high",
+    "dod",
+    "mooncake",
+    "ex",
+    "rx",
+]
+
+
+class PowerPlatformApiDiscovery:
+    """Discovery helper for Power Platform API endpoints."""
+
+    def __init__(self, cluster_category: ClusterCategory) -> None:
+        self.cluster_category = cluster_category
+
+    def get_token_audience(self) -> str:
+        return f"https://{self._get_environment_api_host_name_suffix()}"
+
+    def get_token_endpoint_host(self) -> str:
+        return self._get_environment_api_host_name_suffix()
+
+    def get_tenant_endpoint(self, tenant_id: str) -> str:
+        return self._generate_power_platform_api_domain(tenant_id)
+
+    def get_tenant_island_cluster_endpoint(self, tenant_id: str) -> str:
+        return self._generate_power_platform_api_domain(tenant_id, "il-")
+
+    def _generate_power_platform_api_domain(
+        self, host_name_identifier: str, host_name_prefix: str = ""
+    ) -> str:
+        # Validate allowed characters: alphanumeric and dash
+        if not re.match(r"^[a-zA-Z0-9-]+$", host_name_identifier):
+            raise ValueError(
+                f"Cannot generate Power Platform API endpoint because the tenant identifier contains invalid host name characters, only alphanumeric and dash characters are expected: {host_name_identifier}"
+            )
+
+        host_name_infix = "tenant"
+        hex_name_suffix_length = self._get_hex_api_suffix_length()
+        hex_name = host_name_identifier.lower().replace("-", "")
+
+        if hex_name_suffix_length >= len(hex_name):
+            raise ValueError(
+                f"Cannot generate Power Platform API endpoint because the normalized tenant identifier must be at least {hex_name_suffix_length + 1} "
+                f"characters in length: {hex_name}"
+            )
+
+        hex_name_suffix = hex_name[-hex_name_suffix_length:]
+        hex_name_prefix = hex_name[: len(hex_name) - hex_name_suffix_length]
+        host_name_suffix = self._get_environment_api_host_name_suffix()
+
+        return f"{host_name_prefix}{hex_name_prefix}.{hex_name_suffix}.{host_name_infix}.{host_name_suffix}"
+
+    def _get_hex_api_suffix_length(self) -> int:
+        if self.cluster_category in ("firstrelease", "prod"):
+            return 2
+        return 1
+
+    def _get_environment_api_host_name_suffix(self) -> str:
+        cluster_to_suffix = {
+            "local": "api.powerplatform.localhost",
+            "dev": "api.powerplatform.com",  # defaulting to prod
+            "test": "api.powerplatform.com",  # defaulting to prod
+            "preprod": "api.powerplatform.com",  # defaulting to prod
+            "firstrelease": "api.powerplatform.com",
+            "prod": "api.powerplatform.com",
+            "gov": "api.gov.powerplatform.microsoft.us",
+            "high": "api.high.powerplatform.microsoft.us",
+            "dod": "api.appsplatform.us",
+            "mooncake": "api.powerplatform.partner.microsoftonline.cn",
+            "ex": "api.powerplatform.eaglex.ic.gov",
+            "rx": "api.powerplatform.microsoft.scloud",
+        }
+        cc = self.cluster_category
+        try:
+            return cluster_to_suffix[cc]
+        except KeyError as exc:
+            raise ValueError(f"Invalid ClusterCategory value: {self.cluster_category}") from exc

microsoft_agents_a365/runtime/utility.py

@@ -0,0 +1,82 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""
+Utility functions for Microsoft Agent 365 runtime operations.
+
+This module provides utility functions for token handling, agent identity resolution,
+and other common runtime operations.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any, Optional
+
+import jwt
+
+
+class Utility:
+    """
+    Utility class providing common runtime operations for Agent 365.
+
+    This class contains static methods for token processing, agent identity resolution,
+    and other utility functions used across the Agent 365 runtime.
+    """
+
+    @staticmethod
+    def get_app_id_from_token(token: Optional[str]) -> str:
+        """
+        Decodes the current token and retrieves the App ID (appid or azp claim).
+
+        Args:
+            token: JWT token to decode. Can be None or empty.
+
+        Returns:
+            str: The App ID from the token's claims, or empty GUID if token is invalid.
+                 Returns "00000000-0000-0000-0000-000000000000" if no valid App ID is found.
+        """
+        if not token or not token.strip():
+            return str(uuid.UUID(int=0))
+
+        try:
+            # Decode the JWT token without verification (we only need the claims)
+            # Note: verify=False is used because we only need to extract claims,
+            # not verify the token's authenticity
+            decoded_payload = jwt.decode(token, options={"verify_signature": False})
+
+            # Look for appid or azp claims (appid takes precedence)
+            app_id = decoded_payload.get("appid") or decoded_payload.get("azp")
+            return app_id if app_id else ""
+
+        except (jwt.DecodeError, jwt.InvalidTokenError):
+            # Token is malformed or invalid
+            return ""
+
+    @staticmethod
+    def resolve_agent_identity(context: Any, auth_token: Optional[str]) -> str:
+        """
+        Resolves the agent identity from the turn context or auth token.
+
+        Args:
+            context: Turn context of the conversation turn. Expected to have an Activity
+                    with methods like is_agentic_request() and get_agentic_instance_id().
+            auth_token: Authentication token if available.
+
+        Returns:
+            str: The agent identity (App ID). Returns the agentic instance ID if the
+                 request is agentic, otherwise returns the App ID from the auth token.
+        """
+        try:
+            # App ID is required to pass to MCP server URL
+            # Try to get agentic instance ID if this is an agentic request
+            if context and context.activity and context.activity.is_agentic_request():
+                agentic_id = context.activity.get_agentic_instance_id()
+                return agentic_id if agentic_id else ""
+
+        except (AttributeError, TypeError, Exception):
+            # Context/activity doesn't have the expected methods or properties
+            # or any other error occurred while accessing context/activity
+            pass
+
+        # Fallback to extracting App ID from the auth token
+        return Utility.get_app_id_from_token(auth_token)

microsoft_agents_a365/runtime/version_utils.py

@@ -0,0 +1,34 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""
+Version utilities for Microsoft Agent 365 SDK packages.
+
+This module is deprecated. Versioning is now handled automatically by
+setuptools-git-versioning. See versioning/TARGET-VERSION and
+HOW_TO_SET_A_VERSION.md for details.
+"""
+
+from __future__ import annotations
+
+import os
+
+
+def build_version():
+    """
+    DEPRECATED: This function is no longer used.
+
+    Version is now automatically calculated by setuptools-git-versioning
+    based on Git history and tags. See HOW_TO_SET_A_VERSION.md for details.
+
+    Returns:
+        str: Version from AGENT365_PYTHON_SDK_PACKAGE_VERSION environment variable or "0.0.0"
+    """
+    import warnings
+
+    warnings.warn(
+        "build_version() is deprecated. Version is now managed by setuptools-git-versioning.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return os.environ.get("AGENT365_PYTHON_SDK_PACKAGE_VERSION", "0.0.0")

microsoft_agents_a365_runtime-0.1.0.dist-info/METADATA

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: microsoft-agents-a365-runtime
+Version: 0.1.0
+Summary: Telemetry, tracing, and monitoring components for AI agents
+Author-email: Microsoft <support@microsoft.com>
+License: MIT
+Project-URL: Homepage, https://github.com/microsoft/Agent365-python
+Project-URL: Repository, https://github.com/microsoft/Agent365-python
+Project-URL: Issues, https://github.com/microsoft/Agent365-python/issues
+Project-URL: Documentation, https://github.com/microsoft/Agent365-python/tree/main/libraries/microsoft-agents-a365-runtime
+Keywords: observability,telemetry,tracing,opentelemetry,monitoring,ai,agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: PyJWT>=2.8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
+
+# microsoft-agents-a365-runtime
+
+[![PyPI](https://img.shields.io/pypi/v/microsoft-agents-a365-runtime?label=PyPI&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-runtime)
+[![PyPI Downloads](https://img.shields.io/pypi/dm/microsoft-agents-a365-runtime?label=Downloads&logo=pypi)](https://pypi.org/project/microsoft-agents-a365-runtime)
+
+Core runtime utilities and environment management for AI agent applications. This package provides essential Power Platform API discovery, environment configuration, and authentication scope resolution.
+
+## Installation
+
+```bash
+pip install microsoft-agents-a365-runtime
+```
+
+## Usage
+
+For usage examples and detailed documentation, see the [Microsoft Agent 365 Developer documentation](https://learn.microsoft.com/microsoft-agent-365/developer/?tabs=python) on Microsoft Learn.
+
+## Support
+
+For issues, questions, or feedback:
+
+- File issues in the [GitHub Issues](https://github.com/microsoft/Agent365-python/issues) section
+- See the [main documentation](../../../README.md) for more information
+ 
+## Trademarks
+ 
+*Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653.*
+
+## License
+
+Copyright (c) Microsoft Corporation. All rights reserved.
+
+Licensed under the MIT License - see the [LICENSE](../../../LICENSE.md) file for details.

microsoft_agents_a365_runtime-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+microsoft_agents_a365/runtime/__init__.py,sha256=g5641veSgmz8JErlGhlc-noOXcKYZpsq_yBWMg4bcyM,431
+microsoft_agents_a365/runtime/environment_utils.py,sha256=T5b1DAUV1VxwcKxbjeqxfDkuhFCBZ-8kez-_yGbmv58,1524
+microsoft_agents_a365/runtime/power_platform_api_discovery.py,sha256=CS-Vhd6jsMq7lSwtdZIDh-Oybzn_osOTtvml_uYZ8eQ,3435
+microsoft_agents_a365/runtime/utility.py,sha256=FXrdaDHL1JypZkh8JKL0zh355xAllR5xd9bUDGgDCTI,3114
+microsoft_agents_a365/runtime/version_utils.py,sha256=nkgYIaPXD9OyT_lJ8K3sqpEze_VMJzekMmjsiYNghB8,965
+microsoft_agents_a365_runtime-0.1.0.dist-info/METADATA,sha256=9aej8fSLN9GuLH0jYsnLJnrWN4J4MYIfoQS6LlXFSU0,3206
+microsoft_agents_a365_runtime-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+microsoft_agents_a365_runtime-0.1.0.dist-info/top_level.txt,sha256=G3c2_4sy5_EM_BWO67SbK2tKj4G8XFn-QXRbh8g9Lgk,22
+microsoft_agents_a365_runtime-0.1.0.dist-info/RECORD,,

microsoft_agents_a365_runtime-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

microsoft_agents_a365_runtime-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+microsoft_agents_a365