microsoft.opentelemetry.a365.runtime package

microsoft.opentelemetry.a365.runtime.get_observability_authentication_scope()

Returns the scope for authenticating to the observability service based on the current environment.

The scope can be overridden via the A365_OBSERVABILITY_SCOPE_OVERRIDE environment variable to enable testing against pre-production environments.

Returns:

The authentication scope for the current environment.

Return type:

list[str]

class microsoft.opentelemetry.a365.runtime.PowerPlatformApiDiscovery(cluster_category)

Bases: object

Discovery helper for Power Platform API endpoints.

get_token_audience()

Return type:

str

get_token_endpoint_host()

Return type:

str

get_tenant_endpoint(tenant_id)

Return type:

str

get_tenant_island_cluster_endpoint(tenant_id)

Return type:

str

class microsoft.opentelemetry.a365.runtime.Utility

Bases: object

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.

static get_app_id_from_token(token)

Decodes the current token and retrieves the App ID (appid or azp claim).

WARNING: NO SIGNATURE VERIFICATION - This method uses jwt.decode() which does NOT verify the token signature. The token claims can be spoofed by malicious actors. This method is ONLY suitable for logging, analytics, and diagnostics purposes. Do NOT use the returned value for authorization, access control, or security decisions.

Note: Returns a default GUID (‘00000000-0000-0000-0000-000000000000’) for empty tokens for backward compatibility with callers that expect a valid-looking GUID. For agent identification where empty string is preferred, use get_agent_id_from_token().

Parameters:

token (Optional[str]) – JWT token to decode. Can be None or empty.

Returns:

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.

Return type:

str

static get_agent_id_from_token(token)

Decodes the token and retrieves the best available agent identifier. Checks claims in priority order: xms_par_app_azp (agent blueprint ID) > appid > azp.

WARNING: NO SIGNATURE VERIFICATION - This method uses jwt.decode() which does NOT verify the token signature. The token claims can be spoofed by malicious actors. This method is ONLY suitable for logging, analytics, and diagnostics purposes. Do NOT use the returned value for authorization, access control, or security decisions.

Note: Returns empty string for empty/missing tokens (unlike get_app_id_from_token() which returns a default GUID). This allows callers to omit headers when no identifier is available.

Parameters:

token (Optional[str]) – JWT token to decode. Can be None or empty.

Returns:

Agent ID (GUID) or empty string if not found or token is empty.

Return type:

str

static resolve_agent_identity(context, auth_token)

Resolves the agent identity from the turn context or auth token.

Parameters:

• context (Any) – Turn context of the conversation turn. Expected to have an Activity with methods like is_agentic_request() and get_agentic_instance_id().

• auth_token (Optional[str]) – Authentication token if available.

Returns:

The agent identity (App ID). Returns the agentic instance ID if the

request is agentic, otherwise returns the App ID from the auth token.

Return type:

str

static get_user_agent_header(orchestrator=None)

Generates a User-Agent header string for SDK requests.

Parameters:

orchestrator (Optional[str]) – Optional orchestrator name to include in the User-Agent header. Defaults to empty string if not provided.

Returns:

A formatted User-Agent header string containing SDK version, OS type,

Python version, and optional orchestrator information.

Return type:

str

static get_application_name()

Gets the application name from environment variable or pyproject.toml. The pyproject.toml result is cached at first access to avoid repeated file I/O.

Returns:

Application name or None if not available.

Return type:

Optional[str]

static reset_application_name_cache()

Resets the cached application name. Used for testing purposes.

This method is intended for internal testing only.

Return type:

None

class microsoft.opentelemetry.a365.runtime.OperationError(exception)

Bases: object

Represents an error that occurred during an operation.

This class wraps an exception and provides a consistent interface for accessing error information.

property exception: Exception

Get the exception associated with the error.

Returns:

The exception associated with the error.

Return type:

Exception

property message: str

Get the message associated with the error.

Returns:

The error message from the exception.

Return type:

str

class microsoft.opentelemetry.a365.runtime.OperationResult(succeeded, errors=None)

Bases: object

Represents the result of an operation.

This class encapsulates the success or failure state of an operation along with any associated errors.

property succeeded: bool

Get a flag indicating whether the operation succeeded.

Returns:

True if the operation succeeded, otherwise False.

Return type:

bool

property errors: List[OperationError]

Get the list of errors that occurred during the operation.

Note

This property returns a defensive copy of the internal error list to prevent external modifications, which is especially important for protecting the singleton instance returned by success().

Returns:

A copy of the list of operation errors.

Return type:

List[OperationError]

static success()

Return an OperationResult indicating a successful operation.

Returns:

An OperationResult indicating a successful operation.

Return type:

OperationResult

static failed(*errors)

Create an OperationResult indicating a failed operation.

Parameters:

*errors (OperationError) – Variable number of OperationError instances.

Returns:

An OperationResult indicating a failed operation.

Return type:

OperationResult

Submodules

• microsoft.opentelemetry.a365.runtime.environment_utils module
  • get_observability_authentication_scope()
  • is_development_environment()
• microsoft.opentelemetry.a365.runtime.operation_error module
  • OperationError
    • OperationError.exception
    • OperationError.message
• microsoft.opentelemetry.a365.runtime.operation_result module
  • OperationResult
    • OperationResult.succeeded
    • OperationResult.errors
    • OperationResult.success()
    • OperationResult.failed()
• microsoft.opentelemetry.a365.runtime.power_platform_api_discovery module
  • PowerPlatformApiDiscovery
    • PowerPlatformApiDiscovery.get_token_audience()
    • PowerPlatformApiDiscovery.get_token_endpoint_host()
    • PowerPlatformApiDiscovery.get_tenant_endpoint()
    • PowerPlatformApiDiscovery.get_tenant_island_cluster_endpoint()
• microsoft.opentelemetry.a365.runtime.utility module
  • Utility
    • Utility.get_app_id_from_token()
    • Utility.get_agent_id_from_token()
    • Utility.resolve_agent_identity()
    • Utility.get_user_agent_header()
    • Utility.get_application_name()
    • Utility.reset_application_name_cache()
• microsoft.opentelemetry.a365.runtime.version_utils module
  • build_version()