Utility Class

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.

Constructor

Utility()

Methods

get_agent_id_from_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.
get_app_id_from_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().
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.
get_user_agent_header	Generates a User-Agent header string for SDK requests.
reset_application_name_cache	Resets the cached application name. Used for testing purposes. This method is intended for internal testing only.
resolve_agent_identity	Resolves the agent identity from the turn context or auth token.

get_agent_id_from_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.

static get_agent_id_from_token(token: str | None) -> str

Parameters

Name	Description
token Required	JWT token to decode. Can be None or empty.

Returns

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

get_app_id_from_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().

static get_app_id_from_token(token: str | None) -> str

Parameters

Name	Description
token Required	JWT token to decode. Can be None or empty.

Returns

Type	Description
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.

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.

static get_application_name() -> str | None

Returns

Type	Description
Optional[str]	Application name or None if not available.

get_user_agent_header

Generates a User-Agent header string for SDK requests.

static get_user_agent_header(orchestrator: str | None = None) -> str

Parameters

Name	Description
orchestrator	Optional orchestrator name to include in the User-Agent header. Defaults to empty string if not provided. Default value: None

Returns

Type	Description
str	A formatted User-Agent header string containing SDK version, OS type, Python version, and optional orchestrator information.

reset_application_name_cache

Resets the cached application name. Used for testing purposes.

This method is intended for internal testing only.

static reset_application_name_cache() -> None

resolve_agent_identity

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

static resolve_agent_identity(context: Any, auth_token: str | None) -> str

Parameters

Name	Description
context Required	Turn context of the conversation turn. Expected to have an Activity with methods like is_agentic_request() and get_agentic_instance_id().
auth_token Required	Authentication token if available.

Returns

Type	Description
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.