Share via

Utility class

Package:
@microsoft/agents-a365-runtime

Utility class providing helper methods for agent runtime operations.

Methods

getAgentIdFromToken(string)

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.

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

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

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.

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

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 getAgentIdFromToken.
getApplicationName()

Gets the application name from npm_package_name environment variable or package.json. The package.json result is cached at module load time to avoid sync I/O during requests.
GetUserAgentHeader(string)

Generates a User-Agent header string containing SDK version, OS type, Node.js version, and orchestrator.
ResolveAgentIdentity(TurnContext, string)

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

Method Details

getAgentIdFromToken(string)

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.

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

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

static function getAgentIdFromToken(token: string): string

Parameters

token

string

JWT token to decode

Returns

string

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

GetAppIdFromToken(string)

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.

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

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

static function GetAppIdFromToken(token: string): string

Parameters

token

string

Token to Decode

Returns

string

AppId, or default GUID for empty token, or empty string if decode fails

getApplicationName()

Gets the application name from npm_package_name environment variable or package.json. The package.json result is cached at module load time to avoid sync I/O during requests.

static function getApplicationName(): undefined | string

Returns

undefined | string

Application name or undefined if not available.

GetUserAgentHeader(string)

Generates a User-Agent header string containing SDK version, OS type, Node.js version, and orchestrator.

static function GetUserAgentHeader(orchestrator?: string): string

Parameters

orchestrator

string

Optional orchestrator identifier to include in the User-Agent string.

Returns

string

Formatted User-Agent header string.

ResolveAgentIdentity(TurnContext, string)

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

static function ResolveAgentIdentity(context: TurnContext, authToken: string): string

Parameters

context
TurnContext

Turn Context of the turn.

authToken

string

Auth token if available.

Returns

string

Agent identity (App ID)