microsoft.opentelemetry.a365.runtime.utility module

Utility functions for Microsoft Agent 365 runtime operations.

This module provides utility functions for token handling, agent identity resolution, and other common runtime operations.

class microsoft.opentelemetry.a365.runtime.utility.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