Use Activity helpers and ResolveAgentIdentity for agent telemetry

CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to the Agent365 TypeScript SDK will be documented in this fi
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Breaking Changes (`@microsoft/agents-a365-observability-hosting`)
+
+- **`ScopeUtils.deriveAgentDetails(turnContext, authToken)`** — New required `authToken: string` parameter.
+- **`ScopeUtils.populateInferenceScopeFromTurnContext(details, turnContext, authToken, ...)`** — New required `authToken: string` parameter.
+- **`ScopeUtils.populateInvokeAgentScopeFromTurnContext(details, turnContext, authToken, ...)`** — New required `authToken: string` parameter.
+- **`ScopeUtils.populateExecuteToolScopeFromTurnContext(details, turnContext, authToken, ...)`** — New required `authToken: string` parameter.
+- **`ScopeUtils.buildInvokeAgentDetails(details, turnContext, authToken)`** — New required `authToken: string` parameter.
+
+### Changed (`@microsoft/agents-a365-observability-hosting`)
+
+- `ScopeUtils.deriveAgentDetails` now resolves `agentId` via `RuntimeUtility.ResolveAgentIdentity()` (works for both app-based and blueprint-based agents) instead of reading `recipient.agenticAppId` directly.
+- `ScopeUtils.deriveAgentDetails` now resolves `agentBlueprintId` from the JWT `xms_par_app_azp` claim via `RuntimeUtility.getAgentIdFromToken()` instead of reading `recipient.agenticAppBlueprintId`.
+- `ScopeUtils.deriveAgentDetails` now resolves `agentUPN` via `activity.getAgenticUser()` instead of `recipient.agenticUserId`.
+- `ScopeUtils.deriveTenantDetails` now uses `activity.getAgenticTenantId()` instead of `recipient.tenantId`.
+- `getTargetAgentBaggagePairs` now uses `activity.getAgenticInstanceId()` instead of `recipient.agenticAppId`.
+- `getTenantIdPair` now uses `activity.getAgenticTenantId()` instead of manual `channelData` parsing.
+
 ## [1.1.0] - 2025-12-09
 
 ### Changed

packages/agents-a365-observability-hosting/src/utils/ScopeUtils.ts

@@ -17,6 +17,7 @@ import {
   ToolCallDetails,
   ExecutionType
 } from '@microsoft/agents-a365-observability';
+import { Utility as RuntimeUtility } from '@microsoft/agents-a365-runtime';
 import {
   getExecutionTypePair,
 } from './TurnContextUtils';
@@ -44,26 +45,34 @@ export class ScopeUtils {
    * @returns Tenant details if a recipient tenant id is present; otherwise undefined.
    */
   public static deriveTenantDetails(turnContext: TurnContext): TenantDetails | undefined {
-    const tenantId = turnContext?.activity?.recipient?.tenantId;
+    const tenantId = turnContext?.activity?.getAgenticTenantId();
     return tenantId ? { tenantId } : undefined;
   }
 
   /**
    * Derive target agent details from the activity recipient.
+   * Uses {@link RuntimeUtility.ResolveAgentIdentity} to resolve the agent ID (instance ID for blueprint agents,
+   * appid/azp from token for app-based agents). For blueprint agents, the blueprint ID is resolved
+   * from the token's xms_par_app_azp claim via {@link RuntimeUtility.getAgentIdFromToken}.
    * @param turnContext Activity context
+   * @param authToken Auth token for resolving agent identity from token claims.
    * @returns Agent details built from recipient properties; otherwise undefined.
    */
-  public static deriveAgentDetails(turnContext: TurnContext): AgentDetails | undefined {
+  public static deriveAgentDetails(turnContext: TurnContext, authToken: string): AgentDetails | undefined {
     const recipient = turnContext?.activity?.recipient;
     if (!recipient) return undefined;
+    const agentId = RuntimeUtility.ResolveAgentIdentity(turnContext, authToken);
+    const agentBlueprintId = turnContext?.activity?.isAgenticRequest()
+      ? RuntimeUtility.getAgentIdFromToken(authToken)
+      : undefined;
     return {
-      agentId: recipient.agenticAppId,
+      agentId,
       agentName: recipient.name,
       agentAUID: recipient.aadObjectId,
-      agentBlueprintId: recipient.agenticAppBlueprintId,
-      agentUPN: recipient.agenticUserId,
+      agentBlueprintId,
+      agentUPN: turnContext?.activity?.getAgenticUser(),
       agentDescription: recipient.role,
-      tenantId: recipient.tenantId
+      tenantId: turnContext?.activity?.getAgenticTenantId()
     } as AgentDetails;
   }
 
@@ -131,17 +140,19 @@ export class ScopeUtils {
    * Also records input messages from the context if present.
    * @param details The inference call details (model, provider, tokens, etc.).
    * @param turnContext The current activity context to derive scope parameters from.
+   * @param authToken Auth token for resolving agent identity from token claims.
    * @param startTime Optional explicit start time (ms epoch, Date, or HrTime).
    * @param endTime Optional explicit end time (ms epoch, Date, or HrTime).
    * @returns A started `InferenceScope` enriched with context-derived parameters.
    */
   static populateInferenceScopeFromTurnContext(
     details: InferenceDetails,
     turnContext: TurnContext,
+    authToken: string,
     startTime?: TimeInput,
     endTime?: TimeInput
   ): InferenceScope {
-    const agent = ScopeUtils.deriveAgentDetails(turnContext);
+    const agent = ScopeUtils.deriveAgentDetails(turnContext, authToken);
     const tenant = ScopeUtils.deriveTenantDetails(turnContext);
     const conversationId = ScopeUtils.deriveConversationId(turnContext);
     const sourceMetadata = ScopeUtils.deriveSourceMetadataObject(turnContext);
@@ -165,20 +176,22 @@ export class ScopeUtils {
    * Also sets execution type and input messages from the context if present.
    * @param details The invoke-agent call details to be augmented and used for the scope.
    * @param turnContext The current activity context to derive scope parameters from.
+   * @param authToken Auth token for resolving agent identity from token claims.
    * @param startTime Optional explicit start time (ms epoch, Date, or HrTime).
    * @param endTime Optional explicit end time (ms epoch, Date, or HrTime).
    * @returns A started `InvokeAgentScope` enriched with context-derived parameters.
    */
   static populateInvokeAgentScopeFromTurnContext(
     details: InvokeAgentDetails,
     turnContext: TurnContext,
+    authToken: string,
     startTime?: TimeInput,
     endTime?: TimeInput
   ): InvokeAgentScope {
     const tenant = ScopeUtils.deriveTenantDetails(turnContext);
     const callerAgent = ScopeUtils.deriveCallerAgent(turnContext);
     const caller = ScopeUtils.deriveCallerDetails(turnContext);
-    const invokeAgentDetails = ScopeUtils.buildInvokeAgentDetails(details, turnContext);
+    const invokeAgentDetails = ScopeUtils.buildInvokeAgentDetailsCore(details, turnContext, authToken);
 
     if (!tenant) {
       throw new Error('populateInvokeAgentScopeFromTurnContext: Missing tenant details on TurnContext (recipient)');
@@ -193,10 +206,15 @@ export class ScopeUtils {
    * Build InvokeAgentDetails by merging provided details with agent info, conversation id and source metadata from the TurnContext.
    * @param details Base invoke-agent details to augment
    * @param turnContext Activity context
+   * @param authToken Auth token for resolving agent identity from token claims.
    * @returns New InvokeAgentDetails suitable for starting an InvokeAgentScope.
    */
-  public static buildInvokeAgentDetails(details: InvokeAgentDetails, turnContext: TurnContext): InvokeAgentDetails {
-    const agent = ScopeUtils.deriveAgentDetails(turnContext);
+  public static buildInvokeAgentDetails(details: InvokeAgentDetails, turnContext: TurnContext, authToken: string): InvokeAgentDetails {
+    return ScopeUtils.buildInvokeAgentDetailsCore(details, turnContext, authToken);
+  }
+
+  private static buildInvokeAgentDetailsCore(details: InvokeAgentDetails, turnContext: TurnContext, authToken: string): InvokeAgentDetails {
+    const agent = ScopeUtils.deriveAgentDetails(turnContext, authToken);
     const srcMetaFromContext = ScopeUtils.deriveSourceMetadataObject(turnContext);
     const executionTypePair = getExecutionTypePair(turnContext);
     const baseRequest = details.request ?? {};
@@ -223,6 +241,7 @@ export class ScopeUtils {
    * Derives `agentDetails`, `tenantDetails`, `conversationId`, and `sourceMetadata` (channel name/link) from context.
    * @param details The tool call details (name, type, args, call id, etc.).
    * @param turnContext The current activity context to derive scope parameters from.
+   * @param authToken Auth token for resolving agent identity from token claims.
    * @param startTime Optional explicit start time (ms epoch, Date, or HrTime). Useful when recording a
    *        tool call after execution has already completed.
    * @param endTime Optional explicit end time (ms epoch, Date, or HrTime).
@@ -231,10 +250,11 @@ export class ScopeUtils {
   static populateExecuteToolScopeFromTurnContext(
     details: ToolCallDetails,
     turnContext: TurnContext,
+    authToken: string,
     startTime?: TimeInput,
     endTime?: TimeInput
   ): ExecuteToolScope {
-    const agent = ScopeUtils.deriveAgentDetails(turnContext);
+    const agent = ScopeUtils.deriveAgentDetails(turnContext, authToken);
     const tenant = ScopeUtils.deriveTenantDetails(turnContext);
     const conversationId = ScopeUtils.deriveConversationId(turnContext);
     const sourceMetadata = ScopeUtils.deriveSourceMetadataObject(turnContext);

packages/agents-a365-observability-hosting/src/utils/TurnContextUtils.ts

@@ -70,11 +70,11 @@ export function getExecutionTypePair(turnContext: TurnContext): Array<[string, s
  * @returns Array of [key, value] pairs for agent identity and description
  */
 export function getTargetAgentBaggagePairs(turnContext: TurnContext): Array<[string, string]> {
-  if (!turnContext || !turnContext.activity?.recipient) { 
+  if (!turnContext || !turnContext.activity?.recipient) {
     return [];
   }
-  const recipient = turnContext.activity.recipient; 
-  const agentId = recipient.agenticAppId;
+  const recipient = turnContext.activity.recipient;
+  const agentId = turnContext.activity?.getAgenticInstanceId();
   const agentName = recipient.name;
   const aadObjectId = recipient.aadObjectId;
   const agentDescription  = recipient.role;
@@ -88,29 +88,12 @@ export function getTargetAgentBaggagePairs(turnContext: TurnContext): Array<[str
 }
 
 /**
- * Extracts the tenant ID baggage key-value pair, attempting to retrieve from ChannelData if necessary.
+ * Extracts the tenant ID baggage key-value pair using the Activity's getAgenticTenantId() helper.
  * @param turnContext The current TurnContext (activity context)
  * @returns Array of [key, value] for tenant ID
  */
 export function getTenantIdPair(turnContext: TurnContext): Array<[string, string]> {
-   let tenantId = turnContext.activity?.recipient?.tenantId;
-
-
-  // If not found, try to extract from channelData. Accepts both object and JSON string.
-  if (!tenantId && turnContext.activity?.channelData) {
-    try {
-      let channelData: unknown = turnContext.activity.channelData;
-      if (typeof channelData === 'string') {
-        channelData = JSON.parse(channelData);
-      }
-      if (
-        typeof channelData === 'object' && channelData !== null) {
-        tenantId = (channelData as { tenant: { id?: string } })?.tenant?.id;
-      }
-    } catch (_err) {
-      // ignore JSON parse errors
-    }
-  }
+  const tenantId = turnContext.activity?.getAgenticTenantId();
   return tenantId ? [[OpenTelemetryConstants.TENANT_ID_KEY, tenantId]] : [];
 }